Before: pick one — cheap or smart

In multi-step agent tasks (writing code, operating a computer, multi-step research), most turns are actually mechanical — only a handful of key moments genuinely need top-tier intelligence. But calling a model used to mean picking one of two roads, and neither one was great.

The collaborative mode sits in the middle ground between quality and cost: the vast majority of tokens come from the cheap executor model at its low rate, and only at the few moments that genuinely need brainpower does it spend a few hundred tokens asking the top-tier model for advice.

Midway through the work, place a call to the advisor

The advisor tool sits in the tools array just like any other tool — when to call it is up to the executor model itself. A complete call plays out in four steps.

In step one, the executor model emits a server_tool_use block named advisor, and its input is always empty: the executor model's only job is "deciding now is the moment to ask" — the server automatically fills in the actual context handed to the advisor. In step two, the server runs the advisor model separately on its own side. The advisor uses a system prompt that Anthropic provides for it, and it sees the executor model's full conversation history, including your system prompt, tool definitions, all prior turns and tool results, plus whatever text the executor model has written so far in this turn.

If the advisor hasn't finished answering: resuming from where it paused (pause_turn)

Sometimes the request ends early while the advisor call is still pending — the response comes back with a stop_reason: "pause_turn", containing only the server_tool_use block that initiated the call, with no matching result yet. When that happens, just append that assistant message back into messages as-is (keeping the server_tool_use block), and send another request with the same advisor tool and beta header. You don't need to add a new user message or supply a tool_result block.

Who can advise whom isn't arbitrary

The top-level model field is the executor model, and the model field inside the tool definition is the advisor model — the two must form a valid pairing. There's just one hard rule: the advisor must be Claude Sonnet 4.6 or stronger, and its capability must be at least on par with the executor model's. Get the pairing wrong and the API returns a 400 error naming that unsupported combination outright.

Dashed border = comparable capability, can advise each other (e.g. Opus 4.7 and Opus 4.8). The highlighted row, Sonnet 5, is a clear example: it can only pair with Opus 4.7 or Opus 4.8 — not even Opus 4.6 makes the list.

The logic behind this hard rule — "the advisor's capability must be ≥ the executor's" — is straightforward: if the advisor is weaker than the executor, it can't offer genuinely valuable advice, and the call is wasted. So Anthropic locked the pairings down with a compatibility table; a weaker advisor paired with a stronger executor simply can't be submitted.

Some models don't like asking the advisor on their own, so Anthropic built a "nudge"

Some executor models won't proactively ask the advisor in the first turn, especially lighter models like Claude Haiku 4.5. Anthropic's fix: if it doesn't call the advisor on turn one, insert a short reminder (a nudge) as a separate user message before turn two. But whether that nudge lands early or late changes the outcome significantly.

Anthropic's guidance is quite specific: first measure which turn your executor model typically first calls the advisor without any nudge (call it turn N), and set NUDGE_TURN higher than N. If your workload mixes simple and complex tasks, you can bump NUDGE_TURN up to 3, so simple tasks that would finish in two turns run their course without the nudge forcing an unnecessary consultation.

How the extra tab gets billed

An advisor call is billed as a separate sub-inference at the advisor model's own rate — it doesn't get folded into the executor model's usage totals. To break down exactly how much each segment cost, look at the usage.iterations array.

A typical advisor call outputs 400 to 700 text tokens, and counting the thinking spent before it's discarded, that's about 1,400 to 1,800 tokens total. That's exactly where the savings come from: the advisor isn't responsible for generating that big final chunk of output — the executor model handles that at the lower rate.

A few more details apply only to the executor model and don't automatically extend to the advisor: the top-level max_tokens only constrains the executor's output, not the advisor's sub-inference (to limit that separately, set max_tokens inside the tool definition); the advisor's tokens also don't draw from the executor's task budget; and Priority Tier commitments are counted separately too — unless your organization also has a commitment on the advisor model, advisor calls don't get priority treatment.

Save even more: caching works on the advisor side too

There are two independent layers of caching. On the executor side, the advisor_tool_result block can be cached just like any regular content block — nothing special to worry about there. The one that actually takes care is the advisor's own caching.

Each time the advisor model sees the conversation history, it's the previous one with a new chunk appended — so the prefix is stable. Turn on caching in the tool definition (something like {"type":"ephemeral","ttl":"5m"}), and each call writes a cache entry; the next call reads up to that point and only pays for the new addition. You'll see cache_read_input_tokens become non-zero starting from the second advisor_message iteration onward.

Anthropic also flags two consistency traps: first, once you set the caching switch, keep it consistent throughout — flipping it back and forth mid-conversation invalidates the cache outright; second, a misconfigured clear_thinking (where the keep value isn't "all") shifts the reference records the advisor sees on each turn, which also breaks advisor-side caching. This only worsens cost, though — it doesn't affect the quality of the advice.

What kind of work this suits, and what to leave alone

In its "When to use it" section, Anthropic draws the boundary clearly: this collaboration only pays off for mixed workloads where "most turns can be cheap, a few turns must be strong."

Anthropic states this up front: results vary by task, so evaluate on your own workloads. The tool is currently available in beta on the Claude API and on the Claude Platform on AWS; it doesn't yet support Amazon Bedrock, Google Cloud, or Microsoft Foundry, and it's compatible with Zero Data Retention (ZDR).

The Advisor tool splits "doing the work" from "giving advice": the executor model writes the whole answer, and only at the handful of key decisions does it temporarily bring in a stronger advisor model for a few hundred words of advice, then goes right back to writing. In code, that just means using a cheaper model at the top level and attaching an advisor:

So how does this "quick question" actually happen?

Take a concrete scenario: XiaoHu has the cheap executor model write a piece of concurrent code, and it gets stuck on the key decision of "how to gracefully shut down when the program exits." Instead of muscling through, it calls in the advisor mid-task, and the whole thing plays out in four steps within a single request.

There's a hard rule for who can advise whom: the advisor must be as strong as the executor model or stronger. Pair it with a weaker one and the API rejects it outright — a weaker advisor can't offer genuinely valuable advice.

So where does this collaboration actually save money, and how much? Anthropic gives two measured figures.