Claude API Tool Use Best Practices: Definitions, Errors, Parallel Calls

Once you understand how tool use works, the next step is making it reliable in production. This guide collects best practices for tool definitions, error handling, parallel calls, and result formatting, following the official Anthropic tool use docs. (As of June 2026.)

1. Writing good tool definitions

The single biggest lever on tool-use quality is the tool description. The more clearly and generously you describe what a tool does and when (and when not) to use it, the better Claude chooses. Spell out parameters in input_schema — required vs optional, types, and formats (e.g., date format).

For a production agent where invalid inputs cause failures, add strict: true to the tool. Structured outputs then guarantee Claude's tool inputs match your schema exactly — no type mismatches or missing fields. For models, the latest Opus handles multiple tools and ambiguity best and will seek clarification; Haiku is fine for simple tools but may infer missing parameters.

2. The agent loop and error handling

A tool-using conversation is a loop: call the API → check stop_reason → run tools → append results, repeating while stop_reason == "tool_use". The loop exits on any other stop reason (end_turn, max_tokens, stop_sequence, or refusal).

Tools fail — a calendar API may reject an event with too many attendees, or a date may be malformed. Instead of crashing, return a result block with is_error: true and the error message. Claude reads it and can retry with corrected input, ask the user to clarify, or explain the limitation. The flag is the only difference from a successful result.

{
  "type": "tool_result",
  "tool_use_id": "toolu_02",
  "is_error": true,
  "content": "cat: report.md: No such file or directory"
}

Most SDKs ship a Tool Runner that handles this loop for you (error wrapping, result formatting, conversation management). Unless you need fine-grained control, Tool Runner is simpler.

3. Parallel tool calls — result formatting rules

By default Claude may call several independent tools in one turn. Break the formatting rules and parallelism stops working:

• Put all results in a single user message, each in its own tool_result block.
• In that user message's content array, tool_result blocks come FIRST; any text must come AFTER all results.
• Each tool_result must immediately follow its tool_use; you cannot insert other messages between them.
• Tool calls in a single turn are unordered — run them concurrently (Promise.all, asyncio.gather), sequentially, or in any order.

If one call in a batch fails because it depends on another, just return is_error: true with the natural error message — no need to explain the dependency. Claude recovers and reissues. To disable parallelism, set disable_parallel_tool_use=true: at most one tool when tool_choice is auto, exactly one when it is any or tool.

4. When you have many tools

There is no hard limit on tool definitions, but context consumption scales with their number and complexity — large tool sets can spend significant tokens on definitions alone. In that case, apply the dynamic-discovery patterns the docs describe, such as Tool Search and defer_loading, so only the relevant tools load on demand.

Related reading

How tool use works: the complete tool use guide; forcing JSON-schema output: structured outputs.