A Tool Schema That Tells the Model Which Retry to Take

Before writing schema, settle the policy. Every error a tool can return should resolve to exactly one of three actions.

Two independent axes explain why: transient versus persistent, and infrastructural versus semantic tianpan.co. A 503 is transient and infrastructural, so retry is correct. A 409 is persistent and semantic, so the model must re-observe and replan. A 401 is persistent and infrastructural, so neither retry nor replan helps: escalate. Transport and service errors belong to the orchestration layer, while input validation and logic errors belong to the model n8n. That split is the whole design in one sentence.

HTTP status semantics support the same mapping. Client errors in the 4xx class mean the caller must change something and should not be retried, while 5xx means the server must fix something and can be retried; the class is the contract milanjovanovic.tech. MDN groups responses into exactly these five classes developer.mozilla.org. Temporal's retry recipe publishes a concrete retryable list (408, 429, 500, 502, 503, 504) and a non-retryable list (400, 401, 403, 404, 422) docs.temporal.io. Start from those lists and add your domain's own classes.

Most teams document outputs in prose and leave the machine-readable schema to inputs only. That is backwards if the model must act on the result. A strong tool schema includes five parts: name, description, input schema, output schema and error schema, and the error schema should be structured so the model can retry, ask for missing data or escalate aiquinta.ai. Here is a return envelope that follows that advice.

{
  "ok": false,
  "error": {
    "class": "invalid_argument",
    "message": "guest_count must be a positive integer; received 'two'",
    "retryable": false,
    "field": "guest_count"
  }
}

And here is the same shape expressed as a JSON Schema fragment you can attach to the tool definition. The enum constrains the class; the descriptions carry the policy.

{
  "type": "object",
  "properties": {
    "ok": { "type": "boolean" },
    "error": {
      "type": "object",
      "required": ["class", "message", "retryable"],
      "properties": {
        "class": {
          "type": "string",
          "enum": ["invalid_argument", "not_found", "conflict", "rate_limited", "transient_upstream", "auth_failed", "permission_denied", "partial_execution"],
          "description": "Category of failure. Read the matching description below to choose repair, retry or escalate."
        },
        "message": { "type": "string", "description": "Human-readable detail. Never the basis for the decision; use class." },
        "retryable": { "type": "boolean", "description": "True only when the identical call may succeed after a delay. If false, do not call this tool again with the same arguments." },
        "field": { "type": "string", "description": "For invalid_argument only: the parameter that must be corrected." }
      }
    }
  }
}

The context-dependent defects you need to look for are in the classes and descriptions, not in the type keywords. A bare enum of names is only marginally better than prose; the value comes from what each name says to do.

The model reads descriptions, so the description of each enum value is where the decision actually lives. The rule: every description states the intended action explicitly. Not "the argument was bad" but "the argument was bad; correct the named field and call again." Example pairs for the seven classes above:

Two of these are the ones teams forget. partial_execution is the hardest class to detect and returns HTTP 200, so it must exist as an explicit value scalekit.com. And the conflict example above comes straight from the calendar-write case that motivated the replan argument tianpan.co. Note also that retryable is presentation, not policy: the orchestrator, not the model, executes the retry for rate_limited and transient_upstream, so the flag is telling the model to yield rather than to loop.

Enum descriptions follow the same discipline as parameter descriptions, which should define scope and constraints rather than restate the field name machinelearningmastery.com. A description that says "invalid argument" teaches nothing. A description that says "correct the named field and call again once" is a complete instruction.

A boolean is the cheapest piece of coordination you can ship. It gives the model a single, checkable gate before it burns a call, and it gives your evaluation a clean variable.

The failure it prevents is measurable. A retry budget of three with 200ms, 400ms and 800ms backoffs adds a guaranteed 1.4 seconds to any call that returns a persistent semantic error, and the latency lands on the user watching a spinner during a conflict the agent could have surfaced in 200 milliseconds tianpan.co. There is a correctness cost too: a payment-create call that timed out may have succeeded server-side, so the retry creates a duplicate charge, and replanning forces the agent to re-observe state before acting tianpan.co. The flag encodes both lessons in one bit.

For upstream services that publish instructions, surface them in the flag. Servers can send a Retry-After header to say when to retry, and the notebook that implements this logic treats a present Retry-After as authoritative over a default delay docs.temporal.io. If your tool wraps a dependency that sends those headers, parse them in the tool and set retryable and any delay hint from the response, not from your guess.

Be careful with idempotency claims. Temporal's recipe lists 409 Conflict as retryable "when resource is temporarily locked or in use" docs.temporal.io, but the agents piece argues a 409 is persistent and semantic and retrying is futile tianpan.co. Both can be true: the difference is whether your tool knows the lock is short-lived. If you do not know, set retryable: false and classify as conflict. Default to the safer bit.

The design is only as good as its measurement. The eval is small and cheap: a fixed set of seeded failures, one per class (plus variants), replayed against a fixed agent loop, counting how often the model's next action matches the intended action for that class. Intended actions come from the table in the second section: repair, retry or escalate.

Recommended procedure:

1. Seed at least three variants per class, including one edge case, such as a 409 that clears on re-read versus one that does not.
2. Freeze the user prompt and the tool list so only the schema changes between runs.
3. Record the model's next action, not its narration. Did it change the argument, yield, or escalate?
4. Score per class, then overall. A single blended accuracy figure hides the class that breaks.
5. Re-run the eval whenever you add or rename an enum value.

Use realistic envelopes. A 422 whose message hides the failing field cannot be repaired, and the field that names what to fix is what makes the correction possible: an error body has to tell the client what to fix, while the status tells it whether to fix milanjovanovic.tech. This is exactly the gap the practitioners who wired the Replit domain-buying agent hit, where the agent saw only HTTP Error 422 until the full response body was surfaced to it medium.com.

Treat new enum values like a versioned contract. Schema registries exist to block changes that break consumers, and the compatibility type you choose determines which edits are allowed docs.confluent.io. Adding an enum symbol is the equivalent of adding a union variant or an optional field, and those are governed by explicit compatibility rules rather than left to chance docs.confluent.io. When you retire a class, keep it in the enum and stop emitting it, so prompts and evals written against the old value still parse.

The numbers rarely come back even. The common pattern is repair-heavy classes scoring well because the message names the field, while escalate classes score badly because the model retries a permission_denied "just in case." When that happens, the fix is almost always the description, not the model. Add the words "do not retry" to the class description and re-run.

A second pattern is the model changing arguments on a transient_upstream. That means the description reads like an input problem. Rewrite it to say "do not change the arguments; the orchestrator will retry." A third is the model retrying partial_execution. This one is dangerous: make the description say "re-read state before any further write," and add a state field to the envelope so the re-read is cheap.

If you want to run the eval across several models without rewriting client code per provider, a single OpenAI-compatible endpoint for text, image, video, audio and embedding models removes that friction; Quanta Inference is one option for that. The schema work itself is portable either way, which is the point: the decision belongs to the tool contract, not to any one model's prompt.