D1 · Agentic Architecture › Cluster 3 · Tool Use

3.3 · Parallel Tool Calls

Multiple tool_use blocks in one turn — run all, return all

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).

AspectSequential (default per round-trip)Parallel (fan-out)
tool_use blocks per turnOne at a timeMany in one response
Round-trips for N independent callsN1
LatencySum of all callsMax of the calls (if run concurrently)
Ordering guaranteeStrict, deterministicNo inter-call ordering
🔑 To force at most one tool per response, add "disable_parallel_tool_use": true to tool_choice. That trades throughput for strict, one-at-a-time determinism.
All results still go back in one user message with matching tool_use_ids. Parallel execution changes how you run the tools, not the contract for returning them.

DIAGRAM Fan-out, then converge

flowchart TD A([One assistant turn]) --> B["tool_use #1
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: true for strict, one-at-a-time steps
Rule of thumb: allow parallel for independent reads; disable it when tools have ordering or side-effect dependencies (do X, then decide Y based on X's result).

EXAM TRAPS

Trap: Assuming one 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.
Trap: Returning parallel results in multiple user messages. → Still one user turn with all tool_result blocks; the 3.2 contract doesn't relax for parallel calls.
Trap: Relying on inter-call order under parallel use. → There is no ordering guarantee between parallel tool_use blocks. If order matters, use 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.