D1 · Agentic Architecture › Cluster 3 · Tool Use

3.4 · tool_choice as a Control Lever

auto · any · tool · none — steering when and whether Claude uses tools

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.

SettingMeaningUse 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

flowchart LR N["none
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})
Common architect pattern: use {"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

Trap: Forcing a tool inside the agent loop and never releasing it. → 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.
Trap: Confusing any with tool. → any = "some tool"; tool = "this named tool." Only tool takes a name.
Trap: Expecting a text answer under 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.