CONCEPT Four settings on one dial
tool_choice is how the architect moves control between the model and their own code. It ranges from
"Claude decides" all the way to "Claude must call this exact tool." Picking the right setting is often the
difference between a reliable step and an unpredictable one.
| Setting | Meaning | Use when |
|---|---|---|
{"type":"auto"} | Default. Claude decides whether to use a tool, and which. | General agent loops — let the model judge. |
{"type":"any"} | Claude must use some tool (any one), never a plain text answer. | You always want a structured/tool action this turn. |
{"type":"tool","name":"X"} | Claude must call the named tool X. | Forcing a specific extraction / structured output. |
{"type":"none"} | Claude may not use any tool this turn. | Force a natural-language turn even though tools exist. |
any and tool guarantee a tool call this turn but say nothing
about which round it is — they don't stop the loop, so pair them with your own exit condition to avoid re-forcing a
tool forever.tool_choice composes with disable_parallel_tool_use. Combining
{"type":"any", "disable_parallel_tool_use": true} means "call exactly one tool, no parallelism" — a common
pattern for forcing a single deterministic structured step.DIAGRAM Where the dial sits
no tools this turn"] --> A["auto
Claude decides"] A --> Y["any
must use SOME tool"] Y --> T["tool: X
must use tool X"] N -. more model freedom .-> A T -. more your control .-> Y classDef free fill:#d4edda,stroke:#28a745,color:#155724; classDef mid fill:#d1ecf1,stroke:#17a2b8,color:#0c5460; classDef ctrl fill:#e2d4f0,stroke:#764ba2,color:#3d1a5b; class N free; class A,Y mid; class T ctrl;
CODE The four variants (plus the combo)
# 1) auto — the default; omit tool_choice or set it explicitly. client.messages.create(model="claude-opus-4-8", max_tokens=1024, tools=TOOLS, messages=msgs, tool_choice={"type": "auto"}) # 2) any — Claude MUST call some tool (no plain-text answer this turn). client.messages.create(model="claude-opus-4-8", max_tokens=1024, tools=TOOLS, messages=msgs, tool_choice={"type": "any"}) # 3) tool — force ONE specific tool (e.g. structured extraction). client.messages.create(model="claude-opus-4-8", max_tokens=1024, tools=TOOLS, messages=msgs, tool_choice={"type": "tool", "name": "extract_invoice"}) # 4) none — tools exist but Claude may NOT use them this turn. client.messages.create(model="claude-opus-4-8", max_tokens=1024, tools=TOOLS, messages=msgs, tool_choice={"type": "none"}) # Combo: force exactly one tool, no parallel fan-out. client.messages.create(model="claude-opus-4-8", max_tokens=1024, tools=TOOLS, messages=msgs, tool_choice={"type": "any", "disable_parallel_tool_use": True})
{"type":"tool","name":…} to turn a tool into a
structured-output contract — Claude is guaranteed to emit that tool's schema-shaped input,
which you parse instead of scraping free text.EXAM TRAPS
any /
tool force a tool every turn they're set. If you leave them on across the whole loop, Claude can
never emit end_turn — an infinite tool-call loop. Force on the first turn, then drop back to
auto.any with tool. → any = "some tool";
tool = "this named tool." Only tool takes a name.any. → Under any/tool
Claude won't produce a plain-text reply that turn; if you need prose, use auto or
none.PRACTICE
Q1 · You need every response to be a JSON object matching one schema. Which tool_choice?
{"type":"tool","name":"<your_schema_tool>"}. Forcing that specific tool guarantees
Claude emits its schema-shaped input, which you use as structured output.
Q2 · Your agent got stuck calling tools forever. You had set tool_choice to any. Fix?
Stop forcing a tool on every turn. Use any/tool only where you truly need a
forced call (often just the first turn), then switch to auto so Claude can decide to finish with
end_turn.
Q3 · You want Claude to summarize in prose this turn even though tools are attached. Which setting?
{"type":"none"} — tools stay defined for later turns, but Claude may not call any this
turn, so it produces a text answer.