The Advisor Tool on the Claude Messages API

Most agentic workloads are mostly mechanical: read a file, run a check, adjust the plan slightly, move on. The moments that actually decide whether a task goes well are rarer and harder to spot in advance, an architectural choice, a subtle failure mode, a plan that needs revising before more work builds on top of it. The advisor tool on the Claude Messages API is Anthropic's answer to that shape of problem: pair a fast, cheap executor model with a higher-intelligence advisor model it can consult mid-generation, so you get most of the advisor's judgment without paying the advisor's rate for every token of output.

This is the standalone Messages API version of the same pattern covered on the Managed Agents side in multiagent orchestration in Claude Managed Agents. It's usable well outside Managed Agents, on any Messages API integration, and it's currently in beta.

When it's actually worth adding

Anthropic frames two configurations where the advisor earns its keep:

• You're already running Sonnet on complex tasks. Adding an Opus advisor keeps total cost similar or lower than Sonnet alone; adding a Claude Fable 5 advisor maximizes the quality lift instead.
• You're running Haiku and want a step up in intelligence. An Opus or Fable advisor costs more than Haiku alone, but less than switching the whole executor to a larger model.

It's a weaker fit for single-turn Q&A, where there's nothing to plan ahead of, for pass-through model pickers where your users already choose their own cost and quality tradeoff, or for workloads where genuinely every turn needs the advisor's full capability rather than occasional guidance. Results are task-dependent; Anthropic's own guidance is to evaluate on your own workload rather than assume the pattern transfers.

Quick start

The advisor tool is in beta. Include the beta header advisor-tool-2026-03-01 on every request that uses it:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: advisor-tool-2026-03-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 4096,
    "tools": [
      {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5"
      }
    ],
    "messages": [{
      "role": "user",
      "content": "Build a concurrent worker pool in Go with graceful shutdown."
    }]
  }'

The response's content array includes an advisor_tool_result block carrying the advisor's guidance. With claude-opus-5 as the advisor, as above, that block is an encrypted advisor_redacted_result, readable by the executor server-side but not by your client. Swap in claude-opus-4-8 as the advisor model instead and you get the plaintext advisor_result variant with the advice text visible directly in your response. Both shapes are covered in full below.

How it works under the hood

Adding the advisor to your tools array lets the executor decide when to call it, exactly like any other tool. When it does:

1. The executor emits a server_tool_use block named "advisor" with an empty input. The executor only signals timing; the server itself constructs what the advisor sees.
2. Anthropic runs a separate inference pass on the advisor model, server-side. The advisor runs under its own Anthropic-supplied system prompt and receives the executor's full transcript as quoted context, including your system prompt, tool definitions, prior turns and tool results, and whatever text the executor has produced so far in that turn.
3. The advisor's response comes back as an advisor_tool_result block.
4. The executor continues generating, informed by that advice.

All of this happens inside one /v1/messages request, with no extra round trip on your side, except a turn that pauses mid-call, which you resume with a follow-up request covered below. The advisor itself runs without tools of its own and without context management; its thinking blocks are dropped before the result returns, so only the advice text reaches the executor.

Result variants: plaintext vs redacted

The advisor_tool_result.content field is a discriminated union, and which variant you get depends entirely on the advisor model you chose:

As of this beta, Claude Opus 5, Claude Fable 5 and Claude Mythos 5 return the encrypted advisor_redacted_result. Every other supported advisor model, including Claude Opus 4.8, returns the plaintext advisor_result. The same request sent twice, differing only in the tool definition's model field, shows both shapes:

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_result",
    "text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown..."
  }
}

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ5ZjE0N2M2OC0yYWIxLTRkZTktYjA3ZC1hZTUyMzkxYjhkMmU..."
  }
}

Round-trip either shape verbatim on later turns. With a redacted result, the server decrypts it and renders the plaintext into the executor's prompt on the next turn; your client never needs to read the content, only pass it back unchanged. If you switch advisor models mid-conversation, branch on content.type to handle both shapes rather than assuming one.

Error results

A failed advisor call doesn't fail the whole request. It returns an error inside the result block instead, and the executor continues without the advice:

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_tool_result_error",
    "error_code": "overloaded"
  }
}

Advisor rate limits draw from the same per-model bucket as direct calls to that model. A rate limit on the advisor surfaces as too_many_requests inside the result; a rate limit on the executor itself fails the whole request with HTTP 429, same as any other request.

Tool parameters

Cost: billed separately, at the advisor's rate

Advisor calls are billed as a distinct sub-inference, reported in a usage.iterations array rather than folded into the top-level totals:

{
  "usage": {
    "input_tokens": 1760,
    "output_tokens": 531,
    "iterations": [
      { "type": "message", "input_tokens": 412, "output_tokens": 89 },
      { "type": "advisor_message", "model": "claude-opus-5", "input_tokens": 823, "output_tokens": 1612 },
      { "type": "message", "input_tokens": 1348, "output_tokens": 442 }
    ]
  }
}

Top-level usage fields reflect executor tokens only; advisor_message iterations are billed at the advisor model's rates and have to be read from the array. Advisor output typically runs 400 to 700 text tokens, 1,400 to 1,800 including thinking, and the savings come from the advisor not generating your full final output, the executor still does that at its own, cheaper rate.

Two caps worth knowing: the top-level max_tokens applies to the executor's output only and doesn't bound the advisor's sub-inference at all. To cap the advisor directly, set max_tokens on the tool definition itself (1024 minimum). In Anthropic's own testing on a hard reasoning benchmark, max_tokens: 2048 cut mean advisor output roughly 7x versus leaving it unset, with near-zero truncation. The advisor's tokens also don't draw from any Messages API task budget applied to the executor, and a Priority Tier commitment on the executor model doesn't automatically extend to the advisor; you need a separate commitment on the advisor model for its calls to run at that tier.

For conversation-level cost control, count advisor calls client-side and drop the tool from tools once you hit your own ceiling; you don't need to strip historical advisor_tool_result blocks to do that.

Model compatibility

The advisor must be Claude Sonnet 4.6 or a more capable model, and at least as capable as the executor it advises. Models of equal capability, two Opus versions, for instance, can advise each other. An invalid pairing returns a 400 invalid_request_error naming the unsupported combination. As of this beta, Haiku 4.5, Sonnet 4.6, Sonnet 5, and the Opus 4.6 through Opus 5 line can all serve as executors, each with a defined list of valid advisors ranging from Sonnet-tier up through Claude Mythos 5, Anthropic's own advisor tool documentation publishes the complete pairing table, worth checking directly before you commit to a pairing rather than assuming any two models can be combined.

The tool is currently available in beta on the Claude API and on Claude Platform on AWS. It is not currently available on Amazon Bedrock, Google Cloud, or Microsoft Foundry.

Streaming behaviour

The advisor sub-inference itself does not stream. The executor's stream pauses while the advisor runs, quiet except for standard SSE ping keepalives roughly every 30 seconds, and short advisor calls may show none at all. When the advisor finishes, its result arrives fully formed in a single event, no partial deltas, and executor output resumes streaming immediately after.

Advisor caching is a separate layer from executor caching

There are two independent caching layers here, and it's easy to conflate them. The advisor_tool_result block itself is cacheable like any other content block in the executor's own prompt cache; a cache_control breakpoint placed after it on a later turn hits normally, regardless of which result variant you received.

Separately, setting caching: {"type": "ephemeral", "ttl": "5m"} on the tool definition itself enables caching for the advisor's own transcript across calls within one conversation, since each advisor call's prompt is the previous call's prompt with one more segment appended. This pays off once you're making three or more advisor calls in a conversation; below that, the cache-write cost outweighs what it saves, so leave it off for short tasks and on for long agent loops.

Advisor on Claude Managed Agents

Claude Managed Agents sessions support the same pattern, configured differently: add a {"type": "advisor", "model": ...} entry to an agent's multiagent roster rather than defining it as a Messages API tool, and the session's primary thread can consult that model mid-turn. The roster entry takes no max_uses, max_tokens or caching options of its own, and advice arrives as thread events on the session's event stream rather than as an advisor_tool_result content block. See multiagent orchestration in Claude Managed Agents for the full mechanics of that side.

Troubleshooting

The response contains no advice text at all. Check which model you set as the advisor. Claude Opus 5, Claude Fable 5 and Claude Mythos 5 currently return the encrypted advisor_redacted_result, which never surfaces readable text to your client by design; switch to a plaintext-returning advisor like Claude Opus 4.8 if you need to read the advice directly.

A request with the advisor tool returns a 400 on an otherwise-working integration. Confirm the anthropic-beta: advisor-tool-2026-03-01 header is present on every request that references the tool, including a resume request carrying historical advisor_tool_result blocks in its message history, not just the request that first added the tool.

The executor never calls the advisor. The tool is entirely executor-initiated; there's no automatic trigger. If a workload consistently under-calls it, Anthropic's own guidance covers a mid-conversation nudge technique and forcing a call with tool_choice, both worth reading before assuming the model simply won't use it.

Where to go next

Anthropic's own advisor tool page is the full reference this article draws from, including the complete model compatibility table and prompting guidance for coding workloads specifically. For the Managed Agents configuration of the same pattern, see multiagent orchestration in Claude Managed Agents. For the caching mechanics referenced above, see Claude Code's promptCacheTtl setting explained. Browse the wider catalogue at getclaudeskills.com/skills or by category.

Verified 26 August 2026 directly against Anthropic's advisor tool documentation at platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool, read in full.