ModelRefs / Function Calling & Tool Use — Tutorial
Function Calling & Tool Use — Tutorial
Define tools, parse tool calls, execute them, and return results — the complete round-trip with the Anthropic API. Covers How tool use works in the API.
Overview
Define tools, parse tool calls, execute them, and return results — the complete round-trip with the Anthropic API
Level: Advanced. Estimated reading time: 35 minutes.
How tool use works in the API
When you define tools in an API call, the model can respond with a tool_use content block instead of text. You execute the tool, send the result back, and the model continues its response.
The round-trip: 1. You send: user message + list of tool definitions (JSON schema) 2. Model responds with: tool_use block containing {name, input} 3. You execute the tool with the provided inputs 4. You send back: tool_result block with {tool_use_id, content} 5. Model continues: either calls another tool or gives the final text answer
The model never actually calls your function. It outputs structured JSON describing what to call, and you execute it. This architecture means: you control execution, you can validate inputs, you can enforce permissions.
Tools can be chained: the model might call search_web, then parse_date_from_result, then compute_days_until. Each round-trip gives you the opportunity to intercept and modify.
Defining tools with JSON Schema
Each tool definition has: name (snake_case), description (what it does and when to use it — the model reads this), and input_schema (JSON Schema specifying the parameters).
The description is critical. The model chooses which tool to call based on its description. Be specific: "Search the web for current information. Use when the question requires real-time data or post-training knowledge." vs "Search the web."
Input schema: type: "object", properties (each with type, description, optional enum/minimum/maximum), and required list. The model will attempt to construct valid inputs from the user's message — detailed property descriptions help it do this correctly.
Validation: always validate tool inputs on your side before executing. The model sometimes constructs slightly wrong inputs for edge cases.
Parallel tool use and forced tool choice
Claude can call multiple tools in one response (parallel tool use). If you ask "What's the weather in Paris and Tokyo?", it may return two tool_use blocks in the same response. You execute both, return both results, and it answers once.
tool_choice parameter controls when tools are used: - {"type": "auto"}: model decides (default — uses tools when helpful) - {"type": "any"}: model must call at least one tool - {"type": "tool", "name": "get_weather"}: model must call this specific tool
Force tool use when: you're extracting structured data from text (force a format_data tool), running a test harness that needs the model to always use a specific tool, or building a pipeline where you need structured output regardless of the input.
Continue your research
Use these connected ModelRefs sections to compare alternatives, inspect implementation paths, and review the evidence and governance boundaries relevant to Function Calling & Tool Use — Tutorial.