> ## Documentation Index
> Fetch the complete documentation index at: https://docs.barndoor.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Granular Tool Use Confirmations
> Require human approval for any tool call — including reads — on a per-tool, per-group basis from the Access Control Center.
## Overview
Granular Tool Use Confirmations lets you require human approval for any tool call an access policy governs — including reads, not just creates, updates, and deletes. An agent reading sensitive data (a customer record, a legal contract, a payroll file) can carry as much risk as one changing it, so approval requirements are configured per tool and per group, inside a policy in the **Access Control Center** — not as a single global setting on the agent.
## Before You Begin
You'll need:
* A Barndoor account with **admin privileges**
* At least one access policy governing the agent and MCP server you want to configure
If you haven't set one up yet, see [Managing Policies](/how-tos/manage-policies) first.
## How It Works
Every tool a policy governs has one of three states:
| State | Behavior |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| **Always Allow** | The tool runs immediately, no prompt. |
| **Needs Approval** | The call pauses until a human approves or denies it, then proceeds or fails accordingly. |
| **Off** | This group isn't granted the tool. There's no explicit "deny" state — a tool set to Off is simply omitted from the policy's rule. |
**Off is not a block.** It declines to grant the tool for *this* group; it does not override a grant the same user gets from another group. To make sure nobody can reach a tool through this policy, leave it **Off** in every column, including **All Users**.
Each state is set **per tool, per group** — not globally per agent. That means you can, for example, let a support agent freely read Salesforce records but require approval before it posts to a customer-facing Slack channel, or require approval on both reads and writes for a policy scoped to a more sensitive system.
Because the setting lives on the policy, not the agent, the same agent can have different confirmation rules depending on which policy — and therefore which group or role — is in effect for a given user or session.
### Precedence across groups
When a principal belongs to more than one group with a rule for the same tool, the most permissive state wins: **Always Allow > Needs Approval > Off**. This is order-independent — it doesn't matter which rule was written first.
**All Users** is the policy's baseline: whatever you grant there applies to every user the policy covers, including members of the specific groups beside it. Group columns can add to the baseline; they can't take it away.
Because the baseline wins, an **All Users → Always Allow** grant makes a narrower group's **Needs Approval** grant *dormant*: the prompt never fires, because the user is already allowed unconfirmed. The group's setting is kept, not discarded — remove or lower the baseline grant and the approval requirement takes effect again. This is why a policy can show **Needs Approval** for a group while users in that group are never prompted. If you're scoping approval to a specific group, check that no wider rule already grants Always Allow on the same tool.
## Configure Tool Confirmations
1. Sign in to your Barndoor portal and navigate to the **Access Control Center**.
2. Open the access policy governing the MCP server and agent you want to configure, and go to its **Policy Rules** step.
3. The tool matrix lists the server's tools down the left and one column per audience — **All Users** first, then each group or role you add. Set each cell to **Always Allow**, **Needs Approval**, or **Off**.
4. To move many tools at once, use the **Set all** control in a column header. It applies one state to every tool currently *visible* in that column, so narrow the list with the operation filter or the search box first — the control tells you how many tools it will touch.
5. Save the policy. Changes take effect on the next tool call.
A quick way to lay down a baseline: filter to **Read** and **Set all → Always Allow**, then filter to **Update** and **Delete** and **Set all → Needs Approval**, then clear the filter and turn off anything the group shouldn't reach at all.
Setting a frequently-used tool to **Needs Approval** introduces a pause in the agent's workflow until a human responds. Reserve it for tool calls where the risk of an unreviewed action or an unreviewed data exposure outweighs the friction of a prompt.
## What the User Sees
When a tool set to **Needs Approval** is called, the approval request goes back to the person driving the session — the agent receives a request naming the specific server, tool, and arguments instead of a result, and the call runs only after that person approves it. There is no separate reviewer queue and no reviewer routing to configure.
A tool that no group grants comes back as a policy block instead, worded distinctly from an approval request so an agent doesn't retry it as though it were pending.
## Scope of Enforcement
**Known limitation**: approval prompting currently happens only through ToolIQ / the tool router. On the direct proxy path (non-ToolIQ clients), a tool set to Needs Approval executes without a prompt. If your agents connect through a non-ToolIQ client, treat Needs Approval as not yet enforced for that path — leave the tool **Off** instead where you need it stopped everywhere.
## API and Terraform
Under the hood, each state serializes as an action on the policy rule:
* **Always Allow** → `tools/call:`
* **Needs Approval** → `tools/call::approve` (this action only — never both the plain and `:approve` form on the same tool)
* **Off** → the tool is simply omitted from the rule's `actions`
This is expressed entirely through the `actions` field on a policy rule — the same field [Managing Policies](/how-tos/manage-policies) and the `barndoor_policy` Terraform resource already use. If you manage policies as code, add `:approve` to a rule's `actions` list to require approval on that tool. The suffix is reserved and may appear at most once, at the end of a tool-call action.
## FAQ
Yes — this is the core change. Any tool a policy governs, regardless of whether it reads or writes data, can be set to Always Allow, Needs Approval, or Off.
The user whose session made the call. The request surfaces to them in the client they're working in, and the call proceeds only once they approve it.
The call blocks until it's approved or denied. Approved calls proceed normally; denied calls return an access-denied response to the agent.
Two likely causes. Check whether a broader rule — most often **All Users** — already grants that tool **Always Allow**, which outranks your Needs Approval grant and leaves it dormant. If the grants look right, check how the agent connects: approval prompting happens on the ToolIQ / tool-router path only.
## In this section
Create and structure the access policies that tool confirmations attach to.
Get alerted when a policy changes or a server's tools move underneath it.