Tool Failure Fallback to Human Prompt

This prompt is designed for a single, high-stakes job: generating a structured, machine-readable handoff payload when an AI agent's tool execution fails after all retry policies have been exhausted. The ideal user is a platform engineer or AI reliability engineer who is building an agent harness and needs a deterministic, auditable way to stop an agent from looping on a broken tool. Instead of the agent hallucinating a fix or silently failing, this prompt forces it to package all diagnostic state—the failed tool name, raw error, retry count, partial results, and dependency chain—into a JSON object that a downstream ticketing system, alerting platform, or human operator dashboard can consume without manual parsing.

You should use this prompt only after your application-level retry logic has concluded. The required context is substantial and must be injected into the [TOOL_FAILURE_CONTEXT] placeholder: this includes the fully qualified tool name, the exact error message or stack trace, the number of retries attempted, any partial or intermediate results the tool produced before failing, and the state of the dependency chain (e.g., which upstream tools succeeded and what data they passed). Without this rich context, the model cannot produce a useful diagnostic payload. The output is not a conversational message for a user; it is a system-to-system or system-to-operator payload. Do not use this prompt for live conversational handoffs, where tone and user sentiment are critical, or for guardrail violations, which require a different evidence package focused on policy rules and violating content.

The primary constraint is that this prompt must be called with a clear [OUTPUT_SCHEMA] that your receiving system expects. A common failure mode is generating a handoff that a human can read but an API cannot parse. To prevent this, your harness should validate the generated JSON against your schema immediately and, if validation fails, use a repair prompt or a simpler, more constrained model to fix the structure. For high-risk production systems, log every generated handoff payload before it is sent to the operator queue, creating an audit trail that links the agent's execution trace to the escalation event. Next, review the 'Implementation Harness' section to see how to wire this prompt into a reliable retry-and-escalation loop.

This prompt is designed to be injected into your agent's escalation path immediately after a tool execution failure. Its job is to package the failure's full context—the tool name, error details, retry attempts, partial results, and dependency chain state—into a structured handoff for a human operator. The prompt assumes that your application harness has already captured the raw error and execution metadata; the model's role is to synthesize this into a coherent, actionable payload.

textCopy
You are a diagnostic handoff agent for an AI operations platform. A tool execution has failed after exhausting all automated retries. Your task is to produce a structured handoff payload for a human operator. Do not attempt to re-execute the tool or guess at a resolution.

## Input Context
- Failed Tool Name: [TOOL_NAME]
- Tool Description: [TOOL_DESCRIPTION]
- Error Message: [ERROR_MESSAGE]
- Error Type: [ERROR_TYPE]
- Retry Attempts: [RETRY_COUNT]
- Retry Log: [RETRY_LOG]
- Partial Results (if any): [PARTIAL_RESULTS]
- Dependency Chain State: [DEPENDENCY_STATE]
- Workflow Step: [WORKFLOW_STEP]
- User Impact: [USER_IMPACT]
- System State at Failure: [SYSTEM_STATE]

## Output Schema
Produce a JSON object with the following structure:
{
  "handoff_type": "TOOL_FAILURE",
  "severity": "critical|high|medium|low",
  "failed_tool": {
    "name": "string",
    "description": "string",
    "error_summary": "A one-sentence summary of what went wrong.",
    "error_detail": "A detailed explanation of the error, including the raw error message.",
    "error_type": "string"
  },
  "retry_context": {
    "attempts_made": "number",
    "final_error": "string",
    "retry_log_summary": "A brief summary of the retry attempts and any pattern observed."
  },
  "partial_results": {
    "available": "boolean",
    "data": "object | null",
    "usability_notes": "If partial results exist, describe what is usable and what is missing."
  },
  "dependency_chain": {
    "blocked_steps": ["list of downstream workflow steps that are now blocked"],
    "completed_steps": ["list of steps that completed successfully before the failure"],
    "resume_point": "The exact step or state from which a human should resume."
  },
  "operator_actions": {
    "immediate_actions": ["A prioritized list of 2-4 concrete actions the operator should take first."],
    "investigation_hints": ["Specific logs, dashboards, or systems to check."],
    "rollback_or_fix_options": ["If known, suggest safe remediation paths."]
  },
  "context_for_operator": {
    "user_impact": "string",
    "system_state_at_failure": "string",
    "urgency_rationale": "Explain why this severity level was chosen."
  }
}

## Constraints
- Do not fabricate information not present in the input context.
- If a field's value is unknown, use null or an empty array as appropriate, and note the absence in the relevant summary field.
- The operator_actions must be specific and actionable, not generic advice.
- Preserve any PII or sensitive data as-is; redaction is handled upstream.

To adapt this template, replace each square-bracket placeholder with runtime values from your tool execution harness. The [RETRY_LOG] should be a structured log of each attempt, including timestamps and error codes. The [DEPENDENCY_STATE] should capture the state of upstream and downstream tasks in the workflow DAG. Before deploying, test the prompt with at least three distinct failure modes (e.g., a network timeout, an authorization error, and a malformed API response) and validate that the generated JSON conforms to the schema and that the operator_actions are genuinely useful. For high-severity failures, route the output to an on-call escalation channel rather than a general queue.

This prompt is designed to be the final step in a tool execution retry loop. After an agent's tool call has failed and all configured retry attempts are exhausted, the execution wrapper should call the LLM with this prompt, passing the complete failure context. The prompt's job is to produce a structured JSON handoff payload that a human operator can use to diagnose and complete the interrupted workflow. Do not call this prompt for transient errors that a retry can resolve; reserve it for persistent failures where the agent has reached its safe operating limit.

Wire the prompt into your agent's tool execution wrapper as a terminal handler. The wrapper should collect the failed tool name, the full error message, the number of retry attempts, any partial results returned before failure, and the dependency chain state (which upstream tools succeeded, which downstream tools are now blocked). Pass these as the [FAILED_TOOL], [ERROR_DETAILS], [RETRY_ATTEMPTS], [PARTIAL_RESULTS], and [DEPENDENCY_CHAIN] placeholders. After the LLM returns its response, parse the JSON and validate it against the output contract: handoff_type must equal "tool_failure", operator_actions must be a non-empty array of strings, and diagnostic_context must include the failed tool name and error summary. If validation fails, fall back to a static handoff template that includes the raw error and a generic escalation message. Log the validated handoff payload to your incident management system (e.g., PagerDuty, Opsgenie) and trigger a notification to the on-call operator with a direct link to the workflow trace and the structured payload.

After the handoff is generated and logged, the agent must stop. Do not allow it to continue executing downstream tools, retry the failed tool, or attempt a different code path. The handoff represents a hard boundary where the system has determined that autonomous recovery is not safe or possible. The operator should receive enough context to resume the workflow from the failure point without replaying the entire session. Test this harness by simulating tool failures in a staging environment and verifying that the handoff payload is valid, the notification fires, and the agent halts correctly. Common failure modes include the LLM omitting required fields, hallucinating a resolution, or producing a handoff that lacks actionable operator steps—each of which your validation layer should catch.