Claude Tool Use Guide: Schema, Loops, and Production

Tool use is the mechanism by which Claude transforms from a text generator into an active agent. This claude tool use guide walks through every layer of the pattern: how to define tools, how Claude selects them, how to close the agentic loop, and how to make the whole system production-reliable. These are also the patterns tested most heavily in the CCAR-F exam's two highest-weighted domains.

What is tool use in Claude, and how does the loop work?

Tool use lets Claude request the execution of functions you define. The model reads your tool definitions, decides whether to call one, emits a tool_use content block, and waits. Your code runs the function, returns a tool_result block, and the loop continues until Claude emits end_turn rather than tool_use.

The cycle is deterministic on your side: Claude never executes anything itself. It signals intent; you act.

Understanding stop_reason field inspection is the first skill the exam tests: architects who treat tool_use and end_turn identically write loops that terminate early or run indefinitely.

How do you define a tool for Claude?

Each tool is a JSON object with three required fields: name, description, and input_schema. The schema follows JSON Schema draft 7. A minimal, well-formed example:

{
  "name": "search_orders",
  "description": "Search the order database by customer ID and optional date range. Returns a list of matching orders sorted by date descending. Use this tool when the user asks about past orders or purchase history.",
  "input_schema": {
    "type": "object",
    "properties": {
      "customer_id": {
        "type": "string",
        "description": "The unique customer identifier."
      },
      "since_date": {
        "type": "string",
        "format": "date",
        "description": "Optional ISO 8601 date. Only return orders on or after this date."
      }
    },
    "required": ["customer_id"]
  }
}

Three things distinguish a reliable tool definition from a problematic one:

• Description specificity. Claude routes to tools almost entirely on description text. A description that says "searches orders" is underspecified; one that explains when to use the tool, what it returns, and how results are ordered gives the model the signal it needs. See writing effective tool descriptions for patterns that hold up across different request phrasings.
• Schema precision. Mark every required field in required. Use enum values wherever the field has a fixed domain. Avoid loose string types when you actually expect ISO dates or UUIDs: tighter schemas produce fewer malformed calls.
• Name uniqueness. When two tools have similar names and overlapping descriptions, Claude will misroute. Tool splitting for specificity covers when to break a broad tool into narrow ones and when that makes things worse.

How does Claude choose which tool to call?

Claude's tool selection is driven by the description field, not the name alone. The model reads all tool descriptions in context and picks the one that best matches its current intent.

The tool_choice parameter lets you override free selection. Setting it to {"type": "tool", "name": "search_orders"} forces that specific tool. Setting it to {"type": "any"} forces some tool call without specifying which. This matters for deterministic pipelines where you know a step must call a tool.

Tool choice configuration options covers the full semantics, including the auto default and edge cases where forcing a tool call conflicts with other constraints.

How do you pass tool results back correctly?

The result turn must append both the assistant's tool_use block and a new user message containing the tool_result block. The structure matters:

# After Claude responds with a tool_use block:
tool_use_block = response.content[0]  # type: tool_use

messages = [
    {"role": "user", "content": original_user_message},
    {"role": "assistant", "content": response.content},  # full content, not just text
    {
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": tool_use_block.id,
                "content": json.dumps(query_result),
            }
        ],
    },
]

Two common mistakes here:

1. Dropping the assistant content. Some implementations extract only the text from the assistant response and discard the tool_use block. Without it, Claude loses the record of which tool it called, and the next response may be incoherent.
2. Returning errors silently. If tool execution fails, return a tool_result with is_error: true and a structured error description. An empty success response causes Claude to continue as though the tool ran successfully, compounding the failure.

Tool result appending documents the exact message array structure the API requires.

How do you handle tool errors without breaking the loop?

Error handling is where most naive agentic loops fail. There are four error categories worth treating differently:

The critical distinction is between access failure and a valid empty result. An empty database query is not a failure; marking it is_error: true teaches Claude that empty results indicate a broken tool. See access failure vs valid empty result for the decision rule.

For multi-agent systems, error propagation compounds: a subagent that silently returns empty results will cause the coordinator to synthesise a response with no data. Error propagation in multi-agent systems covers how to surface structured error metadata upward through the hierarchy.

How do you design tools for MCP and multi-agent contexts?

When tools are served via the Model Context Protocol, the same description-first principles apply, but deployment scope adds a second design dimension. MCP servers can be scoped globally, per-project, or per-conversation. Choosing the wrong scope exposes tools to agents that should not access them.

{
  "mcpServers": {
    "order-db": {
      "command": "node",
      "args": ["./mcp/order-server.js"],
      "env": {
        "DB_URL": "${ORDER_DB_URL}"
      }
    }
  }
}

In a multi-agent architecture, the coordinator typically holds a broad tool palette and delegates specific tasks to subagents with narrower tool sets. This reduces the risk of a subagent calling a destructive tool by mistake and keeps each agent's decision space small enough to be reliable.

The CCAR-F exam's Domain 1 (Agentic Architecture and Orchestration, weighted at 27% of the exam) and Domain 2 (Tool Design and MCP Integration, weighted at 18%) together cover the majority of tool use scenarios. The tool design and MCP integration concept library maps every task statement in both domains.

What prompt structure produces the most reliable tool use?

Prompt structure affects whether Claude uses tools at the right moment. Several patterns hold up at production scale.

System prompt:

• Define the agent's role and permitted actions in the first paragraph.
• List any tools Claude must always use for specific request types.
• Keep the system prompt stable across turns so it can be prompt-cached, reducing latency and cost in high-volume systems.

User message ordering:

• Put documents and data before the question, not after. The document-first pattern keeps the task frame visible at the end of a long context window.
• For structured extraction tasks, include one or two worked examples showing the tool call and result you expect. Concrete examples within the user message outperform longer natural-language instructions for format stability.

Tool use vs. structured output:

The prompt engineering and structured output concept domain covers when to reach for each pattern and how to avoid format mixing that degrades reliability.

How do you debug a failing tool use loop?

Debugging tool use requires inspecting the full message array at each turn, not just the final response. Three diagnostic questions:

1. Is stop_reason what you expected? If it is end_turn on the first response, Claude chose not to call a tool. Check whether the description matches the user's phrasing.
2. Did Claude call the right tool? Log tool_use_block.name and tool_use_block.input at each turn. Misrouting almost always traces to a description that overlaps with another tool or is too generic.
3. Did the loop terminate correctly? A loop that never terminates usually means stop_reason is never checked, or tool_use is being returned but the result is not being appended. See agentic loop anti-patterns for the canonical failure modes.

The CCAR-F exam rewards architects who trace failures to root causes rather than applying blanket fixes. Candidates who have worked through the concept library, which covers 174 atomic concepts mapped to the five exam domains, report that tool use debugging scenarios appear across both Domain 1 and Domain 2 sections of the exam.