A database tool times out. What should you send back so that Claude can recover?
Why C is the answer
A tool_result with is_error set to true and a clear message
is_error tells Claude the tool failed, and a useful message lets it retry, try another way, or explain. Pretending it succeeded invites a confident wrong answer.
In detail
- is_error tells Claude that the tool failed.
- A clear message lets it retry, try another way, or explain.
- Pretending it succeeded invites a confident wrong answer.
- Say whether a retry is likely to help.
Use case
An illustrative scenario, not a real incident.
A report tool loses its database connection. With is_error and "database timed out, try again shortly", Claude retries once, then explains the delay.
See it in different ways
sequenceDiagram participant A as Your code participant C as Claude A->>C: Request with tools C-->>A: tool_use blocks A->>A: Run the tools A->>C: tool_result blocks first, then any text C-->>A: Final answer
flowchart TD
Q{"What does the tool return?"}
Q -->|"Empty success"| A0["Confident wrong answer"]
Q -->|"is_error with a clear message"| A1["Retry or explain"]Key point: Tell Claude when a tool failed.
Why the other options are wrong
- A. Nothing, and let the request end
- Ending the request throws away the whole turn, and Claude cannot recover.
- B. An empty string marked as success
- An empty success tells Claude that something worked when it did not.
- D. A new request with a system prompt that describes the outage to the model
- The current tool_use still needs a result, so a new request does not fix this.