Tool permissions
Every tool an agent holds has its own permission — a single dial with four positions that decides how the agent may use that specific tool. It's the most granular of the three governance planes, and it can only ever make an agent more cautious than its supervision mode, never less.
You'll find the dial on each tool card in the agent's Tools tab (and mirrored in Permissions). See The agent workspace.
The four positions#
| Position | What the agent can do | Under the hood |
|---|---|---|
| Off | Cannot use this tool at all. | Access blocked (tool pinned to Block) |
| Read-only | Reads freely; every write becomes a draft you approve. | Access = Assist, oversight inherits |
| Asks first | Fully capable, but every action is reviewed. | Access = Act, oversight = Require approval |
| Autonomous | Acts on its own — workspace guardrails still apply. | Access = Act, oversight inherits |
The dial is one control that writes both underlying planes at once (access level and oversight pin), so they can never drift out of sync. Each position also shows a one-line description right below it, and — after you set it — a live preview like "With this: a Gmail write action → needs your approval."
What each position means in practice#
- Off — the agent literally cannot call the tool. Use it to hold a connected tool in reserve, or to revoke a capability without detaching the account.
- Read-only — the safest useful setting. The agent can see everything (read email, view CRM records) and can prepare actions, but anything that changes the outside world is drafted and parked for your approval. Great for a tool you want visibility from but not yet trust to act.
- Asks first — the agent is fully capable and will act, but every action stops for your sign-off first. Maximum oversight on an otherwise powerful tool.
- Autonomous — the agent acts on its own. This does not mean "unrestricted": the workspace safety floor and the agent's supervision mode still gate genuinely sensitive actions. It means this tool adds no extra friction of its own.
The tighten-only rule#
The single most important thing to understand about the dial:
Tool settings can only tighten, never loosen. A tool pin wins over the agent's mode, but only in the stricter direction. If the workspace floor blocks a category, setting a tool to Autonomous cannot un-block it — block is a floor. Tool permissions add caution; they never remove it.
This is why the dial is safe to hand out: the worst a tool pin can do is make an agent ask more often or do less. It can never grant an agent more freedom than the workspace and the agent's mode already allow. Precedence for non-block decisions is tool pin → agent mode → workspace default, and any block at any level wins outright.
The Custom state#
The dial composes two lower-level fields — Access and Oversight. The four named positions cover the sensible combinations. If you set a combination that doesn't map to one of them (through Advanced, below), the dial shows Custom rather than silently snapping to the nearest preset.
Custom is not an error — it's an honest label meaning "a manual Access + Oversight combination." Examples that read as Custom include Assist + Require approval or Observe-only. If you want to get back to a clean preset, just click one of the four dial positions.
Advanced: Access and Oversight#
The dial is the friendly front end. Underneath, a tool's permission is two independent settings you can also see and set directly.
Access — what the agent is allowed to attempt#
| Access | Meaning |
|---|---|
| Observe | Read only — no actions |
| Assist | Drafts actions — every send needs approval |
| Act | Executes — the workspace floor and mode still gate risky writes |
Access is set when you attach the tool (see Connecting tools) and adjusted here afterward.
Oversight — how closely each action is watched#
| Oversight | Meaning |
|---|---|
| Inherit | Follows the agent's mode and the workspace floor (the default) |
| Require approval | Every action with this tool parks for your sign-off |
| Block | This tool is refused |
Reading the two together reproduces the dial: Access = Assist, Oversight = Inherit is Read-only; Act + Require approval is Asks first; Act + Inherit is Autonomous; any Block is Off. Anything else is Custom.
Verifying a setting#
Not sure what a pin will do? Don't guess — use the Test an action simulator on the Permissions tab. Pick the tool, name an action, and preview whether it would allow, approval, or block, and which level decided. See Supervision & modes.
Changing tool permissions requires an Admin or Owner role. Operators and Viewers see the dial but can't move it (a "Requires Admin" hint appears). Policy is always enforced server-side — the dial is how you express intent, not the gate itself. See Team & roles.
What's next#
- The three planes — how tool pins, agent modes, and the workspace floor combine.
- Supervision & modes — the agent-level dial the tool pin tightens.
- Connecting tools — attach the tools you're setting permissions for.