How to Review an Agent's Tool Permissions

Quick answer
List every tool the session can call, including MCP tools, shell, file writes, and network access.
For each one, name the task that needs it; anything without a named task is a candidate for removal.
Review write and execute tools as a different class from read tools.
Test the boundary with a plausible request outside the task and confirm the agent refuses or is blocked.
Record the reviewed set in the repository and re-review when a server or skill changes.

How do you build the inventory?

Ask the harness to list its tools, then add the ones it does not report: shell access, file writes, browser control, and any MCP server connected outside the project configuration. The inventory is incomplete until you know what the user-level configuration adds.

Group them by effect: read internal, read external, write internal, write external, execute, and communicate. The last two are where incidents happen, because they can move data or change systems.

| Tool                     | Class      | Needed for        | Keep |
|--------------------------|------------|-------------------|------|
| read_file                | read       | every task        | yes  |
| shell                    | execute    | build and test    | yes  |
| mcp: issues.create       | write ext  | ticket follow-up  | no   |
| mcp: db.execute          | write int  | migrations (stag) | yes  |
| browser                  | read ext   | docs lookup       | no   |

How do you decide what to remove?

Remove anything that has no named task in the current workflow. A create-issue tool is convenient, but if the task is code review it is an unnecessary write to an external system. Convenience is the reason tools accumulate; the review is the reason to trim them.

Also remove tools that duplicate a safer path. If the agent can run git through the shell, it may not need a repository-write MCP tool with broader scope. Fewer tools also improves reliability, because the model has fewer choices to reason about.

How do you test the boundary?

Ask the agent to do something plausible but out of scope — read a production config, call an external API, push to main — and confirm it is refused or blocked. Test with the real session configuration, not a hypothetical one.

A refusal from the model is weaker evidence than a denial from the sandbox. Test both: the model should decline, and the system should stop it if the model does not. Only the second one survives a convincing injection.

How often should this be reviewed?

When a tool is added, when a server updates, and when the workflow changes. A quarterly pass catches accumulation: tools that were needed for a one-off migration and stayed connected for a year.

Keep the approved list in the repository next to AGENTS.md. That turns the review into a diff, and a diff is the only review artefact that reliably survives a team change.

Where this bites vibecoders
Generated agent setups connect everything “for flexibility”: browser, issue tracker, database, shell, deploy. Each one was added to solve a moment’s problem and none was removed. The review is mostly deletion, and deletion is where the safety comes from.

Where AI coding assistants get this wrong

Reviewing project tools but not user-level ones.
Keeping a tool because it might be useful later.
Treating a model refusal as a security control.
Missing shell access because it is not a “tool” in the UI.
Giving an external write tool the same scope as an internal read tool.
Never re-reviewing after a server update.

Checklist

Inventory every tool, including user-level ones.
Classify by read, write, execute, and communicate.
Name the task that needs each tool.
Remove tools with no task.
Test refusal and enforcement separately.
Commit the approved list and re-review on change.

FAQ

Can the agent be trusted to follow the allowlist?

The allowlist should be enforced by the harness, not by instruction. Instructions reduce accidental use; enforcement prevents deliberate or injected use. If the harness cannot restrict tools, isolate the session so the tools are not present.

What about tools the task needs occasionally?

Enable them for that task rather than leaving them on. A tool that is present for every session is available to every injected instruction. Per-task tool sets are the practical version of least privilege.

How do I handle a shell tool?

Assume the shell can do anything the user can. Restrict it with the sandbox, not the tool list: a container without credentials, without production network access, and with a read-only mount for anything sensitive.

Should reviewers see the tool inventory?

Yes, in the pull request when it changes. A new tool is a capability change and belongs in the review packet, alongside the credentials it can use and the data it can reach.