Graceful Degradation When Primary Tool Unavailable Prompt Template

This prompt is designed for product reliability teams, SREs, and AI infrastructure engineers who need an AI system to self-heal when a primary tool call fails due to an outage, network partition, or dependency failure. The core job-to-be-done is not a simple retry, but a deliberate orchestration of a degraded operational state. Instead of returning a raw error to the user, the model generates a structured degradation plan that selects an alternative tool, prepares a static fallback response, or crafts a transparent user-facing message. Use this prompt when your application's tool-calling layer detects that a primary tool is unreachable and you need the model to decide the next best action based on available fallback options, feature flags, and operational constraints.

The ideal user is an engineer embedding this prompt into a recovery harness. The required context includes a list of available fallback tools with their capabilities and costs, the current feature flag state, the original user intent, and the specific failure mode (e.g., timeout, 503, connection refused). The prompt is most effective when the system has multiple degraded paths to choose from, such as a cached result, a less-precise alternative tool, or a static help article. It should not be used for simple retry logic, single-tool timeout recovery, or cases where the only acceptable outcome is a successful call to the primary tool. For those, use the dedicated Tool Call Timeout Recovery Prompt Template or API Rejection Retry with Backoff Prompt Template.

A concrete implementation example is an e-commerce support copilot whose primary order-lookup API is returning 503 errors. The harness detects the failure and invokes this prompt with the context of a secondary, read-only reporting database that is 15 minutes stale, a static 'check order status' help page, and a feature flag enabling degraded mode. The model's degradation plan would select the reporting database for a lookup, prepend a staleness warning to the user response, and log the event for the monitoring system. This is a deliberate shift to a functional but degraded state, not a blind retry loop.

Avoid using this prompt when the failure is transient and a simple retry with backoff is the correct engineering response. It is also inappropriate when no alternative tool or fallback path exists, as the model will be forced to generate a plan it cannot execute, leading to a confusing user experience. In high-risk domains such as healthcare or finance, the degradation plan must always include a human review gate before execution, and the prompt's output should be treated as a recommendation, not an autonomous action. The next step after reading this section is to review the prompt template and prepare your tool capability registry and feature flag schema.

This template is designed to be placed in your system prompt or invoked as a dedicated recovery step when your application detects that a primary tool is unreachable, timing out, or returning a fatal error. It forces the model to reason about available alternatives, operational constraints, and user communication before emitting a structured plan. The output is not a conversational reply but a machine-readable degradation decision that your application harness can execute.

textCopy
You are a reliability engineer responsible for maintaining service when a primary tool is unavailable.

## CONTEXT
- Primary tool that failed: [PRIMARY_TOOL_NAME]
- Failure mode: [FAILURE_MODE] (e.g., timeout, 503, connection refused, circuit breaker open)
- User intent that triggered the tool call: [USER_INTENT]
- Available alternative tools with their capabilities, costs, and latencies:
[AVAILABLE_TOOLS]
- Current operational constraints:
  - Latency budget remaining: [LATENCY_BUDGET_MS]ms
  - Cost budget remaining: [COST_BUDGET]
  - Feature flags active: [FEATURE_FLAGS]
  - User permission scope: [USER_PERMISSIONS]
- Retry state: [RETRY_STATE] (e.g., first failure, retries exhausted, circuit breaker open)
- Monitoring alert status: [ALERT_STATUS]

## TASK
Produce a degradation plan as a JSON object with the following schema:
{
  "decision": "fallback_tool" | "static_response" | "user_clarification" | "escalate_to_human" | "fail_gracefully",
  "selected_fallback_tool": string | null,
  "fallback_tool_arguments": object | null,
  "static_response_text": string | null,
  "user_facing_message": string,
  "confidence": 0.0-1.0,
  "reasoning": string,
  "monitoring_alert_update": string | null,
  "requires_human_approval": boolean
}

## CONSTRAINTS
1. If a fallback tool is selected, it must be in the available tools list and must not exceed the latency or cost budgets.
2. If no fallback tool meets constraints, prefer static_response or user_clarification over guessing.
3. The user_facing_message must be transparent about degradation without exposing internal failure details, error codes, or tool names.
4. If confidence is below 0.7, set requires_human_approval to true.
5. If the circuit breaker is open, do not select any tool that depends on the same downstream service.
6. If feature flags disable a fallback tool, treat it as unavailable.
7. If the user lacks permission for a fallback tool, do not select it.

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## OUTPUT
Return only the JSON object. No markdown fences, no commentary.

Adapt this template by replacing the square-bracket placeholders with runtime values from your application context. The [AVAILABLE_TOOLS] placeholder should be populated with a structured list of tool names, descriptions, typical latencies, and costs so the model can make informed trade-offs. The [FEW_SHOT_EXAMPLES] placeholder is critical for production reliability: include at least two examples showing correct degradation decisions for common failure modes in your system. Before deploying, validate that the output JSON matches the schema exactly and that your harness can parse and act on each decision value. For high-risk domains, route any plan with requires_human_approval: true to a review queue before execution.

This prompt is designed to be invoked by an orchestration layer—not directly by an end user. When a primary tool call fails, times out, or returns an unrecoverable error, your application should catch the failure, enrich the context with the original intent, available fallback tools, and operational constraints, then call this prompt to produce a structured degradation plan. The prompt's output is a machine-readable plan that your harness parses and executes, not a user-facing message. Treat the degradation plan as a decision document that your system acts on: select the recommended fallback tool, serve a static response, or trigger a user communication template.

The implementation harness requires several pre-built components. First, maintain a tool registry that maps each primary tool to its fallback alternatives, including their cost profiles, latency characteristics, and capability gaps. Second, integrate a feature-flag service so the prompt can check whether fallback tools are currently enabled for the requesting tenant. Third, build a monitoring alert integration that fires when degradation plans are executed, capturing the failure reason, selected fallback, and SLA impact. Before executing the plan, validate that the selected fallback tool is actually available and that any static response templates referenced in the plan exist in your content store. If the prompt recommends a fallback that is also unavailable, re-invoke the prompt with the updated constraint set rather than silently failing.

Wire the prompt into a degradation decision loop with clear termination conditions. After receiving the structured degradation plan, your harness should: (1) validate the plan against the current tool registry and feature flags, (2) execute the selected fallback action, (3) log the full decision chain including the original failure, the prompt's reasoning, and the executed fallback, and (4) update your circuit breaker state if the fallback also fails. Set a maximum of two degradation attempts before escalating to a human operator via your incident management system. Avoid calling this prompt in a tight retry loop—degradation decisions should be made once per failure event, with the result cached for the duration of the outage window. For high-risk write operations, require explicit human approval before executing any fallback that mutates state, even if the prompt's confidence score is high.