How do you reply when Claude emits multiple tool_use blocks at once?

## What parallel tool use is When Claude sees that several independent facts are needed to answer, it can request them all in a single assistant turn: the `content` array comes back with two, three or more `tool_use` blocks, each with a distinct server-generated `id`, its own `name`, and its own `input`. There may be a leading `text` block too. `stop_reason` is `tool_use`, exactly as for a single call — the count is not signalled anywhere except in the array itself, so your handler must iterate rather than reach for the first block. This is default behaviour on current Claude models, not something you opt into. ## The reply contract One assistant turn with N `tool_use` blocks is answered by **one** user turn containing N `tool_result` blocks. That is the whole rule, and each half of it matters. *All of them.* Every `tool_use` in the immediately preceding assistant message must have a matching `tool_result`. Answering a subset produces a 400. There is no mechanism for deferring a call to a later turn — if you genuinely cannot run one now, return a result saying so and let the model decide what to do. *In one message.* Splitting results across multiple consecutive user messages is malformed, because the API expects the results to answer the immediately preceding assistant turn. Even where a client library papers over the structure, the conversation Claude sees then implies that batched calls come back awkwardly, and the model drifts toward one-call-at-a-time behaviour on later turns — you lose the latency benefit without any error telling you why. Order within the array does not have to match the order of the `tool_use` blocks; the `tool_use_id` join is what pairs them. ## Execute concurrently The calls are independent by construction — Claude batched them precisely because none depends on another's output. Running them sequentially throws away the benefit: three 400 ms lookups become 1.2 s instead of 400 ms. Use a thread pool, `asyncio.gather`, `Promise.all`, or whatever your runtime offers, then assemble the results array once everything has settled. Use a settle-all primitive rather than a fail-fast one, because a single failure must not discard the other results — they still have to be reported. ## Partial failure Mixed outcomes are the normal case, not an edge case. Two calls succeed, one times out: send all three blocks, with the failed one carrying `"is_error": true` and a message the model can act on. Claude then typically answers from what succeeded and either retries the failure or tells the user which part is missing. Dropping the failed block breaks the request; replacing all three with an apology text message throws away work you already paid for. ## Bounding the fan-out Parallel calls multiply everything at once: concurrent load on your downstream services, tokens returned into the context, and blast radius if the tools have side effects. Three concurrent read-only lookups are free money. Three concurrent writes against the same row are a race you did not design. The lever is `"disable_parallel_tool_use": true`, set inside whichever `tool_choice` object you send; it caps each response at one `tool_use` block, trading round trips for serialisation. Apply it when the tool surface mutates shared state, when a human approves each call, or when downstream rate limits are tight enough that a burst is worse than a queue. ## Timeouts and the slowest call A batch finishes when its slowest member does, so one tool with a pathological tail latency sets the pace for the whole turn and, in a long loop, for the whole agent. Give each tool its own timeout well below the request timeout and convert a breach into an error result rather than letting it hang — a fast "timed out" that Claude can route around beats a turn that stalls. ## Idempotency Because a model may retry a call after an error result, and because your own code may retry on a transient failure, side-effecting tools should be idempotent or carry a caller-supplied key. Parallel fan-out makes duplicate execution more likely, not less, since a partially failed batch invites exactly the retry that duplicates the successful half.