Certopolis

Claude Certified Architect – Foundations

Parallel tool use and disable_parallel_tool_use

Claude can return several tool_use blocks in one response, and parallel tool use is on by default. Send every tool_result back together in one user message, and set disable_parallel_tool_use: true inside tool_choice if you want one call at a time.

Running the calls

When a response has stop_reason: "tool_use", it can hold more than one tool_use block. The API does not set an execution order. You can run the calls concurrently, sequentially in the order they appear, or a mix. Independent read-only lookups are usually safe to run in parallel. Calls with side effects or ordering needs are better run one after another.

Whatever you choose, return one tool_result per tool_use block, all in the next user message, each matched by tool_use_id and placed before any text. If you skip a call, for example because an earlier one failed, still return a result for it with is_error: true and a short reason.

Why Claude stops calling in parallel

The most common cause is the message history. If your loop sends each result in its own user message, the transcript shows a one-call-per-turn pattern and Claude learns to follow it. The fix is to collect the results for a turn and send them in a single user message. A stronger system prompt can also raise how often Claude batches calls. If calls in one batch depend on each other, add a system prompt line such as "Only batch tool calls that are independent of each other."

Turning it off

Set disable_parallel_tool_use: true inside the tool_choice object, for example {"type": "auto", "disable_parallel_tool_use": true}. It is not a top-level request parameter. With auto, Claude calls at most one tool per response and can still answer in plain text. With any or tool, Claude calls exactly one tool.

This suits flows where one pending call at a time keeps approval or auditing simple, such as an agent that can run destructive operations.

Where the exam catches people

  • Believing disable_parallel_tool_use is a top-level parameter: it only works inside the tool_choice object.
  • Believing parallel calls need to be switched on: they are on by default, and splitting results across messages is what makes Claude stop.
  • Believing a failed or skipped call can be dropped from the reply: every tool_use needs a tool_result, with is_error: true for failures.
  • Believing the calls in one response must run concurrently: the API sets no order, and running them sequentially is valid.

Written from Anthropic's documentation

Try 3 questions on this

Pick an answer to see why each option is right or wrong.

  1. Your agent's traces show Claude calling three read-only tools in one turn. You send three separate user messages, one per tool_result. Over time Claude stops issuing parallel calls and reverts to one call per turn. What change would most effectively resolve the issue?

    Right. In the game that’s Renown for your Tool Design, MCP and Server Tools building.

    Not that one: B is right. In the game your Tool Design, MCP and Server Tools building would lose a little Renown, and this question would come back later.

    Show the full explanation and doc quotes

    Splitting them across separate messages reshapes the conversation into a serial pattern, and the model learns from that history to stop calling tools in parallel.

    Written from platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use

  2. Your operations agent on Claude Opus 5 (claude-opus-5) may issue destructive infrastructure calls. Approval routing is simplest when at most one tool call is pending at a time, so you want to stop the model requesting several tools in one response, while still letting it choose freely which tool to call. You add disable_parallel_tool_use: true as a top-level request parameter and see no change in behaviour. Which approach should you take?

    Right. In the game that’s Renown for your Tool Design, MCP and Server Tools building.

    Not that one: D is right. In the game your Tool Design, MCP and Server Tools building would lose a little Renown, and this question would come back later.

    Show the full explanation and doc quotes

    Combining it with {"type":"auto"} preserves the model's freedom to pick a tool or to answer directly while guaranteeing at most one pending call per turn. A top-level key of the same name is simply ignored.

    Written from platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use

  3. Your agent on Claude Opus 5 (claude-opus-5) used to receive three tool_use blocks per turn. A refactor made the client execute them sequentially and send each tool_result in its own user message, and drop any block whose tool raised. Over the following weeks the model degenerated to one tool call per turn and occasionally re-invokes a tool that had already failed. You propose adding disable_parallel_tool_use: true at the top level of the request. What change would most effectively address this issue?

    Right. In the game that’s Renown for your Tool Design, MCP and Server Tools building.

    Not that one: A is right. In the game your Tool Design, MCP and Server Tools building would lose a little Renown, and this question would come back later.

    Show the full explanation and doc quotes

    Every tool_result for a turn belongs in a single user message, and a failure is reported with is_error: true on its tool_result rather than by omitting the block.

    Written from platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use