The self-optimize MCP tools
ACP records and decides every tool call an agent makes. These ten MCP tools hand that record back to the agent, so it can ask “what have I been doing, what did it cost, and what should change?” They only cover the caller’s own activity.
Connect any MCP client (streamable HTTP, OAuth sign-in in the browser):
https://api.agenticcontrolplane.com/mcp
An ACP workspace exposes exactly these ten tools over MCP. Nine are read-only. The tenth, acp_propose_rule, writes one thing: a draft rule that a human confirms or rejects in the console. Nothing here applies policy or touches your data.
Scoping. Every tool defaults to the caller’s own principal, so an agent sees its own runs, decisions, and spend. A key with the admin scope can ask for workspace-wide views. The one exception is the plan cap in acp_usage. The workspace limit applies to every member, so every member can see it.
The ten tools
| Tool | What it returns |
|---|---|
acp_check |
Advisory pre-check: pass a tool_name and tool_input, get back whether policy would allow the call. Ask before doing, without doing. |
acp_status |
Connectivity, enforcement state, and the caller’s budget: spent, remaining, and percent used of the identity’s spending cap. Poll it to pace a long task and wrap up before the cap cuts you off. |
acp_audit |
The caller’s recent decided calls: tool, decision (allow / deny / redact / rate), and the reason for each. Filterable by decision, up to 100 rows. |
acp_usage |
The workspace’s monthly plan usage. Calls are unlimited on every plan. The meter counts initiating agents against the plan’s band (ok / nudge / at-limit / over), plus calls used and the caller’s own share. |
acp_cost |
Model spend over a window (today / 7d / 30d): total dollars, run count, and a by-model breakdown. |
acp_recommendations |
Ranked policy suggestions with evidence, computed from the caller’s approval and decision history. A tool approved many times is a candidate for auto-allow, for example. Read-only; you apply them in the console. |
acp_optimize |
The shape of the caller’s cost: prompt-cache hit rate, spend by model, growing-loop share, what fills the context (system vs history vs tool results), and which tools produce the most re-read output. It returns data for the agent to reason over, plus a short hint. |
acp_trace |
The step-by-step trace of one run: ordered steps with tool, kind (leaf / loop / tool), cost, and model, plus totals. Defaults to the caller’s most recent run. |
acp_propose_rule |
Stages a draft policy rule: tool, proposed permission (allow / ask / deny / flag / step_up), tier, a one-sentence rationale, and optional guidance shown to the agent when the rule fires. A human reviews and applies it in the console. Nothing is enforced until they do. |
acp_wait_approval |
Waits for an admin’s decision on a call ACP held. Read-only, and limited to the caller’s own approvals. |
What acp_optimize looks like
A shape like this (example values):
{
"window": "7d",
"scope": "principal",
"runs": 42,
"totalCostUsd": 18.40,
"cacheHitRate": 61,
"inputDecompose": { "cacheRead": 8100000, "cacheWrite": 900000, "uncached": 4200000 },
"loopSharePct": 34,
"costByModelUsd": { "claude-sonnet-4-5": 15.10, "claude-haiku-4-5": 3.30 },
"contextBreakdownPct": { "system": 12, "history": 31, "toolResults": 57 },
"topToolsByOutput": [ { "tool": "Read", "mb": 9.80 }, { "tool": "Bash", "mb": 2.10 } ],
"hint": "uncached (true cache miss) share is 32% — a stable, byte-identical prompt prefix (system + tools) across turns is the biggest lever; cached reads bill at ~10% of full rate. toolResults dominating context → compact or drop stale tool output."
}
Two things the tool does on purpose. The context breakdown is only captured on the ACP proxy path, so when it’s empty the response says so instead of returning zeros that look like “nothing to optimize”. And runs that changed their prompt prefix mid-run are counted, because a changing prefix is the cause of a low cache rate.
The advice depends on the tier. “Consider a subagent” only appears for autonomous runs. In an interactive session the growing loop is the work.
A realistic loop
An agent partway through a long autonomous task, running this on itself:
- Pace.
acp_statussays 71% of the spending cap is used. That is enough to finish, not enough to explore. - Attribute.
acp_optimize(window7d) shows a 61% cache-hit rate,toolResultsat 57% of context, andReadas the top producer by output bytes. - Adjust. The agent compacts its context, stops re-reading whole files, and routes leaf lookups to a cheaper model. All of that is within its own control.
- Verify.
acp_traceon the next run shows the loop steps got cheaper, and the totals confirm it. - Propose.
acp_auditshows a human approved the same read-only command 14 times this week. The agent runsacp_propose_rulewith permissionallowand a one-line rationale. The draft lands in the console and the human applies it or doesn’t. Approval fatigue goes down without the agent ever touching policy.
The agent can read everything about itself and change none of its own rules. Every proposal ends with a human.
Related
- The Agent Optimization Manual: measured field notes from running this loop on our own agents.
- Ways to set up ACP: the proxy step that unlocks the full cost composition.
- Policies & scopes: what the proposed rules land in.
Running coding agents? ACP records each tool call its hook sees and makes the dangerous shell commands (a force-push, destructive SQL, curl | sh) wait for you. One command, free up to 5 agents:
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
irm https://agenticcontrolplane.com/install.ps1 | iex