A library’s assistant checks whether a portable projector is available for a workshop. Claude asks an application-controlled tool for the item status, but the inventory API times out. If the application silently turns that failure into an empty result, the assistant may tell a visitor that there are no projectors. Claude’s client-tool protocol provides tool_use identifiers and tool_result blocks, including an is_error flag, to communicate what actually happened. This guide keeps a failed lookup visibly unconfirmed and uses fictional inventory records only.
Define the lookup result states before creating tools
Start with a read-only inventory endpoint and a clear result contract: item found with a verified status, item definitively not found, tool unavailable, request invalid and permission denied. A timeout is not the same as a zero-result search. Record the item’s stable catalog key and the time the status was checked. The demo projector and workshop date are invented, and the article does not query a real library.
Separate status displayed to a patron from the internal reason a call failed. Avoid exposing raw network details, access tokens or staff-only inventory fields. If the user is asking to reserve an item rather than merely check its status, put reservation or assignment behind a separate approval workflow. A read-only tool must never inherit write permissions simply because the model phrases a request confidently.
Parse the assistant tool_use block instead of text
For client-executed tools, Claude returns content blocks of type tool_use when it requests an operation. Each block carries an ID, tool name and input object, while the assistant turn can have stop_reason tool_use. The application—not the model—runs the trusted tool. Validate the requested name and arguments against a schema and an allowlist before sending anything to the catalog database.
Preserve each tool-use ID across retries and logging so every returned value belongs to the correct invocation. If Claude requests several read-only lookups, each result needs its own matching ID. Do not treat the tool’s suggested arguments as authorized database scope; enforce tenant, user and permission checks in the backend. Source documents and tool outputs are untrusted input to later model reasoning.
Return a structured success without overstating freshness
When the catalog returns an authorized current record, construct a tool_result block with tool_use_id equal to the originating tool_use ID. Include only required fields such as item key, status, source revision and last checked timestamp. The protocol places client tool results in a following user message, with the result blocks before any ordinary text content. Preserve the full assistant tool-use turn in the conversation history.
Even a successful tool call is not a transaction or an item hold. If the inventory status is ‘available’, the assistant can report that availability as of the checked time but must not say a reservation is confirmed. Keep quote-like user-visible wording tied to the actual returned fields. For rapidly changing inventory, attach an expiration or a policy for rechecking before a patron travels to collect an item.
Signal real execution failures using is_error
Claude’s tool-handling documentation specifies is_error: true for a tool_result when a client tool fails. Include a concise, sanitized message such as ‘inventory service temporarily unavailable’ and the matching tool_use_id. A failure should not be encoded as an empty list, false Boolean or invented product record. The model can then explain that the lookup did not complete, while the application retains a separate trace of the outage.
The tool protocol also covers invalid arguments and missing tool parameters. Validate requests before execution, return a clear error signal, and cap retries in the application. If the underlying tool might have side effects, an error may occur after a write; never blindly replay the action without checking its state. For this article the tool is read-only, but the same discipline protects future reservation features from duplicate commitments.
Compare missing data, failed execution and verified answer
The first illustrated state shows a timeout incorrectly converted into ‘not available’. The middle state shows a real error but no linked call ID, leaving the conversation inconsistent. In the reviewed state, the failed tool_result is matched to the correct tool_use and the assistant states that availability could not be verified. A later successful lookup can update the answer with its own timestamp and proof.
These drawings are protocol diagrams, not screenshots or observed Anthropic logs. Do not use a high model confidence score as evidence that a backend call completed. Test whether the application displays distinct messages for a genuine zero match, a permission block and an outage. Keep raw tool failures in controlled diagnostics, not in the public answer or in a prompt that might expose secrets.
Respect message ordering and parallel tool calls
Claude documentation requires tool_result blocks immediately after the corresponding assistant tool-use turn, and result blocks first in the following user message. An application that inserts an unrelated message can trigger a protocol error or confuse result attribution. When a response contains several client tool calls, return a separate matching result for each in the same next message, even if one failed and others succeeded.
A failed call does not justify discarding another tool’s valid result. For example, the projector lookup could fail while a read-only branch-hours lookup succeeds. Display the branch hours with its source date and keep the projector availability unknown. Avoid parallel execution for dependent or side-effecting operations until your backend provides appropriate locking and transactional guarantees.
Test outages and ambiguity with a fixed fixture
Create synthetic cases for a valid item, missing item, permission denied, network timeout, malformed tool arguments, multiple tool_use blocks and a stale inventory response. Define the correct assistant wording and result object for each before testing. Check that no failed case becomes a false reservation confirmation. Inspect how the model responds after is_error and whether the interface still shows a stable item identifier.
Record the API request ID, sanitized error category and retry decision in operational logs. Avoid storing unredacted patron questions unless necessary and authorized. This tutorial did not call Claude or measure model recovery rates. It shows a protocol-consistent handling pattern that teams must verify with their own SDK version, network policies and representative inventory fixtures.
Publish only confirmed catalog state with an audit trail
Before deploying a patron-facing assistant, verify the tool allowlist, schema checks, result-ID matching, timeouts, authorization and final user wording. A real hold or checkout must be confirmed by the authoritative inventory system and should return a reference number from that system, not from the model. When the status cannot be checked, direct the visitor to the library’s official booking or contact route without inventing stock.
Review Anthropic’s current client-tool documentation for tool_result formatting, stop reasons and errors whenever an SDK or model changes. Treat external tool output as untrusted data and keep approval of changes outside the model. The measure of reliability is correct distinction among confirmed, missing and unknown states, rather than how smoothly an assistant phrases an unverified answer.
How We Research
We researched this November 2026 article from named official documentation: Claude: Handle tool calls; Claude: How tool use works; Claude: Troubleshooting tool use. We compared documented request parameters and operational limitations with a hypothetical community organization use case, then designed independent human review and regression checks. Images are original fictional educational diagrams, not product screenshots, actual measured benchmark charts or verified customer cases. We did not submit live API requests, upload personal files, process museum assets or measure vendor accuracy. Implementers must verify current endpoint versions, access controls, region support, pricing and retention before deployment. Factual and rights-sensitive results require review of primary sources.
Frequently Asked Questions
It tells Claude that client-side tool execution failed rather than returning successful data.
Use tool_use_id to match the ID of the originating tool_use block.
No. Availability is unknown until a reliable lookup confirms it.
No. A separate authorized transaction must provide an actual confirmation.
The application must bound retries and verify state before replaying any side-effecting action.