Handling Claude Tool Calls: The Agentic Loop, Errors, and Approvals

1.The harness loop: dispatching client tool calls

Claude can't run your code, so every client tool call is a round trip. Claude asks, your harness runs the tool, and you report back. The standard harness is a while loop keyed on stop_reason. The loop exits on any other stop reason (end_turn, max_tokens, stop_sequence, refusal), and your application should handle each of those.

For each tool_use block, dispatch on name, pass in input, and keep the id. Blocks from the computer use or browser use toolsets also carry a toolset_name, so dispatch those on both fields. If you'd rather not write the loop yourself, the SDK's Tool Runner runs your tools and sends the results back automatically.

tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")

# Run the tool, then send the result back in a tool_result block.
weather = "15 degrees Celsius, partly cloudy"  # your weather lookup goes here
messages += [
    {"role": "assistant", "content": response.content},
    {
        "role": "user",
        "content": [
            {"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
        ],
    },
]

Sources123

2.Formatting tool_result blocks

A tool result goes in a user message as a tool_result block. tool_use_id is required and matches the id of the request it answers. content is optional. It can be a plain string, or a list of text, image, document, or search_result blocks, so a tool can return a caption and a screenshot together. You may leave content out entirely. Results for toolset members are stricter: they must echo the same toolset_name, and the API rejects a member result without it.

Sources2

3.Error handling: execution failures versus invalid calls

There are two kinds of failure. In an execution error, the tool itself fails, for example the weather API returns HTTP 500. Return the error message as the content with is_error: true, and Claude will work the failure into its reply to the user. In an invalid call, Claude's request is malformed, for example a required parameter is missing. That usually means the definition didn't give Claude enough to go on. During development, the fix is a more detailed description. At runtime, you can return an is_error result that names the problem, and Claude will retry 2–3 times with corrections before apologizing. Strict tool use stops schema violations before they happen.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      " ? ": true
    }
  ]
}

Sources2

4.Server tools at runtime: pause_turn and mixed turns

Server tools run their own loop inside Anthropic's infrastructure. In the response, they appear as server_tool_use blocks whose ids start with srvtoolu_, each followed by its result block. You never send a tool_result for them, and server tool errors are handled transparently, so there's no is_error to manage. Two exceptions hand control back to you. First, the server loop has an iteration cap. When Claude hits it, you get pause_turn: re-send the paused response as-is with the same tools, and repeat with a cap on continuations. Second, Claude may call a server tool and a client tool in the same parallel group. Then you get tool_use with a server_tool_use block that has no matching result. Send only the client tool_result blocks and keep the same tools array. The API then runs the deferred server tool.

Sources41

5.Approval patterns: deciding which calls may run

Claude only ever sends a request, and your code runs every client tool. That makes your harness the natural place to approve or block calls. The Agent SDK builds this in with permission modes, hooks, and declarative allow/deny rules. Hooks run custom code that can allow, deny, or modify a tool request. Allow rules such as allowed_tools=["Read", "Grep"] auto-approve the tools they list. Unlisted tools still exist, and their calls fall through to the permission mode and the canUseTool callback. A disallowed_tools entry is a different thing: it removes the tool definition from the request entirely. When no earlier step settles a call, canUseTool asks the user at runtime.

      // Return allow or deny based on user's response
      if (response.toLowerCase() === "y") {
        // Allow: tool executes with the original (or modified) input
        return { behavior: "allow", updatedInput: input };
      } else {
        // Deny: tool doesn't execute, Claude sees the message
        return { behavior: "deny", message: "User denied this action" };
      }

Sources51

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Server tools need a tool_result from you, and is_error handling just like client tools.Why is that wrong?

   The API runs server tools itself and puts their result blocks in the same response. Server tool errors are handled transparently.

   Covered in Server tools at runtime: pause_turn and mixed turns

2. 2.When a server tool hasn't run yet, the response is always pause_turn, so you re-send it as-is.Why is that wrong?

   If Claude also called a client tool, the API returns tool_use without running the server tool, and you continue by sending the client tool_result blocks.

   Covered in Server tools at runtime: pause_turn and mixed turns

3. 3.Leaving a tool out of allowed_tools blocks Claude from using it.Why is that wrong?

   allowed_tools only auto-approves. Unlisted tools still exist and fall through to the permission mode and canUseTool. To remove a tool, use disallowed_tools.

   Covered in Approval patterns: deciding which calls may run