CCA-F: Claude Certified Architect — Foundations

By Anthropic · Question Mode

QuestionQ57

Tool Design & MCP Integration

Anthropic's tool use documentation advises: "Write instructive error messages. Instead of generic errors like 'failed', include what went wrong and what Claude should try next."

A billing dispute agent uses a lookup_order tool that catches all exceptions and always returns a tool result with is_error: true and the message "Tool execution failed". Monitoring reveals two distinct failure patterns:

  • The agent repeatedly retries the identical call until it hits the turn limit.
  • The agent immediately calls escalate_to_human without attempting any alternative tool.

Which change follows the documented recommendation and gives Claude the information it needs to choose the correct recovery action for each type of error?

Explanation

Anthropic's documentation on handling tool errors specifically instructs developers to write instructive, differentiated error messages rather than generic ones, because Claude relies entirely on the text in the tool_result content to decide how to recover — it has no other insight into why a call failed. A single generic string like "Tool execution failed" collapses distinct failure categories (a nonexistent order vs. a transient database timeout) into one indistinguishable signal, so Claude either retries an operation that can never succeed (a data-not-found error) or gives up and escalates a transient error that a retry would have resolved. By returning error-type-specific messages that both explain what went wrong and state what to try next (e.g., pointing to get_customer for a not-found error, or indicating that a timeout is transient and worth retrying), while still setting is_error: true so Claude correctly recognizes the result as a failure condition, the tool gives Claude exactly the actionable context the documentation calls for, letting it select retry, try-an-alternative-tool, or escalate as appropriate per error type.

Learn more

Community Discussion

No comments yet. Be the first to start the discussion!