Skip to content
Home › Architect's Playbook Patterns

Graceful Tool Failure

Architect's Playbook Patterns

Definition

Returning tool errors as structured data in the tool result (with isError / errorCategory / isRetryable flags) so the agent can respond politely and fail fast, rather than crashing the agent with application exceptions.

Key points

  • Sequence: User → Agent → Tool Server (lookup_order). Tool returns {isError: true, errorCategory: "transient", isRetryable: true}. Agent gives a polite response ("I'm experiencing a delay, please try again later.").
  • Anti-pattern: Throwing application exceptions that crash the agent, or returning empty strings.
  • Correct pattern: Return the error message in the tool result content with the isError flag set to true.

Why it matters for the exam

  • Tests recognition of the exact flag names — isError, errorCategory (e.g. "transient"), isRetryable — and that errors belong in the tool result content, not as thrown exceptions.

Common gotchas

  • Crashing with an exception or returning an empty string are both wrong — the agent needs the error surfaced inside the tool result so it can reason about retry/response.
  • isError goes in the tool result content; the extra errorCategory/isRetryable fields let the agent decide whether to retry.

See also

Sources

Referenced by