Skip to content
Clawdemy

Summary: Tool use, the foundation

Phase 2 opens. The jump from one-shot calls (lessons 1-3) to letting Claude reach beyond its training corpus through function calls. A tool definition is three fields: name (model uses to call), description (the model’s instruction manual; vague descriptions produce wrong calls), input_schema (JSON Schema for parameters). The four-step loop: (1) your app sends a request with the tools array, (2) the model returns stop_reason: tool_use and one or more tool_use content blocks carrying id / name / input, (3) your code executes the tool and assembles a tool_result content block with tool_use_id / content (and optional is_error), (4) you send a new request including the original messages, the full assistant turn from step 2, and a user message containing the tool_result; the model continues and typically finishes with stop_reason: end_turn. Two ordering rules the API enforces (both 400 on violation): tool_result must immediately follow tool_use in the message history; tool_result blocks come FIRST in their user message’s content array, any text comes AFTER. tool_choice controls how tools are used: auto (default), any (force a tool, model picks), tool (specific tool by name), none (tools defined but not usable this turn). Parallel tool calls are just multiple tool_use blocks in one response, with matching tool_result blocks in one fan-in user message. Errors use is_error: true with an instructive message per the docs (“Rate limit exceeded. Retry after 60 seconds.” gives the model context to recover; “failed” does not). Client tools (you execute) are this lesson; server tools (Anthropic executes; web_search, web_fetch, code_execution, tool_search) are lesson 5. Token cost overhead of tool use is a few hundred system-prompt tokens per the Tool use overview’s per-model table (with the any and specific-tool modes slightly higher than auto and none) plus the tools array tokens; lesson 7 (prompt caching) cuts the repeated cost. The primitive every Phase 2, Phase 3, and Phase 4 lesson extends.

Core ideas

Section titled “Core ideas”
  • Tool definition: three fields. name (dispatch key), description (the model’s instruction manual; specificity matters), input_schema (JSON Schema). Use required / enum / per-field description to constrain inputs.
  • Four-step loop: request with tools → model returns tool_use (with id, name, input) and stop_reason: tool_use → your code executes → you send tool_result (with tool_use_id, content, optional is_error) in a user message → model continues.
  • Two ordering rules. tool_result IMMEDIATELY after tool_use in the history; tool_result blocks FIRST in their content array, text AFTER. 400 error message when broken: “tool_use ids were found without tool_result blocks immediately after”.
  • tool_choice options. auto (default, model decides), any (force a tool, model picks), tool (specific tool by name), none (tools available but not usable).
  • Parallel tool calls. Multiple tool_use blocks in one response; one fan-in user message with N tool_result blocks matched by tool_use_id.
  • Error handling. is_error: true with instructive content. The model recovers from clear errors and retries 2-3 times on invalid tool inputs before apologizing.
  • Client tools (your code) vs server tools (Anthropic’s infra; web_search, web_fetch, code_execution, tool_search) vs Anthropic-schema client tools (your code, but with a canonical Anthropic schema you do not author; bash, computer use, memory, text_editor). Same declaration shape; different round-trip pattern. Lesson 5 of this track covers all of them.
  • Tool use vs structured outputs. Tool use is “model calls my code, I send result back, model continues.” Structured outputs (output_config: {format: {type: "json_schema", schema: {...}}}) is “model’s response conforms to a JSON schema.” Different features; both can combine via strict: true on tool definitions.
  • Token overhead. A few hundred tokens for the tool-use system prompt, varying by model per the Tool use overview’s table. The any and specific-tool modes are slightly higher than auto and none (the model commits to a tool call). Examples: Opus 4.8 290/410, Opus 4.7 675/804, Sonnet 4.6 / Opus 4.6 497/589. Plus the tools array tokens. Lesson 7 (prompt caching) cuts the repeated cost.

What changes for you

Section titled “What changes for you”

Before this lesson, your application could ask the model questions and get answers. After this lesson, your application can let the model act: look up data, query a database, hit an internal API, return a result the model uses to continue. The chat product becomes a builder product the moment the model can do something on the user’s behalf, not just talk about doing it. The single highest-leverage change this week: pick one feature where the model currently says “I do not have access to X” and add a client tool that gives it access. The lesson’s try-it-yourself walks the smallest version of that exercise; extend it to your real application by replacing get_weather with the actual function from your codebase. Phase 2 extends this primitive on every axis: lesson 5 lets Anthropic run general tools (web search, code execution); lesson 6 makes one tool definition portable across providers (Model Context Protocol); lesson 7 cuts the repeated-tools cost via caching. Phase 3 (lessons 8-11) turns one round-trip into a multi-step loop where the model and your tools talk back and forth until the task is done. Every subsequent T22 lesson sits on top of the four-step loop this lesson establishes.