When a Tool Must Reject a Caller: Writing the Denial Response

A denial response should be JSON with a stable shape across every tool you expose. The minimum viable set:

Two of these carry more weight than the rest. The cause object must name the principal, the resource and the verb separately, because an agent debugging a denial needs to know whether it was the agent identity, the delegated user context or the target record that failed. The alternatives array is what separates a good denial from a dead end. If a caller asked to export a full customer table and the agent only holds a field-restricted scope, list summarize_customer_segment and read_customer_record as permitted calls. That mirrors the field-level and record-level constraint approach recommended in permission playbooks, where agents get whitelisted objects, fields and verbs, with higher-risk actions requiring a separate approval as laid out by Pedowitz Group.

Echoing request_id is not optional. Structured logs with correlation ids are the basis for auditing which agent did what across a tool chain per Scalekit's guidance on tool calling authentication. Without the echo, the denial sits in your logs as an orphan and the caller's trace shows only a failed step.

Here is a working shape:

{
  "request_id": "req_9f2c1a",
  "denied": true,
  "reason_code": "SCOPE_MISSING",
  "retryable": false,
  "retry_after_seconds": null,
  "cause": {
    "principal": "agent:support-triage",
    "delegated_user": "user:4471",
    "resource": "crm.accounts",
    "action": "export_bulk"
  },
  "alternatives": ["crm.accounts.read_one", "crm.accounts.summarize_segment"],
  "escalation": {
    "owner": "[email protected]",
    "channel": "ticket",
    "ticket_ref": "AC-2291",
    "expected_response_hours": 8
  },
  "human_message": "Bulk account export needs a manager-approved scope."
}

The single most useful decision you make is the retryable flag, and getting it wrong costs real money. Conflating retryable and non-retryable failures is described as one of the fastest ways to break a production agent, because blind retries of malformed or unauthorized calls burn tokens for identical failures as n8n's error handling guide explains. A denial should be classified before it leaves your service.

Hard denials are deterministic. The same call with the same credentials will fail forever. These carry retryable: false and always include an escalation target. Examples:

• SCOPE_MISSING: the agent's token does not carry the required scope.
• POLICY_BLOCK: a policy rule forbids the action outright, such as exporting regulated fields to an external destination.
• TENANT_MISMATCH: the resource belongs to a different tenant than the delegated user.
• FORBIDDEN_TOOL: the tool is not on the agent's allowlist.

Soft denials are temporary. The call is legitimate and the credential is sufficient, but a limit or window blocks it right now. These carry retryable: true and a retry_after_seconds value. Examples:

• QUOTA_EXCEEDED: a per-agent call budget is spent for the current period.
• RATE_WINDOW: the downstream service is throttling.
• APPROVAL_PENDING: a human approval exists but has not been granted yet.

The decision rule is simple: if a retry with the identical payload and identical credentials could plausibly succeed once the stated condition clears, the denial is soft. If not, it is hard. Never set retryable: true without retry_after_seconds, because a model told "you may retry" with no bound will loop.

One subtlety worth building in: distinguish "retry identical" from "retry after changing the request." An input validation rejection is neither soft nor hard in the usual sense. The model must inspect the error and repair the call. Handle those in your orchestration layer with a repair path rather than a retry budget, as the retry-classify pattern recommends by routing validation errors to a repair strategy instead of backoff in the seven-patterns production guide.

Example 1: scope missing on a bulk export. A triage agent asks for a bulk export of accounts. It holds one-token-per-resource style delegated credential scoped to reads. The service returns SCOPE_MISSING, retryable: false, cause.action: export_bulk, and an escalation block pointing at the RevOps access owner with a ticket reference. It also lists two alternatives that succeed today. The agent's plan changes: it summarizes the segment instead. No human is paged, and the trace shows the denied attempt next to the successful alternative. This is the pattern of task-scoped, ephemeral credentials that expire with the session described by Sweet Security.

Example 2: quota exceeded mid-workflow. A reporting agent has been calling one tool in a loop and hits the per-session budget. The service returns QUOTA_EXCEEDED, retryable: true, retry_after_seconds: 900. Because the response names the condition, the caller's orchestration layer can pause and resume instead of failing the whole run. A circuit breaker that opens after repeated failures and reports a bounded cool-down to the agent is a close cousin of this pattern as shown in the production patterns guide.

Example 3: approval pending on a write. A coding agent proposes a change to a deployment configuration. The policy allows the write only with human approval, so the service returns APPROVAL_PENDING, retryable: true, retry_after_seconds: 300, and an escalation block naming the on-call approver. The general rule for agents is that they may propose high-consequence actions but execution pauses until a human approves per Sweet Security's privilege abuse guidance. The agent stores the fact that it is waiting, reports to the user, and rechecks. Without retry_after_seconds, the agent would either give up too early or hammer your approval queue.

Note what all three share. The caller never has to parse a stack trace or a sentence in English to decide what to do next. The payload short-circuits the model's improvisation.

Denial logs are your highest-value audit data because they record intent that was blocked. Log these fields immutably for every denial: request id, agent identity, delegated user, tool name, the cause object, the reason code, the verdict, the enforcement action taken, and a timestamp. That set matches the logging expectations for AI agent policy decisions, where records should capture the requested action, agent identity, relevant context, policy evaluated, verdict and outcome as Sweet Security lists.

Three rules make the logs useful rather than merely present.

First, make denial records write-once. The Lasso analysis of runtime enforcement notes that compliance frameworks increasingly require evidence that safeguards are actively enforced during operation, not just documented at design time per Lasso's enforcement overview. A mutable denial log is weak evidence.

Second, log the alternatives you offered along with whether the caller took one. A denial where the caller immediately found a permitted path means your allowlist is well designed. A denial with no follow-up call means the agent gave up or the payload was unclear. That ratio is the metric to watch.

Third, watch for chains that combine low-risk permissions into a high-risk outcome. Read-only in one system plus write in another can still be dangerous when an agent joins the two, which is why access decisions need to be evaluated across workflows and not just within single tools per Pluto Security. Failed denials near a successful chain are the strongest signal that a policy is too coarse.

If you are running agents through a single inference endpoint, that endpoint is the natural place to attach the same request id you emit in denials, so one trace spans model calls and tool calls. Quanta Inference exposes text, image, video, audio and embedding models through one OpenAI-compatible API, which keeps that correlation simple across model types Quanta Inference.

The denial path is the code most likely to rot, because it fires only on the unhappy route. Treat it like any other contract and test it three ways.

Unit contract tests. For every tool, assert that a denial returns all required fields, that denied is true, that retryable: false always carries a non-null escalation, and that retryable: true always carries a positive retry_after_seconds. This is a schema assertion, not a behavior test, and it catches the common drift where a new reason code ships without its mapping.

Agent behavior tests. Give a test agent a denied tool and check what it does next. The expected behaviors are: stops and reports on a hard denial, waits the stated interval and retries on a soft denial with a bounded budget, and picks an alternative when one is listed. This is where most real defects surface, because the model interprets your payload. One practitioner warns that asking the model to self-regulate on policy decisions is not enough; enforcement should be deterministic and not rely on the model as Lasso argues. Your tests are where you verify that the deterministic layer actually bounded the unpredictable one.

Adversarial tests. Craft calls that attempt to trigger the denial indirectly: a prompt injection that steers the agent toward a forbidden tool, a delegated token reused for a tool outside its task, or two permitted reads that together expose another tenant's data. Fine-grained access control that blocks any tool call outside the agent's explicit scope is the stated mitigation for prompt injection risk as Auth0's access control review explains. Test that the block surfaces as a clean POLICY_BLOCK denial, not a 500.

Close the loop by replaying real denials from your logs against a staging build after any policy change. If a previously clean SCOPE_MISSING now returns POLICY_BLOCK, you changed a rule and should know before a customer does.

The escalation object only helps if the owner it names is real and reachable. Approval workflows for elevated access should route through a ticketed process with business justification and an expiration, rather than an ad hoc request per the access and permissions playbook. Map each reason code to an owner in configuration, not in code, so the mapping is reviewable:

escalation_map:
  SCOPE_MISSING:
    owner: [email protected]
    channel: ticket
    expected_response_hours: 8
  POLICY_BLOCK:
    owner: [email protected]
    channel: ticket
    expected_response_hours: 24
  APPROVAL_PENDING:
    owner: [email protected]
    channel: pager
    expected_response_hours: 1

Review that map on the same cadence as your access recertification. Quarterly reviews that remove dormant accounts and collapse duplicate roles should also validate that no denial points at a person or queue that no longer exists per Pedowitz's governance guidance. A stale owner is worse than none, because it teaches the caller to escalate into a void.

When the denial discipline needs to extend across a whole line of business, an expert that already reads your context and hands back finished deliverables can carry the review load: Quanta Experts are built for exactly that division of work Quanta Experts.