CONCEPT Four values of tool_choice
tool_choice decides whether and which tool Claude calls. There are exactly four values:
| Value | Behavior | Default when… |
|---|---|---|
{"type":"auto"} | Claude decides whether to call any tool | tools are provided |
{"type":"any"} | Claude must use one of the tools (its pick) | — |
{"type":"tool","name":"x"} | Claude must use tool x | — |
{"type":"none"} | Claude cannot use any tool | no tools provided |
With any or tool, the API prefills the assistant turn — Claude emits
no natural-language text before the tool_use block, even if asked to. To keep a spoken explanation,
use auto and put "use the X tool" in a user message.
auto and none are allowed — any/tool error. And forced choice
is incompatible with programmatic tool calling (4.4).CONCEPT disable_parallel_tool_use — force exactly one call
By default, a single assistant turn can contain multiple tool_use blocks (Claude
calls several tools at once). To force at most one tool call per turn, add
"disable_parallel_tool_use": true inside the tool_choice object — it's a flag on
tool_choice, valid with any of the four values.
Combine it with a forced choice to get a precise guarantee:
{"type":"any", "disable_parallel_tool_use": true}→ exactly one tool call, Claude picks which.{"type":"tool","name":"x","disable_parallel_tool_use": true}→ exactly one call, and it'sx.{"type":"auto","disable_parallel_tool_use": true}→ Claude may still choose zero tools, but never more than one.
any/tool)
plus disable_parallel_tool_use: true. any alone still permits multiple
parallel calls; the flag alone still permits zero.DIAGRAM Choosing the right control
CODE Force exactly one tool call
The flag lives inside tool_choice. Here any + the flag guarantees a single tool call
of Claude's choosing; swap in {"type":"tool","name":…} to also pin which tool.
resp = client.messages.create( model="claude-opus-4-8", max_tokens=1024, tools=[weather_tool, time_tool], tool_choice={ "type": "any", # must call a tool... "disable_parallel_tool_use": True, # ...and only ONE per turn }, messages=[{"role": "user", "content": "What's it like in Paris right now?"}], ) calls = [b for b in resp.content if b.type == "tool_use"] assert len(calls) == 1 # exactly one, guaranteed # For guaranteed shape too, pair with strict tools (4.2): # tool_choice={"type":"any","disable_parallel_tool_use":True} # + "strict": True on each tool → one call AND valid input. # NOTE: 'any'/'tool' are NOT allowed with extended thinking — auto/none only.
TRADE-OFFS Parallel calls vs. one-at-a-time
✅ Default (parallel allowed)
- Claude batches independent calls in one turn → fewer round trips
- Faster for read-only fan-out (several
grep/read)
⚠️ disable_parallel_tool_use: true
- Serializes — needed when calls have ordering or side-effect dependencies
- One gate/confirm at a time; predictable single-call turns
- Slower when calls are actually independent
EXAM TRAPS
any means "one tool." → any means "at least one,"
and it may still emit multiple parallel calls. Add
disable_parallel_tool_use: true to force exactly one.disable_parallel_tool_use at the top level of the request. →
It's a field inside tool_choice, not a top-level parameter.tool_choice: any or tool while extended thinking is
on. → Errors — thinking permits only auto and none (see 4.1).any and
tool prefill the assistant turn, so no natural-language precedes the tool_use block.PRACTICE
Q1 · How do you force Claude to make exactly one tool call?
Combine a forcing tool_choice ({"type":"any"} or
{"type":"tool","name":…}) with "disable_parallel_tool_use": true inside the same
tool_choice object. any alone can still emit multiple calls; the flag alone still allows
zero.
Q2 · Which tool_choice values are legal with extended thinking, and why?
Only auto and none. any and tool require
prefilling the assistant turn to force a tool, which conflicts with a leading thinking block — so they error when
thinking is on.
Q3 · Give one case for disabling parallel tool use and one for leaving it on.
Disable when calls are dependent or have side effects that must be ordered/gated
(one action per turn). Leave on for independent read-only fan-out (several read/grep)
where batching cuts round trips.