disable_parallel_tool_use: Forcing One Tool Call Per Turn

The Default: Parallel Tool Calls

Current Claude models default to requesting multiple independent tool calls in a single turn whenever the subtasks don't depend on each other -- Claude emits several `tool_use blocks in one assistant turn, your code executes them concurrently, and you return all the corresponding tool_result blocks together in a single follow-up user` message. This is a throughput win: three independent lookups don't need three separate round trips.

When Parallel Calls Are the Wrong Default

Parallelism assumes independence, and not every pair of tool calls is independent. When one tool's output feeds the next call's arguments -- the second call literally cannot be constructed until the first result comes back -- the calls have a real sequential dependency, and letting the model issue them as if they were parallel produces malformed or nonsensical arguments for the second call. The fix at the schema/request level is disable_parallel_tool_use: set it to force the model to request at most one tool call per turn, so a genuine dependency is modeled as separate turns instead of a single batch of blocks.

Where It's Set

disable_parallel_tool_use is a boolean set alongside `tool_choice` in the request. It doesn't change what any individual tool does -- it changes the model's calling *cadence*, forcing strict sequencing.

The Two Reasons to Reach for It

1. Genuine sequential dependency -- each tool call's result determines the next call's arguments, so batching them in parallel would require guessing at inputs that don't exist yet.
2. An auditability or replay invariant -- some systems require a strict one-call-per-turn trace for logging, replay, or compliance reasons, independent of whether the calls are logically independent. Forcing single-call turns gives a clean, linear execution trace to audit.

Common exam traps

• Assuming parallel tool calling is always beneficial and never needs to be turned off. A real dependency between calls is exactly the case where forcing sequential calls prevents malformed arguments.
• Confusing disable_parallel_tool_use with `tool_choice itself -- tool_choice controls whether/which tool must be called; disable_parallel_tool_use` controls how many calls can appear in a single turn.
• Assuming the fix for a sequential-dependency bug is a better tool description. Description quality drives *which* tool gets picked; it does not prevent the model from batching two calls that have a genuine ordering dependency -- that's what disable_parallel_tool_use is for.