Tool Denial Explanation Prompt Template

This prompt is for platform operators and security engineers who need to generate clear, auditable explanations when an agent's tool action is blocked by a safety or permission boundary. The primary job-to-be-done is transparency: turning a silent failure or a generic 'access denied' error into a structured message that tells the user or calling system exactly what was blocked, which policy was violated, and what alternatives exist. The ideal user is an AI platform engineer integrating this prompt into a tool execution gateway, a compliance officer requiring audit trails for denied actions, or a developer building user-facing copilots where unexplained denials erode trust.

Use this prompt when your system has already made a blocking decision—via an allowlist, a confirmation gate, a scope check, or a least-privilege enforcement layer—and you need to communicate that decision downstream. The prompt requires specific inputs: the blocked tool name and arguments, the policy that triggered the denial, the user's original intent, and any available alternatives. Do not use this prompt as the enforcement mechanism itself. It explains a denial; it does not decide whether to deny. The decision must be made by deterministic guardrails before this prompt is invoked. Also avoid using this prompt for transient errors like network timeouts or rate limits; those require a different retry-and-fallback communication pattern.

Before deploying, ensure you have wired the prompt into a post-denial handler that captures the policy reference, the violating argument, and the user's original request. Test with edge cases where multiple policies could apply, where the user's intent is ambiguous, and where no safe alternative exists. The output should be parseable by both humans and downstream systems—consider including a machine-readable status code alongside the natural-language explanation. If the denial involves regulated data or high-risk operations, route the explanation through a human review queue before it reaches the end user.

This template produces a structured denial explanation for the user or calling system. It forces the model to reference the specific policy that was violated, describe what was blocked, and offer concrete alternatives or an appeal path. The prompt is designed to be wired into a post-decision handler in your agent orchestration layer—after a policy engine or guardrail has already determined the action is blocked, not as the decision-maker itself.

textCopy
You are generating a tool denial explanation for a user or calling system. Your goal is to be transparent, precise, and helpful without revealing internal security details or suggesting workarounds that would violate policy.

## INPUT
- Blocked Action: [BLOCKED_ACTION]
- Tool Name: [TOOL_NAME]
- Violated Policy: [POLICY_NAME]
- Policy Description: [POLICY_DESCRIPTION]
- User Request Summary: [USER_REQUEST_SUMMARY]
- Available Alternatives: [ALTERNATIVES]
- Appeal Path: [APPEAL_PATH]
- Risk Level: [RISK_LEVEL]

## OUTPUT SCHEMA
Return a JSON object with these fields:
- `explanation_summary` (string, 1-2 sentences): Plain-language summary of what was blocked and why.
- `policy_reference` (string): Name and brief description of the violated policy.
- `alternatives` (array of strings): Concrete, safe alternatives the user can try. Empty array if none exist.
- `appeal_instructions` (string or null): How to request a review or exception. Null if no appeal path exists.
- `risk_classification` (string): One of "low", "medium", "high", "critical".

## CONSTRAINTS
- Do not reveal internal system architecture, security rules, or the names of other blocked actions.
- Do not suggest ways to bypass the policy.
- If the risk level is "high" or "critical", include a note that the action was automatically blocked and logged for security review.
- Use a neutral, professional tone. Do not apologize excessively or blame the user.
- If no alternatives exist, state that clearly rather than inventing weak options.
- Keep the explanation under 150 words total.

## EXAMPLES

### Example 1: Read-only scope violation
Input: User requested DELETE on production database via SQL tool. Policy: "Production databases are read-only for automated agents."
Output:
{
  "explanation_summary": "The requested DELETE operation on the production database was blocked because automated agents have read-only access to production systems.",
  "policy_reference": "Production Database Read-Only Policy (DB-RO-001): Automated agents may only execute SELECT queries against production databases.",
  "alternatives": ["Request a read-only report of the data you wanted to delete", "Submit a manual change request through the DBA team"],
  "appeal_instructions": "To request an exception, file a change request at https://internal.example.com/dba-requests with justification.",
  "risk_classification": "high"
}

### Example 2: Rate limit exceeded
Input: User attempted 500 API calls in 1 minute. Policy: "Maximum 100 calls per minute per user."
Output:
{
  "explanation_summary": "Your request was blocked because you exceeded the rate limit of 100 calls per minute. You sent 500 requests in the last 60 seconds.",
  "policy_reference": "API Rate Limit Policy (RATE-002): Users are limited to 100 API calls per minute.",
  "alternatives": ["Wait 60 seconds and retry", "Batch your requests into fewer calls", "Request a rate limit increase for your account"],
  "appeal_instructions": "To request a higher rate limit, contact your account administrator.",
  "risk_classification": "low"
}

Now generate the denial explanation for the provided input.

Adapt this template by replacing the example scenarios with ones that match your actual tool policies and risk classifications. The [ALTERNATIVES] and [APPEAL_PATH] placeholders should be populated by your policy engine before the prompt is assembled—don't ask the model to invent safe alternatives at runtime. For high-risk domains like healthcare or finance, add a [REVIEWER_ID] field and require that the explanation be logged alongside the blocking decision for audit purposes. Test this prompt against edge cases where the blocked action is ambiguous or the user request summary is incomplete; the model should ask for clarification rather than guessing at the violation.

The Tool Denial Explanation prompt is not a standalone chat interaction—it is a structured response generator that sits inside a policy enforcement point in your agent platform. When a tool invocation is blocked by a permission boundary, allowlist, or scope check, your application code should call this prompt with the blocked action details, the violated policy, and the user's original intent. The prompt's output becomes the machine-readable denial payload returned to the calling system or end user. This means you must treat the prompt as a deterministic component with a strict input contract and a validated output schema, not as an open-ended conversational fallback.

Wire the prompt into your tool execution middleware. When your permission engine denies a tool call, construct the input object with [BLOCKED_ACTION] (the tool name and arguments that were rejected), [VIOLATED_POLICY] (the specific policy rule or boundary that triggered the denial), [USER_INTENT] (the original request that led to the blocked action), and [AVAILABLE_ALTERNATIVES] (any permitted tools or actions that could partially satisfy the request). Pass this structured input to the model with a low temperature setting (0.0–0.2) to maximize output consistency. Validate the response against your expected schema before returning it: check that denial_reason is populated, policy_reference includes a traceable rule ID, and alternatives is either a valid list or explicitly null. If validation fails, retry once with the validation errors appended to the prompt as [CONSTRAINTS]. After a second failure, fall back to a hardcoded denial template and log the full prompt-response pair for debugging.

Log every denial event with the full input, output, policy reference, and user session ID. These logs serve three purposes: audit evidence for compliance reviews, debugging data for permission-tuning cycles, and trend analysis for identifying policies that generate excessive friction. If your platform supports human appeal workflows, include the appeal_path field from the prompt output as an actionable link or reference in your UI. Do not allow the agent to continue execution after a denial—the denial response should terminate the current tool chain and return control to the user or orchestrator. For high-risk domains, require a human reviewer to confirm that the denial was correct before the appeal process begins, and never let the model itself decide to override a policy denial.