You are building a customer support resolution agent using the Claude Agent SDK.

The agent is behaving inconsistently because every failure is represented identically. “Operation failed” contains no information about permanence, user correctability, authorization, or whether another attempt is likely to succeed. Adding structured fields converts the error into an actionable interface contract.

Anthropic instructs tool implementations to mark failures using an error flag and return information Claude can use to retry with corrected input, ask for clarification, or explain a limitation. Tool design should expose sufficient detail for the model to choose the correct next action rather than forcing it to infer the cause from a generic message. ( https://platform.claude.com/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent?utm_source=chatgpt.com )

With error_category , isRetryable , and a causal description, the agent can retry transient network failures, request corrected identifiers for validation errors, and escalate or report permission failures without pointless repetitions. Option B retries permanent validation and permission failures unnecessarily. Option C adds another tool call and failure point merely to classify information the original tool already possesses. Option D relies on parsing variable text and examples rather than providing explicit machine-readable semantics.

The tool should preserve isError: true , return a stable structured error object, include a safe customer-facing message where appropriate, and avoid exposing internal secrets or stack traces.

Official references/topics: MCP error contracts, actionable tool results, retryability metadata, agent-computer interface design.