Claude API Tool Use: A Practical Guide for Developers

Tool use is a structured conversation protocol, not remote code execution. You pass a tools array in your Messages API request; each entry has a name, a description, and an input_schema written in JSON Schema. When Claude decides a tool is needed, the response ends with a stop_reason of tool_use and contains one or more tool-call blocks with validated-shape JSON arguments.

Your application then executes the real function — Claude never touches your infrastructure directly — and sends the output back as a tool_result block in the next user message. The model reads the result and either calls another tool or produces its final answer. Three consequences matter architecturally:

• You own execution, so you own authorization, timeouts, and retries.
• Every tool call is auditable as a discrete message in the transcript.
• The loop is stateless per request — you resend conversation history each turn.

Most tool-use failures are schema-design failures. Claude reads your tool descriptions the way a new engineer reads documentation, so write them that way: state what the tool does, when to use it, and what it returns. A minimal, well-described tool outperforms a clever, ambiguous one.

tools = [{
  "name": "get_invoice",
  "description": "Fetch one invoice by ID from billing. Use when the user references a specific invoice.",
  "input_schema": {
    "type": "object",
    "properties": {"invoice_id": {"type": "string"}},
    "required": ["invoice_id"]
  }
}]

Practical rules that hold up in production:

• Use enum for closed sets instead of free-text strings.
• Mark truly required fields required; make everything else optional with sane defaults.
• Keep tool counts focused — a dozen sharp tools beats fifty overlapping ones.
• Describe units, formats, and edge cases (dates, currencies, IDs) explicitly.

The core pattern is a while-loop: call the API, execute any requested tools, append results, repeat until Claude stops asking. Keep it boring and observable.

while response.stop_reason == "tool_use":
    calls = [b for b in response.content if b.type == "tool_use"]
    results = [run_tool(c.name, c.input) for c in calls]
    messages.append({"role": "assistant", "content": response.content})
    messages.append({"role": "user", "content": [
        tool_result(c.id, r) for c, r in zip(calls, results)
    ]})
    response = client.messages.create(model=MODEL, tools=tools,
                                      messages=messages, max_tokens=2048)

Production hardening belongs around this loop, not inside the model: cap the number of iterations to prevent runaway loops, set per-tool timeouts, and log every tool call with its arguments and latency. Treat the loop as a state machine you can replay when debugging — the full message list is your trace.

Three capabilities change the ergonomics of tool use once you move past the happy path. First, streaming: the Messages API streams via server-sent events, and tool-call arguments arrive as incremental JSON deltas. Buffer them until the block completes before parsing — partial JSON is not parseable JSON.

Second, parallel tool calls: Claude can request several independent tools in a single turn, such as fetching a customer record and their open tickets simultaneously. Execute these concurrently and return all tool_result blocks together in one message; serializing them wastes latency for no correctness gain.

Third, structured outputs: when what you really want is a guaranteed JSON payload rather than an action, use structured outputs to constrain the final response shape instead of inventing a fake “return_answer” tool. Reserve tool use for genuine side effects and lookups; use output constraints for formatting. Mixing the two muddies both.

Tools fail in production — APIs time out, records go missing, inputs arrive malformed. The design question is what Claude sees when they do. Return errors as tool results with is_error set, containing a short, actionable message (“invoice not found; verify the ID”) rather than a raw stack trace. Claude will typically retry sensibly, ask the user for clarification, or explain the failure — but only if the error text gives it something to reason about.

Layer guardrails outside the model as well:

• Validate tool inputs against your schema server-side before executing; never trust arguments blindly for destructive operations.
• Require explicit human confirmation for irreversible actions (payments, deletions, external emails).
• Scope each tool’s credentials to the minimum it needs — least privilege applies to model-invoked functions exactly as it does to microservices.
• Rate-limit tool execution independently of the API loop.