Learn · Tool design & MCP · CCAR-F task 2.2

Structured error responses

When a tool fails, say so in a way Claude can act on: isError, a category, isRetryable and a useful message. Never an empty result.

Key ideas

Report failures as errors: isError: true in MCP, is_error: true on the tool_result in the Messages API.
Include an error category, whether it is retryable, and a human-readable message with a next step.
Transient errors: retry with bounded backoff. Validation: fix the input and retry.
Business-rule and permission errors are not retryable: explain to the user or escalate.
An access failure is not a valid empty result; never return [] when the call failed.
Subagents recover transient errors locally and propagate the rest with partial results and what they tried.

The message tells Claude why the call failed, that retrying the same input won't help, and which tool to try instead.

Returning an empty result on failure; the agent concludes nothing exists.
Retrying a business-rule or permission error, which can never succeed.
A generic 'error occurred' message with no category or next step.
Letting a tool exception crash the agent loop instead of returning an error result.
Subagents escalating every transient error instead of retrying locally first.