Graceful Degradation User Experience Prompt Template

This prompt is for product teams and AI engineers who need to generate a user-facing message when a backend tool call fails. Its job is to transparently communicate the degradation, set accurate expectations, and offer alternatives without exposing internal failure details, error codes, or system architecture. Use this prompt inside a recovery harness that catches tool call exceptions and routes them to a user-communication layer. This is not a prompt for retrying the tool call or fixing the error; it is for managing the user's experience after the system has decided to degrade gracefully.

The ideal user is a product reliability engineer, a full-stack AI developer, or a technical product manager responsible for the end-to-end user experience of an AI-powered feature. The required context includes the original user intent, the name of the unavailable capability, an estimated recovery time if known, and any available alternative actions the user can take. You should not use this prompt when the system can silently retry with a fallback tool and produce an equivalent result without the user noticing a change. It is also inappropriate for internal logging or debugging messages; those require different structures and can safely include error codes and stack traces.

Before wiring this prompt into production, define clear boundaries for what constitutes a user-visible degradation versus a transparent recovery. If the system can switch to a cached result, a slower but functional endpoint, or a simplified version of the same capability, you may not need a user-facing message at all. Reserve this prompt for cases where the user's workflow is materially impacted—a feature is unavailable, a response will be delayed, or the output quality will be reduced. Pair this prompt with feature-flag checks and permission re-verification to ensure the degradation message does not accidentally promise capabilities the user's current plan or role does not permit.

This template produces a user-facing message when a primary tool call has failed and the system must degrade gracefully. It is designed to be inserted into your system prompt or used as a user message template in a recovery handler. The prompt instructs the model to acknowledge the degradation without exposing internal failure details, set realistic expectations, and offer concrete alternatives. Use it when you have already classified the failure, selected a fallback strategy, and need to communicate the situation to the end user.

textCopy
You are generating a user-facing message for a product experience where a background operation has degraded.

[CONTEXT]
- User request: [USER_REQUEST]
- Primary tool attempted: [PRIMARY_TOOL_NAME]
- Failure classification: [FAILURE_CLASSIFICATION] (e.g., timeout, unavailable, rate_limited, partial_result, empty_result)
- Fallback action taken: [FALLBACK_ACTION] (e.g., serving_cached_result, using_alternative_tool, deferring, manual_review_queued)
- Estimated impact: [IMPACT_DESCRIPTION] (e.g., "results may be up to 15 minutes stale", "only text results are available, images omitted")
- Available alternatives: [ALTERNATIVES_LIST]
- Feature flags checked: [FEATURE_FLAGS]
- User permission level: [USER_PERMISSION_LEVEL]

[OUTPUT_SCHEMA]
{
  "message": "string (user-facing message, 1-3 sentences, plain text)",
  "tone": "string (one of: reassuring, neutral, apologetic)",
  "expectation_set": "string (what the user should expect next)",
  "alternative_offered": "boolean",
  "internal_failure_exposed": "boolean (must be false)"
}

[CONSTRAINTS]
- Do not mention internal tool names, error codes, stack traces, or infrastructure details.
- Do not over-apologize or use alarmist language.
- If a cached or partial result is being shown, state its freshness or completeness honestly.
- If the user can retry, tell them when and how.
- If the user cannot fix the issue, do not suggest they try again immediately.
- Match the tone to the impact: minor staleness is reassuring; complete unavailability is neutral and direct.
- If [USER_PERMISSION_LEVEL] is insufficient for any alternative, do not offer that alternative.
- Respect feature flags: if a fallback is disabled via [FEATURE_FLAGS], do not mention it.

[EXAMPLES]
Example 1:
User request: "Show me Q3 revenue by region"
Failure: timeout on live analytics tool
Fallback: serving cached report from 2 hours ago
Message: "Live analytics are temporarily slow, so we're showing your Q3 revenue report from about 2 hours ago. The numbers should be very close to current. We'll refresh automatically when the system recovers."

Example 2:
User request: "Generate a custom export of all transactions"
Failure: export service unavailable
Fallback: queued for processing, user will be notified
Message: "We weren't able to generate your export right now, but it's been queued and we'll send it to you as soon as it's ready—usually within 15 minutes. No further action needed from you."

Adapt this template by replacing the [CONTEXT] block with values from your tool call recovery handler. The failure classification should come from your error interpreter, not from raw error codes. The fallback action should reflect the actual recovery path selected by your fallback selection logic. Before deploying, test the prompt against each failure classification in your system to ensure the tone and expectation-setting match your product's voice. Wire the output through a post-generation validator that confirms internal_failure_exposed is false and that no banned terms (tool names, error codes, stack traces) appear in the message.

This prompt is designed to sit behind a tool-call failure handler in your application layer, not as a standalone user-facing endpoint. When a primary tool call fails, times out, or returns an error, your application should catch that failure, enrich the context with the failure classification, available fallback options, and user permission state, then invoke this prompt to generate the user-facing degradation message. The prompt expects structured inputs about what failed, what alternatives exist, and what the user is still allowed to do. Do not pass raw stack traces or internal error codes to the prompt; pre-process failures into user-safe categories such as 'temporarily unavailable,' 'partial results available,' or 'feature disabled for maintenance.'

Wire the prompt into a recovery middleware that intercepts tool call failures before they reach the user. The middleware should: (1) classify the failure type using the tool's HTTP status code, error body, or timeout signal; (2) check feature flags and user permissions to determine which alternative tools or static responses are available; (3) assemble the [FAILED_ACTION], [FAILURE_CLASSIFICATION], [AVAILABLE_ALTERNATIVES], [USER_PERMISSIONS], and [FEATURE_FLAG_STATE] inputs; (4) call the LLM with this prompt; (5) validate the output against the expected schema before rendering it to the user. Validation should confirm the response includes a user_message string, an alternatives array, and an expectations object with resolution_time_estimate and retry_guidance fields. If validation fails, fall back to a static degradation template stored in your application config, not a retry loop that adds latency during an already degraded experience.

For observability, log every degradation event with the failure classification, the prompt version used, the generated message, and whether the user engaged with any offered alternative. This data feeds your reliability metrics and helps tune the degradation prompt over time. Avoid calling this prompt when the primary tool succeeds or when the failure is transparently retryable at the infrastructure layer without user visibility. The prompt is for user-visible degradation only. If you are using a model router, prefer a fast, cost-effective model for this prompt since degradation messages are latency-sensitive and do not require complex reasoning. Test the harness by simulating tool failures in a staging environment and confirming that the full pipeline—failure detection, prompt invocation, output validation, static fallback—behaves correctly under each failure class.