D2 · Tool Design & MCP › Cluster 4 · Advanced Tool Use

4.5 · tool_choice Control & Parallel Toggle

Steer selection precisely

CONCEPT Four values of tool_choice

tool_choice decides whether and which tool Claude calls. There are exactly four values:

ValueBehaviorDefault when…
{"type":"auto"}Claude decides whether to call any tooltools 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 toolno 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.

⚠️ Two constraints from earlier clusters: with extended thinking (4.1) only 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:

🔑 "Force exactly one tool call" = a forcing choice (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

flowchart TD Q{"Do you need a tool called?"} -->|"maybe — let Claude decide"| AUTO["auto (default)"] Q -->|"yes, but Claude picks which"| ANY["any"] Q -->|"yes, this specific tool"| TOOL["tool + name"] Q -->|"no tools this turn"| NONE["none"] ANY --> P{"Exactly ONE call?"} TOOL --> P P -->|"yes"| ONE["🟢 add disable_parallel_tool_use: true"] P -->|"parallel ok"| MANY["🔵 leave default (multiple allowed)"] AUTO --> TH{"Thinking on?"} NONE --> TH TH -->|"auto / none only"| OKT["🟢 compatible with thinking"] ANY -.->|"errors with thinking"| BADT["🔴 any/tool + thinking = error"] TOOL -.-> BADT classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef mid fill:#cce5ff,stroke:#4a90d9,color:#0a3a6a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class ONE ok; class OKT ok; class MANY mid; class BADT bad;

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
Leave parallel on for independent reads; disable it when a turn must produce exactly one action (e.g. a single gated, irreversible call, or a structured-extraction turn).

EXAM TRAPS

Trap: Thinking 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.
Trap: Putting disable_parallel_tool_use at the top level of the request. → It's a field inside tool_choice, not a top-level parameter.
Trap: Using tool_choice: any or tool while extended thinking is on. → Errors — thinking permits only auto and none (see 4.1).
Trap: Expecting spoken text before a forced tool call. → 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.