The Agent Tool Permission Matrix Every AI App Needs
An agent tool permission matrix is a simple table that answers one security question before prompt injection answers it for you: what can this agent read, write, send, delete, or buy?
Quick Answer
- Split tools by capability, not by API provider.
- Treat external sends and destructive writes as high risk.
- Give read-only agents read-only keys.
- Require confirmation for money, email, public posts, and deletion.
- Log the exact tool call and the text that justified it.
The matrix
| Permission | Examples | Default |
|---|---|---|
| Read | search docs, list events, fetch records | Allow when needed |
| Draft | create unsent email, draft update, preview change | Allow with logging |
| Write | update CRM, create event, edit ticket | Scope tightly |
| Send | email, Slack, public post, webhook | Confirm |
| Spend | payment, paid API, purchase | Confirm and budget |
| Delete | remove data, revoke access, drop files | Confirm or block |
| Network | browse web, fetch URLs, call external API | Allowlist |
Why this beats one big key
One broad API key turns a model mistake into an application incident. A scoped key turns the same mistake into a failed or harmless tool call.
Prompt injection defense works best when the model is not the only boundary. The system should make the dangerous action hard even when the model is confused.
Test the boundary
Add hostile prompts that try to move from read to write, write to send, and send to spend. The expected behavior should be boring: refusal, confirmation request, or blocked tool call.
FAQ
Is confirmation enough?
No. Confirmation helps humans catch risky actions, but the tool key should still be scoped.
Should the matrix live in code?
Yes. A doc is useful, but enforcement should live in the tool registry, middleware, or API gateway.
What should BreakMyAgent test?
Whether hostile input can cause a tool call outside the intended permission tier.