Structured Tool Errors

Definition

A convention for returning tool failures as machine-readable, categorized results so Claude can decide whether to retry, correct inputs, or escalate — rather than a vague failure string.

Key points

• Fields: isError (bool), errorCategory (transient | validation | permission), isRetryable (transient → true; validation/permission → false).
• Retry only makes sense for transient errors; validation errors need corrected inputs, permission errors need escalation.
• MCP tool results carry is_error on the mcp_tool_result block.
• Return enough structured context for the model (or a subagent) to act — see Subagent Error Handling.

Why it matters for the exam

• Domain 2 explicitly flags that a generic "operation failed" is always the wrong answer.
• Tests mapping each errorCategory to the correct next action (retry vs fix vs escalate).

Common gotchas

• "operation failed" / opaque messages are always wrong — the exam rewards structured, categorized errors.
• Marking a validation or permission error as retryable is incorrect; only transient is retryable.

See also

• Subagent Error Handling
• Effective Tool Descriptions
• MCP Connector

Sources

• docs-tools-agents
• netlight-study-guide