advisor-tool changedagents-and-tools/tool-use/advisor-tool
Nearest release: v2.1.296, 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+32added
Lines−30removed
From line
735
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits13to this page, all time
The whole hunk
from line 735, old and new numbered
/
from line 735
735735
736736### Mid-conversation nudge for under-calling executors
737737
738If 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.
738If 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 on Claude Haiku 4.5 executors, this raised task pass rates by roughly 7 percentage points. 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.
739739
740740With 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.
741741
from line 775
775775
776776 for turn in range(1, MAX_TURNS + 1):
777777 response = client.beta.messages.create(
778 model="claude-haiku-4-5",
778 model="claude-haiku-5-5",
779779 max_tokens=4096,
780780 betas=["advisor-tool-2026-03-01"],
781781 tools=tools,
from line 786
786786 block.type == "server_tool_use" and block.name == "advisor"
787787 for block in response.content
788788 )
789 if response.stop_reason == "end_turn":
790 break
791789 if response.stop_reason == "pause_turn":
792790 continue # server tool pending; re-send to let the API complete it
791 if response.stop_reason != "tool_use":
792 break # end_turn, or a stop such as max_tokens that needs handling (see below)
793793
794794 results = run_your_tools(response.content) # list of tool_result blocks
795795 if results:
from line 832
832832
833833 for (let turn = 1; turn <= MAX_TURNS; turn++) {
834834 const response = await client.beta.messages.create({
835 model: "claude-haiku-4-5",
835 model: "claude-haiku-5-5",
836836 max_tokens: 4096,
837837 betas: ["advisor-tool-2026-03-01"],
838838 tools,
from line 844
844844 response.content.some(
845845 (block) => block.type === "server_tool_use" && block.name === "advisor"
846846 );
847 if (response.stop_reason === "end_turn") {
848 break;
849 }
850847 if (response.stop_reason === "pause_turn") {
851848 continue; // server tool pending; re-send to let the API complete it
852849 }
850 if (response.stop_reason !== "tool_use") {
851 break; // end_turn, or a stop such as max_tokens that needs handling (see below)
852 }
853853
854854 const results = runYourTools(response.content); // list of tool_result blocks
855855 if (results.length > 0) {
from line 906
906906 {
907907 var response = await client.Beta.Messages.Create(new MessageCreateParams
908908 {
909 Model = Messages::Model.ClaudeHaiku4_5,
909 Model = Messages::Model.ClaudeHaiku5_5,
910910 MaxTokens = 4096,
911911 Tools = tools,
912912 Messages = messages,
from line 923
923923 block.TryPickServerToolUse(out var serverToolUse)
924924 && serverToolUse.Name.Value() == Name.Advisor
925925 );
926 if (response.StopReason == BetaStopReason.EndTurn)
927 {
928 break;
929 }
930926 if (response.StopReason == BetaStopReason.PauseTurn)
931927 {
932928 continue; // server tool pending; re-send to let the API complete it
933929 }
930 if (response.StopReason != BetaStopReason.ToolUse)
931 {
932 break; // end_turn, or a stop such as max_tokens that needs handling (see below)
933 }
934934
935935 var results = RunYourTools(response.Content); // list of tool_result blocks
936936 if (results.Count > 0)
from line 982
982982
983983 for turn := 1; turn <= maxTurns; turn++ {
984984 response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
985 Model: anthropic.ModelClaudeHaiku4_5,
985 Model: anthropic.ModelClaudeHaiku5_5,
986986 MaxTokens: 4096,
987987 Tools: tools,
988988 Messages: messages,
from line 1001
10011001 advisorCalled = true
10021002 }
10031003 }
1004 if response.StopReason == anthropic.BetaStopReasonEndTurn {
1005 break
1006 }
10071004 if response.StopReason == anthropic.BetaStopReasonPauseTurn {
10081005 continue // server tool pending; re-send to let the API complete it
10091006 }
1007 if response.StopReason != anthropic.BetaStopReasonToolUse {
1008 break // end_turn, or a stop such as max_tokens that needs handling (see below)
1009 }
10101010
10111011 results := runYourTools(response.Content) // list of tool_result blocks
10121012 if len(results) > 0 {
from line 1076
10761076
10771077 for (int turn = 1; turn <= MAX_TURNS; turn++) {
10781078 BetaMessage response = client.beta().messages().create(MessageCreateParams.builder()
1079 .model(Model.CLAUDE_HAIKU_4_5)
1079 .model(Model.CLAUDE_HAIKU_5_5)
10801080 .maxTokens(4096L)
10811081 .tools(tools)
10821082 .messages(messages)
from line 1092
10921092 block.isServerToolUse()
10931093 && block.asServerToolUse().name().equals(BetaServerToolUseBlock.Name.ADVISOR));
10941094 BetaStopReason stopReason = response.stopReason().orElse(null);
1095 if (BetaStopReason.END_TURN.equals(stopReason)) {
1096 break;
1097 }
10981095 if (BetaStopReason.PAUSE_TURN.equals(stopReason)) {
10991096 continue; // server tool pending; re-send to let the API complete it
11001097 }
1098 if (!BetaStopReason.TOOL_USE.equals(stopReason)) {
1099 break; // end_turn, or a stop such as max_tokens that needs handling (see below)
1100 }
11011101
11021102 List<BetaContentBlockParam> results = runYourTools(response.content()); // list of tool_result blocks
11031103 if (!results.isEmpty()) {
from line 1154
11541154 $response = $client->beta->messages->create(
11551155 maxTokens: 4096,
11561156 messages: $messages,
1157 model: 'claude-haiku-4-5',
1157 model: 'claude-haiku-5-5',
11581158 tools: $tools,
11591159 betas: ['advisor-tool-2026-03-01'],
11601160 );
from line 1164
11641164 $advisorCalled = true;
11651165 }
11661166 }
1167 if ($response->stopReason === 'end_turn') {
1168 break;
1169 }
11701167 if ($response->stopReason === 'pause_turn') {
11711168 continue; // server tool pending; re-send to let the API complete it
11721169 }
1170 if ($response->stopReason !== 'tool_use') {
1171 break; // end_turn, or a stop such as max_tokens that needs handling (see below)
1172 }
11731173
11741174 $results = runYourTools($response->content); // list of tool_result blocks
11751175 if ($results !== []) {
from line 1210
12101210
12111211 (1..MAX_TURNS).each do |turn|
12121212 response = client.beta.messages.create(
1213 model: "claude-haiku-4-5",
1213 model: "claude-haiku-5-5",
12141214 max_tokens: 4096,
12151215 tools: tools,
12161216 messages: messages,
from line 1220
12201220 advisor_called ||= response.content.any? do |block|
12211221 block.type == :server_tool_use && block.name == :advisor
12221222 end
1223 break if response.stop_reason == :end_turn
12241223 next if response.stop_reason == :pause_turn # server tool pending; re-send to let the API complete it
1224 break unless response.stop_reason == :tool_use # end_turn, or a stop such as max_tokens that needs handling (see below)
12251225
12261226 results = run_your_tools(response.content) # list of tool_result blocks
12271227 messages << { role: "user", content: results } unless results.empty?
from line 1231
12311231 ```
12321232</CodeGroup>
12331233
1234Append 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.
1234The loop ends on any stop reason other than `tool_use` or `pause_turn`. If `max_tokens` cuts a response off, drop the truncated assistant turn from `messages` and [retry with a higher `max_tokens`](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons#max-tokens). When that turn contains no `tool_use` block, you can instead keep it and [continue the response](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons#ensuring-complete-responses) with a new user message. Re-sending the truncated assistant turn as the last message is a [prefill](https://platform.claude.com/docs/en/api/errors#prefill-not-supported), which Claude 4.6 and later models reject.
12351235
1236Append 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 Claude Haiku 4.5 and Sonnet executors they behaved equivalently to a sibling block. The separate-message shape also keeps the reminder clearly distinct from tool output.
1237
12361238**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.
12371239
1238The 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.
1240The plain-text nudge is highly salient on Claude Haiku 4.5 and Sonnet executors: 74 percent (Sonnet) to 98 percent (Claude Haiku 4.5) 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.
12391241
12401242To 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 Opus 5.5, Claude Sonnet 5.5, 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.
12411243
from line 1403
14011403**Keep it consistent:** Set `caching` once and leave it for the whole conversation. Toggling it off and on mid-conversation causes cache misses.
14021404
14031405<Warning>
1404 [`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 Haiku models through Claude Haiku 4.5, whereas on Opus 4.5+, Sonnet 4.6+, and Haiku 5.5 the default is to keep all turns). Set `keep: "all"` to preserve advisor cache stability.
1406 [`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 thinking is on without explicit `clear_thinking` configuration, the API defaults to `keep: {type: "thinking_turns", value: 1}`, which triggers this behavior (the default on earlier Opus and Sonnet models and on Haiku models through Claude Haiku 4.5; on Claude Opus 4.5 and later Opus models, Claude Sonnet 4.6 and later Sonnet models, and Claude Haiku 5.5, the default is to keep all turns). Set `keep: "all"` to preserve advisor cache stability.
14051407</Warning>
14061408
14071409## Combining with other tools
No line in this hunk matches that.