Tool Use Flow & Mechanics

Core

Design and implement agentic loops for autonomous task execution · Difficulty 2/5

tool-usemechanicsapi

Tool use in the Claude API follows a structured request-response cycle that your application must implement.

The Tool Use Cycle

Define tools: Provide tool definitions in the API request

Claude selects a tool: Response includes `tool_use` content block with tool name and input

Execute the tool: Your application runs the actual tool/function

Return results: Send tool results back to Claude in a tool_result content block

Claude continues: Uses the results to generate its response or call more tools

Response Structure

When Claude wants to use a tool, the response contains:

`stop_reason: "tool_use"`

Content blocks of type `tool_use with name, id, and input`

Model-Driven vs Pre-Configured

The distinction matters for architecture:

Model-driven: Claude reasons about which tool to call next based on context. More flexible, adapts to novel situations.

Pre-configured: Fixed decision trees or tool sequences defined in code. More predictable, but less adaptable.

Parallel Tool Use

Claude can request multiple tools in a single turn. Return all tool results together before the next API call to minimize round-trips.

Key Takeaways

✓Tool use follows a define -> select -> execute -> return cycle
✓stop_reason 'tool_use' signals your app should execute the requested tool
✓Claude can request multiple tools in parallel to reduce round-trips
✓Model-driven tool selection adapts to context; pre-configured sequences are more predictable

Glossary Terms

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.

stop_reason

A field in the Claude API response indicating why the model stopped generating. Values: 'end_turn' (natural completion), 'max_tokens' (hit limit), 'stop_sequence' (hit custom stop), 'tool_use' (wants to call a tool). The primary signal for controlling agentic loops.