Claude tool interfaces should be treated as production API contracts, not as a thin list of functions. A good contract makes the intended action obvious, limits each call to valid inputs, preserves the relationship between a call and its result, and makes failure safe to handle. Claude's tool-use flow lets the model select tools and emit structured inputs, while the application remains responsible for execution and for returning results.
Architecture Overview: Keep Reasoning and Effects Separate
Tool use has two distinct responsibilities. Claude decides whether a described capability is useful and produces a tool-use block with an input. The application executes the requested operation and sends a tool_result block back in a later user message. This separation is important: a model proposing an action is not proof that the action is authorized, valid, or safe to perform.
Anthropic documentation distinguishes client tools, which your application executes after Claude returns a tool-use request, from server tools that run on Anthropic's infrastructure when supported. Design each contract around where execution happens and which system owns credentials, audit records, policy decisions, and recovery.
For operations with side effects—such as changing records, sending messages, or invoking a paid service—place authorization and business validation in the executor. Do not rely on a tool description or model instruction as an access-control boundary.
Core Components of a Tool Contract
Choose a Narrow Capability
Start with one business outcome that has a clear owner and failure boundary. get_customer_order is easier to select and validate than a generic customer_api tool that exposes many unrelated actions. Narrow tools reduce ambiguity, simplify permission checks, and make audit events meaningful.
Avoid splitting one atomic business operation into several tools merely to expose implementation details. Conversely, do not bundle unrelated read, write, and administrative actions under one broad interface. The right boundary is one action whose inputs, authorization, success result, and compensation path can be explained together.
Write Names and Descriptions for Selection
The tool name identifies a stable capability; the description tells Claude when to use it, when not to use it, and what the result represents. Use specific verbs and domain nouns. State important preconditions, units, formats, or exclusions in the description rather than expecting the model to infer them.
Descriptions are guidance, not enforcement. The executor must still reject unauthorized callers and malformed or semantically invalid requests. This distinction is especially important when a tool can affect external systems.
Constrain Inputs with JSON Schema
Claude tool definitions use an input_schema expressed as JSON Schema. Define required fields, enumerated values, object shapes, and meaningful descriptions so that the model has a constrained interface rather than an informal text protocol.
Schema validation is necessary but not sufficient. A syntactically valid amount can still exceed a business limit, and a valid resource identifier can still be outside the caller's tenant. Layer application validation after schema validation and before the effect occurs.
Execution and Result Contracts
Preserve Tool-Result Ordering
When Claude returns one or more tool-use blocks, return a tool_result for every requested tool use and correlate each result with its matching tool_use_id. Send the results in the immediately following user message, and place all tool_result blocks before any text in that message. These are the documented message-shape requirements; do not impose an unsupported same-order requirement on parallel results.
Treat the identifier as a correlation key. Store it with the executor's request and outcome so an operator can trace a proposed action, its authorization decision, external call, and response without guessing from conversational text.
Make Results Useful but Bounded
Return the minimum result that lets Claude continue safely: a confirmed identifier, a normalized status, an actionable validation error, or a compact summary. Do not dump raw records, secrets, stack traces, or high-volume payloads into model context. Large or sensitive results increase both context cost and disclosure risk; return a bounded summary and provide a separately authorized retrieval path when necessary.
For a write action, distinguish “accepted for processing,” “completed,” and “unknown outcome.” A network timeout after a downstream service received a request must not be presented as a confirmed failure merely because the caller did not receive a response.
Use is_error for Tool-Level Failure
Set is_error: true on a tool_result when the tool execution failed in a way Claude should handle. Anthropic documents is_error as the signal that lets Claude receive the failure result and decide an appropriate next step.
Return a concise, safe explanation such as “the record was not found” or “the requested field is not permitted.” Do not expose credentials, internal topology, or raw exception details. A policy denial should be explicit enough for Claude to stop or ask for a legitimate alternative, rather than encouraging repeated attempts.
Strictness, Retries, and Idempotency Boundaries
If an interface needs dependable shapes, use the documented strict tool-use options where they apply, and test the exact model and platform combination used in production. Strictness improves contract adherence; it does not authorize a call or replace domain validation.
Retry logic belongs to the executor and should be classified by effect:
- Safe reads may be retried after bounded, observable transient failures.
- A write should be retried only when the downstream operation supports a stable idempotency key or an equivalent deduplication contract.
- An unknown write outcome should trigger a status check or human escalation, not an unbounded repeat.
Set timeouts, retry budgets, and logging before deployment. Repeated tool calls can create duplicate changes or costs, so make the idempotency boundary visible in the tool description, application behavior, and operational runbook.
Common Tool-Contract Mistakes
The most damaging designs ask the model to infer hidden inputs, return unbounded data, or execute privileged effects without an independent policy check. Another common failure is treating every exception as retriable. That can convert a permanent validation or authorization failure into noisy repeated requests.
Do not confuse a tool contract with a general structured response contract. This article covers calls that an executor performs and returns to Claude. Schema-constrained non-tool output is a separate output-design concern.
Conclusion
The reliable Claude tool interface is small, explicit, validated twice, and observable end to end. Let descriptions and JSON Schema help Claude select and populate the right action; let the executor own authorization, side effects, correlation, retry policy, and error disclosure. That division makes tool use useful without making the model the security boundary.