Claude Architect · Lesson

Retryable Metadata & Partial Results

errorCategory, isRetryable, attempted_query, partials.

Why Error Shape Matters

When a tool or MCP server fails, the model has to decide what to do next. A generic status like "Operation failed" gives it nothing to reason about, so the only safe move is to abort or guess.

A structured error turns a dead end into a decision: should we retry, route around the failure, or escalate to a human? In this lesson you'll learn the four metadata fields that make that possible: errorCategory, isRetryable, attempted_query, and partial_results.

The isError Flag

Every structured MCP error starts with one boolean: isError: true. This is the unambiguous signal that the tool result is a failure, not data.

Without it, the model may treat an error message as a legitimate answer and happily summarize the failure as if it were a result. The flag is the gate that activates all the recovery logic that follows.

tool_result = {
    "isError": True,
    "errorCategory": "transient",
    "isRetryable": True,
    "message": "Upstream timeout contacting orders DB",
    "attempted_query": "SELECT * FROM orders WHERE id='A-2291'",
    "partial_results": []
}

All lessons in this course

← Back to Claude Architect