Tool denied

In production, DefaultToolAuthzPolicy(default_deny=True) denies any tool operation that is not explicitly classified. This page explains the most common denial reasons.

Common causes

1. Unclassified tool

A registered connection with no classified operations denies every tool.

Fix with alquimia registry tools set-operation:

alquimia registry tools set-operation filesystem-tools "list_*" \
  --match glob --severity read-only --tier-grants reader,editor,operator

2. Role tier not granted

The agent’s role must appear in the operation’s effective tier_grants. A reader agent cannot invoke an operation that only grants editor or operator.

3. Severity floor excludes the role

Severity	Max grantable tier
`read-only`	`reader`, `editor`, `operator`
`mutating-recoverable`	`editor`, `operator`
`destructive`	`operator` only

Even if tier_grants includes reader, a mutating-recoverable operation excludes reader.

4. `tier_ceiling` is too narrow

An agent spec can narrow registry grants with tier_ceiling but never widen them:

{
  "provider_id": "mcp",
  "tool_ref": "filesystem-tools",
  "tier_ceiling": ["reader"]
}

This denies any operation that requires editor or operator.

Inspect the resolved policy

alquimia registry tools inspect filesystem-tools --for-tool "delete_file"

This prints the matched operation, effective tier grants, and whether approval is required.

Checklist

The tool is registered with at least one classified operation.
The operation name matches the runtime tool name (exact, glob, or regex).
The agent’s role is in the operation’s tier_grants.
The operation severity does not exclude the agent’s role.
The agent’s tier_ceiling does not exclude the operation.