CONCEPT One assistant turn can request many tools at once
When several independent tools are needed, Claude doesn't have to serialize them across round-trips. It can emit
multiple tool_use blocks in a single response — a fan-out. Your job is to run them all
(ideally concurrently) and return every result in one user turn, as required by the
tool_result contract (3.2).
| Aspect | Sequential (default per round-trip) | Parallel (fan-out) |
|---|---|---|
| tool_use blocks per turn | One at a time | Many in one response |
| Round-trips for N independent calls | N | 1 |
| Latency | Sum of all calls | Max of the calls (if run concurrently) |
| Ordering guarantee | Strict, deterministic | No inter-call ordering |
"disable_parallel_tool_use": true to tool_choice. That trades throughput for strict,
one-at-a-time determinism.tool_use_ids. Parallel execution changes how you run the tools, not the contract for
returning them.DIAGRAM Fan-out, then converge
get_weather(Paris)"] A --> C["tool_use #2
get_weather(Tokyo)"] A --> D["tool_use #3
get_flights(...)"] B --> R1["tool_result id#1"] C --> R2["tool_result id#2"] D --> R3["tool_result id#3"] R1 --> U["🔵 ONE user turn
all 3 tool_result blocks"] R2 --> U R3 --> U U --> N([Next API call]) classDef fan fill:#e2d4f0,stroke:#764ba2,color:#3d1a5b; classDef conv fill:#d1ecf1,stroke:#17a2b8,color:#0c5460; class B,C,D fan; class U conv;
CODE Loop over every tool_use block
Collect all tool_use blocks, run them (here concurrently), and return all results in one user turn.
from concurrent.futures import ThreadPoolExecutor resp = client.messages.create( model="claude-opus-4-8", max_tokens=1024, tools=TOOLS, messages=messages, ) messages.append({"role": "assistant", "content": resp.content}) # Claude may return MANY tool_use blocks in this one turn. tool_uses = [b for b in resp.content if b.type == "tool_use"] # Run them concurrently — independent calls need not be serialized. with ThreadPoolExecutor() as pool: outs = list(pool.map(lambda tu: run_tool(tu.name, tu.input), tool_uses)) # Return ALL results in ONE user turn, ids matched to each tool_use. results = [{ "type": "tool_result", "tool_use_id": tu.id, "content": out, } for tu, out in zip(tool_uses, outs)] messages.append({"role": "user", "content": results}) # --- Force sequential (≤1 tool per response) when ordering matters --- resp = client.messages.create( model="claude-opus-4-8", max_tokens=1024, tools=TOOLS, messages=messages, tool_choice={"type": "auto", "disable_parallel_tool_use": True}, )
TRADE-OFFS Parallel speed vs. deterministic ordering
✅ Parallel fan-out
- Fewer round-trips → lower wall-clock latency
- Great for independent reads (multiple lookups, searches)
- Model batches naturally when calls don't depend on each other
⚠️ Costs / when to disable
- No ordering between calls — bad if one write must precede another
- Harder to reason about for side-effecting / stateful tools
- Set
disable_parallel_tool_use: truefor strict, one-at-a-time steps
EXAM TRAPS
tool_use block per response. → Claude can return
several in one turn; loop over all of them or you'll drop a call and 400 on the next request.tool_result blocks; the 3.2 contract doesn't relax for parallel calls.disable_parallel_tool_use: true.PRACTICE
Q1 · Claude returns 3 tool_use blocks but you only handle content[0]. What happens next call?
HTTP 400 — the next user turn is missing tool_results for two of the three
tool_use ids. Every tool_use in an assistant turn must be answered in the following single user turn.
Q2 · You need "book the flight, then charge the card in that order." Parallel or not?
Not parallel — those have an ordering/side-effect dependency. Set
tool_choice={"type":"auto","disable_parallel_tool_use": true} so Claude issues at most one tool per
response and you keep strict sequencing.
Q3 · Three independent city-weather lookups. Best pattern for latency?
Let Claude fan out three tool_use blocks in one turn, run them concurrently
(e.g. a thread pool), and return all three results in one user turn — one round-trip instead of three.