Session 3 / 6 — API

Tool Use API & Agentic Loop

The Tool Use API is the low-level mechanism behind all multi-agent patterns. Understanding tool_choice, stop_reason, and tool structure is essential for the technical questions on the exam.

Write the full structure of a tool (name, description, input_schema)
Distinguish the 3 tool_choice modes: auto, any, tool-specific
Understand the agentic loop and its 2 exit conditions
Know when stop_reason is "end_turn" vs "tool_use"
Choose the right model for each use case (Haiku/Sonnet/Opus)

Exercise 1

Tool Structure — The 3 Required Components

Objective: write a complete tool with name, description, and input_schema. The description is often underestimated — it guides Claude in deciding whether to use the tool.

Ask Claude to create a complete tool and explain what it must cover:

💬 Type in Claude Code

Write the complete definition of a tool for the Anthropic API that allows searching for products in a catalog. The tool must have: - An explicit name - A description that specifies WHEN to use it (not just what it does) - A JSON Schema input_schema with at least 3 parameters including 1 optional with a default value - Descriptions for each parameter Then explain why the tool description is critical for Claude to use it correctly.

✅ Expected structure

{
  "name": "search_products",
  "description": "Searches products... Use this tool when...",
  "input_schema": {
    "type": "object",
    "properties": { ... },
    "required": [...]
  }
}

Dig deeper into the description question:

💬 Type in Claude Code

A developer wrote a tool with this description: "Searches products". What problems can this overly vague description cause? Rewrite it optimally, specifying when to use the tool, when NOT to use it, and the format of the inputs.

💡 Rule on descriptions

A tool description = the instruction to Claude for deciding WHEN to call it. It must include: what the tool does, when to use it, when NOT to use it (frequent ambiguities), and constraints on inputs. Without this, Claude may over-use or ignore it.

Exercise 2

tool_choice — The 3 Modes and Their Effects

Objective: concretely understand what each tool_choice value does and when to use it.

Explore the 3 modes:

💬 Type in Claude Code

Explain the 3 values of tool_choice in the Anthropic API with a concrete example for each: 1. {"type": "auto"} 2. {"type": "any"} 3. {"type": "tool", "name": "search_products"} For each mode, describe: what Claude does, an appropriate use case, and a case where this mode would be a bad idea.

✅ Expected answers auto: Claude decides (tool or text). any: Claude MUST use a tool (at least one from those available). tool: Claude MUST use THAT specific tool.

Practical choice scenario:

💬 Type in Claude Code

For these 3 scenarios, which tool_choice would you use and why? 1. A chatbot that can respond in text OR call a weather API if the user mentions weather 2. A structured data extraction pipeline where the response MUST be in JSON via a tool 3. An agent that must always start by calling a "get_user_context" tool before responding

⚠️ Exam Trap

"tool_choice: any guarantees Claude will use all available tools" → FALSE. any guarantees that at least ONE tool will be called, not all. Claude chooses which one is most appropriate among the available tools.

Exercise 3

Agentic Loop — stop_reason and Exit Conditions

Objective: understand the complete agentic loop cycle and the 2 stop_reason values that drive it.

Visualize the agentic loop:

API Call

→

Claude responds

→

stop_reason?

→

tool_use → execute tool

→

Return result

↻ loop

stop_reason

→

end_turn → EXIT

💬 Type in Claude Code

Describe precisely the agentic loop of the Tool Use API: 1. What are the 2 possible values of stop_reason that relate to tools? 2. For which value does the loop continue? 3. For which value does the loop end? 4. What must the "tool" message contain that we send back to the API after executing a tool? 5. What happens if you implement a loop without an exit condition?

✅ Expected answers tool_use → continue (execute the tool, send back the result). end_turn → exit (Claude finished without wanting a tool). The tool message must include tool_use_id + content of the result.

💡 Agentic loop summary

API call → Claude responds. If stop_reason: "tool_use": execute the tool(s), send back results, loop again. If stop_reason: "end_turn" AND no tool_use in the response: end of loop, final response to user.

Exercise 4

Claude Models — Choosing Haiku, Sonnet, or Opus

Objective: master the exact model IDs and their positioning (speed/cost vs capability). Frequent exam questions.

Learn the exact IDs and use cases:

💬 Type in Claude Code

Give me a summary table of available Claude models with: - The exact model ID (the one to use in the API) - The family (Haiku / Sonnet / Opus) - The positioning (speed+cost vs capability) - 2 typical use cases for each - The case where you should NOT use it

✅ IDs to remember claude-haiku-4-5-20251001 — speed/volume. claude-sonnet-5 — balance. claude-opus-5 — complex reasoning. claude-fable-5-1 — storytelling.

Positioning test: find the right model:

💬 Type in Claude Code

For each of these use cases, which Claude model would you choose and why? 1. Router in a multi-agent system: classify the request type (among 5 categories) 2. Senior analyst: audit a complex microservices architecture and identify flaws 3. Support agent: respond to 10,000 tickets/day with templated responses 4. Creative writer: write an interactive novel with coherent narrative arcs

✅ Expected answers 1→Haiku (simple classification, volume), 2→Opus (complex reasoning), 3→Haiku (volume, simple responses), 4→Fable (storytelling).

⚠️ Exam Trap

"Opus is always the best choice" → FALSE. Opus is the most expensive and slowest. For simple or high-volume tasks, Haiku is superior (cost/performance ratio). Multi-agent architectures often use Haiku for routing and Opus only for complex tasks.