Tool Call Error Code Interpretation and Retry Prompt Template

This prompt is designed for the specific moment inside an agent's execution loop when a tool call has returned an error. Its job is to interpret the raw error code and produce a structured, machine-readable recovery action. The ideal user is a platform engineer or AI reliability engineer building a harness that orchestrates tool use. The required context is the failed tool call's name, its arguments, the exact error code returned, and the available recovery strategies your system supports. Without this context, the prompt cannot make a safe decision between retrying, adjusting arguments, or escalating permanently.

Use this prompt when your system needs to distinguish between transient and permanent failures programmatically. For example, a 429 Rate Limit Exceeded error should map to a retry action with a backoff instruction, while a 403 Forbidden or 401 Unauthorized error should map to a permanent escalation, as no argument adjustment will resolve an authentication failure. The prompt is most effective when your harness has a defined taxonomy of error codes and a fixed set of recovery actions, such as RETRY_WITH_BACKOFF, ADJUST_ARGUMENTS_AND_RETRY, or ESCALATE_TO_HUMAN. It is not a general-purpose debugging assistant; it is a decision router for a known failure space.

Do not use this prompt when the error is a malformed JSON syntax error or a schema validation failure. Those failures require a different class of repair prompts that focus on structural correction of the payload itself, not on interpreting a semantic error code from an external service. Similarly, avoid this prompt when the tool call succeeded but returned an unexpected business-logic result; that is an output validation problem, not a tool-call error recovery scenario. After implementing this prompt, your next step should be to wire it into a retry loop with a strict budget and to add evaluation cases that verify the correct recovery action is chosen for each error code in your taxonomy.

This prompt template is designed to be injected into your agent harness immediately after a tool call returns an error code. Instead of blindly retrying with the same arguments or escalating every failure, the prompt forces the model to classify the error, determine if it is retryable, and produce a corrected tool call only when recovery is possible. The template uses square-bracket placeholders so you can wire it directly into your error-handling middleware without manual rewriting.

textCopy
You are an agent error recovery specialist. A tool call has failed with an error code. Your job is to interpret the error, decide whether a retry is appropriate, and produce a corrected tool call if recovery is possible.

## Error Context
- Tool Name: [TOOL_NAME]
- Original Arguments: [ORIGINAL_ARGUMENTS]
- Error Code: [ERROR_CODE]
- Error Message: [ERROR_MESSAGE]
- Attempt Number: [ATTEMPT_NUMBER]
- Retry Budget Remaining: [RETRIES_REMAINING]

## Available Tool Schema
[TOOL_SCHEMA]

## Conversation Context
[CONVERSATION_CONTEXT]

## Error Code Taxonomy
Use this taxonomy to classify the error and determine the recovery action:

| Category | Error Codes | Retryable? | Recovery Strategy |
|----------|-------------|------------|-------------------|
| TRANSIENT | 429, 503, 504, TIMEOUT | Yes | Retry with exponential backoff; preserve original arguments; reuse idempotency key if present |
| VALIDATION | 400, 422, INVALID_ARGUMENT, SCHEMA_MISMATCH, TYPE_ERROR, ENUM_VIOLATION, MISSING_REQUIRED | Yes | Correct the specific argument that failed validation; leave valid fields intact; do not invent new values |
| AUTHENTICATION | 401, 403, UNAUTHORIZED, FORBIDDEN | No | Do not retry; escalate with auth failure summary |
| NOT_FOUND | 404, TOOL_NOT_FOUND, ENDPOINT_NOT_FOUND | Conditional | If a similar tool exists in the available tool schema, substitute it; otherwise escalate |
| PERMANENT | 500, 501, 502, INTERNAL, UNIMPLEMENTED, DEPRECATED | No | Do not retry; escalate with failure summary |
| QUOTA | 429_QUOTA, RATE_LIMITED, RESOURCE_EXHAUSTED | Conditional | Retry only if retry budget >= 2 and a backoff duration is provided; otherwise escalate |
| DEPENDENCY | DEPENDENCY_FAILURE, UPSTREAM_ERROR, CHAIN_FAILURE | Conditional | Identify the failed dependency; if it can be re-executed with corrected arguments, produce a dependency retry plan; otherwise escalate |
| AMBIGUOUS | AMBIGUOUS_INPUT, MULTIPLE_MATCHES, DISAMBIGUATION_REQUIRED | Conditional | If conversation context resolves the ambiguity, produce disambiguated arguments; otherwise request clarification |
| TIMEOUT | TOOL_TIMEOUT, EXECUTION_TIMEOUT | Conditional | Retry once with original arguments and a timeout-adjustment note; if partial results are available, include them |

## Output Schema
Return a JSON object with this exact structure:
{
  "error_category": "<one of: TRANSIENT, VALIDATION, AUTHENTICATION, NOT_FOUND, PERMANENT, QUOTA, DEPENDENCY, AMBIGUOUS, TIMEOUT>",
  "retryable": true or false,
  "action": "<RETRY | ESCALATE | REQUEST_CLARIFICATION | DEPENDENCY_RETRY | TOOL_SUBSTITUTION>",
  "corrected_tool_call": {
    "tool_name": "<string>",
    "arguments": {}
  } or null,
  "correction_summary": "<one-sentence explanation of what was changed and why>",
  "escalation_payload": {
    "failure_summary": "<string>",
    "original_error": "<string>",
    "attempts_exhausted": true or false,
    "recommended_human_action": "<string>"
  } or null,
  "clarification_question": "<string>" or null
}

## Constraints
- If the error is retryable and you can produce a corrected call, set `action` to RETRY and populate `corrected_tool_call`.
- If the error is permanent or the retry budget is exhausted, set `action` to ESCALATE and populate `escalation_payload`.
- If the error requires user clarification, set `action` to REQUEST_CLARIFICATION and populate `clarification_question`.
- If a dependency failure can be repaired, set `action` to DEPENDENCY_RETRY and include the dependency repair plan in `correction_summary`.
- If tool substitution is appropriate, set `action` to TOOL_SUBSTITUTION and populate `corrected_tool_call` with the alternative tool.
- Never invent tool names, endpoints, or argument values that are not present in the available tool schema or conversation context.
- Preserve all valid arguments from the original call; only modify the fields that caused the error.
- If the error code does not match any taxonomy entry, classify it as PERMANENT and escalate.

To adapt this template for your harness, replace each square-bracket placeholder with live data from your error handler. [TOOL_SCHEMA] should contain the full JSON Schema or function definition for the tool that failed. [CONVERSATION_CONTEXT] should include the last N user and assistant messages so the model can infer missing parameters or resolve ambiguities. [RETRIES_REMAINING] is critical: when it reaches zero, the taxonomy rules force escalation regardless of error category, preventing infinite retry loops. If your system uses custom error codes beyond the taxonomy, extend the table before deploying. Always validate the model's output against the output schema before executing a retry; a malformed recovery response should itself trigger escalation.

This prompt is designed to sit inside a tool-execution retry harness, not as a standalone chat interaction. When a tool call returns an error code, the harness should intercept the failure, classify the error category, and inject the relevant error context into this prompt before re-invoking the model. The harness is responsible for enforcing retry budgets, preventing infinite loops, and routing permanent failures to human review or dead-letter queues. Do not expose raw error traces directly to end users; the harness should sanitize sensitive details while preserving enough diagnostic information for the model to produce a useful recovery action.

The implementation flow follows a strict sequence: (1) execute the tool call and capture the response; (2) if the response contains an error code, classify it against your error taxonomy (retryable, permanent, auth, rate-limit, schema, timeout, dependency); (3) select the corresponding recovery strategy from your mapping table; (4) populate the prompt template with the original tool call, the error code, the error message, the recovery strategy, and any relevant tool schema; (5) invoke the model with the populated prompt; (6) validate the model's output against the expected recovery action schema before executing the retry; (7) increment the retry counter and check against the budget; (8) if the budget is exhausted, route to the escalation path instead of retrying. Each step should emit structured logs with trace IDs, retry counts, error categories, and recovery actions for observability.

For validation, the harness must check that the model's recovery output contains a valid action type (retry, modify_and_retry, switch_tool, clarify, escalate), preserves the original intent parameters where applicable, and does not hallucinate new tool names or endpoints not present in the available tool catalog. Implement a schema validator that rejects recovery actions referencing non-existent functions or proposing argument mutations that violate the target tool's parameter constraints. For high-risk domains such as financial transactions or healthcare operations, insert a human approval gate before executing any modify_and_retry or switch_tool action that alters the original call's semantic intent. Log every validation failure as a separate event to distinguish model errors from tool errors in your observability pipeline.

Model choice matters here: use a model with strong instruction-following and structured output capabilities, such as Claude 3.5 Sonnet or GPT-4o, because the recovery action must conform to a strict schema under error conditions. Lighter models often hallucinate tool names or produce recovery actions that don't match the error category. If latency is critical, consider routing permanent errors and escalation decisions to a faster model while reserving the stronger model for complex retry scenarios like dependency failures or schema mismatches. Always set a timeout on the model invocation itself; if the model fails to produce a valid recovery action within the timeout window, treat that as an escalation trigger rather than retrying the prompt.

The most common production failure mode is error category misclassification at step 2, which feeds the wrong recovery strategy into the prompt and produces an inappropriate retry action. Test your error taxonomy against real tool error responses before deploying, and add a periodic review of misclassifications from production traces. A secondary failure mode is argument drift across retries, where each recovery cycle subtly changes the original intent until the retried call no longer serves the user's goal. Mitigate this by storing the original validated arguments at the start of the retry loop and diffing each recovery action against them, flagging any semantic deviation above a configurable threshold for human review.