Repository Public
1---2title: Advisor tool3url: https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool4description: Pair a faster executor model with a higher-intelligence advisor model that provides strategic guidance mid-generation.5---67The advisor tool lets a faster, lower-cost **executor model** consult a higher-intelligence **advisor model** mid-generation for strategic guidance. The advisor reads the full conversation, produces a plan or course correction, and the executor continues with the task.89This pattern fits long-horizon agentic workloads (coding agents, computer use, multistep research pipelines) where most turns are mechanical but having an excellent plan is crucial. You get close to advisor-solo quality while the bulk of token generation happens at executor-model rates. For measured results, including how the benefit shrinks as the executor's own capability approaches the advisor's, see [Optimizing for cost and intelligence](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence).1011```mermaid12sequenceDiagram13 participant U as Your application14 participant E as Executor model15 participant A as Advisor model1617 U->>E: Request with advisor tool18 note over E: Executor begins the task19 E->>A: server_tool_use (server-side)20 note over A: Reads the full transcript,<br/>returns strategic guidance21 A-->>E: advisor_tool_result22 note over E: Executor continues,<br/>informed by the advice23 E-->>U: Response24```2526<Note>27 To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).28</Note>2930## When to use it3132The advisor fits these configurations:3334* **You currently use Sonnet on complex tasks:** Add a higher-tier advisor. Opus keeps total cost similar or lower; Claude Fable 5.1 maximizes the quality lift.35* **You currently use Haiku and want a step up in intelligence:** Add an Opus or Fable advisor. Expect higher cost than Haiku alone, but lower than switching the executor to a larger model.3637Results are task-dependent. Evaluate on your own workload.3839The advisor is a weaker fit for single-turn Q\&A (nothing to plan), pure pass-through model pickers where your users already choose their own cost and quality tradeoff, or workloads where every turn genuinely requires the advisor model's full capability.4041## Quick start4243<Note>44 The advisor tool is in beta. Include the beta header `advisor-tool-2026-03-01` in your requests.45</Note>4647<CodeGroup>48 ```bash cURL49 curl https://api.anthropic.com/v1/messages \50 -H "x-api-key: $ANTHROPIC_API_KEY" \51 -H "anthropic-version: 2023-06-01" \52 -H "anthropic-beta: advisor-tool-2026-03-01" \53 -H "content-type: application/json" \54 -d '{55 "model": "claude-sonnet-5",56 "max_tokens": 4096,57 "tools": [58 {59 "type": "advisor_20260301",60 "name": "advisor",61 "model": "claude-opus-5"62 }63 ],64 "messages": [{65 "role": "user",66 "content": "Build a concurrent worker pool in Go with graceful shutdown."67 }]68 }'69 ```7071 ```bash CLI72 ant beta:messages create --beta advisor-tool-2026-03-01 <<'YAML'73 model: claude-sonnet-574 max_tokens: 409675 tools:76 - type: advisor_2026030177 name: advisor78 model: claude-opus-579 messages:80 - role: user81 content: Build a concurrent worker pool in Go with graceful shutdown.82 YAML83 ```8485 ```python Python86 client = anthropic.Anthropic()8788 response = client.beta.messages.create(89 model="claude-sonnet-5",90 max_tokens=4096,91 betas=["advisor-tool-2026-03-01"],92 tools=[93 {94 "type": "advisor_20260301",95 "name": "advisor",96 "model": "claude-opus-5",97 }98 ],99 messages=[100 {101 "role": "user",102 "content": "Build a concurrent worker pool in Go with graceful shutdown.",103 }104 ],105 )106107 print(response)108 ```109110 ```typescript TypeScript111 const client = new Anthropic();112113 const response = await client.beta.messages.create({114 model: "claude-sonnet-5",115 max_tokens: 4096,116 betas: ["advisor-tool-2026-03-01"],117 tools: [118 {119 type: "advisor_20260301",120 name: "advisor",121 model: "claude-opus-5"122 }123 ],124 messages: [125 {126 role: "user",127 content: "Build a concurrent worker pool in Go with graceful shutdown."128 }129 ]130 });131132 console.log(response);133 ```134135 ```csharp C#136 using Anthropic.Models.Beta.Messages;137 using Messages = Anthropic.Models.Messages;138139 var client = new AnthropicClient();140141 var parameters = new MessageCreateParams142 {143 Model = Messages::Model.ClaudeSonnet5,144 MaxTokens = 4096,145 Tools = new BetaToolUnion[]146 {147 new BetaAdvisorTool20260301148 {149 Model = Messages::Model.ClaudeOpus5150 }151 },152 Messages =153 [154 new BetaMessageParam155 {156 Role = Role.User,157 Content = "Build a concurrent worker pool in Go with graceful shutdown."158 }159 ],160 Betas = ["advisor-tool-2026-03-01"]161 };162163 var response = await client.Beta.Messages.Create(parameters);164 Console.WriteLine(response);165 ```166167 ```go Go168 client := anthropic.NewClient()169170 response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{171 Model: anthropic.ModelClaudeSonnet5,172 MaxTokens: 4096,173 Tools: []anthropic.BetaToolUnionParam{174 {OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{175 Model: anthropic.ModelClaudeOpus5,176 }},177 },178 Messages: []anthropic.BetaMessageParam{179 anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Build a concurrent worker pool in Go with graceful shutdown.")),180 },181 Betas: []anthropic.AnthropicBeta{182 anthropic.AnthropicBetaAdvisorTool2026_03_01,183 },184 })185 if err != nil {186 log.Fatal(err)187 }188 fmt.Println(response)189 ```190191 ```java Java192 import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;193 import com.anthropic.models.beta.messages.BetaMessage;194 import com.anthropic.models.beta.messages.MessageCreateParams;195 import com.anthropic.models.messages.Model;196197 void main() {198 AnthropicClient client = AnthropicOkHttpClient.fromEnv();199200 MessageCreateParams params = MessageCreateParams.builder()201 .model(Model.CLAUDE_SONNET_5)202 .maxTokens(4096L)203 .addTool(BetaAdvisorTool20260301.builder()204 .model(Model.CLAUDE_OPUS_5)205 .build())206 .addUserMessage("Build a concurrent worker pool in Go with graceful shutdown.")207 .addBeta("advisor-tool-2026-03-01")208 .build();209210 BetaMessage response = client.beta().messages().create(params);211 IO.println(response);212 }213 ```214215 ```php PHP216 $client = new Client();217218 $response = $client->beta->messages->create(219 maxTokens: 4096,220 messages: [221 [222 'role' => 'user',223 'content' => 'Build a concurrent worker pool in Go with graceful shutdown.',224 ],225 ],226 model: 'claude-sonnet-5',227 tools: [228 [229 'type' => 'advisor_20260301',230 'name' => 'advisor',231 'model' => 'claude-opus-5',232 ],233 ],234 betas: ['advisor-tool-2026-03-01'],235 );236237 echo $response;238 ```239240 ```ruby Ruby241 client = Anthropic::Client.new242243 response = client.beta.messages.create(244 model: "claude-sonnet-5",245 max_tokens: 4096,246 tools: [247 {248 type: "advisor_20260301",249 name: "advisor",250 model: "claude-opus-5"251 }252 ],253 messages: [254 {255 role: "user",256 content: "Build a concurrent worker pool in Go with graceful shutdown."257 }258 ],259 betas: ["advisor-tool-2026-03-01"]260 )261262 puts response263 ```264</CodeGroup>265266The response `content` includes an `advisor_tool_result` block carrying the advisor's guidance. With `claude-opus-5` as the advisor, as in this quick start, the block's `content` field is an `advisor_redacted_result` variant (encrypted; the executor reads it server-side, but your client does not). To see the advice text directly in your response, use `claude-opus-4-8` as the advisor model instead, which returns the plaintext `advisor_result` variant. See [Result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants) for both shapes side by side and which advisor models return which, and [Model compatibility](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#model-compatibility) for the full list of valid pairs.267268## How it works269270When you add the advisor tool to your `tools` array, the executor model determines when to call it, like any other tool. When the executor calls the advisor:2712721. The executor emits a [`server_tool_use`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools) block with `name: "advisor"` and an empty `input`. The executor signals timing, and the server supplies context.2732. 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 in its input. That transcript includes your system prompt, the tool definitions, the prior turns and tool results, and the text the executor has produced so far in this turn.2743. The advisor's response returns to the executor as an `advisor_tool_result` block.2754. The executor continues generating, informed by the advice.276277All of this occurs inside a single `/v1/messages` request, with no extra round trips on your side. The exception is a turn that pauses mid-call, which you resume with a follow-up request (see [Resuming a paused turn](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#resuming-a-paused-turn)).278279The advisor itself runs without tools and without context management. Its thinking blocks are dropped before the result returns. Only the advice text reaches the executor.280281## Tool parameters282283| Parameter | Type | Default | Description |284| ------------ | -------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |285| `type` | string | *required* | Must be `"advisor_20260301"`. |286| `name` | string | *required* | Must be `"advisor"`. |287| `model` | string | *required* | The advisor model ID, such as claude-opus-5. Billed at this model's rates for the sub-inference. |288| `max_uses` | integer | unlimited | Maximum number of advisor calls allowed in a single request. Once the executor reaches this cap, further advisor calls return an `advisor_tool_result_error` with `error_code: "max_uses_exceeded"` and the executor continues without further advice. This is a per-request cap, not a per-conversation cap. See [Cost control](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#cost-control) for conversation-level limits. |289| `max_tokens` | integer | advisor model's output cap | Caps the advisor's total output (thinking plus text) per call. Minimum 1024. See [Capping advisor output](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#capping-advisor-output). |290| `caching` | object \| null | `null` (off) | Enables [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for the advisor's own transcript across calls within a conversation. See [Advisor prompt caching](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#advisor-prompt-caching). |291292The `caching` object has the shape `{"type": "ephemeral", "ttl": "5m" | "1h"}`. Unlike `cache_control` on content blocks, this is not a breakpoint marker. It is an on/off switch. The server determines where cache boundaries go.293294The advisor tool also accepts the generic properties available on any tool definition: `cache_control`, `allowed_callers`, `defer_loading`, and `strict` (covered in [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)). See the [Tool reference](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference#tool-definition-properties) for their semantics.295296## Response structure297298### Successful advisor call299300When the advisor is called, a `server_tool_use` block is followed by an `advisor_tool_result` block in the assistant's content. The following example shows the plaintext `advisor_result` variant returned by a Claude Opus 4.8 advisor. The [Quick start](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#quick-start) uses Claude Opus 5, which returns the encrypted `advisor_redacted_result` variant instead; see [Result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants) for both shapes side by side.301302```json303{304 "role": "assistant",305 "content": [306 {307 "type": "text",308 "text": "Let me consult the advisor on this."309 },310 {311 "type": "server_tool_use",312 "id": "srvtoolu_abc123",313 "name": "advisor",314 "input": {}315 },316 {317 "type": "advisor_tool_result",318 "tool_use_id": "srvtoolu_abc123",319 "content": {320 "type": "advisor_result",321 "text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."322 }323 },324 {325 "type": "text",326 "text": "Here's the implementation. I'm using a channel-based coordination pattern to avoid writer starvation..."327 }328 ]329}330```331332The `server_tool_use.input` is always empty. The server constructs the advisor's view from the full transcript automatically. Nothing the executor puts in `input` reaches the advisor.333334### Result variants335336The `advisor_tool_result.content` field is a discriminated union. For successful calls, the variant depends on the advisor model:337338| Variant | Fields | Returned when |339| ------------------------- | ---------------------------------- | ------------------------------------------------------------------- |340| `advisor_result` | `text`, `stop_reason` | The advisor model returns plaintext (for example, Claude Opus 4.8). |341| `advisor_redacted_result` | `encrypted_content`, `stop_reason` | The advisor model returns encrypted output. |342343<Note>344 Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5, Claude Fable 5, and Claude Mythos 5 advisors return the encrypted `advisor_redacted_result`. Every other advisor model in the [compatibility table](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#model-compatibility) returns the plaintext `advisor_result`. To read the advice text in your own responses, use an advisor that returns plaintext, such as `claude-opus-4-8`, where your executor's row in the [compatibility table](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#model-compatibility) lists one. Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5, Claude Fable 5, and Claude Mythos 5 executors pair only with advisors that return the encrypted form, so on those executors the advice text isn't readable in the response.345</Note>346347Here is the same request sent twice, identical except for the advisor `model` in the tool definition, showing both variants.348349With `"model": "claude-opus-4-8"`, the advice is plaintext:350351```json352{353 "type": "advisor_tool_result",354 "tool_use_id": "srvtoolu_abc123",355 "content": {356 "type": "advisor_result",357 "text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."358 }359}360```361362With `"model": "claude-opus-5"`, the advice is encrypted:363364```json365{366 "type": "advisor_tool_result",367 "tool_use_id": "srvtoolu_abc123",368 "content": {369 "type": "advisor_redacted_result",370 "encrypted_content": "EqQBCkYIBRgCIiQ5ZjE0N2M2OC0yYWIxLTRkZTktYjA3ZC1hZTUyMzkxYjhkMmU..."371 }372}373```374375Both result variants carry a `stop_reason` field when you set [`max_tokens`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#capping-advisor-output) on the tool definition, and omit it when you do not. It holds the advisor sub-call's stop reason, typically `"end_turn"`, or `"max_tokens"` when the cap is hit. The values match the top-level Messages API [`stop_reason`](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons).376377With `advisor_result`, the `text` field contains human-readable advice. With `advisor_redacted_result`, the `encrypted_content` field contains an opaque blob that you cannot read. On the next turn, the server decrypts it and renders the plaintext into the executor's prompt.378379In both cases, round-trip the content verbatim on subsequent turns. If you switch advisor models mid-conversation, branch on `content.type` to handle both shapes.380381### Error results382383If the advisor call fails, the result carries an error:384385```json386{387 "type": "advisor_tool_result",388 "tool_use_id": "srvtoolu_abc123",389 "content": {390 "type": "advisor_tool_result_error",391 "error_code": "overloaded"392 }393}394```395396The executor sees the error and continues without further advice. The request itself does not fail.397398| `error_code` | Meaning |399| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |400| `max_uses_exceeded` | The request reached the `max_uses` cap set on the tool definition. Further advisor calls in the same request return this error. |401| `too_many_requests` | The advisor sub-inference was rate-limited. |402| `overloaded` | The advisor sub-inference hit capacity limits. |403| `prompt_too_long` | The transcript exceeded the advisor model's context window. |404| `execution_time_exceeded` | The advisor sub-inference timed out. |405| `model_not_found` | The configured advisor model is not available. |406| `unavailable` | Any other advisor failure. |407408Advisor rate limits draw from the same per-model bucket as direct calls to the advisor model. A rate limit on the advisor appears as `too_many_requests` inside the tool result. A rate limit on the executor fails the whole request with HTTP 429.409410## Multi-turn conversations411412Pass the full assistant content, including `advisor_tool_result` blocks, back to the API on subsequent turns. Round-trip the result blocks verbatim: with a Claude Opus 5 advisor the result block's `content` is the encrypted `advisor_redacted_result` variant, and the server decrypts it and renders the advice into the executor's prompt on the next turn (see [Result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants)). The mechanics are identical for any advisor model.413414<CodeGroup exclude="shell">415 ```python Python416 client = anthropic.Anthropic()417418 tools = [419 {420 "type": "advisor_20260301",421 "name": "advisor",422 "model": "claude-opus-5",423 }424 ]425426 messages = [427 {428 "role": "user",429 "content": "Build a concurrent worker pool in Go with graceful shutdown.",430 }431 ]432433 response = client.beta.messages.create(434 model="claude-sonnet-5",435 max_tokens=1024,436 betas=["advisor-tool-2026-03-01"],437 tools=tools,438 messages=messages,439 )440441 # Append the full response content, including any advisor_tool_result blocks442 messages.append({"role": "assistant", "content": response.content})443444 # Continue the conversation445 messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})446447 response = client.beta.messages.create(448 model="claude-sonnet-5",449 max_tokens=1024,450 betas=["advisor-tool-2026-03-01"],451 tools=tools,452 messages=messages,453 )454 ```455456 ```typescript TypeScript457 const client = new Anthropic();458459 const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [460 {461 type: "advisor_20260301",462 name: "advisor",463 model: "claude-opus-5"464 }465 ];466467 const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [468 {469 role: "user",470 content: "Build a concurrent worker pool in Go with graceful shutdown."471 }472 ];473474 const response = await client.beta.messages.create({475 model: "claude-sonnet-5",476 max_tokens: 1024,477 betas: ["advisor-tool-2026-03-01"],478 tools,479 messages480 });481482 // Append the full response content, including any advisor_tool_result blocks483 messages.push({ role: "assistant", content: response.content });484485 // Continue the conversation486 messages.push({ role: "user", content: "Now add a max-in-flight limit of 10." });487488 const followUp = await client.beta.messages.create({489 model: "claude-sonnet-5",490 max_tokens: 1024,491 betas: ["advisor-tool-2026-03-01"],492 tools,493 messages494 });495 ```496497 ```csharp C#498 using Anthropic.Models.Beta.Messages;499 using Messages = Anthropic.Models.Messages;500501 var client = new AnthropicClient();502503 var tools = new BetaToolUnion[]504 {505 new BetaAdvisorTool20260301 { Model = Messages::Model.ClaudeOpus5 }506 };507508 var messages = new List<BetaMessageParam>509 {510 new() { Role = Role.User, Content = "Build a concurrent worker pool in Go with graceful shutdown." }511 };512513 var response = await client.Beta.Messages.Create(new MessageCreateParams514 {515 Model = Messages::Model.ClaudeSonnet5,516 MaxTokens = 1024,517 Tools = tools,518 Messages = messages,519 Betas = ["advisor-tool-2026-03-01"]520 });521522 // Append the full response content, including any advisor_tool_result blocks523 messages.Add(new BetaMessageParam524 {525 Role = Role.Assistant,526 Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList()527 });528529 // Continue the conversation530 messages.Add(new BetaMessageParam { Role = Role.User, Content = "Now add a max-in-flight limit of 10." });531532 var followUp = await client.Beta.Messages.Create(new MessageCreateParams533 {534 Model = Messages::Model.ClaudeSonnet5,535 MaxTokens = 1024,536 Tools = tools,537 Messages = messages,538 Betas = ["advisor-tool-2026-03-01"]539 });540 ```541542 ```go Go543 client := anthropic.NewClient()544545 tools := []anthropic.BetaToolUnionParam{546 {OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{547 Model: anthropic.ModelClaudeOpus5,548 }},549 }550551 messages := []anthropic.BetaMessageParam{552 anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Build a concurrent worker pool in Go with graceful shutdown.")),553 }554555 response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{556 Model: anthropic.ModelClaudeSonnet5,557 MaxTokens: 1024,558 Tools: tools,559 Messages: messages,560 Betas: []anthropic.AnthropicBeta{561 anthropic.AnthropicBetaAdvisorTool2026_03_01,562 },563 })564 if err != nil {565 log.Fatal(err)566 }567568 // Append the full response content, including any advisor_tool_result blocks.569 messages = append(messages, response.ToParam())570571 // Continue the conversation572 messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Now add a max-in-flight limit of 10.")))573574 response, err = client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{575 Model: anthropic.ModelClaudeSonnet5,576 MaxTokens: 1024,577 Tools: tools,578 Messages: messages,579 Betas: []anthropic.AnthropicBeta{580 anthropic.AnthropicBetaAdvisorTool2026_03_01,581 },582 })583 if err != nil {584 log.Fatal(err)585 }586 ```587588 ```java Java589 import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;590 import com.anthropic.models.beta.messages.BetaContentBlock;591 import com.anthropic.models.beta.messages.BetaMessage;592 import com.anthropic.models.beta.messages.BetaMessageParam;593 import com.anthropic.models.beta.messages.BetaToolUnion;594 import com.anthropic.models.beta.messages.MessageCreateParams;595 import com.anthropic.models.messages.Model;596597 void main() {598 AnthropicClient client = AnthropicOkHttpClient.fromEnv();599600 List<BetaToolUnion> tools = List.of(601 BetaToolUnion.ofAdvisorTool20260301(602 BetaAdvisorTool20260301.builder().model(Model.CLAUDE_OPUS_5).build()));603604 List<BetaMessageParam> messages = new ArrayList<>();605 messages.add(BetaMessageParam.builder()606 .role(BetaMessageParam.Role.USER)607 .content("Build a concurrent worker pool in Go with graceful shutdown.")608 .build());609610 BetaMessage response = client.beta().messages().create(MessageCreateParams.builder()611 .model(Model.CLAUDE_SONNET_5)612 .maxTokens(1024L)613 .tools(tools)614 .messages(messages)615 .addBeta("advisor-tool-2026-03-01")616 .build());617618 // Append the full response content, including any advisor_tool_result blocks619 messages.add(BetaMessageParam.builder()620 .role(BetaMessageParam.Role.ASSISTANT)621 .contentOfBetaContentBlockParams(622 response.content().stream().map(BetaContentBlock::toParam).toList())623 .build());624625 // Continue the conversation626 messages.add(BetaMessageParam.builder()627 .role(BetaMessageParam.Role.USER)628 .content("Now add a max-in-flight limit of 10.")629 .build());630631 BetaMessage followUp = client.beta().messages().create(MessageCreateParams.builder()632 .model(Model.CLAUDE_SONNET_5)633 .maxTokens(1024L)634 .tools(tools)635 .messages(messages)636 .addBeta("advisor-tool-2026-03-01")637 .build());638 }639 ```640641 ```php PHP642 $client = new Client();643644 $tools = [645 [646 'type' => 'advisor_20260301',647 'name' => 'advisor',648 'model' => 'claude-opus-5',649 ],650 ];651652 $messages = [653 [654 'role' => 'user',655 'content' => 'Build a concurrent worker pool in Go with graceful shutdown.',656 ],657 ];658659 $response = $client->beta->messages->create(660 maxTokens: 1024,661 messages: $messages,662 model: 'claude-sonnet-5',663 tools: $tools,664 betas: ['advisor-tool-2026-03-01'],665 );666667 // Append the full response content, including any advisor_tool_result blocks668 $messages[] = ['role' => 'assistant', 'content' => $response->content];669670 // Continue the conversation671 $messages[] = ['role' => 'user', 'content' => 'Now add a max-in-flight limit of 10.'];672673 $response = $client->beta->messages->create(674 maxTokens: 1024,675 messages: $messages,676 model: 'claude-sonnet-5',677 tools: $tools,678 betas: ['advisor-tool-2026-03-01'],679 );680 ```681682 ```ruby Ruby683 client = Anthropic::Client.new684685 tools = [686 {687 type: "advisor_20260301",688 name: "advisor",689 model: "claude-opus-5"690 }691 ]692693 messages = [694 {695 role: "user",696 content: "Build a concurrent worker pool in Go with graceful shutdown."697 }698 ]699700 response = client.beta.messages.create(701 model: "claude-sonnet-5",702 max_tokens: 1024,703 tools: tools,704 messages: messages,705 betas: ["advisor-tool-2026-03-01"]706 )707708 # Append the full response content, including any advisor_tool_result blocks709 messages << { role: "assistant", content: response.content }710711 # Continue the conversation712 messages << { role: "user", content: "Now add a max-in-flight limit of 10." }713714 response = client.beta.messages.create(715 model: "claude-sonnet-5",716 max_tokens: 1024,717 tools: tools,718 messages: messages,719 betas: ["advisor-tool-2026-03-01"]720 )721 ```722</CodeGroup>723724You can drop the advisor tool from `tools` on a follow-up turn while the message history still contains `advisor_tool_result` blocks. The request is accepted and the historical blocks are preserved; the model cannot call the advisor on that turn. You must still send the `advisor-tool-2026-03-01` beta header for those history blocks to be accepted.725726<Note>727 The advisor tool has no built-in conversation-level cap. To limit advisor calls across a conversation, count them client-side. When you reach your ceiling, remove the advisor tool from your `tools` array. You do not need to strip `advisor_tool_result` blocks from your message history.728</Note>729730### Resuming a paused turn731732A response can end with `stop_reason: "pause_turn"` while an advisor call is still pending. When that occurs, the response contains the advisor's `server_tool_use` block with no `advisor_tool_result` for it. To resume, append that assistant message to `messages` with its content unchanged, keeping the `server_tool_use` block, and send the request again with the same advisor tool and beta header. You do not need to add a user message or a `tool_result` block. The API runs the pending advisor call and continues the executor's turn in the new response. A resumed turn can pause again. If it does, repeat the same step. Omitting the advisor tool from the resume request returns a 400 `invalid_request_error`, because the pending `server_tool_use` block has no tool definition to run against; include the tool whenever a call is pending. If instead the executor called one of your tools in the same turn, the response ends with `stop_reason: "tool_use"` while the advisor call is still pending. Send the `tool_result` blocks as usual, and the pending advisor call runs at the start of that next request. See [Mixing server tools and client tools in one turn](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn).733734### Mid-conversation nudge for under-calling executors735736If a Haiku executor has not called the advisor in its first assistant turn, append a short reminder as an additional user message before the second assistant turn. In Anthropic's internal behavioral evaluation this raised task pass rates by roughly 7 percentage points on Haiku executors. On Sonnet executors, the plain-text nudge had no measurable effect in Anthropic's testing. The call-timing considerations that follow are especially relevant for Sonnet. Do not apply the nudge to Opus executors: On Opus it slightly lowered pass rates.737738With the default `NUDGE_TURN` of 2, the reminder typically arrives after the model has oriented on the task but before it has committed to an approach.739740<CodeGroup exclude="shell">741 ```python Python742 client = anthropic.Anthropic()743744 NUDGE_TURN = 2 # inject before this assistant turn if no advisor call yet745 NUDGE_TEXT = (746 "You have not consulted the advisor yet. If the task has a non-obvious "747 "design decision or a failure mode you haven't ruled out, call advisor "748 "now before committing to an approach."749 )750 MAX_TURNS = 10 # agent loop cap751752753 def run_your_tools(content):754 # Replace with your tool dispatch. Returns one tool_result block per tool_use block.755 return [756 {757 "type": "tool_result",758 "tool_use_id": block.id,759 "content": "Replace with your tool output.",760 }761 for block in content762 if block.type == "tool_use"763 ]764765766 tools = [767 {"type": "advisor_20260301", "name": "advisor", "model": "claude-opus-5"},768 # ... your other tools769 ]770 task = "Build a concurrent worker pool in Go with graceful shutdown."771 messages = [{"role": "user", "content": task}]772 advisor_called = False773774 for turn in range(1, MAX_TURNS + 1):775 response = client.beta.messages.create(776 model="claude-haiku-4-5",777 max_tokens=4096,778 betas=["advisor-tool-2026-03-01"],779 tools=tools,780 messages=messages,781 )782 messages.append({"role": "assistant", "content": response.content})783 advisor_called = advisor_called or any(784 block.type == "server_tool_use" and block.name == "advisor"785 for block in response.content786 )787 if response.stop_reason == "end_turn":788 break789 if response.stop_reason == "pause_turn":790 continue # server tool pending; re-send to let the API complete it791792 results = run_your_tools(response.content) # list of tool_result blocks793 if results:794 messages.append({"role": "user", "content": results})795 # Skip this if your system prompt already tells the model to call sparingly.796 if turn == NUDGE_TURN - 1 and not advisor_called:797 messages.append({"role": "user", "content": NUDGE_TEXT})798 ```799800 ```typescript TypeScript801 const client = new Anthropic();802803 const NUDGE_TURN = 2; // inject before this assistant turn if no advisor call yet804 const NUDGE_TEXT =805 "You have not consulted the advisor yet. If the task has a non-obvious " +806 "design decision or a failure mode you haven't ruled out, call advisor " +807 "now before committing to an approach.";808 const MAX_TURNS = 10; // agent loop cap809810 function runYourTools(811 content: Anthropic.Beta.Messages.BetaContentBlock[]812 ): Anthropic.Beta.Messages.BetaToolResultBlockParam[] {813 // Replace with your tool dispatch. Returns one tool_result block per tool_use block.814 return content815 .filter((block) => block.type === "tool_use")816 .map((block) => ({817 type: "tool_result" as const,818 tool_use_id: block.id,819 content: "Replace with your tool output."820 }));821 }822823 const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [824 { type: "advisor_20260301", name: "advisor", model: "claude-opus-5" }825 // ... your other tools826 ];827 const task = "Build a concurrent worker pool in Go with graceful shutdown.";828 const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [{ role: "user", content: task }];829 let advisorCalled = false;830831 for (let turn = 1; turn <= MAX_TURNS; turn++) {832 const response = await client.beta.messages.create({833 model: "claude-haiku-4-5",834 max_tokens: 4096,835 betas: ["advisor-tool-2026-03-01"],836 tools,837 messages838 });839 messages.push({ role: "assistant", content: response.content });840 advisorCalled =841 advisorCalled ||842 response.content.some(843 (block) => block.type === "server_tool_use" && block.name === "advisor"844 );845 if (response.stop_reason === "end_turn") {846 break;847 }848 if (response.stop_reason === "pause_turn") {849 continue; // server tool pending; re-send to let the API complete it850 }851852 const results = runYourTools(response.content); // list of tool_result blocks853 if (results.length > 0) {854 messages.push({ role: "user", content: results });855 }856 // Skip this if your system prompt already tells the model to call sparingly.857 if (turn === NUDGE_TURN - 1 && !advisorCalled) {858 messages.push({ role: "user", content: NUDGE_TEXT });859 }860 }861 ```862863 ```csharp C#864 using Anthropic.Models.Beta.Messages;865 using Messages = Anthropic.Models.Messages;866867 var client = new AnthropicClient();868869 const int NudgeTurn = 2; // inject before this assistant turn if no advisor call yet870 const string NudgeText =871 "You have not consulted the advisor yet. If the task has a non-obvious "872 + "design decision or a failure mode you haven't ruled out, call advisor "873 + "now before committing to an approach.";874 const int MaxTurns = 10; // agent loop cap875876 // Replace with your tool dispatch. Returns one tool_result block per tool_use block.877 List<BetaContentBlockParam> RunYourTools(IReadOnlyList<BetaContentBlock> content)878 {879 List<BetaContentBlockParam> results = [];880 foreach (var block in content)881 {882 if (block.TryPickToolUse(out var toolUse))883 {884 results.Add(new BetaToolResultBlockParam885 {886 ToolUseID = toolUse.ID,887 Content = "Replace with your tool output."888 });889 }890 }891 return results;892 }893894 var tools = new BetaToolUnion[]895 {896 new BetaAdvisorTool20260301 { Model = Messages::Model.ClaudeOpus5 }897 // ... your other tools898 };899 var task = "Build a concurrent worker pool in Go with graceful shutdown.";900 var messages = new List<BetaMessageParam> { new() { Role = Role.User, Content = task } };901 var advisorCalled = false;902903 for (var turn = 1; turn <= MaxTurns; turn++)904 {905 var response = await client.Beta.Messages.Create(new MessageCreateParams906 {907 Model = Messages::Model.ClaudeHaiku4_5,908 MaxTokens = 4096,909 Tools = tools,910 Messages = messages,911 Betas = ["advisor-tool-2026-03-01"]912 });913 messages.Add(new BetaMessageParam914 {915 Role = Role.Assistant,916 Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList()917 });918 advisorCalled =919 advisorCalled920 || response.Content.Any(block =>921 block.TryPickServerToolUse(out var serverToolUse)922 && serverToolUse.Name.Value() == Name.Advisor923 );924 if (response.StopReason == BetaStopReason.EndTurn)925 {926 break;927 }928 if (response.StopReason == BetaStopReason.PauseTurn)929 {930 continue; // server tool pending; re-send to let the API complete it931 }932933 var results = RunYourTools(response.Content); // list of tool_result blocks934 if (results.Count > 0)935 {936 messages.Add(new BetaMessageParam { Role = Role.User, Content = results });937 }938 // Skip this if your system prompt already tells the model to call sparingly.939 if (turn == NudgeTurn - 1 && !advisorCalled)940 {941 messages.Add(new BetaMessageParam { Role = Role.User, Content = NudgeText });942 }943 }944 ```945946 ```go Go947 const (948 nudgeTurn = 2 // inject before this assistant turn if no advisor call yet949 nudgeText = "You have not consulted the advisor yet. If the task has a non-obvious " +950 "design decision or a failure mode you haven't ruled out, call advisor " +951 "now before committing to an approach."952 maxTurns = 10 // agent loop cap953 )954955 // Replace with your tool dispatch. Returns one tool_result block per tool_use block.956 func runYourTools(content []anthropic.BetaContentBlockUnion) []anthropic.BetaContentBlockParamUnion {957 var results []anthropic.BetaContentBlockParamUnion958 for _, block := range content {959 if block.Type == "tool_use" {960 results = append(results, anthropic.NewBetaToolResultBlock(block.ID, "Replace with your tool output.", false))961 }962 }963 return results964 }965966 func main() {967 client := anthropic.NewClient()968969 tools := []anthropic.BetaToolUnionParam{970 {OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{971 Model: anthropic.ModelClaudeOpus5,972 }},973 // ... your other tools974 }975 task := "Build a concurrent worker pool in Go with graceful shutdown."976 messages := []anthropic.BetaMessageParam{977 anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(task)),978 }979 advisorCalled := false980981 for turn := 1; turn <= maxTurns; turn++ {982 response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{983 Model: anthropic.ModelClaudeHaiku4_5,984 MaxTokens: 4096,985 Tools: tools,986 Messages: messages,987 Betas: []anthropic.AnthropicBeta{988 anthropic.AnthropicBetaAdvisorTool2026_03_01,989 },990 })991 if err != nil {992 log.Fatal(err)993 }994995 messages = append(messages, response.ToParam())996997 for _, block := range response.Content {998 if block.Type == "server_tool_use" && block.Name == "advisor" {999 advisorCalled = true1000 }1001 }1002 if response.StopReason == anthropic.BetaStopReasonEndTurn {1003 break1004 }1005 if response.StopReason == anthropic.BetaStopReasonPauseTurn {1006 continue // server tool pending; re-send to let the API complete it1007 }10081009 results := runYourTools(response.Content) // list of tool_result blocks1010 if len(results) > 0 {1011 messages = append(messages, anthropic.BetaMessageParam{1012 Role: anthropic.BetaMessageParamRoleUser,1013 Content: results,1014 })1015 }1016 // Skip this if your system prompt already tells the model to call sparingly.1017 if turn == nudgeTurn-1 && !advisorCalled {1018 messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(nudgeText)))1019 }1020 }1021 }1022 ```10231024 ```java Java1025 import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;1026 import com.anthropic.models.beta.messages.BetaContentBlock;1027 import com.anthropic.models.beta.messages.BetaContentBlockParam;1028 import com.anthropic.models.beta.messages.BetaMessage;1029 import com.anthropic.models.beta.messages.BetaMessageParam;1030 import com.anthropic.models.beta.messages.BetaServerToolUseBlock;1031 import com.anthropic.models.beta.messages.BetaStopReason;1032 import com.anthropic.models.beta.messages.BetaToolResultBlockParam;1033 import com.anthropic.models.beta.messages.BetaToolUnion;1034 import com.anthropic.models.beta.messages.MessageCreateParams;1035 import com.anthropic.models.messages.Model;10361037 static final int NUDGE_TURN = 2; // inject before this assistant turn if no advisor call yet1038 static final String NUDGE_TEXT =1039 "You have not consulted the advisor yet. If the task has a non-obvious "1040 + "design decision or a failure mode you haven't ruled out, call advisor "1041 + "now before committing to an approach.";1042 static final int MAX_TURNS = 10; // agent loop cap10431044 // Replace with your tool dispatch. Returns one tool_result block per tool_use block.1045 List<BetaContentBlockParam> runYourTools(List<BetaContentBlock> content) {1046 List<BetaContentBlockParam> results = new ArrayList<>();1047 for (BetaContentBlock block : content) {1048 if (block.isToolUse()) {1049 results.add(BetaContentBlockParam.ofToolResult(1050 BetaToolResultBlockParam.builder()1051 .toolUseId(block.asToolUse().id())1052 .content("Replace with your tool output.")1053 .build()));1054 }1055 }1056 return results;1057 }10581059 void main() {1060 AnthropicClient client = AnthropicOkHttpClient.fromEnv();10611062 List<BetaToolUnion> tools = List.of(1063 BetaToolUnion.ofAdvisorTool20260301(1064 BetaAdvisorTool20260301.builder().model(Model.CLAUDE_OPUS_5).build())1065 // ... your other tools1066 );1067 String task = "Build a concurrent worker pool in Go with graceful shutdown.";1068 List<BetaMessageParam> messages = new ArrayList<>();1069 messages.add(BetaMessageParam.builder()1070 .role(BetaMessageParam.Role.USER)1071 .content(task)1072 .build());1073 boolean advisorCalled = false;10741075 for (int turn = 1; turn <= MAX_TURNS; turn++) {1076 BetaMessage response = client.beta().messages().create(MessageCreateParams.builder()1077 .model(Model.CLAUDE_HAIKU_4_5)1078 .maxTokens(4096L)1079 .tools(tools)1080 .messages(messages)1081 .addBeta("advisor-tool-2026-03-01")1082 .build());1083 messages.add(BetaMessageParam.builder()1084 .role(BetaMessageParam.Role.ASSISTANT)1085 .contentOfBetaContentBlockParams(1086 response.content().stream().map(BetaContentBlock::toParam).toList())1087 .build());1088 advisorCalled = advisorCalled1089 || response.content().stream().anyMatch(block ->1090 block.isServerToolUse()1091 && block.asServerToolUse().name().equals(BetaServerToolUseBlock.Name.ADVISOR));1092 BetaStopReason stopReason = response.stopReason().orElse(null);1093 if (BetaStopReason.END_TURN.equals(stopReason)) {1094 break;1095 }1096 if (BetaStopReason.PAUSE_TURN.equals(stopReason)) {1097 continue; // server tool pending; re-send to let the API complete it1098 }10991100 List<BetaContentBlockParam> results = runYourTools(response.content()); // list of tool_result blocks1101 if (!results.isEmpty()) {1102 messages.add(BetaMessageParam.builder()1103 .role(BetaMessageParam.Role.USER)1104 .contentOfBetaContentBlockParams(results)1105 .build());1106 }1107 // Skip this if your system prompt already tells the model to call sparingly.1108 if (turn == NUDGE_TURN - 1 && !advisorCalled) {1109 messages.add(BetaMessageParam.builder()1110 .role(BetaMessageParam.Role.USER)1111 .content(NUDGE_TEXT)1112 .build());1113 }1114 }1115 }1116 ```11171118 ```php PHP1119 $client = new Client();11201121 const NUDGE_TURN = 2; // inject before this assistant turn if no advisor call yet1122 const NUDGE_TEXT = "You have not consulted the advisor yet. If the task has a non-obvious "1123 . "design decision or a failure mode you haven't ruled out, call advisor "1124 . "now before committing to an approach.";1125 const MAX_TURNS = 10; // agent loop cap11261127 // Replace with your tool dispatch. Returns one tool_result block per tool_use block.1128 function runYourTools(array $content): array1129 {1130 $results = [];1131 foreach ($content as $block) {1132 if ($block->type === 'tool_use') {1133 $results[] = [1134 'type' => 'tool_result',1135 'tool_use_id' => $block->id,1136 'content' => 'Replace with your tool output.',1137 ];1138 }1139 }1140 return $results;1141 }11421143 $tools = [1144 ['type' => 'advisor_20260301', 'name' => 'advisor', 'model' => 'claude-opus-5'],1145 // ... your other tools1146 ];1147 $task = 'Build a concurrent worker pool in Go with graceful shutdown.';1148 $messages = [['role' => 'user', 'content' => $task]];1149 $advisorCalled = false;11501151 for ($turn = 1; $turn <= MAX_TURNS; $turn++) {1152 $response = $client->beta->messages->create(1153 maxTokens: 4096,1154 messages: $messages,1155 model: 'claude-haiku-4-5',1156 tools: $tools,1157 betas: ['advisor-tool-2026-03-01'],1158 );1159 $messages[] = ['role' => 'assistant', 'content' => $response->content];1160 foreach ($response->content as $block) {1161 if ($block->type === 'server_tool_use' && $block->name === 'advisor') {1162 $advisorCalled = true;1163 }1164 }1165 if ($response->stopReason === 'end_turn') {1166 break;1167 }1168 if ($response->stopReason === 'pause_turn') {1169 continue; // server tool pending; re-send to let the API complete it1170 }11711172 $results = runYourTools($response->content); // list of tool_result blocks1173 if ($results !== []) {1174 $messages[] = ['role' => 'user', 'content' => $results];1175 }1176 // Skip this if your system prompt already tells the model to call sparingly.1177 if ($turn === NUDGE_TURN - 1 && !$advisorCalled) {1178 $messages[] = ['role' => 'user', 'content' => NUDGE_TEXT];1179 }1180 }1181 ```11821183 ```ruby Ruby1184 client = Anthropic::Client.new11851186 NUDGE_TURN = 2 # inject before this assistant turn if no advisor call yet1187 NUDGE_TEXT =1188 "You have not consulted the advisor yet. If the task has a non-obvious " \1189 "design decision or a failure mode you haven't ruled out, call advisor " \1190 "now before committing to an approach."1191 MAX_TURNS = 10 # agent loop cap11921193 # Replace with your tool dispatch. Returns one tool_result block per tool_use block.1194 def run_your_tools(content)1195 content.filter_map do |block|1196 next unless block.type == :tool_use1197 { type: "tool_result", tool_use_id: block.id, content: "Replace with your tool output." }1198 end1199 end12001201 tools = [1202 { type: "advisor_20260301", name: "advisor", model: "claude-opus-5" }1203 # ... your other tools1204 ]1205 task = "Build a concurrent worker pool in Go with graceful shutdown."1206 messages = [{ role: "user", content: task }]1207 advisor_called = false12081209 (1..MAX_TURNS).each do |turn|1210 response = client.beta.messages.create(1211 model: "claude-haiku-4-5",1212 max_tokens: 4096,1213 tools: tools,1214 messages: messages,1215 betas: ["advisor-tool-2026-03-01"]1216 )1217 messages << { role: "assistant", content: response.content }1218 advisor_called ||= response.content.any? do |block|1219 block.type == :server_tool_use && block.name == :advisor1220 end1221 break if response.stop_reason == :end_turn1222 next if response.stop_reason == :pause_turn # server tool pending; re-send to let the API complete it12231224 results = run_your_tools(response.content) # list of tool_result blocks1225 messages << { role: "user", content: results } unless results.empty?1226 # Skip this if your system prompt already tells the model to call sparingly.1227 messages << { role: "user", content: NUDGE_TEXT } if turn == NUDGE_TURN - 1 && !advisor_called1228 end1229 ```1230</CodeGroup>12311232Append the nudge as its own user message after the tool results rather than as a sibling block in the same message. Consecutive user messages are valid. In Anthropic's testing on Haiku and Sonnet executors they behaved equivalently to a sibling block. The separate-message shape also keeps the reminder clearly distinct from tool output.12331234**Trade-offs:** The nudge raises the call rate, which can push trivially simple tasks into an unnecessary consult. If your workload mixes simple and complex tasks, consider raising `NUDGE_TURN` to 3 so two-turn tasks complete before the nudge fires, or gate the nudge on a task-complexity signal you already compute. If your system prompt already contains restraint language ("reserve the advisor for genuine uncertainty"), skip the nudge entirely, because the two instructions conflict.12351236The plain-text nudge is highly salient on Haiku and Sonnet executors: 74 percent (Sonnet) to 98 percent (Haiku) of nudged attempts in Anthropic's testing called the advisor immediately at turn 2. If that lands before your executor has read the problem or gathered context, the resulting advisor call is low-context and can displace a better-timed later call. Measure your executor's baseline first-call turn before adding the nudge. If the executor already calls the advisor reliably and its first call typically lands at turn N, set `NUDGE_TURN` greater than N. In Anthropic's testing, a turn-2 nudge on workloads where the baseline first call was turn 7 or later correlated with a 3 to 4 percentage-point task-performance drop. On a browse workload where the baseline call rate was 86 percent, the same nudge raised engagement with no task-performance cost.12371238To force a consult on a specific request instead of nudging, set `tool_choice` to `{"type": "tool", "name": "advisor"}`, subject to the constraints in [Forcing tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools#forcing-tool-use). Forcing tool use cannot be combined with manual extended thinking (`thinking: {type: "enabled"}`): the API returns a `400 invalid_request_error` if you enable both. Adaptive thinking supports forced tool use. Claude Fable 5.1 and Claude Mythos 5.1 executors reject `tool_choice` types `tool` and `any`, so use the prompt nudge on those models instead.12391240## Streaming12411242The advisor sub-inference does not stream. The executor's stream pauses while the advisor runs; then the full result arrives in a single event.12431244The `server_tool_use` block with `name: "advisor"` signals that an advisor call is starting. The pause begins when that block closes (`content_block_stop`). During the pause, the stream is quiet except for standard SSE `ping` keepalives emitted roughly every 30 seconds. Short advisor calls might show no pings.12451246When the advisor finishes, the `advisor_tool_result` arrives fully formed in a single `content_block_start` event (no deltas). Executor output then resumes streaming.12471248A `message_delta` event follows with the updated `usage.iterations` array reflecting the advisor's token counts.12491250## Usage and billing12511252Advisor calls run as a separate sub-inference billed at the advisor model's rates. Usage is reported in the `usage.iterations[]` array:12531254```json1255{1256 "usage": {1257 "input_tokens": 1760,1258 "cache_read_input_tokens": 412,1259 "cache_creation_input_tokens": 0,1260 "output_tokens": 531,1261 "iterations": [1262 {1263 "type": "message",1264 "input_tokens": 412,1265 "cache_read_input_tokens": 0,1266 "cache_creation_input_tokens": 0,1267 "output_tokens": 891268 },1269 {1270 "type": "advisor_message",1271 "model": "claude-opus-5",1272 "input_tokens": 823,1273 "cache_read_input_tokens": 0,1274 "cache_creation_input_tokens": 0,1275 "output_tokens": 16121276 },1277 {1278 "type": "message",1279 "input_tokens": 1348,1280 "cache_read_input_tokens": 412,1281 "cache_creation_input_tokens": 0,1282 "output_tokens": 4421283 }1284 ]1285 }1286}1287```12881289Top-level `usage` fields reflect executor tokens only. Advisor tokens are not rolled into the top-level totals because they are billed at a different rate. Iterations with `type: "advisor_message"` are billed at the advisor model's rates, and iterations with `type: "message"` are billed at the executor model's rates.12901291Every top-level `usage` field is the sum of that field across all executor iterations, including `input_tokens`, `output_tokens`, and `cache_read_input_tokens`. Because each executor iteration re-sends the growing conversation, later iterations' inputs include earlier iterations' output, so summed `input_tokens` exceeds the size of any single prompt. Use `usage.iterations` for a full per-iteration breakdown when building cost-tracking logic.12921293Advisor output is typically 400 to 700 text tokens, or 1,400 to 1,800 tokens total including thinking. The cost savings come from the advisor not generating your full final output. The executor does that at its lower rate.12941295The top-level `max_tokens` applies to executor output only. It does not bound advisor sub-inference tokens. To cap advisor output directly, set [`max_tokens` on the tool definition](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#capping-advisor-output). The advisor's tokens also do not draw from any [task budget](https://platform.claude.com/docs/en/build-with-claude/task-budgets) applied to the executor.12961297[Priority Tier](https://platform.claude.com/docs/en/api/service-tiers) applies to each model independently. A Priority Tier commitment on the executor model does not extend to the advisor. Advisor calls run at Priority Tier only if your organization also holds a commitment on the advisor model.12981299## Advisor prompt caching13001301There are two independent caching layers.13021303### Executor-side caching13041305The `advisor_tool_result` block is cacheable like any other content block. A `cache_control` breakpoint placed after it on a subsequent turn hits. 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.13061307### Advisor-side caching13081309Set `caching` on the tool definition to enable prompt caching for the advisor's own transcript across calls within the same conversation:13101311<CodeGroup exclude="shell">1312 ```python Python1313 tools = [1314 {1315 "type": "advisor_20260301",1316 "name": "advisor",1317 "model": "claude-opus-5",1318 "caching": {"type": "ephemeral", "ttl": "5m"},1319 }1320 ]1321 ```13221323 ```typescript TypeScript1324 const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [1325 {1326 type: "advisor_20260301",1327 name: "advisor",1328 model: "claude-opus-5",1329 caching: { type: "ephemeral", ttl: "5m" }1330 }1331 ];1332 ```13331334 ```csharp C#1335 using Anthropic.Models.Beta.Messages;1336 using Messages = Anthropic.Models.Messages;13371338 var tools = new BetaToolUnion[]1339 {1340 new BetaAdvisorTool202603011341 {1342 Model = Messages::Model.ClaudeOpus5,1343 Caching = new BetaCacheControlEphemeral { Ttl = Ttl.Ttl5m }1344 }1345 };1346 ```13471348 ```go Go1349 tools := []anthropic.BetaToolUnionParam{1350 {OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{1351 Model: anthropic.ModelClaudeOpus5,1352 Caching: anthropic.BetaCacheControlEphemeralParam{TTL: anthropic.BetaCacheControlEphemeralTTLTTL5m},1353 }},1354 }1355 ```13561357 ```java Java1358 import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;1359 import com.anthropic.models.beta.messages.BetaCacheControlEphemeral;1360 import com.anthropic.models.beta.messages.BetaToolUnion;1361 import com.anthropic.models.messages.Model;13621363 List<BetaToolUnion> tools = List.of(1364 BetaToolUnion.ofAdvisorTool20260301(BetaAdvisorTool20260301.builder()1365 .model(Model.CLAUDE_OPUS_5)1366 .caching(BetaCacheControlEphemeral.builder()1367 .ttl(BetaCacheControlEphemeral.Ttl.TTL_5M)1368 .build())1369 .build()));1370 ```13711372 ```php PHP1373 $tools = [1374 [1375 'type' => 'advisor_20260301',1376 'name' => 'advisor',1377 'model' => 'claude-opus-5',1378 'caching' => ['type' => 'ephemeral', 'ttl' => '5m'],1379 ],1380 ];1381 ```13821383 ```ruby Ruby1384 tools = [1385 {1386 type: "advisor_20260301",1387 name: "advisor",1388 model: "claude-opus-5",1389 caching: { type: "ephemeral", ttl: "5m" }1390 }1391 ]1392 ```1393</CodeGroup>13941395The advisor's prompt on the Nth call is the (N-1)th call's prompt with one more segment appended, so the prefix is stable across calls. With `caching` enabled, each advisor call writes a cache entry, and the next call reads up to that point and pays only for the delta. You'll see `cache_read_input_tokens` become non-zero on the second and later `advisor_message` iterations.13961397**When to enable it:** The cache write costs more than the reads save when the advisor is called two or fewer times per conversation. Caching breaks even at roughly three advisor calls and improves from there. Enable it for long agent loops, and keep it off for short tasks.13981399**Keep it consistent:** Set `caching` once and leave it for the whole conversation. Toggling it off and on mid-conversation causes cache misses.14001401<Warning>1402 [`clear_thinking`](https://platform.claude.com/docs/en/build-with-claude/context-editing) with a `keep` value other than `"all"` shifts the advisor's quoted transcript each turn, causing advisor-side cache misses. This is a cost degradation only. Advice quality is unaffected. When extended thinking is enabled without explicit `clear_thinking` configuration, the API defaults to `keep: {type: "thinking_turns", value: 1}`, which triggers this behavior (the default on earlier Opus/Sonnet models and all Haiku models, whereas on Opus 4.5+ and Sonnet 4.6+ the default is to keep all turns). Set `keep: "all"` to preserve advisor cache stability.1403</Warning>14041405## Combining with other tools14061407The advisor tool composes with other server-side and client-side tools. Add them all to the same `tools` array:14081409<CodeGroup exclude="shell">1410 ```python Python1411 tools = [1412 {1413 "type": "web_search_20250305",1414 "name": "web_search",1415 "max_uses": 5,1416 },1417 {1418 "type": "advisor_20260301",1419 "name": "advisor",1420 "model": "claude-opus-5",1421 },1422 {1423 "name": "run_bash",1424 "description": "Run a bash command",1425 "input_schema": {1426 "type": "object",1427 "properties": {"command": {"type": "string"}},1428 },1429 },1430 ]1431 ```14321433 ```typescript TypeScript1434 const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [1435 {1436 type: "web_search_20250305",1437 name: "web_search",1438 max_uses: 51439 },1440 {1441 type: "advisor_20260301",1442 name: "advisor",1443 model: "claude-opus-5"1444 },1445 {1446 name: "run_bash",1447 description: "Run a bash command",1448 input_schema: {1449 type: "object",1450 properties: { command: { type: "string" } }1451 }1452 }1453 ];1454 ```14551456 ```csharp C#1457 using System.Text.Json;1458 using Anthropic.Models.Beta.Messages;1459 using Messages = Anthropic.Models.Messages;14601461 var tools = new BetaToolUnion[]1462 {1463 new BetaWebSearchTool20250305 { MaxUses = 5 },1464 new BetaAdvisorTool20260301 { Model = Messages::Model.ClaudeOpus5 },1465 new BetaTool1466 {1467 Name = "run_bash",1468 Description = "Run a bash command",1469 InputSchema = new()1470 {1471 Properties = new Dictionary<string, JsonElement>1472 {1473 ["command"] = JsonSerializer.SerializeToElement(new { type = "string" })1474 }1475 }1476 }1477 };1478 ```14791480 ```go Go1481 tools := []anthropic.BetaToolUnionParam{1482 {OfWebSearchTool20250305: &anthropic.BetaWebSearchTool20250305Param{1483 MaxUses: anthropic.Int(5),1484 }},1485 {OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{1486 Model: anthropic.ModelClaudeOpus5,1487 }},1488 {OfTool: &anthropic.BetaToolParam{1489 Name: "run_bash",1490 Description: anthropic.String("Run a bash command"),1491 InputSchema: anthropic.BetaToolInputSchemaParam{1492 Properties: map[string]any{1493 "command": map[string]any{"type": "string"},1494 },1495 },1496 }},1497 }1498 ```14991500 ```java Java1501 import com.anthropic.core.JsonValue;1502 import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;1503 import com.anthropic.models.beta.messages.BetaTool;1504 import com.anthropic.models.beta.messages.BetaToolUnion;1505 import com.anthropic.models.beta.messages.BetaWebSearchTool20250305;1506 import com.anthropic.models.messages.Model;15071508 List<BetaToolUnion> tools = List.of(1509 BetaToolUnion.ofWebSearchTool20250305(BetaWebSearchTool20250305.builder()1510 .maxUses(5L)1511 .build()),1512 BetaToolUnion.ofAdvisorTool20260301(BetaAdvisorTool20260301.builder()1513 .model(Model.CLAUDE_OPUS_5)1514 .build()),1515 BetaToolUnion.ofBetaTool(BetaTool.builder()1516 .name("run_bash")1517 .description("Run a bash command")1518 .inputSchema(BetaTool.InputSchema.builder()1519 .properties(JsonValue.from(Map.of(1520 "command", Map.of("type", "string"))))1521 .build())1522 .build()));1523 ```15241525 ```php PHP1526 $tools = [1527 [1528 'type' => 'web_search_20250305',1529 'name' => 'web_search',1530 'max_uses' => 5,1531 ],1532 [1533 'type' => 'advisor_20260301',1534 'name' => 'advisor',1535 'model' => 'claude-opus-5',1536 ],1537 [1538 'name' => 'run_bash',1539 'description' => 'Run a bash command',1540 'input_schema' => [1541 'type' => 'object',1542 'properties' => ['command' => ['type' => 'string']],1543 ],1544 ],1545 ];1546 ```15471548 ```ruby Ruby1549 tools = [1550 {1551 type: "web_search_20250305",1552 name: "web_search",1553 max_uses: 51554 },1555 {1556 type: "advisor_20260301",1557 name: "advisor",1558 model: "claude-opus-5"1559 },1560 {1561 name: "run_bash",1562 description: "Run a bash command",1563 input_schema: {1564 type: "object",1565 properties: { command: { type: "string" } }1566 }1567 }1568 ]1569 ```1570</CodeGroup>15711572The executor can search the web, call the advisor, and use your custom tools in the same turn. The advisor's plan can inform which tools the executor reaches for next.15731574| Feature | Interaction |1575| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1576| [Batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing) | Supported. `usage.iterations` is reported per item. |1577| [Token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) | Returns the executor's first-iteration input tokens only. For a rough advisor estimate, call `count_tokens` with `model` set to the advisor model and the same messages. |1578| [Context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) | `clear_tool_uses` is not fully compatible with advisor tool blocks. With `clear_thinking`, see the earlier caching warning. |1579| `pause_turn` | A dangling advisor call ends the response with `stop_reason: "pause_turn"` and a `server_tool_use` block with no result when no client `tool_use` block is awaiting your result in the same turn. The advisor runs on resumption. If the executor also called one of your tools in that turn, the response ends with `stop_reason: "tool_use"` instead, and the pending advisor call runs at the start of your next request, after you send the `tool_result` blocks. See [Resuming a paused turn](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#resuming-a-paused-turn), [Mixing server tools and client tools in one turn](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn), and [Server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn). |15801581## Best practices15821583### Prompting for coding and agent tasks15841585The advisor tool ships with a built-in description that nudges the executor to call it near the start of complex tasks and when it hits difficulty. For research tasks, no additional prompting is typically needed.15861587On coding and agent tasks, the advisor produces higher intelligence at similar cost when it reduces total tool calls and conversation length. Two timings drive this improvement:158815891. An early first advisor call, after a few exploratory reads are in the transcript.15902. For difficult tasks, a final advisor call after file writes and test outputs are in the transcript.15911592If your agent exposes other planner-like tools (for example, a todo list tool), prompt the model to call the advisor before those tools so the advisor's plan funnels into them. The [suggested system prompt](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#suggested-system-prompt-for-coding-tasks) reinforces the early-call pattern. Add your own funnel-in sentence pointing at whichever planner tools your agent exposes.15931594#### Suggested system prompt for coding tasks15951596Without system-prompt steering, the executor tends to under-call the advisor in some domains, particularly coding tasks. For coding tasks where you want consistent advisor timing and around two to three calls for each task, prepend the following blocks to your executor system prompt before any other sentences that mention the advisor.15971598Timing guidance:15991600```text wrap1601You have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters — when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.16021603Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.16041605Also call advisor:1606- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.1607- When stuck — errors recurring, approach not converging, results that don't fit.1608- When considering a change of approach.16091610On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes.1611```16121613How the executor should treat the advice (place directly after the timing block):16141615```text wrap1616Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it's evidence your test doesn't check what the advice is checking.16171618If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call — "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.1619```16201621#### Alternative system prompt for Haiku on coding workloads16221623Claude Haiku 4.5 applies the default advisor guidance conservatively. That keeps its call rate appropriately low on research and lookup workloads but gives up quality on coding workloads, where an early advisor consult reliably pays for itself. On an internal coding benchmark, a close variant of the following block (the read-only carve-out in the Hard rule was added after measurement) raised Haiku pass rates by roughly 7.5 percentage points over the built-in default.16241625Use this block in place of the earlier timing and advice blocks when your Haiku executor runs predominantly coding or write-task workloads:16261627```text wrap1628Consult a stronger reviewer who sees your full conversation transcript.16291630No parameters. When you call advisor(), your entire history -- task, every tool call and result, your reasoning -- is automatically forwarded. The advisor sees exactly what you've done.16311632Call advisor BEFORE substantive work -- before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.16331634Also call advisor:1635- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.1636- When stuck -- errors recurring, approach not converging, results that don't fit.1637- When considering a change of approach.16381639On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling -- the advisor adds most of its value on the first call, before the approach crystallizes.16401641Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong -- it's evidence your test doesn't check what the advice is checking.16421643If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call -- "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.16441645Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first -- that judgment call is exactly where a second opinion is highest-value.16461647Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.1648```16491650**Caveat:** On an internal browse-comprehension benchmark (n = 1,266), a close variant of this block cost roughly 4 percentage points of accuracy relative to the built-in default. If your workload mixes coding with substantial lookup or retrieval, stay with the [suggested blocks](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#suggested-system-prompt-for-coding-tasks), or gate the swap on a workload-type signal you already compute.16511652#### Increasing advisor calls on Opus executors16531654Opus executors typically call the advisor at an appropriate rate without additional prompting. If your Opus executor is under-calling on your workload, add the following checkpoint to your system prompt:16551656```text wrap1657Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first. That judgment call is exactly where a second opinion is highest-value. (This does not apply to simple factual lookups or arithmetic; those you answer directly.)16581659Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.1660```16611662**Caveat:** In Anthropic's testing, a close variant of this block (the read-only carve-out in the Hard rule was added after measurement) raised pass rates on under-calling tasks by roughly 7 to 10 percentage points but caused Opus to over-call on tasks whose first action needs no planning. The net effect was roughly flat on a mixed workload. Only add it if you have observed Opus skipping the advisor on tasks where a consult would have helped. Do not add it as a default.16631664#### Trimming advisor output length16651666Advisor output is the advisor's largest cost driver, and the top-level `max_tokens` does not bound it. The advisor sees both your system prompt and your user messages as quoted context about the executor's task, so instructions that address the advisor directly are followed much more reliably than third-person descriptions. The most effective placement Anthropic tested is a line in the user message:16671668```text wrap1669(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)1670```16711672This line can be prefixed programmatically by your agent framework before sending the request. The limit is a soft constraint. The advisor occasionally exceeds it, so ask for roughly 80 percent of your true ceiling.16731674<Note>1675 In Anthropic's testing this line also increased how often the executor consults the advisor, but the net effect was still lower total cost (more consults, each shorter).1676</Note>16771678Pair this approach with the timing guidance in [Suggested system prompt for coding tasks](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#suggested-system-prompt-for-coding-tasks) (or the [alternative Haiku block](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#alternative-system-prompt-for-haiku-on-coding-workloads) if you swapped it in) for the strongest cost-versus-quality tradeoff. For a hard ceiling rather than a soft request, see [Capping advisor output](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#capping-advisor-output).16791680### Capping advisor output16811682Set `max_tokens` on the tool definition to cap the advisor's total output (thinking plus text) per call:16831684<CodeGroup exclude="shell">1685 ```python Python1686 tools = [1687 {1688 "type": "advisor_20260301",1689 "name": "advisor",1690 "model": "claude-opus-5",1691 "max_tokens": 2048,1692 }1693 ]1694 ```16951696 ```typescript TypeScript1697 const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [1698 {1699 type: "advisor_20260301",1700 name: "advisor",1701 model: "claude-opus-5",1702 max_tokens: 20481703 }1704 ];1705 ```17061707 ```csharp C#1708 using Anthropic.Models.Beta.Messages;1709 using Messages = Anthropic.Models.Messages;17101711 var tools = new BetaToolUnion[]1712 {1713 new BetaAdvisorTool202603011714 {1715 Model = Messages::Model.ClaudeOpus5,1716 MaxTokens = 20481717 }1718 };1719 ```17201721 ```go Go1722 tools := []anthropic.BetaToolUnionParam{1723 {OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{1724 Model: anthropic.ModelClaudeOpus5,1725 MaxTokens: anthropic.Int(2048),1726 }},1727 }1728 ```17291730 ```java Java1731 import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;1732 import com.anthropic.models.beta.messages.BetaToolUnion;1733 import com.anthropic.models.messages.Model;17341735 List<BetaToolUnion> tools = List.of(1736 BetaToolUnion.ofAdvisorTool20260301(BetaAdvisorTool20260301.builder()1737 .model(Model.CLAUDE_OPUS_5)1738 .maxTokens(2048L)1739 .build()));1740 ```17411742 ```php PHP1743 $tools = [1744 [1745 'type' => 'advisor_20260301',1746 'name' => 'advisor',1747 'model' => 'claude-opus-5',1748 'max_tokens' => 2048,1749 ],1750 ];1751 ```17521753 ```ruby Ruby1754 tools = [1755 {1756 type: "advisor_20260301",1757 name: "advisor",1758 model: "claude-opus-5",1759 max_tokens: 20481760 }1761 ]1762 ```1763</CodeGroup>17641765The minimum value is 1024. Setting `max_tokens` above the advisor model's own output cap returns a 400 error. The cap applies to each advisor call independently and is not shared across calls in the same request.17661767This is not a hard truncation alone. The server also passes the advisor its remaining-token budget, so the advisor shapes its response to fit.17681769**Recommended starting point:** `max_tokens: 2048`. In Anthropic's testing on a hard reasoning benchmark (n = 40 per configuration), this reduced mean advisor output by roughly 7x compared with leaving the cap unset, with near-zero truncation and no detectable quality degradation. The minimum value of 1024 reduced output roughly 10x but truncated around 10 percent of calls. Accuracy differences across all configurations were within noise at this sample size. Validate on your own workload.17701771| `max_tokens` | Mean advisor output tokens | Calls truncated |1772| ------------ | -------------------------- | --------------- |1773| unset | \~4,200 to 5,900 | n/a |1774| 2048 | \~630 to 840 | \~0% |1775| 1024 | \~370 to 480 | \~10% |17761777Hard reasoning tasks elicit substantially longer advisor output than the [typical 1,400 to 1,800 tokens](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#usage-and-billing) quoted earlier for lighter workloads. Use this table to size the savings ratio, not as a universal baseline for advisor output.17781779When the advisor does hit the cap, the result block carries `stop_reason: "max_tokens"` on both [result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants), whichever advisor model you use. Use `stop_reason` to detect truncated advice and decide whether to raise the cap or let the executor proceed with partial guidance. The API also appends `[Advisor output truncated at max_tokens=2048.]` (naming your cap) to the advice text, so the executor sees the truncation in its own context; with a plaintext `advisor_result` advisor that marker is visible to your client as well. Both signals appear only when you set `max_tokens` on the tool definition.17801781```json1782{1783 "type": "advisor_tool_result",1784 "tool_use_id": "srvtoolu_abc123",1785 "content": {1786 "type": "advisor_redacted_result",1787 "encrypted_content": "EqQBCkYIBRgCIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",1788 "stop_reason": "max_tokens"1789 }1790}1791```17921793Check `output_tokens` on the corresponding `advisor_message` entry in `usage.iterations` to see how close each call came to its cap.17941795Compared with the [prompt-based approach](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#trimming-advisor-output-length), `max_tokens` is a hard ceiling rather than a soft request. Use `max_tokens` when you need a guaranteed bound for cost or latency. Use the prompt-based approach (or both together) when you want to bias toward brevity without risking a mid-thought cut.17961797### Pairing with effort settings17981799For coding tasks, pairing a Sonnet executor at medium [effort](https://platform.claude.com/docs/en/build-with-claude/effort) with an Opus advisor achieves intelligence comparable to Sonnet at default effort, at lower cost. For maximum intelligence, keep the executor at default effort.18001801### Cost control18021803* For conversation-level budgets, count advisor calls client-side. When you reach your cap, remove the advisor tool from `tools`; you do not need to strip `advisor_tool_result` blocks from your message history (see the note in [Multi-turn conversations](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#multi-turn-conversations)).1804* Enable `caching` only for conversations where you expect three or more advisor calls.18051806## Model compatibility18071808The executor model (the top-level `model` field) and the advisor model (the `model` field inside the tool definition) must form a valid pair. The advisor must be Claude Sonnet 4.6 or a more capable model, and it must be at least as capable as the executor. Models of equal capability (for example, Claude Opus 4.7 and Claude Opus 4.8) can advise each other.18091810| Executor models | Advisor models |1811| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1812| Claude Haiku 4.5 (claude-haiku-4-5) | Claude Mythos 5.1 (claude-mythos-5-1) Claude Fable 5.1 (claude-fable-5-1) Claude Mythos 5 (claude-mythos-5) Claude Fable 5 (claude-fable-5) Claude Opus 5 (claude-opus-5) Claude Opus 4.8 (claude-opus-4-8) Claude Opus 4.7 (claude-opus-4-7) Claude Opus 4.6 (claude-opus-4-6) Claude Sonnet 5 (claude-sonnet-5) Claude Sonnet 4.6 (claude-sonnet-4-6) |1813| Claude Sonnet 4.6 (claude-sonnet-4-6) | Claude Mythos 5.1 (claude-mythos-5-1) Claude Fable 5.1 (claude-fable-5-1) Claude Mythos 5 (claude-mythos-5) Claude Fable 5 (claude-fable-5) Claude Opus 5 (claude-opus-5) Claude Opus 4.8 (claude-opus-4-8) Claude Opus 4.7 (claude-opus-4-7) Claude Opus 4.6 (claude-opus-4-6) Claude Sonnet 5 (claude-sonnet-5) Claude Sonnet 4.6 (claude-sonnet-4-6) |1814| Claude Sonnet 5 (claude-sonnet-5) | Claude Mythos 5.1 (claude-mythos-5-1) Claude Fable 5.1 (claude-fable-5-1) Claude Mythos 5 (claude-mythos-5) Claude Fable 5 (claude-fable-5) Claude Opus 5 (claude-opus-5) Claude Opus 4.8 (claude-opus-4-8) Claude Opus 4.7 (claude-opus-4-7) Claude Sonnet 5 (claude-sonnet-5) |1815| Claude Opus 4.6 (claude-opus-4-6) | Claude Mythos 5.1 (claude-mythos-5-1) Claude Fable 5.1 (claude-fable-5-1) Claude Mythos 5 (claude-mythos-5) Claude Fable 5 (claude-fable-5) Claude Opus 5 (claude-opus-5) Claude Opus 4.8 (claude-opus-4-8) Claude Opus 4.7 (claude-opus-4-7) Claude Opus 4.6 (claude-opus-4-6) Claude Sonnet 5 (claude-sonnet-5) |1816| Claude Opus 4.7 (claude-opus-4-7) | Claude Mythos 5.1 (claude-mythos-5-1) Claude Fable 5.1 (claude-fable-5-1) Claude Mythos 5 (claude-mythos-5) Claude Fable 5 (claude-fable-5) Claude Opus 5 (claude-opus-5) Claude Opus 4.8 (claude-opus-4-8) Claude Opus 4.7 (claude-opus-4-7) |1817| Claude Opus 4.8 (claude-opus-4-8) | Claude Mythos 5.1 (claude-mythos-5-1) Claude Fable 5.1 (claude-fable-5-1) Claude Mythos 5 (claude-mythos-5) Claude Fable 5 (claude-fable-5) Claude Opus 5 (claude-opus-5) Claude Opus 4.8 (claude-opus-4-8) Claude Opus 4.7 (claude-opus-4-7) |1818| Claude Opus 5 (claude-opus-5) | Claude Mythos 5.1 (claude-mythos-5-1) Claude Fable 5.1 (claude-fable-5-1) Claude Mythos 5 (claude-mythos-5) Claude Fable 5 (claude-fable-5) Claude Opus 5 (claude-opus-5) |1819| Claude Fable 5 (claude-fable-5) | Claude Mythos 5.1 (claude-mythos-5-1) Claude Fable 5.1 (claude-fable-5-1) Claude Mythos 5 (claude-mythos-5) Claude Fable 5 (claude-fable-5) Claude Opus 5 (claude-opus-5) |1820| Claude Mythos 5 (claude-mythos-5) | Claude Mythos 5.1 (claude-mythos-5-1) Claude Fable 5.1 (claude-fable-5-1) Claude Mythos 5 (claude-mythos-5) Claude Fable 5 (claude-fable-5) Claude Opus 5 (claude-opus-5) |1821| Claude Fable 5.1 (claude-fable-5-1) | Claude Mythos 5.1 (claude-mythos-5-1) Claude Fable 5.1 (claude-fable-5-1) |1822| Claude Mythos 5.1 (claude-mythos-5-1) | Claude Mythos 5.1 (claude-mythos-5-1) Claude Fable 5.1 (claude-fable-5-1) |18231824If you request an invalid pair, the API returns a `400 invalid_request_error` naming the unsupported combination.18251826### Platform availability18271828The advisor tool is available in beta on the Claude API and on [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws). It is not currently available on Amazon Bedrock, Google Cloud, or Microsoft Foundry.18291830## Advisor on Claude Managed Agents18311832[Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) sessions support an advisor as well, configured as part of the agent rather than as a tool definition: add a `{"type": "advisor", "model": ...}` entry to the agent's multiagent roster, and the session's primary thread can consult that model mid-turn. The roster entry takes no `max_uses`, `max_tokens`, or `caching` options, and advice is delivered as thread events on the session's event stream rather than as `advisor_tool_result` blocks in the response. See [Give the session an advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor).18331834## Next steps18351836<CardGroup cols={2}>1837 <Card title="Memory tool" icon="brain" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool">1838 Store and retrieve information across conversations with a client-side memory directory.1839 </Card>18401841 <Card title="Server tools" icon="tool" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools">1842 Work with Anthropic-executed tools: server\_tool\_use blocks, pause\_turn continuation, and domain filtering.1843 </Card>18441845 <Card title="Tool reference" icon="book" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference">1846 Directory of Anthropic-provided tools and reference for optional tool definition properties.1847 </Card>18481849 <Card title="Effort" icon="gauge" href="https://platform.claude.com/docs/en/build-with-claude/effort">1850 Control how many tokens Claude uses when responding with the effort parameter, trading off between response thoroughness and token efficiency.1851 </Card>1852</CardGroup>1853