Tool Denial Explanation Prompt for End Users

This prompt is designed for a single, well-scoped job: generating a user-facing explanation after an upstream policy engine, risk scorer, or allowlist check has already decided to deny a tool invocation. It does not make the denial decision. It does not evaluate the safety of the request. It assumes the decision is final and focuses entirely on the communication layer—translating a machine-level denial into a clear, non-technical message that maintains user trust and offers a constructive path forward. The ideal user is a product designer or frontend engineer integrating an AI copilot or chat interface where a raw error code or silent failure would degrade the experience.

Before using this prompt, you must have the following inputs available: the name of the denied tool, a machine-readable reason code (e.g., RISK_THRESHOLD_EXCEEDED, ROLE_NOT_AUTHORIZED, SUBSCRIPTION_TIER_INSUFFICIENT), the user's visible role or context, and any relevant policy citation. The prompt template uses square-bracket placeholders like [DENIED_TOOL], [DENIAL_REASON_CODE], [USER_CONTEXT], and [POLICY_REFERENCE] to wire these inputs into the generation. You should also provide a [SAFE_ALTERNATIVE] or [ESCALATION_PATH] if one exists; if not, the prompt is designed to gracefully acknowledge the lack of alternatives rather than fabricating them. The output is a plain-language message suitable for rendering directly in a chat bubble or inline notification.

Do not use this prompt for internal logging, audit trail generation, or system-to-system communication. Those use cases require structured, machine-readable outputs with full fidelity to the denial metadata, not user-friendly prose. Do not use this prompt to make the denial decision itself—that responsibility belongs to a deterministic policy engine or a separate classification model with its own evaluation and calibration. Do not use this prompt when the denial reason involves a transient error or retryable condition; users should receive a different message class for TRY_AGAIN scenarios. Finally, do not use this prompt as a substitute for a system-level refusal policy or safety classifier. It is a communication tool, not a safety control. If you are operating in a regulated domain, ensure that a human reviews the generated messages for a representative sample of denial scenarios before production deployment, and log both the denial metadata and the generated message together for auditability.

This template generates a clear, non-technical refusal message when an agent's tool call is blocked by a policy engine. It is designed to be inserted into the system prompt or a post-tool-decision handler. The goal is to maintain user trust by being transparent about the denial reason, citing the relevant policy, and providing a constructive path forward—either a safe alternative tool or an escalation channel. Do not use this template for security-sensitive denials where revealing the policy rationale could aid an attacker; in those cases, use a generic refusal and log the details internally.

codeCopy
SYSTEM: You are an assistant that explains tool access denials to end users. When a tool invocation is denied, you will receive a structured denial record. Your task is to translate that record into a helpful, non-technical message for the user.

DENIAL RECORD:
- Denied Tool: [DENIED_TOOL_NAME]
- Denial Reason Code: [REASON_CODE]
- Policy Reference: [POLICY_CLAUSE_ID]
- User's Role: [USER_ROLE]
- Session Risk Score: [RISK_SCORE]
- Safe Alternative Tool (if any): [ALTERNATIVE_TOOL]
- Escalation Contact: [ESCALATION_EMAIL]

OUTPUT REQUIREMENTS:
1. Acknowledge the user's request without repeating the full technical tool name.
2. Explain the denial in plain language, referencing the policy reason without exposing internal risk thresholds.
3. If [ALTERNATIVE_TOOL] is provided, suggest it as a permitted way to achieve a similar outcome.
4. If no alternative is available, provide the escalation path: "If you believe this is an error, you can request a review by contacting [ESCALATION_EMAIL]."
5. Maintain a helpful, professional tone. Do not apologize excessively or imply the policy is arbitrary.
6. Output ONLY the user-facing message. No JSON, no metadata.

CONSTRAINTS:
- Never reveal the raw [RISK_SCORE] or internal [REASON_CODE] to the user.
- Do not suggest workarounds that involve rephrasing the request to bypass the policy.
- If the denial is for a regulated domain action, include a brief disclaimer that a human review is required.

To adapt this template, replace the square-bracket placeholders with values from your policy engine, session state, and product configuration. The [REASON_CODE] and [POLICY_CLAUSE_ID] should map to a human-readable policy library that the model can reference if needed. For high-risk domains like finance or healthcare, add a [REGULATED_DOMAIN] flag that triggers mandatory human-review language. Before deploying, run this prompt through a regression suite that includes edge cases such as: a user with a borderline risk score, a denied tool that has no safe alternative, and a user attempting to escalate for a clearly malicious request. Validate that the output never leaks internal risk scores or raw policy codes.

This prompt should be invoked after a tool access decision has been made by the authorization layer, not before. The authorization system (e.g., a policy engine evaluating user role, risk score, or session state) produces a structured denial reason—such as POLICY_VIOLATION, TIER_RESTRICTION, or RISK_THRESHOLD_EXCEEDED. That denial reason, along with the denied tool name and any relevant policy citation, is passed into this prompt as [DENIAL_REASON], [DENIED_TOOL], and [POLICY_REFERENCE]. The model's only job is to generate a user-facing explanation message. It must not re-evaluate the access decision or suggest workarounds that bypass the policy.

Wire this prompt as a synchronous post-denial step in your tool-execution middleware. In pseudocode: if auth.check_tool_access(tool_call) == DENY: explanation = llm.generate(denial_prompt, context). The output must be validated against the [OUTPUT_SCHEMA] before being returned to the user. At minimum, validate that the message field is non-empty, does not contain the denied tool's invocation syntax, and does not leak internal policy logic or system prompt fragments. For high-risk deployments, add a regex blocklist that rejects explanations containing phrases like 'ignore previous instructions,' 'you now have access,' or the names of restricted tools. Log the full denial tuple—user ID, session ID, denied tool, denial reason, generated explanation, and validator result—to your observability stack for audit and over-refusal analysis.

Choose a fast, cost-effective model for this step. The explanation generation is a low-complexity, high-volume task that does not require a frontier model. A small model like GPT-4o-mini, Claude Haiku, or a fine-tuned open-weight model is appropriate. If latency is critical, pre-cache common denial templates and use the model only for edge cases. Implement a retry with fallback strategy: if the generated explanation fails schema validation or triggers the blocklist, retry once with an explicit instruction to avoid the flagged pattern. If the retry also fails, fall back to a static, human-reviewed safe message such as 'This action isn't available right now. Contact support for help.' Never surface a raw model failure to the user. For regulated domains, route all generated explanations through a human review queue during an initial probation period, then sample-review after the system demonstrates consistent performance against your eval suite.