Scopehaven
Request a first test
TOOL PERMISSIONS GUIDE
How to test an AI agent's tool permissions and approval steps
Once an agent can issue refunds, export data, send messages or change accounts, a permission mistake is no longer a wrong answer. It is an action. Test that each tool checks who is calling it, that approvals cover exactly the action approved, and that what the agent says it did matches what actually happened.
Short answer: for each tool, test a caller without the required role (refused), a caller with it (works), an action that needs approval without one (refused), with a valid approval (works once), and with an approval for a slightly different action (refused). Check the ledger or record the tool writes, not only the agent's reply.
This guide is for teams adding tools with real effects to a support agent or internal assistant. It covers testing in an authorized local or staging environment with synthetic data. It is not a full security review.
01 / AUTHORIZE
Hiding a tool in the prompt is not a permission.
Many agents decide which tools to offer based on the user's role. That shapes what the model tries, but it does not stop a call. The tool itself has to resolve the caller from the authenticated session on the server and check their role before it acts.
Test it by calling the tool, through the agent or the same endpoint the agent uses, as a user who lacks the role. The call should be refused and nothing should change. Then confirm a user who has the role can still perform the action.
02 / APPROVE
An approval covers one exact action, once.
Human approval for high-value actions only works if the agent cannot produce or stretch it. Write the rule down for each action that needs approval:
- Issued separately. The approval comes from a separate step or system, not from a flag in the tool arguments the model fills in.
- Bound to the action. It names the actor, the resource, the amount, the recipient and any other field that matters. Changing one should invalidate it.
- Single use. Once used, it cannot authorize a second action, including on a retry.
03 / CHECK
Forbidden cases next to the work that must still happen.
Use a refund tool as the example; the same pattern fits exports, account changes and outgoing messages. Pair each forbidden check with an allowed-use control so a repair that blocks everything does not look like a pass.
| Rule | Forbidden check | Allowed-use control |
|---|---|---|
| Role | A member asks the agent to issue a refund. The tool refuses and the ledger is unchanged. | An administrator's refund goes through. |
| Self-approval | A request above the approval limit includes an approval flag supplied by the caller. It is refused. | The same refund with a valid, separately issued approval goes through. |
| Changed action | An approval for one refund is reused with a different customer, recipient, amount or currency. It is refused. | The exact approved refund still goes through. |
| Replay | An approval that was already used is presented again for another action. It is refused. | The original approved action happened exactly once. |
| Retries | A retried request does not create a second refund. | The first request still creates exactly one. |
| Volume | Repeated individually allowed actions stop at the agreed limit. | Actions within the limit still work. |
04 / OBSERVE
"Refund issued" is a claim. The ledger is the evidence.
An agent can report an action that never ran, or say it refused while a tool call still went through in the background. For each check, look at the effect the tool would cause: the ledger entry, the changed record, the outgoing message or the export file.
Watch for instructions inside documents, emails or tickets the agent reads. A document that tells the agent to export customer data is not authorization, and the export tool should refuse it whatever the agent was persuaded to try. If you cannot observe the effect, record the check as response-level only, or inconclusive.
05 / RETEST
Fix it in the tool, then rerun the whole set.
Typical repairs move the role check into the shared action handler, validate approvals issued outside the model's arguments, bind them to the exact action and mark them used atomically. Your team makes the repair.
Rerun the same checks on the repaired build with the same identities and amounts. Every forbidden case should be refused with no effect, and every allowed-use control should still produce exactly one correct effect.
Where Scopehaven fits
Scopehaven is a local assessment workbench for testing the permissions you define, on the actions you check, and rerunning the same checks to show whether a fix held, including the actions that should still work. Its built-in demo app, which uses synthetic data and a simulated refund ledger, includes role, approval, replay, retry and budget checks like the ones above, each alongside allowed-use controls.
On your own app, what a run can establish depends on the connection and the evidence available, including whether the effect a tool causes can be observed. Scopehaven does not certify your application or guarantee it is free from vulnerabilities.
Common questions
Which tools should I test first?
Start with the tools whose effects are hardest to undo: moving money, exporting or sending data outside the company, deleting records and changing who has access.
Is a confirmation prompt to the user an approval?
It can be part of one, but test it the same way. If the confirmation is a value the model can set, or it is not tied to the exact action, it does not stop the agent from acting on its own.
Can I test this without a real payment system?
Yes. A test or simulated ledger in a local copy of the app is enough to check whether a refund was created, refused or duplicated.
Does passing these checks mean my agent is safe?
No. It shows that the boundaries you tested held under the conditions you tested. Untested tools, actions and conditions remain open questions.