Authentication Failure Tool Call Recovery Prompt

This prompt is designed for security-aware platform engineers and SRE teams who need their AI system to self-heal when a tool call is rejected with an HTTP 401 (Unauthorized) or 403 (Forbidden) status. Instead of crashing the workflow or returning a generic error to the user, the model uses this prompt to classify the auth failure, select a recovery strategy from available options, and produce a corrected tool call or a structured escalation request. The core job-to-be-done is to maintain operational continuity by programmatically resolving authentication failures without human intervention for every transient credential issue.

The ideal deployment context is a production system with multiple available authentication methods (e.g., OAuth2 tokens, API keys, mTLS certificates), a defined credential refresh path (e.g., a token endpoint or a secrets manager), or a structured human re-authentication flow. The prompt requires the following inputs to be effective: the original tool call that failed, the full HTTP response (status code, headers, body), a list of available alternative authentication methods with their refresh capabilities, and the system's escalation policy. Without this context, the model cannot make a safe recovery decision. A concrete implementation would wire this prompt into a middleware layer that intercepts 401/403 responses from tool calls, enriches the failure event with the required context, and then invokes the model to generate a recovery instruction before the workflow proceeds.

Do not use this prompt when the system has only one hardcoded credential with no refresh mechanism. In that case, the failure is terminal and should be handled by application-level retry logic with exponential backoff, not an LLM recovery prompt. Similarly, avoid this prompt in environments where credential rotation is strictly manual and audited out-of-band, as the model's recovery suggestion could conflict with change management policies. The next step after reading this section is to inventory your system's authentication methods and ensure you can provide the required context before integrating the prompt template.

This prompt template is designed to be injected into your error-handling middleware or recovery agent when a tool call returns an HTTP 401 (Unauthorized) or 403 (Forbidden) status. It instructs the model to analyze the failure, classify the root cause (expired token, insufficient scope, revoked credentials), and produce a structured recovery instruction. The output is not a user-facing message but a machine-readable decision that your application harness can execute: retry with a refreshed token, switch to a fallback tool with lower privilege requirements, or escalate for human re-authentication. The template uses square-bracket placeholders so you can adapt it to your specific auth stack, tool catalog, and escalation policies without rewriting the core logic.

textCopy
You are an authentication failure recovery agent. Your job is to analyze a tool call that was rejected with an HTTP 401 or 403 status and produce a structured recovery instruction.

## CONTEXT
- Failed Tool Name: [FAILED_TOOL_NAME]
- Failed Tool Arguments: [FAILED_TOOL_ARGUMENTS]
- HTTP Status Code: [HTTP_STATUS]
- Error Response Body: [ERROR_RESPONSE_BODY]
- Current Auth Method: [CURRENT_AUTH_METHOD]
- Available Auth Methods: [AVAILABLE_AUTH_METHODS]
- Fallback Tool Catalog: [FALLBACK_TOOL_CATALOG]
- Retry Budget Remaining: [RETRY_BUDGET_REMAINING]
- Human Escalation Policy: [ESCALATION_POLICY]

## RECOVERY OPTIONS
You must select exactly one of the following recovery actions:
1. **Retry with alternative auth**: Choose a different auth method from the available list and specify the credential source.
2. **Refresh current credentials**: Instruct the system to refresh the existing token or credential before retrying the same tool call.
3. **Fallback to alternative tool**: Select a tool from the fallback catalog that can satisfy the original intent with lower or different auth requirements.
4. **Escalate for human re-authentication**: Stop automated recovery and request human intervention with a clear reason.
5. **Abort with explanation**: No recovery is possible; produce a terminal failure reason.

## CONSTRAINTS
- Do not invent credentials, tokens, or auth headers.
- If the error indicates a permission scope issue (403), do not retry with the same auth method.
- If the retry budget is exhausted, you must escalate or abort.
- Prefer fallback tools that are read-only over those that mutate state.
- If human escalation is selected, include the exact context a human operator needs to re-authenticate.

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "recovery_action": "retry_alternative_auth" | "refresh_credentials" | "fallback_tool" | "escalate_human" | "abort",
  "reasoning": "string explaining the decision with reference to the error and constraints",
  "alternative_auth_method": "string | null",
  "credential_source": "string | null",
  "fallback_tool_name": "string | null",
  "fallback_tool_arguments": {} | null,
  "escalation_message": "string | null",
  "terminal_failure_reason": "string | null"
}

## EXAMPLES
[RECOVERY_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

To adapt this template, replace the square-bracket placeholders with your production values. [FAILED_TOOL_NAME] and [FAILED_TOOL_ARGUMENTS] come from the failed tool call payload. [AVAILABLE_AUTH_METHODS] should list the auth mechanisms your system supports (e.g., ["oauth2_bearer", "api_key_header", "mtls_certificate"]). [FALLBACK_TOOL_CATALOG] is a mapping of primary tools to their degraded alternatives with auth requirements noted. [RECOVERY_EXAMPLES] should include 2-3 few-shot examples showing correct recovery decisions for common failure patterns in your system. [RISK_LEVEL] should be set to "high" if the tool performs writes or accesses sensitive data, triggering stricter validation of the recovery decision before execution. After adapting, validate the output JSON against your schema before executing any recovery action, and log every recovery decision for auditability.

This prompt is designed to sit inside a recovery middleware layer that intercepts 401 and 403 responses from tool calls before they reach the main agent loop. The middleware should catch the error, enrich the context with the failed request metadata, and invoke this prompt to produce a structured recovery instruction. The recovery instruction is then executed by a tool call executor that can refresh credentials, switch auth methods, or escalate to a human. Do not expose raw auth tokens or secrets to the model; the prompt should reference auth method identifiers and metadata only, never actual bearer tokens or API keys.

Integration flow: 1) The tool call executor detects a 401/403 status. 2) It captures the failed tool name, endpoint, auth method used, error body, and current retry count. 3) It calls this prompt with [FAILED_TOOL], [AUTH_METHOD_USED], [ERROR_DETAILS], [AVAILABLE_AUTH_METHODS], [RETRY_COUNT], and [MAX_RETRIES]. 4) The prompt returns a JSON recovery instruction with fields action (one of retry_with_alternate_auth, refresh_credentials, escalate_to_human, fallback_tool, or abort), selected_auth_method, fallback_tool_name, user_message, and reasoning. 5) The middleware validates the JSON against a strict schema before acting. Validation checks: confirm action is a known enum value; if action is retry_with_alternate_auth, selected_auth_method must be non-null and present in [AVAILABLE_AUTH_METHODS]; if action is fallback_tool, fallback_tool_name must be a valid tool identifier; if action is escalate_to_human, user_message must be populated. Reject and retry the prompt once if validation fails; if it fails twice, escalate to human with the raw model output logged.

Model choice: Use a model with strong instruction-following and JSON mode support (GPT-4o, Claude 3.5 Sonnet, or equivalent). Set temperature=0 to maximize deterministic recovery decisions. Logging and audit: Log every recovery decision with the full prompt input, model output, validation result, and executed action. This is critical for security audit trails—auth failures can indicate credential rotation events, permission misconfigurations, or attack attempts. Human review gate: If action is escalate_to_human, route to an on-call channel with the user_message, reasoning, and a link to the audit log. If action is refresh_credentials, ensure the credential refresh is performed by a secure secrets manager, not by the model or prompt. What to avoid: Never let the model generate new credentials or tokens. Never pass raw tokens in [ERROR_DETAILS]—strip them before prompt assembly. Never allow the recovery loop to exceed [MAX_RETRIES] without forcing escalation.