Error Code Interpretation from Tool Output Prompt Template

This prompt is designed for reliability engineers and AI infrastructure teams building self-healing systems where an LLM must interpret raw error codes from external tools (APIs, databases, gRPC services) and produce a structured, actionable interpretation. Use this prompt when your AI agent or copilot receives a non-zero exit code, an HTTP error status, or a structured error payload from a tool call and needs to decide the next step without human intervention. The prompt forces the model to ground its explanation in the provided error code mapping, preventing hallucinated causes or generic advice. It is appropriate for production incident response, automated retry logic, and observability pipelines where every tool failure must be classified, explained, and routed to the correct recovery path.

The ideal user is an AI infrastructure engineer or SRE who has already instrumented their tool-calling layer to capture error outputs and now needs a reliable translation layer between raw error signals and the agent's decision logic. You should have a predefined error code mapping—such as a JSON dictionary linking HTTP status codes, gRPC codes, or database error numbers to plain-language causes and recovery actions—that you can inject into the prompt as the [ERROR_CODE_MAP] variable. The prompt expects a structured input containing the tool name, the error code, the raw error message, and any relevant request context. Without this grounding data, the model will default to generic troubleshooting advice, which undermines the reliability goals of a self-healing system.

Do not use this prompt when the error is already fully handled by application-level retry logic with deterministic backoff, when the error code is unknown and no mapping exists, or when the recovery action involves irreversible side effects such as database deletions, financial transactions, or user notification without human approval. In these high-risk scenarios, the prompt's output should be treated as a recommendation that requires explicit human review before execution. Additionally, avoid this prompt for user-facing error messages where tone, branding, and localization matter more than structured classification—those cases require a separate user-message generation prompt with tone constraints and localization hooks.

Before deploying, ensure your error code mapping is versioned and tested alongside the prompt. A stale mapping that lacks entries for new error codes will cause the model to fall back on its own parametric knowledge, producing plausible but incorrect interpretations. Pair this prompt with a validation harness that checks whether the output's error_code field matches the input, whether the recovery_action is one of the allowed enum values (retry, fallback, escalate, ignore), and whether the explanation references the provided mapping rather than inventing causes. For high-severity errors, route the output to a human on-call before any automated recovery action is taken.

This template is designed to be placed directly into your system or developer message. It instructs the model to act as a reliability interpreter, translating opaque error codes and stack traces from tool outputs into structured, actionable guidance. The prompt forces the model to consult a provided error code mapping before generating any explanation, preventing hallucinated interpretations of unfamiliar codes.

textCopy
You are a tool-output error interpreter for a production AI system. Your job is to translate raw error payloads from tool calls into plain-language explanations, identify the likely cause, and recommend a concrete recovery action.

You will receive:
- A raw error payload from a tool call: [ERROR_PAYLOAD]
- The name of the tool that produced the error: [TOOL_NAME]
- The context of the original user request: [USER_REQUEST_CONTEXT]
- A mapping of known error codes to their meanings and recovery strategies: [ERROR_CODE_MAP]

Your response must be a single valid JSON object conforming to this schema:
{
  "error_summary": "A one-sentence plain-language summary of what went wrong.",
  "error_code_identified": "The specific error code extracted from the payload, or 'UNKNOWN'.",
  "likely_cause": "A 1-2 sentence explanation of the most probable cause, grounded in the error code map if available.",
  "recommended_action": "One of: RETRY, FALLBACK, ESCALATE, or IGNORE.",
  "action_rationale": "A brief justification for the recommended action, referencing the error code map or payload details.",
  "user_facing_message": "A safe, non-technical message suitable to show the end-user, or null if the error should not be exposed.",
  "retry_strategy": {
    "should_retry": true or false,
    "max_retries": "An integer, 0 if should_retry is false.",
    "retry_delay_seconds": "An integer suggesting backoff.",
    "retry_modifications": "Any changes to arguments or context for the retry, or null."
  },
  "escalation_reason": "If action is ESCALATE, explain why human intervention is needed. Otherwise null.",
  "fallback_tool": "The name of a fallback tool to call if action is FALLBACK, or null."
}

Rules:
1. Always consult the [ERROR_CODE_MAP] first. If the error code is not found, set error_code_identified to 'UNKNOWN' and base your analysis solely on the payload structure and message.
2. Never invent error meanings. If the cause is unclear, state that explicitly.
3. For 4xx errors, prefer FALLBACK or ESCALATE over RETRY unless the error map indicates a client-correctable issue.
4. For 5xx errors, prefer RETRY with exponential backoff unless the error map indicates a persistent outage.
5. For timeout errors, always suggest RETRY with a longer timeout.
6. The user_facing_message must never expose internal stack traces, API keys, database queries, or system paths.
7. If the error payload contains sensitive data (PII, secrets, tokens), set user_facing_message to null and set recommended_action to ESCALATE.

To adapt this template, replace the square-bracket placeholders with your runtime data. The [ERROR_CODE_MAP] is the most critical input and should be maintained as a structured JSON or YAML object mapping known error codes (e.g., HTTP 429, gRPC UNAVAILABLE, Postgres 23505) to their plain-language meaning and recommended recovery. If your system does not have a formal error code map, start by documenting the top 10 most frequent tool errors and their resolutions. For high-risk domains, always route ESCALATE actions to a human review queue and log the full prompt and response for auditability.

This prompt is designed to be called immediately after a tool execution failure. In your application harness, wrap every tool call in a try/catch or error-handling middleware that captures the raw error object—including the error code, message, and the tool that failed. Pass this captured error context directly into the prompt's [ERROR_CODE], [ERROR_MESSAGE], and [TOOL_NAME] placeholders. Do not send raw stack traces or internal hostnames to the model; sanitize the error payload before injection to prevent information leakage. The prompt should be invoked as a synchronous step before any retry logic executes, so the model's classification can inform the recovery strategy.

The harness must enforce a strict output contract. Parse the model's JSON response and validate that action is one of the allowed enum values: retry, fallback, escalate, or noop. If the action is retry, check that retry_strategy is populated with a valid value (exponential_backoff, immediate, or after_delay) and that retry_delay_ms is a positive integer. If the action is fallback, confirm that fallback_tool is a non-empty string matching a tool in your approved fallback registry. Reject any response that does not conform to this schema and either re-prompt with a stricter format instruction or default to escalate with a human_review_required flag set to true. Log every interpretation attempt—including the raw error, the model's classification, and the harness's validation decision—for later observability and prompt debugging.

For retry logic, use the model's retry_delay_ms as an upper bound, not an exact instruction. Implement a jittered backoff in your application code to avoid thundering herd problems on downstream services. Cap the maximum number of automatic retries at three, and after the third failure, force an escalation regardless of the model's recommendation. For HTTP error codes like 429 (Rate Limited), the harness should always respect the Retry-After header if present, using the model's interpretation only as a fallback when the header is missing. For gRPC errors, map the gRPC status code to the prompt's [ERROR_CODE] field using the standard string representation (e.g., UNAVAILABLE, DEADLINE_EXCEEDED). For database errors, include the SQLSTATE code if available, but strip query parameters and table names from the error message to avoid exposing schema details to the model.

When the model recommends escalate, the harness should create a structured incident record that includes the original user request, the tool that failed, the full error payload, the model's explanation and user_message fields, and a direct link to the relevant runbook. Route this record to the on-call channel or ticketing system specified in your escalation policy. Do not expose the model's raw user_message to end users without review; it should be treated as a draft that a human operator can approve, edit, or replace. For high-severity error codes (e.g., database connection failures, authentication errors), bypass the model entirely and escalate immediately from the harness—the prompt is for interpretable failures, not catastrophic infrastructure outages. Test this harness with a golden dataset of known error scenarios, including rate limits, timeouts, permission denials, and malformed responses, to ensure the routing logic and validation guards behave correctly before production deployment.