Automation · AI operations

How to scope an AI agent's tool access

Q: What does scoping an agent's tool access mean?

Deciding which tools an AI agent can call, whose identity each one runs as, and what limits apply, so the agent can do its job and nothing more.

A helpdesk agent was connected with an admin's credentials because that was the account that worked in the demo. Six months later it can still delete any record in the CRM. Here is the model behind tool access that fits the job, the prompts that build it, and what it takes to run in production.

Built with Tray Headless

System Agent
Step Tools for the job
Step Act as the requester
Step Check at call time
System Salesforce

Also Quarterly access review

Each tool is defined by the job, runs with the narrowest identity that can do it, and is checked again at the moment it is called.

The short answer

What does scoping an agent's tool access mean?

Scoping an agent's tool access comes down to four decisions: which tools the job needs and nothing else, whose identity each tool runs as, which tools only read and which can change data, and when the access gets reviewed. The mistake that causes most incidents is connecting the agent with one powerful account because it was the account that worked in the demo. An agent with an admin's access is an admin that takes instructions from anyone who can type into it.

Stage 2 of 5: Scope its tool access. Part of AI agent deployment, end to end : every stage, the systems it runs on and the guide that builds it.

What matters here

Start from the job, not from the connector. List the actions the agent must take, then build a tool for each one.
Prefer narrow tools to general ones. Update the case status is safer and easier to test than update any field on any object.
Run as the person asking where you can, so the agent can never see or do more than they could.
Split read tools from write tools, and give write tools their own limits on volume and value.
Review access on a schedule. An agent's job changes and its permissions rarely shrink by themselves.

Who this is for

You own an AI agent that is about to act in real systems: the CRM, the service desk, the ERP. You need to decide what it may touch before someone else decides for you by accident.

How it works in practice

What happens between an agent deciding it needs a tool and that tool changing a record.

1

The agent only sees the tools listed for its job

A support agent has look up order and issue credit under a limit. It has no tool for anything else, so it cannot be talked into it.
2

Each tool states whose identity it runs as

The person asking, where the system supports it. A narrow service account where it does not. Never a shared admin.
3

Access is checked again when the tool is called

The requester's current groups are read at call time, so someone who left the team last week cannot use the agent to act for it.
4

Write tools carry their own limits

How many records, what value, which objects. Anything over a limit goes to approval instead of running.
5

Every call is logged with the identity used

Who asked, which tool, which account it ran as, and what changed.
6

Access is reviewed on a schedule

Unused tools are removed and every service account is confirmed by an owner.

What tool access is made of

Four parts. The second decides how bad a mistake can get.

A tool list per job

Built from the actions the job needs. A general tool that can do anything makes the agent's instructions the only thing standing between it and every record.

An identity per tool

The requester's own access where possible, otherwise a service account with exactly the rights that tool needs. One shared admin account turns every prompt into an admin request.

Read and write kept apart

Read tools can be generous. Write tools are few, narrow, and limited by count and value, with anything larger sent for approval.

A review cycle

An owner per agent confirms its tools and accounts every quarter. Tools nobody called in that time are removed.

The Tray Headless prompts

Paste these into Claude Code or Codex with the Tray Headless plugin installed. Each stage runs on its own. The systems named in them are the worked example rather than a requirement, and every prompt says so.

Once per project, run /tray-workflows:set-workspace to pick the workspace these build in. Point it at a sandbox first.

Start here: list the job, then the tools

The tool list is the boundary, so it comes first.

Headless skills build-workflow

Use build-workflow.

For this agent, write down the job in plain sentences, then list every
action the job needs to take in another system. For each action, build
one tool that does exactly that action:

  Look up an order by number (read)
  Look up the account owner (read)
  Update the status on a support case (write, one record)
  Issue a credit up to a set amount (write, has a value limit)

Do not build a general tool such as "update any Salesforce record". A
general tool means the only control left is the prompt, and the prompt
is the part an attacker or a confused user can change.

Give every tool a short, specific description so the agent picks the
right one, and a fixed set of inputs it is allowed to pass.

If the job needs more than about fifteen tools, it is probably two jobs. Split the agent before you widen its access.

Decide whose identity each tool runs as

This sets the worst case.

For each tool, set the identity it runs as, in this order of preference:

  1. The person asking, using their own access to the system, so the
     agent can never see or change more than they could themselves
  2. A service account created for this one tool, with only the rights
     that tool needs
  3. A service account shared by a small group of read-only tools

Never use a person's admin account, and never share one account across
read and write tools.

Record the owner of every service account. An account with no owner is
an account nobody will remove.

Check access at the moment of the call

Permissions change after the agent was built.

Headless skills tray-patterns

Use tray-patterns.

Before any write tool runs, read the requester's current groups from
Okta and confirm they are still allowed to ask for this action. Do not
rely on what was true when the conversation started or when the agent
was set up.

If the check fails, stop and tell the agent the request is not allowed
for this person, in words it can pass back: who would need to ask, or
where to request access.

Log the check either way, with the groups that were read.

Put limits on write tools

A correct tool used four hundred times is still a problem.

Give every write tool its own limits:

  Records changed per call and per hour
  Value per call where money moves, such as a credit or a refund
  Objects and fields it may change, listed, with everything else refused

Anything over a limit is sent for approval rather than refused outright,
so the agent can still finish the job with a person's sign-off.

Count the calls per agent per hour and pause the agent's write tools if
the count jumps well past its usual level. A loop that keeps retrying
the same change looks exactly like that.

Log identity on every call, then review quarterly

Access only shrinks when someone looks at it.

Log every tool call with: the agent, the requester, the tool, the
identity it ran as, the inputs, and what changed. Send it to Snowflake
so it can be queried next to the rest of the agent's activity.

Then build a quarterly review that goes to each agent's owner in Slack:

  Every tool the agent has, with how often it was called
  Every service account it uses, with its current rights
  Tools with no calls in the quarter, marked for removal

The owner confirms or removes each one. Anything not confirmed in two
weeks is switched off.

Test it, then hand the tool list over

Because the job will change and the tool list should change with it.

Run the per-step checks and the whole-workflow audit before the agent
touches production. Try the requests it must refuse: a user from the
wrong group, a credit over the limit, a change to a field it was not
given. Each one should stop with a clear message.

Then open the same workflows in Tray Build so the agent's owner can add
or remove a tool in the visual canvas, with IT approving any new write
tool before it is published.

What it connects to

The agent asks, the tool checks, and the system of record only sees a narrow, named identity.

Okta

Read the requester's current groups at call time, so access reflects today, not the day the agent was built.

Reads

Salesforce

The system the agent acts in, through tools that each change one kind of record under a named identity.

Reads and writes

ServiceNow

Update the status or assignment of a ticket, through a tool limited to those fields.

Reads and writes

Slack

Send the quarterly access review to each agent's owner, and approval requests for anything over a limit.

Writes

Snowflake

Keep the log of every call with the identity used, for audit and for the review.

Writes

Same build, other stacks

The design does not change if you run something else in one of these seats. The same prompts build it against Microsoft Dynamics 365, Google BigQuery, Microsoft Teams, Azure Active Directory, Jira or HubSpot.

Connections in this build

Field mapping, templates and common problems for each pairing: Okta + Salesforce, Okta + ServiceNow, ServiceNow + Salesforce and Okta + Slack.

Named systems are the ones most teams run, not the only ones that work. Each is an authentication in your Tray workspace, referenced by name, so the workflow never holds a credential. Where we have a connector page, the name links to it.

Running it in production

Tool access is the control that decides how much damage a wrong answer can do.

Credentials stay in the workspace

Service accounts and user connections are held by the platform, never pasted into an agent's instructions or a config file.

Every call names its identity

The log shows which account each change ran as, so an auditor can see the agent never acted with more access than the person who asked.

Write tools fail closed

If the access check cannot run, the tool does not run. An outage at the identity provider pauses changes rather than skipping the check.

Owners keep the list current

The tool list and limits open in Tray Build, so the agent's owner can change them without a rebuild, and IT approves new write access.

Access review is a workflow, not a memo

The quarterly review runs on a schedule, goes to a named owner, and switches off what nobody confirms.

Questions people ask

Should an agent run with its own account or as the user?

As the user wherever the system supports it, so the agent can never see or change more than the person asking could. Where that is not possible, use a service account made for that one tool, with only the rights it needs.

Why not give the agent one general tool for each system?

Because a general tool leaves the prompt as the only control. Narrow tools such as update case status are easier to test, easier to log and impossible to talk into doing something else.

How many tools should an agent have?

As few as the job needs. If the list grows past about fifteen, the agent is usually doing two jobs and should be split.

What happens when someone asks for something outside the agent's access?

The tool stops and the agent explains who could make the request or where to ask for access. It never falls back to a more powerful account.

How often should agent access be reviewed?

Quarterly at least, by a named owner, with unused tools removed and anything not confirmed switched off.

Related guides

AI operations