The advisor tool: Sonnet does the work, Fable does the thinking

Intermediate

Anthropic shipped a quiet but consequential primitive in beta: the advisor tool. A fast executor model (Sonnet, Haiku) drives the turn; at decision points it hands the full transcript to a stronger advisor (Opus 5, Fable 5, Mythos 5), the advisor returns a plan, and the executor keeps typing. All server-side, in one /v1/messages call — no extra round trip on your side.

If you've been switching between models by hand — Opus for planning, Sonnet to write it out — the advisor collapses that dance into a single request. It's also the first mainstream production pattern where you're routinely billed across two model tiers inside one response, which breaks every naive usage.output_tokens * price cost-tracker written before March 2026.

What you'll learn

Send a request with the beta header advisor-tool-2026-03-01, an executor model, and the advisor tool definition
Read usage.iterations correctly — top-level output_tokens is executor only; advisor tokens live inside iteration entries of type advisor_message
Pick the executor/advisor pair — the advisor must be at least as capable as the executor, and Opus 5 / Fable 5 / Mythos 5 return encrypted content you must round-trip verbatim
Cap runaway advice with max_tokens on the tool definition (min 1024) — top-level max_tokens does NOT bound the advisor
Enable advisor-side caching for conversations with 3+ advisor calls, and know why clear_thinking's default silently kills that cache
Turn on /advisor in Claude Code with a saved advisorModel — including the Fable 5 rollout gotcha (currently disabled as an advisor even for organizations with Fable access)

Why the advisor exists (and why it isn't just "call two APIs")

The naive alternative is obvious: call Opus, get a plan, then call Sonnet with the plan as system prompt. Anthropic's own docs are blunt about why the advisor beats that:

The advisor reads the full executor transcript — every prior turn, every tool call, every result, plus the text the executor has produced so far in the current turn. You'd have to serialize and forward all of that yourself.
It runs inside one /v1/messages request. Your streaming connection just pauses (with SSE ping keepalives every ~30s) and then the advisor_tool_result block arrives fully formed in a single content_block_start event — no deltas. Executor output resumes streaming right after.
The executor decides when to call the advisor. You don't hardcode "always plan first." Claude tends to call it before committing to an approach, when the same error keeps recurring, and before declaring the task complete.

The advisor runs under its own Anthropic-supplied system prompt, without tools, without context management, and its thinking blocks are stripped before the result returns. Only the advice text (or an encrypted blob) reaches the executor.

Quick start — the minimum viable advisor request

Sonnet 5 executor + Fable 5 advisor (Python)

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
  model="claude-sonnet-5",
  max_tokens=4096,
  betas=["advisor-tool-2026-03-01"],
  tools=[
      {
          "type": "advisor_20260301",
          "name": "advisor",
          "model": "claude-fable-5",
      }
  ],
  messages=[
      {
          "role": "user",
          "content": "Build a concurrent worker pool in Go with graceful shutdown.",
      }
  ],
)

print(response)

Three things to notice:

The type string is "advisor_20260301" and the name must be "advisor". Both are enforced literally.
The betas=["advisor-tool-2026-03-01"] header is the flag that opens the tool. Same string on cURL as -H "anthropic-beta: advisor-tool-2026-03-01".
The input on the server_tool_use block the executor emits is always empty. You never fill it. The server constructs the advisor's view from the transcript automatically.

The pairing rule (and the surprise about Fable 5)

The advisor must be at least as capable as the executor, and Anthropic ranks equally-capable models as advisers for each other (Opus 4.7 and Opus 4.8 can advise each other, Sonnet 5 and Opus 4.6 too). Here's the full accepted matrix on the Claude API as of Aug 2026:

Executor	Accepted advisers
`claude-haiku-4-5`	Mythos 5, Fable 5, Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5, Sonnet 4.6
`claude-sonnet-4-6`	Mythos 5, Fable 5, Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5, Sonnet 4.6
`claude-sonnet-5`	Mythos 5, Fable 5, Opus 5, Opus 4.8, Opus 4.7, Sonnet 5
`claude-opus-4-6`	Mythos 5, Fable 5, Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5
`claude-opus-4-7`	Mythos 5, Fable 5, Opus 5, Opus 4.8, Opus 4.7
`claude-opus-4-8`	Mythos 5, Fable 5, Opus 5, Opus 4.8, Opus 4.7
`claude-opus-5`	Mythos 5, Fable 5, Opus 5
`claude-fable-5`	Fable 5, Opus 5
`claude-mythos-5`	Mythos 5, Opus 5

Invalid pairs return a 400 invalid_request_error naming the unsupported combination. And there's a Claude Code twist worth flagging separately: Fable 5 is currently disabled as an advisor in Claude Code for organizations that otherwise have Fable 5 access, controlled by a server-side rollout. The /advisor picker shows a dimmed Fable 5 (temporarily unavailable) row and /advisor fable is rejected. This does not affect the API, where claude-fable-5 as the advisor works today.

The token-accounting trap most integrators walk into

This is the single most surprising thing about the advisor and the reason you should not ship an advisor integration without rewriting your cost tracker first.

Top-level usage.output_tokens reflects executor tokens only. Advisor tokens are not rolled into the top-level totals because they are billed at the advisor model's rates, which are almost always different. To see the full picture you have to read usage.iterations[], an array Anthropic added specifically for this feature:

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

Iterations tagged advisor_message are billed at the advisor's rates; iterations tagged message are billed at the executor's rates. The aggregation rules for the top-level fields are also asymmetric — top-level output_tokens sums all executor iterations, but top-level input_tokens and cache_read_input_tokens reflect the first executor iteration only (later executor iterations' inputs include prior output tokens, so re-summing them would double-count).

Watch out

If you compute cost as usage.input_tokens * exec_input_price + usage.output_tokens * exec_output_price, you will silently under-report by the advisor's entire spend — advisor calls typically emit 1,400 to 1,800 tokens total including thinking, at a substantially higher per-token rate.
Advisor tokens do NOT draw from any task budget applied to the executor. If you rely on task_budget as a hard spending ceiling, the advisor sits outside it.
Priority Tier applies per-model. A Priority Tier commitment on the executor does not extend to the advisor. Advisor calls run at Priority Tier only if your organization also holds a commitment on the advisor model.

Capping runaway advice — the max_tokens gotcha

The top-level max_tokens bounds executor output only. To cap the advisor's total output per call (thinking + text), set max_tokens on the tool definition:

Cap advisor at 2048 tokens per call

tools = [
  {
      "type": "advisor_20260301",
      "name": "advisor",
      "model": "claude-fable-5",
      "max_tokens": 2048,   # minimum is 1024; setting above the advisor's own output cap returns 400
      "max_uses": 5         # optional per-request cap; extra calls return error_code max_uses_exceeded
  }
]

Anthropic's own hard-reasoning benchmark (n=40 per configuration) reports these numbers as the practical starting points:

`max_tokens` on tool	Mean advisor output	Calls truncated
Not set	~10k+ tokens on hard tasks	0%
2048 (recommended)	~7x smaller than unset	~0%
1024 (minimum)	~10x smaller than unset	~10%

Accuracy differences between the three configurations were within noise at that sample size. When the advisor hits the cap, the result block carries stop_reason: "max_tokens" and Anthropic appends [Advisor output truncated at max_tokens=2048.] (naming your actual cap) to the advice text so the executor sees the truncation in its own context. Both signals only appear when you set max_tokens on the tool definition — omit it and you get neither.

The prompt-caching layer everyone misses

There are two independent caching layers around the advisor, and getting either wrong is a silent cost regression.

Guided walkthrough1 of 3

The advisor_tool_result block is cacheable like any other content block. A cache_control breakpoint placed after it on a subsequent turn hits normally. The executor's prompt always contains the plaintext advice regardless of whether your client received text or encrypted_content, so caching behavior is identical for both result variants.

Toggling caching on and off mid-conversation also invalidates the cache. Set it once, leave it.

The two result variants and why they're both fine

Successful advisor calls return one of two content shapes:

advisor_result with a text field — human-readable advice. Returned by Claude Opus 4.8 and the other non-Opus-5-generation advisers.
advisor_redacted_result with an encrypted_content field — an opaque blob you cannot read. Returned by Claude Opus 5, Claude Fable 5, and Claude Mythos 5 advisers.

Round-trip whichever one you get verbatim on subsequent turns. On the next turn, the server decrypts the blob and renders the plaintext into the executor's prompt — the executor sees the same content either way. If you switch advisers mid-conversation, branch on content.type to handle both shapes.

Pro tip

The redacted variant isn't a limitation — it's the mechanism that lets Opus 5 / Fable 5 / Mythos 5 emit advice the executor can act on without exposing internal reasoning to your client. If you need the advice text at your logging layer, use Opus 4.8 as the advisor.
Both variants carry a stop_reason when you set max_tokens on the tool definition, and omit it when you don't. Use it to detect truncation without parsing the appended string.

Multi-turn: the invisible 400 you'll hit exactly once

If you omit the advisor tool from tools on a follow-up turn while the message history still contains advisor_tool_result blocks, the API returns 400 invalid_request_error. Two consequences:

Advisor state is sticky. Once a turn used the advisor, subsequent turns in that conversation must keep the tool in tools OR strip the advisor result blocks from history. There's no built-in conversation-level cap.
To enforce a client-side per-conversation budget, count advisor calls yourself. When you hit your ceiling, remove the advisor tool from tools and delete every advisor_tool_result block from message history in the same request.

There's also a resume-a-paused-turn dance worth naming so you don't cargo-cult around it: a response can end with stop_reason: "pause_turn" while an advisor call is still pending (the response contains the server_tool_use block but no advisor_tool_result yet). To resume, append that assistant message to messages unchanged, keeping the server_tool_use block, and re-send with the same advisor tool + beta header. No user message, no tool_result. The API runs the pending advisor call and continues the executor's turn. A resumed turn can pause again — just repeat.

Error codes you should ignore vs surface

The advisor sub-call failing does not fail the request. The executor sees the error and continues without further advice. The complete error table:

`error_code`	Meaning	Practical response
`max_uses_exceeded`	Hit the per-request `max_uses` cap	Expected — you configured it. Log at debug level.
`too_many_requests`	Advisor sub-inference rate-limited (from the same per-model bucket as direct calls)	Alert if it happens repeatedly — you're saturating your advisor-model rate limit
`overloaded`	Advisor sub-inference hit capacity	Retry the whole turn if quality matters; otherwise let it slide
`prompt_too_long`	Transcript exceeded the advisor's context window	Rare with 1M-context Opus 5 advisers; more likely with smaller-context adviser choices
`execution_time_exceeded`	Advisor sub-inference timed out	Cap `max_tokens` on the tool definition to reduce advisor generation length
`unavailable`	Anything else	Treat as transient

The critical asymmetry: a rate limit on the executor fails the whole request with HTTP 429. A rate limit on the advisor appears inside the tool result and the request still succeeds.

Claude Code: /advisor, --advisor, and advisorModel

The CLI exposes the advisor through three surfaces that all set the same setting:

Enable the advisor in Claude Code — three equivalent ways

# 1. Interactive picker or direct assignment (saves to your user settings)
/advisor
/advisor opus
/advisor sonnet
/advisor claude-opus-5   # full model ID also works

# 2. Persistent default in your settings file
# ~/.config/claude/settings.json (or equivalent)
{ "advisorModel": "opus" }

# 3. Per-session flag (overrides advisorModel for that launch, hidden from --help)
claude --advisor opus

# Turn off
/advisor off
# Or disable the tool entirely (all three surfaces become no-ops):
export CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1

The main-model / advisor pairing matrix in Claude Code is a subset of the API matrix — opus and sonnet are aliases that resolve to Claude Code's built-in default version and advance with releases. Notable rules:

Opus 4.7+ mains only accept Opus 4.7 or later as adviser — an Opus 4.7 main with an Opus 4.6 or Sonnet 5 advisor is rejected.
Sonnet 5 main rejects Sonnet 4.6 as advisor — but accepts Sonnet 5 (a "second Sonnet reads the first" for a cheap independent check).
Subagents inherit the configured advisor and apply the same pairing check against their own model.
Enabling or disabling the advisor mid-session does NOT invalidate the main model's prompt cache — unlike changing model or effort level, which does. This is why /advisor is safe to toggle mid-task.

Watch the transcript for an Advising line with the advisor model name while the call is in progress; press Ctrl+O to expand it and read the full guidance. Claude generally follows the advice but adapts when its own evidence contradicts a specific claim (a step fails when tried, file contents contradict the advice) — it surfaces the conflict rather than following unconditionally.

The two production prompt patterns Anthropic actually ships

The official docs include two system prompts Anthropic tested at scale. They're worth copying, because "advisor knows what to do" is not a default — the executor needs explicit guidance on when to call the advisor, and the advisor benefits from prompts written in the second person (it sees your system prompt as quoted context, so "you are..." lands more reliably than "the executor is...").

Suggested system prompt for coding tasks (Sonnet/Opus executor)

You have access to an advisor tool that consults a stronger model for
strategic guidance. Call it when the plan matters more than the code:

- Before committing to an approach on a non-trivial task.
- When stuck — errors recurring, approach not converging, results that
don't fit.
- Before declaring the task complete, to independently check the work.

Do NOT call it for routine turns where the next step is obvious. The
advisor sees the full transcript, so state the specific decision you
want reviewed in the turn where you invoke it.

For the Haiku executor, Anthropic ships a slightly nudged variant that encourages more advisor calls (Haiku under-consults by default):

Alternative system prompt for Haiku executors

You have access to an advisor tool. Consult it whenever a decision
requires judgment beyond mechanical execution:

- Before committing to a non-trivial approach.
- When stuck -- errors recurring, approach not converging, results that
don't fit.
- Before declaring the task complete.
- When the user's request contains ambiguity you cannot resolve from
context.

Bias toward calling the advisor rather than guessing. The cost of a
consult is small compared to the cost of a wrong direction on a long
task.

To trim advisor output length via prompting (an alternative or complement to max_tokens on the tool), Anthropic's tested placement is a line in the user message — not the system prompt — because the advisor sees both quoted, but user-message instructions addressing it directly are followed more reliably than third-person system prompts. Example: Advisor: keep guidance to 3-5 sentences.

To force a consult on a specific request, set tool_choice to {"type": "tool", "name": "advisor"}. One incompatibility: forced tool use cannot be combined with manual extended thinking (thinking: {type: "enabled"}) — the API returns 400 invalid_request_error if you enable both. Adaptive thinking supports forced tool use.

Where the advisor beats — and loses to — its alternatives

You have four ways to combine model strengths in Claude Code. Pick based on when you want the stronger model to run.

Approach	Stronger model runs	Started by
Advisor tool	At decision points, mid-task	Claude calls it when it needs guidance
opusplan	During plan mode, then switches to Sonnet for execution	You enter plan mode
Subagents with `model` set	For the entire delegated subtask	Claude delegates, or you invoke it
`/model` switch	For all subsequent turns	You switch models manually

The advisor is the only one that runs the strong model at Claude's discretion, on demand. opusplan is deterministic (plan mode entry) but scoped to planning. Subagents commit the strong model to a whole subtask. /model is the sledgehammer.

Platform availability (the one you'll trip on)

The advisor tool is available in beta on the Anthropic API and Claude Platform on AWS. It is not available on Amazon Bedrock, Google Cloud Vertex, or Microsoft Foundry as of August 2026. Through an LLM gateway configured with ANTHROPIC_BASE_URL, availability depends on whether the gateway forwards the request intact.

If you're multi-cloud and pass requests through Bedrock or Vertex to survive an Anthropic outage, the advisor is not part of that failover path today.

Check yourself

0/5

Your Sonnet 5 executor + Fable 5 advisor request returns a response with usage.output_tokens = 400. How much did the advisor generate?
You want a hard 2048-token ceiling on every advisor call. Where do you set max_tokens?
You configure claude-opus-4-7 as the executor and claude-sonnet-5 as the advisor. What happens?
Your Claude Fable 5 advisor returns content of type advisor_redacted_result with an encrypted_content field. What do you do on the next turn?
You want to remove the advisor tool from your `tools` array on a follow-up turn to enforce a client-side cost cap. What else must you do?

Press Enter or Space to flip the card. Use the left and right arrow keys to move between cards.Term shown.

1 / 9

Sources & further reading

Anthropic — Advisor tool (Claude API docs) — the primary source; field reference, pairing matrix, streaming behavior, and the Anthropic-tested prompts and truncation benchmarks quoted throughout this page
Anthropic — Escalate hard decisions with the advisor tool (Claude Code docs) — the CLI-specific surface: /advisor, advisorModel, --advisor, the Fable-5-disabled-as-advisor rollout, and the pairing subset
Anthropic — Server tools reference — the server_tool_use block shape and the "mixing server tools and client tools in one turn" behavior the advisor inherits
Anthropic — Prompt caching — cache semantics that apply to both the executor-side advisor_tool_result block and the advisor-side caching opt-in
Anthropic — Context editing — the clear_thinking default that silently kills advisor-side caching on older executors
AILmanac — Effort tuning: 5 levels, model defaults, and the cache trap — the sister feature that pairs with the advisor; both are per-model surface knobs that change token accounting
AILmanac — Choosing a model — the model tiers that determine which executor/advisor pairs are legal
Anthropic Blog — The advisor strategy — the "why a fast executor with a stronger advisor works" framing from Anthropic's blog

Why the advisor exists (and why it isn't just "call two APIs")​

Quick start — the minimum viable advisor request​

Sonnet 5 executor + Fable 5 advisor (Python)

The pairing rule (and the surprise about Fable 5)​

The token-accounting trap most integrators walk into​

Capping runaway advice — the max_tokens gotcha​

Cap advisor at 2048 tokens per call

The prompt-caching layer everyone misses​

The two result variants and why they're both fine​

Multi-turn: the invisible 400 you'll hit exactly once​

Error codes you should ignore vs surface​

Claude Code: /advisor, --advisor, and advisorModel​