Tool Use Flow & Mechanics
CoreDesign and implement agentic loops for autonomous task execution · Difficulty 2/5
Explanation
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_resultcontent 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
withname,id, andinput`
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
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.
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.
Related Concepts