AI Agent Tool Permission Matrix
When an agent calls a tool, it does something real: reads a customer record, sends a message, runs a database query. The tool permission matrix is the document that makes those capabilities explicit — what data is touched, what the scope is, what risk level applies, and what controls are required before an agent is allowed to call the tool at all.
Fill in this matrix before attaching any tool to an agent in production. Review it when tools are updated or when an agent's trust level changes.
When to use this template
- When designing a new agent and deciding which skills to attach
- When a security or compliance review asks for an inventory of agent capabilities
- When evaluating whether an agent's
trustlevel (low,medium, orhigh) is set appropriately given its tool access - As part of the deployment checklist before promoting an agent to production
- When responding to a SOC2 or vendor security questionnaire about AI system access controls
Risk level guidelines
Use these definitions consistently across your matrix. When in doubt, assign the higher risk level.
| Pattern | Risk level |
|---|---|
| Read-only access, no external side effects | low |
| Write to an internal system only | medium |
| Write to an external system, or any external communication | high |
| Financial transaction, legal action, user data deletion, or access to secrets or credentials | critical |
The matrix (copyable blank template)
# Tool Permission Matrix
**Workspace:**
**Last reviewed:**
**Reviewed by:**
| Tool / Skill | Data accessed | Scope | External side effects | Risk level | Approval required | Allowed trust levels | Audit event | Owner |
|---|---|---|---|---|---|---|---|---|
| | | | | | | | | |
Column definitions:
- Tool / Skill — name of the skill, MCP tool, or action step
- Data accessed — what data the tool reads, writes, or deletes
- Scope —
Read/Write/Delete/Execute - External side effects —
Noneor a description of what happens outside the platform - Risk level —
low/medium/high/critical - Approval required —
No/Yes/Conditional(specify the condition) - Allowed trust levels — which agent trust levels (
low,medium,high) may call this tool - Audit event — the audit log event that fires on use (from the ProvenanceOne audit event list)
- Owner — the role or team responsible for this tool's configuration and security
Example: completed permission matrix
The table below reflects a realistic configuration for a CX automation workspace with CRM, email, Slack, database, GitHub, billing, and file storage access.
| Tool / Skill | Data accessed | Scope | External side effects | Risk level | Approval required | Allowed trust levels | Audit event | Owner |
|---|---|---|---|---|---|---|---|---|
| CRM read (Salesforce / HubSpot) | Contact records, account data, deal stage | Read | None | low | No | low, medium, high | connection.accessed | CRM team |
| CRM write (update deal stage, add note) | Contact records, deal stage | Write | None | medium | Conditional — if agent trust is low | medium, high | connection.accessed | CRM team |
| Email draft | Draft email content (no send) | Execute | None | low | No | low, medium, high | run.completed | Platform team |
| Email send | Outbound email to external recipient | Execute | Sends email outside the organisation | high | Yes — single reviewer, 60 min SLA | high only | connection.accessed | CX ops |
| Slack message (channel post) | Slack channel messages | Write | Posts to internal Slack channel | medium | No | medium, high | connection.accessed | Platform team |
| Slack DM | Direct message to a named user | Write | Sends a message to an individual | high | Conditional — if recipient is external | medium, high | connection.accessed | Platform team |
| Jira ticket create | Jira project, issue fields | Write | Creates a visible ticket in Jira | medium | No | low, medium, high | connection.accessed | Engineering |
| Jira ticket update (status, priority, assignee) | Existing Jira issue fields | Write | Modifies a ticket visible to the Jira project | medium | Conditional — if assigning to a person outside the team | medium, high | connection.accessed | Engineering |
| SQL query (read-only) | Database rows matching query | Read | None | low | No | low, medium, high | connection.accessed | Data team |
| SQL write (INSERT / UPDATE / DELETE) | Database rows | Write / Delete | Modifies or removes production data | critical | Yes — two reviewers, 30 min SLA | high only | connection.accessed | Data team |
| GitHub PR read | PR diff, commit messages, review comments | Read | None | low | No | low, medium, high | connection.accessed | Engineering |
| GitHub commit / push | Repository code | Write | Pushes code to a branch | high | Yes — single reviewer, 60 min SLA | high only | connection.accessed | Engineering |
| Billing lookup | Invoice history, payment status | Read | None | medium | No | medium, high | connection.accessed | Finance team |
| Billing charge (initiate charge or refund) | Payment method, charge amount | Execute | Initiates a financial transaction | critical | Yes — two reviewers, 30 min SLA | high only | approval.granted | Finance team |
| File storage read | Files in configured datastore | Read | None | low | No | low, medium, high | connection.accessed | Platform team |
| File storage write | Files in configured datastore | Write | None | medium | Conditional — if writing outside the agent's scoped folder | medium, high | connection.accessed | Platform team |
Secret reveal (/secrets/{id}/reveal) | Secret value from the secrets vault | Execute | Exposes credential value in memory | critical | Yes — admin only, 30 min SLA | high only | secret.accessed | Security team |
How to customise this template
Add rows for every tool your agents use. The matrix is only useful if it is complete. An unlisted tool has no defined controls.
Review the "Allowed trust levels" column carefully. A low trust agent should not have access to critical tools. If the task genuinely requires a critical tool, set the agent to high trust only after completing the agent evaluation rubric, and always require approval.
Use the "Conditional" value in the approval column sparingly. Every conditional should specify its condition explicitly — for example, "Conditional — if recipient count exceeds 10." Vague conditionals are treated as unenforced in practice.
Keep the Owner column current. When a team restructures or a tool migrates to a new owner, update this column. Stale ownership means no one responds when the tool causes a problem.
Cross-reference with your approval policy. The risk levels in this matrix should drive the approval configuration in your workflow steps. A critical tool that says "Yes — two reviewers" in the matrix should have a corresponding approval step in every workflow that calls it, with slaMinutes: 30 and two assignees.
Attach evidence to approval requests for high and critical tools. When an agent calls a high or critical tool, the approval request should include relevant evidence items (for example: recipient count, transaction amount, confidence score) so reviewers can make an informed decision.
Common mistakes
Giving low trust agents access to high or critical tools. Trust level and tool access are two separate controls. An agent with low trust should not be attached to a billing charge skill or secret reveal endpoint.
Leaving external side effects as "None" when the tool does have them. Sending a Slack message to an internal channel is an external side effect relative to the ProvenanceOne run. Be precise.
Not updating the matrix after adding a new skill to an agent. When you attach a skill to an existing agent, the matrix needs a new row before the change goes to production.
Marking all write tools as requiring approval, then approval-fatiguing reviewers into rubber-stamping. Reserve required approval for high and critical tools. Over-approving creates reviewer fatigue that undermines the gates you actually need.
Setting the audit event to a generic value for all rows. Use the specific event type that fires for that operation. secret.accessed is different from connection.accessed — they go to different audit queries and alert rules.
Do I need a row for every tool, or only the risky ones?▾
Every tool. A complete matrix is the baseline. If a tool is missing, there is no documented control for it, which means no one has reviewed what access it has or whether it should require approval. Start with the complete list and mark low-risk rows explicitly — do not simply omit them.
What is the difference between Scope 'Execute' and 'Write'?▾
Write means the tool modifies data in a persistent store (a database, CRM, file system). Execute means the tool triggers an action that may not write to a datastore but has a side effect — sending an email, initiating a charge, revealing a secret. An email send does not write data, but it has a consequential external side effect.
Can an agent with medium trust call a critical tool if approval is required?▾
The matrix recommendation is to restrict critical tools to high trust agents only. A medium trust agent calling a critical tool means you are relying entirely on the approval gate — if that gate is misconfigured or bypassed, there is no trust-level backstop. Reserve critical tools for high trust agents that have been evaluated and approved for that scope.
Which audit event should I use for a custom skill?▾
For custom skills, use run.completed or run.failed for the overall run-level event. If the skill accesses a connection (external system), connection.accessed fires. If it accesses a secret, secret.accessed fires. You can also emit custom events from within skill code using the ProvenanceOne event bus.
How does this matrix relate to the ProvenanceOne approval step configuration?▾
The matrix is the design document; the approval step in the workflow is the enforcement mechanism. For every row marked Yes or Conditional in the Approval required column, there should be a corresponding approval step in the workflow before the tool call executes. Review both documents together when auditing an agent's governance posture.
Should I create a separate matrix per agent or one matrix per workspace?▾
One matrix per workspace covering all tools available in that workspace, with a separate column or section noting which agents are permitted to use each tool. This avoids duplication and makes cross-agent comparison straightforward. Reference the workspace matrix in individual agent documentation.
Related pages
- Approval Policy Template — configure the approval steps that enforce this matrix
- Risk Assessment Checklist — full deployment risk assessment for agents with critical tool access
- Agent Evaluation Rubric — score an agent's tool-use accuracy before production
- Skills — ProvenanceOne skill configuration and categories
- Agents — agent trust levels and how they interact with tool access
- Audit — full list of ProvenanceOne audit events