# Advisor tool (advisor_20260301, beta)

Status: DOCUMENTED · BETA · LIVE_VERIFIED 2026-09-18 for acceptance only (k18: haiku executor + sonnet 4.6 advisor, "Reply with OK." → 200, no advisor call, usage.iterations present; k18b without header → 400 unknown tag). No advisor sub-inference was triggered (cost control). Sources: Advisor tool · Release notes 2026-04-09 / 2026-05-28 / 2026-06-02 · Token counting. Last verified: 2026-09-18.

# Definition (header anthropic-beta: advisor-tool-2026-03-01)

{"type": "advisor_20260301", "name": "advisor", "model": "claude-opus-5",
 "max_uses": 3,                              // per request; then advisor_tool_result_error max_uses_exceeded
 "max_tokens": 2048,                         // advisor output cap (thinking+text), min 1024; adds stop_reason to the result
 "caching": {"type": "ephemeral", "ttl": "5m"}}   // advisor-side prompt caching switch (not a breakpoint)

Plus generic cache_control, allowed_callers, defer_loading, strict. Executor = top-level model; advisor must be ≥ Sonnet 4.6 and at least as capable as the executor (invalid pair → 400). Pairs table (executor → advisors): Haiku 4.5 / Sonnet 4.6 → Mythos 5.1, Fable 5.1, Mythos 5, Fable 5, Opus 5, Opus 4.8, 4.7, 4.6, Sonnet 5, Sonnet 4.6; Sonnet 5 → …4.7, Sonnet 5; Opus 4.6 → …4.6, Sonnet 5; Opus 4.7 / 4.8 → Mythos/Fable/Opus 5/4.8/4.7; Opus 5 / Fable 5 / Mythos 5 → Mythos 5.1, Fable 5.1, Mythos 5, Fable 5, Opus 5; Fable 5.1 / Mythos 5.1 → Mythos 5.1, Fable 5.1. Platforms: Claude API + Claude Platform on AWS.

# Response

server_tool_use{name:"advisor", input:{}} (input always empty; the server builds the advisor's view from the full transcript) followed by:

{"type":"advisor_tool_result","tool_use_id":"srvtoolu_…","content":{"type":"advisor_result","text":"Use a channel-based coordination pattern…","stop_reason":"end_turn"}}
// Fable 5.1 / Mythos 5.1 / Opus 5 / Fable 5 / Mythos 5 advisors return the encrypted variant instead:
{"type":"advisor_tool_result","tool_use_id":"srvtoolu_…","content":{"type":"advisor_redacted_result","encrypted_content":"EqQB…"}}
// error (request still 200):
{"type":"advisor_tool_result","tool_use_id":"srvtoolu_…","content":{"type":"advisor_tool_result_error","error_code":"overloaded"}}

Error codes: max_uses_exceeded, too_many_requests, overloaded, prompt_too_long, execution_time_exceeded, model_not_found, unavailable. Round-trip result blocks verbatim; you may drop the tool later but must keep the beta header while history contains advisor blocks. pause_turn may occur with a pending advisor call → re-send as-is with the tool. Streaming: quiet (pings) while the advisor runs, then the result in one content_block_start, then message_delta with usage.iterations.

# Billing

usage.iterations[] lists {type: "message", …} (executor rate) and {type: "advisor_message", model, …} (advisor rate); top-level usage = executor only; top-level max_tokens does not bound the advisor. Live k18 usage carried iterations with a single executor iteration (990 in / 5 out). count_tokens accepts the advisor tool (covers the executor's first sampling call only). Managed Agents use a roster entry {"type":"advisor","model":…} instead.

Example: examples/anthropic/tools/advisor/basic.sh.