The AI Agent Tool Permission Matrix#

Most agent security problems start with one lazy sentence:

Give the agent access to our tools.

Which tools?

Read access or write access?

For every user or only one workspace?

With approval or without approval?

Logged where?

Revoked how?

That sentence is where the mess begins.

Start with a matrix#

Before the agent touches anything real, create a permission matrix.

Nothing fancy. Just a table the team can argue with.

Tool        Scope        Risk      Mode        Approval
Slack       Thread read  Low       Auto        No
Slack       Post reply   Medium    Draft/send  Yes
GitHub      Read code    Low       Auto        No
GitHub      Comment PR   Medium    Draft/send  Yes
Stripe      Read account Medium    Auto        No
Stripe      Issue refund High      Execute     Yes
Vercel      Read deploys Low       Auto        No
Vercel      Rollback     Critical  Execute     Yes
Database    Read replica Medium    Query       Maybe
Database    Write        Critical  Blocked     Always

That matrix will save you from pretending prompts are access control.

Split tools by action#

Do not define a tool as "GitHub."

Define the actual actions:

• Search repo.
• Read file.
• Read PR.
• Draft PR comment.
• Post PR comment.
• Create issue.
• Update issue.
• Merge PR.

Those are different permissions.

An agent that can read a PR is not the same as an agent that can merge one.

Use risk tiers#

I like four tiers.

Low risk

Read-only context. Public docs. Non-sensitive metadata. Safe search.

Medium risk

Private context. Internal docs. Customer metadata. Drafting messages.

High risk

Customer-facing output. Billing changes. Account changes. Production config changes.

Critical risk

Deploys, rollbacks, data deletion, permission changes, secret rotation, anything that can hurt customers quickly.

The tier decides the default behavior.

Low-risk tools can run automatically. High-risk tools need approval. Critical tools need stronger review or should stay out of v1.

Separate draft from execute#

This is one of the easiest wins.

Give the agent permission to draft.

Make the human execute.

Examples:

• Draft a Slack reply, but do not post it.
• Draft a GitHub comment, but do not submit it.
• Draft a refund reason, but do not issue the refund.
• Draft a rollback plan, but do not roll back production.

You still get most of the productivity without pretending the workflow is ready for autonomy on day one.

MCP needs the same discipline#

MCP makes tool discovery cleaner.

It does not magically make permissions cleaner.

Every MCP server still needs:

• Narrow scopes.
• Clear tool names.
• Input schemas.
• Output schemas.
• Trusted server boundaries.
• User confirmation for sensitive actions.
• Logs for every call.
• Timeouts and rate limits.

If a tool is dangerous as an API, it is dangerous as an MCP tool too.

Permission mistakes to avoid#

The common failures:

• One broad token for the whole agent.
• Read and write actions in the same tool.
• Tool descriptions that hide side effects.
• No approval for customer-facing output.
• No audit trail.
• No rollback path.
• Exposing admin tools in early demos.
• Letting retrieved content influence tool permissions.

The model can reason.

The platform still has to enforce.

Where Codelit fits#

Codelit turns the permission conversation into something visible.

For an agent workflow, you can map:

• Agent roles.
• Tool risk.
• Auth scopes.
• Approval gates.
• MCP servers.
• Skills.
• Runtime services.
• Evals.
• Logs.
• Handoff files for engineering.

That makes the workflow reviewable before anyone wires real credentials.

Build it in Codelit#

Try this:

Create a permission matrix for a production AI agent that uses Slack, GitHub, Linear, Stripe, Vercel, PostHog, and an MCP server. Split every tool into read, draft, write, and admin actions with risk tiers and approval rules.

Create an agent permission matrix

If the permission matrix feels annoying, good. It is catching problems while they are still cheap.