How to Design Tool Permissions for AI Agents

Ask what an agent can do and the honest answer is: whatever its tools can do, in the worst case, if it is steered. Designing tool permissions is therefore designing the blast radius. This guide gives FISTA's method: classify, split, scope, gate, test. It applies the agent identity and access control whitepaper at the tool level and complements MCP security risks.

Step 1: How are actions classified?

Class	Definition	Control
Read	Returns data; changes nothing	Flows; logged
Reversible write	Creates or updates records that can be corrected: notes, drafts, comments, low-value updates	Flows with sampling; confirmation for new agents
Consequential write	Irreversible, high-value, or regulated: payments, master-data changes, closures, external communication	Human approval at the gateway; separate principal

The system owner classifies; security approves consequential classifications. A tool that could be either is consequential until proven otherwise.

Step 2: Why split consequential actions into separate tools?

Because a tool is the unit of permission. update_customer with a free-form payload can change a bank account or a preference and cannot be scoped. update_customer_preferences and update_customer_bank_details can each carry a classification, a principal, and a gate, and the second can be withheld from every role that does not need it. Precise schemas with enumerated fields also make the model's calls predictable and testable.

Step 3: How is a principal scoped per tool?

Tool	Class	Principal
Read tools	Read	Read-only principal, restricted to the entities the role serves
Reversible writers	Reversible	Writer limited to the specific objects and fields
Consequential	Consequential	Separate principal, issued only to roles that need it, credentials brokered and short-lived

Principals are combined with delegated user context so effective permission is the intersection, per non-human identities for AI agents.

Step 4: Where are gates enforced?

At the gateway, which sees every call regardless of host, reads the classification from the registry, and passes, samples, or pauses accordingly. Approval requests carry the agent, user, tool, parameters, and the trace of what the agent read. Gates in prompts are advisory and fail under injection. The gateway build is in how to build an MCP gateway; the oversight design in human-in-the-loop AI explained.

Step 5: How are permissions assigned to roles?

Each agent role's specification lists its tools; the registry records which roles may use which tools; consequential tools are withheld by default and added by a gated change. A role gaining a consequential tool is a security review, not a configuration tweak. The specification format is in AI agent specification template.

Step 6: How is the design tested?

• Permission tests: each tool executes only under its principal; a role without a tool cannot invoke it.
• Delegation tests: a user without access to a record cannot reach it through the agent.
• Injection tests: tool results and documents containing instructions to perform consequential actions produce no such action.
• Gate tests: consequential calls pause, expire, and reject correctly.
• End-state tests: after sandboxed runs, nothing outside the specification changed.

Tests run in CI and before any permission change, per AI regression testing.

What does a worked example look like?

A support agent's tool list starts with eight tools. Classification sorts them: five reads (customer, order, shipment, invoice, policy lookups) get a read-only principal restricted to the verified customer; two reversible writes (add case note, start return within policy) get a scoped writer with sampling; one consequential write (issue refund above threshold) is split out of what was a single process_refund tool, given its own principal, withheld from the tier-one role entirely, and gated for the escalation role. The specification now states that the tier-one agent cannot refund above threshold because the tool is not in its permissions, which is a claim the adversarial suite can verify by trying. When the process owner later wants the agent to update addresses, the change adds one classified tool through a review rather than widening a general permission.

What are the recurring design errors?

1. Permissions per agent, not per tool, so one broad principal covers everything.
2. General write tools.
3. Consequential tools granted "for now."
4. Gates in prompts.
5. Delegated context omitted, so the agent acts with its full role for every user.
6. No adversarial tests, so the design is assumed rather than proven.

What does a permission review look like?

Quarterly, per role: list the tools, confirm classifications with the system owner, remove unused tools, confirm principals are still minimal, check that consequential tools remain withheld from roles that do not need them, and re-run the adversarial suite. Findings feed the registry and the Digital FTE performance review.

How does FISTA Solutions help?

FISTA Solutions designs tool permissions for every AI agent it delivers using this method, builds the gateway enforcement and adversarial tests as part of its AI enablement practice, and works with your security team through forward deployed engineers so classifications match your control framework. FISTA has delivered 150+ projects for 50+ companies across 12+ countries.

To review the permissions your agents hold today, message FISTA on WhatsApp, or read AI agent sandboxing for the environment-level controls that back permissions up.