The Tool-Use Loop: tool_use, tool_result, and Who Executes

Core

Implement tools and understand the function-calling loop · Difficulty 1/5

tool-usefunction-callingtool-resultagentic-loop

Explanation

How Tool Use Works

Tool use (function calling) follows a fixed loop:

You send a request with a tools array; each tool has a name, a description, and an input_schema (JSON Schema).
If Claude decides it needs a tool, it responds with `stop_reason: "tool_use" and a tool_use block containing the tool's name and the input` arguments.
Your code executes the tool -- Claude never runs it itself -- and you return the result as a `tool_result block inside a new user message, matched to the request by tool_use_id`.
Claude uses the result to continue the turn, possibly calling more tools, until it reaches end_turn.

Client-Side vs. Server-Side Tools

*Client-side* tools are the default pattern: your application executes the tool. *Server-side* tools run within Anthropic's own infrastructure (certain built-in tools). Knowing which category a given tool falls into determines who is responsible for execution and where the code that implements it lives.

Agentic Harness Dispatch and Approval

In an agent, a dispatcher maps each `tool_use` name to the corresponding function and runs it. For sensitive or destructive tools, an approval pattern requires human or hook-based sign-off before the tool actually executes.

Common exam traps

"Claude executes the tool." False -- Claude only *requests* a tool call by emitting a `tool_use` block; your code runs it and returns the result.
Forgetting to feed the `tool_result back with the matching tool_use_id` -- without it, the loop cannot continue and Claude has no way to use the outcome of the call.
Assuming all tools are client-side; some built-in tools execute server-side within Anthropic's infrastructure.

Key Takeaways

The loop is: send tools array -> Claude emits a tool_use block (name + input) -> your code executes it -> you return a tool_result matched by tool_use_id -> Claude continues or ends the turn
Claude never executes a tool itself; it only requests the call, and your application code is what actually runs it
Client-side tools are executed by your app (the default); server-side tools run within Anthropic's infrastructure
Sensitive or destructive tools should sit behind an approval pattern (human or hook-based) before executing

Glossary Terms

Content Block

The structured units that make up Claude's response. Types include: `text` (plain text response), `tool_use` (a request to call a tool with specific inputs), `tool_result` (the caller's response to a tool request), and `thinking` (internal reasoning when extended thinking is enabled). A single response can contain multiple content blocks of mixed types.

tool_choice

API parameter controlling how Claude selects tools. 'auto' (default): Claude decides whether to use tools. 'any': Claude must use at least one tool. 'none': Claude cannot use tools. '{type: tool, name: X}': Claude must use the specific named tool. Used to force structured output via a schema tool.

tool_result

A content block type in the user message that returns the output of a tool execution back to Claude. Must include the 'tool_use_id' matching the original tool_use block. Can be text, images, or error messages. Claude processes the result and continues reasoning.

tool_use

A content block type in Claude's response indicating the model wants to call a specific tool. Contains 'id', 'name', and 'input' fields. The agent must execute the tool and return results in a tool_result content block for the conversation to continue.

Related Concepts

Writing Good Tool Definitions: Descriptions, Schemas, and Errors

Tool description quality -- what it does, when to use it, what each parameter means -- is the top driver of correct tool selection