Assigning Tool Access
Tool access decides which tools a role's members may call. It's separate from both publishing and dashboard permissions, and it's the piece most often missed.
The rule
A member sees a tool only when both are true:
tool is Published (Tool Catalog)
AND
a role they hold has access to it (this page)Miss either and the tool doesn't appear. Publishing alone isn't enough.
Workspace admins typically see every tool regardless. So a workspace can look completely healthy to you while your team sees nothing. Always verify as a non-admin member before announcing a connection is ready.
Where to set it
Two routes to the same setting:
| From | Best for |
|---|---|
| Members & Access → Roles → select a role → Tools | Setting up a role's full tool list at once |
| Tool Catalog → the Access column | Checking or fixing which roles reach one specific tool |
Use the role view when configuring a new role; the catalog view when auditing a single tool.
Granting access
Open a role, go to Tools, and select the tools it may call. Changes take effect immediately — no re-provisioning, no reconnection required, though some AI clients cache the tool list for the current session and need a reconnect to notice.
Designing access
Start from zero and add. Grant a role the tools its people actually need rather than granting broadly and pruning later. An AI client will eventually call anything it can see.
Keep destructive tools isolated. If delete_customer or issue_refund is published, it should sit in one narrow role — not ride along inside a general-purpose one because it happened to be in the same spec.
Match roles to jobs. A support agent needs lookups and ticket updates; an analyst needs reads only; an operator needs routine writes. Three roles with tight tool lists beat one role with everything.
A pattern that works:
| Role | Tool access |
|---|---|
| Admin | Everything |
| Operator | Reads + routine writes |
| Analyst | Reads only |
| Support | Reads + customer-facing writes, no billing |
Multiple roles stack
A member holding several roles gets the union of their tool access — Analyst plus Operator means every tool either role permits.
So adding a role only ever widens access. To reduce what someone can call, remove a role rather than adding a narrower one.
Enum injection: narrowing within a tool
Role access is all-or-nothing per tool. You can go finer and constrain a tool's parameters to the specific resource IDs the current user is allowed to touch — so the AI can't construct an out-of-scope call at all. This works on all three identity models.
Set up per tool and role via the role's inject keys. See Enum Injection.
This is a quality improvement, not a security boundary. Your API must still enforce authorisation — schema constraints shape what the AI attempts, not what your backend accepts.
Auditing access
Periodically worth checking, especially after adding tools:
- Tool Catalog → scan the Access column for tools reaching more roles than intended.
- Roles → open each role's Tools list and confirm it still matches the job.
- Confirm newly published tools didn't land in a broad role by default.
- Check which roles reach destructive tools.
Every tool call is attributed to a user in the Audit Log, so you can also work backwards — see what's actually being called and by whom.
Troubleshooting
| Symptom | Cause |
|---|---|
| Member sees no tools | No role, or their role has no tool access |
| Works for me, not for them | You're an admin — verify as a member |
| Member sees fewer tools than expected | The role's list is narrower than assumed |
| Tool still visible after removing access | Client cached the list; reconnect |
| Tool visible but calls fail | Access is fine — the upstream call is failing. Check Tool Studio. |
Where to go next
- Roles and Permissions — the other half of what a role controls
- Tool Catalog — publishing
- Enum Injection — per-user parameter scoping