Set action permissions
Every action a connector exposes has one of three settings, per connection. This is the gate that decides what an allowed agent can actually do.
The three settings
| Setting | What it does |
|---|---|
| Allowed | "Runs without approval." |
| Ask first | "A human must approve each call." The agent waits; the call becomes a review request. |
| Off | "Agents cannot run this action." |
Change one action
- Open the connector and select the Permissions tab.
- Use Find an action to filter the list.
- Select the setting on the action's row.
Changes take effect on the next call. There is no reconnect and no restart.
The summary above the list reads back the current state — Allowed for, Ask first for, and Off for — so you can confirm a bulk change without scrolling the whole catalog.
Read the risk classification
Each action carries a classification Paperclip derives from the provider's tool metadata and name:
- read — no known mutation.
- write — creates or changes something.
- destructive — deletes or is otherwise not reversible.
A provider annotation is authoritative. If the server marks a tool destructiveHint, it is destructive regardless of its name. In the other direction, name-based inference is used when the provider supplies nothing: verbs like delete, remove, destroy, and unpublish classify destructive; create, update, write, send, publish, post, archive, and similar classify write.
Some providers get provider-specific handling because a generic rule would be wrong:
- PostHog — an unannotated tool is treated as a write, not a read. Its
exectool is always destructive. - Notion — mutations whose names do not use a create/update/delete verb (move, duplicate, convert) are enumerated explicitly as writes.
- Shopify —
cancel-cart,cancel-checkout, andcomplete-checkoutare always destructive.
Refresh the action list
The action list belongs to the provider. When they add, rename, or remove a tool, your list is stale until it is re-read.
Select Refresh actions on the Permissions tab. The API equivalents are:
GET /api/tool-connections/{connectionId}/catalog
POST /api/tool-connections/{connectionId}/catalog/refresh
The refresh reports how many actions it discovered — "Found 24 actions" — and, when any were held back, how many need you: "3 new actions need your OK."
What happens to a brand-new action
This depends on how the connection was created. It is worth knowing which case you are in before you refresh a production connection.
| How the connection was set up | A newly discovered or changed action |
|---|---|
| Managed — "Connect with Paperclip" | New or changed actions are normally quarantined on refresh. Where safe defaults are enabled, read-classified actions are exempt. Check the resulting action list |
| Your own credential or OAuth client — the ordinary catalog setup for most connectors | Becomes active on discovery. It is then governed by the action policies already in force for that connection, not held in a separate review queue |
| A custom MCP server you pasted a URL for | Becomes active on discovery, as above |
| A Paperclip example connection | Safe defaults exempt read-classified actions; new or changed write and destructive actions are held back |
For the ordinary case, the wizard projects the app's action defaults into policies when you finish setup, rather than using a review queue as the access state. This means you should not assume a refresh can only ever reduce what an agent can do.
Warning: A managed connection is not an unconditional guarantee that every new action requires approval. Refresh behavior depends on the connection's configuration and the action's classification. Review the refreshed list and set unwanted actions to Off.
Two details worth knowing wherever held-back review does apply: an action you had already set to Off stays off rather than reappearing for review, and a connection configured for safe defaults exempts actions classified read, holding back only writes and destructive actions.
Limits you cannot lift
A permission switch cannot grant something the connector was never allowed to do.
- Gmail permanently blocks send, trash, spam, and label mutation. There is no setting that enables sending mail. See Gmail.
- Google Workspace connectors allow only the reviewed reads and the write tools of the capability group you connected. A preview tool outside that list is denied.
- A connection created with a read-only capability group does not gain write actions by changing a switch; you reconnect with the write group instead.
The shell exception
Per-action settings govern tool calls through Paperclip's tool gateway. They do not govern commands an agent runs in its own workspace shell.
When you change a permission on a GitHub connection bound to an agent identity, Paperclip says so at that moment: "Shell Git and gh use this account for the run and are not constrained by per-tool Ask-first controls." Read that as scoped to GitHub and to shell Git and gh — it is not a statement that other connectors are sandboxed.