CONCEPT One parameter, four modes
The tool_choice parameter controls whether Claude may, must, or
must not call a tool on this turn. It has four values:
| Value | Effect | Default when… |
|---|---|---|
{"type": "auto"} | Claude decides whether to use any tool or answer directly | …tools are provided |
{"type": "any"} | Claude must use one of the provided tools (any of them) | — |
{"type": "tool", "name": "x"} | Claude must use the specific named tool | — |
{"type": "none"} | Claude cannot use any tool | …no tools are provided |
any and tool force a tool call —
auto merely allows one. Use forcing when the task must route through a tool (e.g.
structured extraction); use auto for conversational agents that should answer directly when they
can.CONCEPT Forcing prefills the assistant — no preamble
When tool_choice is any or tool, the API prefills the
assistant message to force a tool call. The consequence: Claude emits the tool_use
block directly, with no natural-language text before it — even if you asked it to
explain first.
tool_choice: auto
and instruct in the user message: "…Use the get_weather tool in your response." That
preserves the natural-language preamble while still steering the choice.any and
tool are not supported and return an error — only auto and
none are compatible. Some models (e.g. Mythos Preview) also reject forced tool use with a 400.DIAGRAM How each mode routes the turn
tool OR direct answer"] M -->|"any"| B["Must call SOME tool
(prefilled → no preamble)"] M -->|"tool: name"| C["Must call THAT tool
(prefilled → no preamble)"] M -->|"none"| D["No tools — answer directly"] classDef allow fill:#e7f1ff,stroke:#4a90d9,color:#1a3a5a; classDef force fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef off fill:#f1f3f5,stroke:#adb5bd,color:#495057; class A allow; class B force; class C force; class D off;
CODE Forcing a specific tool
Force get_weather, and separately cap the turn to one tool call with
disable_parallel_tool_use (valid on any tool_choice).
resp = client.messages.create( model="claude-opus-4-8", max_tokens=1024, tools=tools, # Force THIS tool. Claude emits tool_use with no text preamble. tool_choice={"type": "tool", "name": "get_weather"}, messages=[{"role": "user", "content": "Weather in Paris?"}], ) # "any" forces SOME tool; add disable_parallel_tool_use to # cap the turn to at most one tool call. resp = client.messages.create( model="claude-opus-4-8", max_tokens=1024, tools=tools, tool_choice={"type": "any", "disable_parallel_tool_use": True}, messages=[{"role": "user", "content": "Book a flight to Tokyo."}], ) # "none" forbids tools entirely — Claude answers directly. resp = client.messages.create( model="claude-opus-4-8", max_tokens=1024, tools=tools, tool_choice={"type": "none"}, messages=[{"role": "user", "content": "Just chat with me."}], )
TRADE-OFFS Force a tool vs. let Claude choose
✅ any / tool (force)
- Guarantees the turn routes through a tool — good for pipelines & extraction
- Pair with
strict: trueto also guarantee schema-valid input - Deterministic control flow
⚠️ Cost of forcing
- No natural-language preamble (prefilled assistant turn)
- Incompatible with extended thinking
- Can push a tool call where a direct answer was better → use
autofor chat
EXAM TRAPS
any forces a specific tool." → No —
any forces some tool (Claude picks which). Use {"type": "tool", "name": …}
to force a particular one.any/tool. → Forcing
prefills the assistant, so Claude jumps straight to tool_use with no explanation. Use
auto + a user-message instruction if you want both.any and
tool are not supported with extended thinking and error out; only auto and
none work.auto is the default when
tools are provided; none is the default when no tools are provided.PRACTICE
Q1 · Which tool_choice values force a tool call, and what's the difference?
any and tool. any forces Claude to use one of
the provided tools (its pick); {"type": "tool", "name": "x"} forces that specific tool.
auto only allows a call; none forbids all tools.
Q2 · Why does forcing a tool suppress Claude's usual explanation text?
Because any/tool prefill the assistant message to force a
tool call, so the response begins with the tool_use block — no natural-language preamble. To
keep an explanation, use tool_choice: auto and ask for the tool in the user message.
Q3 · You have tools defined but pass no tool_choice. What happens?
The default is {"type": "auto"} whenever tools are provided — Claude decides
per turn whether to call a tool or answer directly. (With no tools provided, the default is
none.)