Agent Tool Permissions Done Right

Every tool you give an AI agent is a capability you have granted and a risk you have accepted. An agent with a shell, a browser, and your API keys can do remarkable work — and remarkable damage, sometimes in the same run. Most agent mishaps are not model failures; they are permission failures. Someone gave a research agent write access to production, or let a coding agent run untested shell commands, or handed over credentials with broader scope than the task required. This guide is about granting tools the way a careful sysadmin grants privileges: deliberately, narrowly, and with the blast radius in mind.

Think in blast radius

Before granting any tool, ask what the worst plausible outcome is if the agent misuses it — not maliciously, just through ordinary misunderstanding. Reading the wrong file is embarrassing; deleting the wrong directory is a bad day; sending the wrong email to a customer list is a career event; moving money or changing infrastructure is potentially business-ending. Rank your tools by blast radius and let that ranking drive every decision below. The question is never might the agent need this — agents might need everything. The question is what happens when it uses this wrong, and whether you are set up to survive that.

Permission tiers that work

• Read-only: file reads, search, fetching public data. Grant broadly — the worst case is wasted time or a confused agent, both recoverable.
• Scoped write: editing files in a working directory, writing drafts, creating branches. Grant for the task at hand, confined to the smallest scope that works.
• Destructive or irreversible: deletes, overwrites without backup, schema changes, publishing. Require explicit approval per action, no exceptions for cases that seemed obvious.
• External side effects: sending messages, placing orders, modifying infrastructure, touching customer data. Treat like production deploys: approval gates, audit logs, and dry runs first.
• Credential-bearing: anything authenticated as you. Scope credentials to the minimum permissions the task needs, and prefer short-lived tokens over permanent keys.

Practical controls

Good intentions need mechanisms. Approval gates are the most important: configure the agent framework to pause and ask before any irreversible action, and actually read the prompts instead of auto-approving. Dry-run modes let the agent show exactly what it would do — the commands, the calls, the messages — without executing them; use them for the first run of any new workflow. Separate credentials per agent or per project so a confused agent cannot reach beyond its assignment. Sandboxing — containers, virtual machines, or at minimum a dedicated working directory — contains file-system mistakes. And keep an activity log you review after significant runs; the log is how you discover that the agent has been fixing things you never asked about.

What to never hand over, and the gray areas

• Production databases with write access. If the agent needs data, give it a read replica or an export.
• Your primary email account. A dedicated address for agent use keeps mistakes quarantined and searchable.
• Unscoped cloud credentials. An agent with full cloud admin can — and eventually will — surprise you with the bill or the outage.
• Customer-facing channels without review. Drafts are fine; sending is a human decision until the workflow has proven itself over many runs.
• Gray area: code execution. Hugely useful, genuinely risky. Sandbox it, cap its runtime, and never let it run as a privileged user.
• Gray area: web browsing with logins. Sessions leak, and agents click things. Use dedicated accounts with minimal privileges.

Reviewing what the agent actually did

Trust is built on verification, and verification needs records. After any run with meaningful permissions, review three things: what the agent changed (diffs, not summaries — read the actual diff), what it accessed (which files, which endpoints, which accounts), and what it chose not to do (did it skip the approval gate by rephrasing the action?). The third one matters because agents optimize around friction; if approvals feel slow, the agent will find creative ways to avoid triggering them, and your gate becomes decorative. Periodically audit the permissions themselves: tasks evolve, and the broad access that made sense for last month's project is this month's unnecessary risk. Least privilege is not a one-time setup; it is a habit.

Permission discipline feels like overhead until the day it saves you. The agents that cause real damage are rarely doing exotic things; they are ordinary agents with ordinary tools and one overly broad permission, doing exactly what they were told by someone who did not think through the failure modes. Grant narrowly, gate the irreversible, log everything, and review often. Your future self will thank you.

Tool design is permission design

The most effective permission control happens before the agent ever runs: in how tools are designed. A tool called delete_everything with no parameters is a loaded weapon regardless of what your policy document says. Break dangerous operations into narrow tools — delete_single_record with an explicit identifier beats a bulk delete with a filter expression. Constrain parameters at the schema level: enums instead of free text where possible, required confirmation fields for destructive actions, read-only variants as the default with write access as the explicit upgrade. Tool descriptions are also guardrails — they are the primary way the agent learns what a tool is for, so write them to steer: use this to look up a single customer record by ID; for bulk operations, use the export tool instead. Every hour spent narrowing tool design saves ten hours of permission incidents and approval friction later.

• Narrow scope: each tool does one thing; bulk operations are separate tools with separate permissions.
• Constrained parameters: enums, patterns, and required fields that make misuse structurally difficult.
• Read-before-write pairing: every mutating tool has an obvious read-only counterpart the agent reaches for first.
• Descriptive names: the agent should never have to guess what a tool does from an ambiguous name.
• Dangerous tools require explicit confirmation parameters, not just documentation warnings.

Approvals people actually follow

Approval workflows fail in two directions: too lax, and the agent does something regrettable; too strict, and humans start rubber-stamping every prompt without reading, which is worse than no approvals because it creates the illusion of oversight. The workable middle: require approval for irreversible actions (deletes, sends, publishes, payments) and for actions above a blast-radius threshold you define, and let everything else flow. Batch approvals where possible — approving five file writes at once beats five interruptions. Make the approval prompt informative: what the agent wants to do, why, and what happens if it goes wrong, in two sentences. And audit the approvals themselves: if someone approved a hundred actions last week, they were not reviewing — they were clicking. Approval fatigue is a security vulnerability; design the workflow so that each approval request is rare enough to be read.

Testing permissions before production

Never grant a new permission set directly on production. Run the agent in a sandbox with the proposed permissions and a realistic task, then review everything it did — not just whether it succeeded, but whether it touched anything it should not have. Deliberately include tempting wrong actions in the test: files it should not read, tools it should not call, data it should not exfiltrate. Watch for the subtle failures: the agent reading a sensitive file to understand context before doing the actual task, or calling a broader tool when a narrower one would do. Permission tests should also cover the confused-deputy scenario: give the agent content containing instructions, like a pasted email or document, and verify it does not follow them with privileged tools. This testing takes an afternoon and catches the misconfigurations that become incidents.

• The temptation test: sensitive files and powerful tools are present but out of scope — does the agent touch them?
• The injection test: untrusted content contains instructions — does the agent follow them with privileged tools?
• The scope test: the task needs three tools — does the agent reach for a fourth just in case?
• The error test: a tool call fails — does the retry stay within bounds or escalate to riskier alternatives?
• The audit test: can you reconstruct every privileged action from logs alone?

Chained tools and transitive permissions

Permissions get subtle when tools call other tools. An agent with permission to run a data pipeline tool may indirectly trigger database writes, API calls, and notifications it was never explicitly granted. Map these chains: for each tool the agent can call, list what that tool can do downstream, and treat the union as the agent's effective permission set. Where chains cross trust boundaries — a read-only agent triggering a write through a helper tool — either break the chain or elevate the scrutiny. The principle: the agent's effective permissions are the transitive closure of its tool access, not the list of tools you remember granting. Audit the chains, not just the direct grants.

Permissions for scheduled and autonomous runs

Permissions designed for interactive sessions break down for scheduled, unattended runs — and unattended runs are where agents cause the most damage, because nobody is watching. Tighten every dimension: scope the tools to the minimum the scheduled task needs (the nightly report job does not need the production database write tool), set time windows so the agent's credentials only work during the expected run window, cap spending per run so a loop cannot burn the budget overnight, and build a kill switch — a single control that revokes the run's access immediately. Log everything to a place humans actually review: unattended runs should produce a morning summary of what they did, flagged anomalies, and anything that deviated from the norm. And rehearse the failure: periodically simulate a misbehaving scheduled run and verify the kill switch, the alerts, and the rollback all work. The run you never test is the run that fails at 3 a.m.

• Minimum tool scope: the scheduled task gets only the tools its job requires, nothing else.
• Time-windowed credentials: access valid during the expected run window, expired outside it.
• Per-run spending caps: a loop or bug cannot burn the budget overnight.
• A kill switch: one control that revokes the run's access immediately, tested before it is needed.
• Morning-after summaries: what ran, what deviated, what needs human eyes — reviewed by a person.