advisor-tool changedagents-and-tools/tool-use/advisor-tool
Nearest release: v2.1.319, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+46added
Lines−44removed
From line
256
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits29to this page, all time
The whole hunk
from line 256, old and new numbered
/
from line 256
256256 [
257257 'type' => 'advisor_20260301',
258258 'name' => 'advisor',
259 'model' => 'claude-opus-5-5',
259 'model' => Model::CLAUDE_OPUS_5_5,
260260 ],
261261 ],
262262 betas: ['advisor-tool-2026-03-01'],
from line 269
269269 client = Anthropic::Client.new
270270
271271 response = client.beta.messages.create(
272 model: "claude-sonnet-5",
272 model: Anthropic::Model::CLAUDE_SONNET_5,
273273 max_tokens: 16000,
274274 tools: [
275275 {
276276 type: "advisor_20260301",
277277 name: "advisor",
278 model: "claude-opus-5-5"
278 model: Anthropic::Model::CLAUDE_OPUS_5_5
279279 }
280280 ],
281281 messages: [
from line 308
308308
309309## Tool parameters
310310
311| Parameter | Type | Default | Description |
312| ------------ | -------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
313| `type` | string | *required* | Must be `"advisor_20260301"`. |
314| `name` | string | *required* | Must be `"advisor"`. |
315| `model` | string | *required* | The advisor model ID, such as claude-opus-5-5. Billed at this model’s rates for the sub-inference. |
316| `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. |
317| `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). |
318| `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). |
311| Parameter | Type | Default | Description |
312| ------------ | -------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
313| `type` | string | *required* | Must be `"advisor_20260301"`. |
314| `name` | string | *required* | Must be `"advisor"`. |
315| `model` | string | *required* | The advisor model ID, such as claude-opus-5-5. Billed at this model’s rates for the sub-inference. |
316| `max_uses` | integer | unlimited | Maximum number of advisor calls allowed in a single turn. 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. See [Cost control](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#cost-control) for conversation-level limits. |
317| `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). |
318| `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). |
319319
320The `max_uses` cap applies to a whole turn, and a turn can span several requests. A request continues the turn when it [resumes after `pause_turn`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#resuming-a-paused-turn) or when its last message contains only `tool_result` blocks. Advisor calls from earlier requests in that turn count against the cap.
321
320322The `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.
321323
322324The 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 [Tool definition properties](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference#tool-definition-properties) in the Tool reference for their semantics.
from line 404
402404
403405Both 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).
404406
405With `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.
407With `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. In the next request, the server decrypts it and renders the plaintext into the executor’s prompt.
406408
407In 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.
409In both cases, round-trip the content verbatim in later requests. If you switch advisor models mid-conversation, branch on `content.type` to handle both shapes.
408410
409411### Error results
410412
from line 425
423425
424426The executor receives the error and continues without further advice. The request itself does not fail.
425427
426| `error_code` | Meaning |
427| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
428| `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. |
429| `too_many_requests` | The advisor sub-inference was rate-limited. |
430| `overloaded` | The advisor sub-inference hit capacity limits. |
431| `prompt_too_long` | The transcript exceeded the advisor model’s context window. |
432| `execution_time_exceeded` | The advisor sub-inference timed out. |
433| `model_not_found` | The configured advisor model is not available. |
434| `unavailable` | Any other advisor failure. |
428| `error_code` | Meaning |
429| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
430| `max_uses_exceeded` | The turn reached the [`max_uses`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#tool-parameters) cap set on the tool definition. Further advisor calls in the same turn return this error. |
431| `too_many_requests` | The advisor sub-inference was rate-limited. |
432| `overloaded` | The advisor sub-inference hit capacity limits. |
433| `prompt_too_long` | The transcript exceeded the advisor model’s context window. |
434| `execution_time_exceeded` | The advisor sub-inference timed out. |
435| `model_not_found` | The configured advisor model is not available. |
436| `unavailable` | Any other advisor failure. |
435437
436438Advisor 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.
437439
438440## Multi-turn conversations
439441
440Pass the full assistant content, including `advisor_tool_result` blocks, back to the API on subsequent turns. Round-trip the result blocks verbatim: with the newest Opus model as the advisor, as in this example, 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.
442Pass the full assistant content, including `advisor_tool_result` blocks, back to the API in later requests. Round-trip the result blocks verbatim. With the newest Opus model as the advisor, as in this example, the result block’s `content` is the encrypted `advisor_redacted_result` variant. In the next request, the server decrypts it and renders the advice into the executor’s prompt (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.
441443
442444<CodeGroup exclude="shell">
443445 ```python Python
from line 666
664666 [
665667 'type' => 'advisor_20260301',
666668 'name' => 'advisor',
667 'model' => 'claude-opus-5-5',
669 'model' => Model::CLAUDE_OPUS_5_5,
668670 ],
669671 ];
670672
from line 680
678680 $response = $client->beta->messages->create(
679681 maxTokens: 16000,
680682 messages: $messages,
681 model: 'claude-sonnet-5',
683 model: Model::CLAUDE_SONNET_5,
682684 tools: $tools,
683685 betas: ['advisor-tool-2026-03-01'],
684686 );
from line 694
692694 $response = $client->beta->messages->create(
693695 maxTokens: 16000,
694696 messages: $messages,
695 model: 'claude-sonnet-5',
697 model: Model::CLAUDE_SONNET_5,
696698 tools: $tools,
697699 betas: ['advisor-tool-2026-03-01'],
698700 );
from line 707
705707 {
706708 type: "advisor_20260301",
707709 name: "advisor",
708 model: "claude-opus-5-5"
710 model: Anthropic::Model::CLAUDE_OPUS_5_5
709711 }
710712 ]
711713
from line 719
717719 ]
718720
719721 response = client.beta.messages.create(
720 model: "claude-sonnet-5",
722 model: Anthropic::Model::CLAUDE_SONNET_5,
721723 max_tokens: 16000,
722724 tools: tools,
723725 messages: messages,
from line 733
731733 messages << { role: "user", content: "Now add a max-in-flight limit of 10." }
732734
733735 response = client.beta.messages.create(
734 model: "claude-sonnet-5",
736 model: Anthropic::Model::CLAUDE_SONNET_5,
735737 max_tokens: 16000,
736738 tools: tools,
737739 messages: messages,
from line 742
740742 ```
741743</CodeGroup>
742744
743You 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.
745You can drop the advisor tool from `tools` in a follow-up request while the message history still contains `advisor_tool_result` blocks, as long as no advisor call is [still pending](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#resuming-a-paused-turn). The API accepts the request and keeps the historical blocks, but the model cannot call the advisor in that request. You must still send the `advisor-tool-2026-03-01` beta header for those history blocks to be accepted.
744746
745747<Note>
746748 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.
from line 1149
11471149 {
11481150 $results = [];
11491151 foreach ($content as $block) {
1150 if ($block->type === 'tool_use') {
1152 if ($block instanceof \Anthropic\Beta\Messages\BetaToolUseBlock) {
11511153 $results[] = [
11521154 'type' => 'tool_result',
11531155 'tool_use_id' => $block->id,
from line 1161
11591161 }
11601162
11611163 $tools = [
1162 ['type' => 'advisor_20260301', 'name' => 'advisor', 'model' => 'claude-opus-5-5'],
1164 ['type' => 'advisor_20260301', 'name' => 'advisor', 'model' => Model::CLAUDE_OPUS_5_5],
11631165 // ... your other tools
11641166 ];
11651167 $task = 'Build a concurrent worker pool in Go with graceful shutdown.';
from line 1172
11701172 $response = $client->beta->messages->create(
11711173 maxTokens: 4096,
11721174 messages: $messages,
1173 model: 'claude-haiku-5-5',
1175 model: Model::CLAUDE_HAIKU_5_5,
11741176 tools: $tools,
11751177 betas: ['advisor-tool-2026-03-01'],
11761178 );
11771179 $messages[] = ['role' => 'assistant', 'content' => $response->content];
11781180 foreach ($response->content as $block) {
1179 if ($block->type === 'server_tool_use' && $block->name === 'advisor') {
1181 if ($block instanceof \Anthropic\Beta\Messages\BetaServerToolUseBlock && $block->name === 'advisor') {
11801182 $advisorCalled = true;
11811183 }
11821184 }
from line 1328
13261328
13271329### Executor-side caching
13281330
1329The `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.
1331The `advisor_tool_result` block is cacheable like any other content block. A `cache_control` breakpoint placed after it in a later request 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.
13301332
13311333### Advisor-side caching
13321334
from line 1400
13981400 [
13991401 'type' => 'advisor_20260301',
14001402 'name' => 'advisor',
1401 'model' => 'claude-opus-5-5',
1403 'model' => Model::CLAUDE_OPUS_5_5,
14021404 'caching' => ['type' => 'ephemeral', 'ttl' => '5m'],
14031405 ],
14041406 ];
from line 1411
14091411 {
14101412 type: "advisor_20260301",
14111413 name: "advisor",
1412 model: "claude-opus-5-5",
1414 model: Anthropic::Model::CLAUDE_OPUS_5_5,
14131415 caching: { type: "ephemeral", ttl: "5m" }
14141416 }
14151417 ]
from line 1558
15561558 [
15571559 'type' => 'advisor_20260301',
15581560 'name' => 'advisor',
1559 'model' => 'claude-opus-5-5',
1561 'model' => Model::CLAUDE_OPUS_5_5,
15601562 ],
15611563 [
15621564 'name' => 'run_bash',
from line 1581
15791581 {
15801582 type: "advisor_20260301",
15811583 name: "advisor",
1582 model: "claude-opus-5-5"
1584 model: Anthropic::Model::CLAUDE_OPUS_5_5
15831585 },
15841586 {
15851587 name: "run_bash",
from line 1692
16901692Advisor output is the advisor’s largest cost driver, and the top-level `max_tokens` does not bound it. The advisor receives 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:
16911693
16921694```text wrap
1693(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)
1695(Advisor: please keep your guidance under 80 words. I need a focused starting point, not a comprehensive plan.)
16941696```
16951697
16961698This 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.
from line 1770
17681770 [
17691771 'type' => 'advisor_20260301',
17701772 'name' => 'advisor',
1771 'model' => 'claude-opus-5-5',
1773 'model' => Model::CLAUDE_OPUS_5_5,
17721774 'max_tokens' => 2048,
17731775 ],
17741776 ];
from line 1781
17791781 {
17801782 type: "advisor_20260301",
17811783 name: "advisor",
1782 model: "claude-opus-5-5",
1784 model: Anthropic::Model::CLAUDE_OPUS_5_5,
17831785 max_tokens: 2048
17841786 }
17851787 ]
from line 2002
20002002
20012003### Platform availability
20022004
2003The advisor tool is available in beta on the Claude API, on [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), and on [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed). It is not currently available on Amazon Bedrock, Claude Models on Google Cloud (Google managed), or Microsoft Foundry.
2005The advisor tool is available in beta on the Claude API, on [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), and on [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed).
20042006
20052007## Advisor on Claude Managed Agents
20062008
No line in this hunk matches that.