Tool Policies - Stackone

Tool Policies is only available on certain plans. See plans and pricing.

Tool Policies control which tools an agent may use, and how, on behalf of the member it acts for. StackOne checks the policies that apply to that member before a tool call reaches the provider, and refuses the call when an enforced policy denies it. Value rules, semantic rules and PII checks also look at the data itself. Value rules check the argument values a tool receives before it executes. Semantic rules and PII checks run on the tool’s inputs before it executes and on the response before the agent sees it.

Flow diagram with three lanes. An AI agent makes a tool call and Tool Policies are checked. Allowed: the provider is called and the response returns unchanged. Redact PII or Read a field: the provider is called and the response returns with PII redacted or fields masked. Denied, including Write a field denials: the provider is not called and a refusal is returned. All three responses come back to the AI agent. A note under the diagram says semantic rules and PII checks run on both the inputs and the response

How a policy is evaluated

A policy carries a single rule that allows or denies capabilities. Rules are made up of 4 parts:

Part	Options	What it means
Who it applies to	Everyone, Users, Groups	The members whose agents the rule governs. Groups come from Manage Groups.
What it does	Allow, Deny	A deny rule refuses exactly what it covers for those users or groups. An allow rule restricts nothing and cannot undo a deny.
Capabilities	Use a tool, Read a field, Write a field, Value rule, Redact PII, Semantic rule	The operations the rule covers. One capability per kind of access, each narrowed on its own terms. See Capabilities below.
Applies to	Everything, A connector category, A connector, An account, Specific tools	Where the capability is covered. Tools matching narrows any target with a name pattern.

Four guarantees hold across every policy:

A deny always wins

When policies overlap, a matching deny refuses the call whatever any allow says.

Policies narrow access

Connector Profile scoping and account access apply restrictions before policies.

Policies follow the member

Policies apply when the member is known, which is the case for AI platform sessions. A call made with a project API key is memberless — govern that traffic with Connector Profile scoping instead.

Policies stay in their project

A policy belongs to the project it is created in and governs calls made in that project only. To apply the same rule in several projects, create it in each.

Capabilities

A capability is the kind of access a rule governs: running a tool, reading or writing a field, passing an argument value outside the range or list you set, passing PII through a call, or sending and receiving data that a semantic rule’s question flags. Denying one removes that access for the users or groups the rule covers.

Capability	What denying it does
Use a tool	Refuses the call. The agent may not run the tool at all.
Read a field	Masks the field in responses.
Write a field	Refuses calls that would change the field.
Value rule	Refuses calls whose argument values fall outside the condition, such as a payment amount outside 25 to 500 USD. Calls with values inside it keep their existing access.
Redact PII	Finds the chosen classes of PII (email addresses, phone numbers, SSNs, or credit card numbers) in the tool’s inputs and responses, then redacts the detected span or blocks the call. Record UUIDs, order numbers, and API keys stay intact. See PII Redaction.
Semantic rule	Asks a plain-language question about the data in the call. On inputs, a matching answer refuses the call before the tool runs. On a response, it masks the field the answer applies to.

Rules can carry more than one capability. Capabilities are alternatives rather than conditions: the rule applies where any one of them matches, so adding a second says “or also” rather than narrowing the first. Each is scoped on its own terms, so one rule can deny a tool outright on one connector and only mask a field on another.

Create a policy

Open Policies

Select the project, open Project Settings > Policies, and click Create policy. Give the policy a descriptive name.

Set the enforcement level

Choose an Enforcement level:

Enforced: Refuses calls the policy denies, masks fields, and blocks or redacts data according to the rule.
Monitored: Records decisions in the logs without blocking or modifying calls.
Disabled: Stores the policy without evaluating it.

Start new deny rules in Monitored, verify the decisions in your logs, then switch to Enforced.

Choose who it applies to

Select Everyone, Users, or Groups, then search for the users or groups the rule covers.

Choose what it does

Select Deny to refuse the capability for those users or groups, or Allow to state permitted use without restricting anything.

Set the capability and its targets

Add the capabilities the rule governs:

Denying Use a tool refuses the call.Choose which targets it applies under Applies to:

Everything covers every tool in the project.
A connector category covers every tool on every connector in the category, including connectors added later.
A connector covers every tool on the connectors you pick.
An account covers the tools of specific Linked Accounts. Search accounts by name or owner.
Specific tools lets you pick a connector, then the tools on it by name.

To narrow the tools covered by the target selection, enter a name pattern under Tools matching (see the pattern syntax below). An empty pattern covers every tool the targets include, so a deny refuses every call to them. A capability takes either specific tools or a pattern, not both.

Denying Value rule keeps a tool available and checks the values the agent passes in its arguments.Choose which targets it applies under Applies to, the same way as Use a tool, then pick the argument and the condition its value must meet:

A range for numbers, such as a payment amount between 25 and 500 with the currency USD.
Allowed or blocked values, such as an invoice status that may be Draft or Submitted but not Authorized, or a sharing type that may not be anyone.

A call whose value falls outside the condition is refused before the tool runs. A call that leaves the argument out, or sends it in another type or currency, is refused too.

Pattern syntax - wildcards

* is the only wildcard, and it matches any run of characters.
A pattern has to cover the whole name: salary matches only something named exactly that, so use *salary* to match it anywhere.
Matching is case-sensitive.
?, [a-z], and {a,b} are ordinary characters here, not wildcards. A pattern using one saves cleanly and then never matches anything.

Pattern	Matches	Does not match
`delete`	`personio_delete_person`	`okta_remove_user_from_group`
`salary`	`salary`	`employee.compensation.salary`
`Delete`	Nothing, since matching is case-sensitive.	`personio_delete_person`

Add exemptions

For a deny rule, use Exempt from this rule to name users or groups the rule does not apply to. Another matching deny can still refuse the call.

Review and create

Review the policy:

Plain Text: the panel footer restates the rule in plain words, for example:
Everyone in this project may not use a tool matching *delete* on Workday, except Finance (Group).
Cedar: the exact statement the engine will evaluate, in Cedar syntax. The view is read-only; change the form and the statement follows.
JSON: the same statement in Cedar’s JSON encoding.

Then click Create policy.

If you used the assistant, the button reads Accept changes and create. See Build a policy with the Policy AI Assistant.

Create policy panel with Policy chat on the left and the form on the right, showing a policy named Contractors cannot use tools that delete records, the audience set to the Contractors group, and a Deny rule on the Use a tool capability — A deny rule on the Create policy panel, with Fields, Cedar, and JSON views above the form.

Build a policy with the Policy AI Assistant

The Policy AI Assistant opens beside the form, as Policy chat, whenever you create or edit a policy. Describe the rule in your own words and the assistant drafts it in the form for you to review:

Suggestions are highlighted in the form, with the previous value shown underneath.
Each suggestion can be applied or reverted individually.
All changes can be applied using the buttons at the top of the form or by clicking Accept changes and create or Accept changes and save.

The assistant drafts every capability, including value rules, semantic rules and PII redaction. Ask for Keep unreleased financial results out of Slack for everyone outside Finance and it writes the semantic rule’s question, picks the send tools, and sets the audience and exemption.

Create policy panel split in two, with Policy chat on the left showing completed search_principals and update_policy_draft tool calls and an explanation of the proposed rule, and the policy form on the right with a bar reading 3 changes from the assistant need review — The Policy AI Assistant beside the form. The assistant looked up the Contractors group, proposed a deny rule, and left three changes marked for review.

What the assistant can access

The assistant can look things up in the project as it drafts, and the transcript shows each lookup as it runs:

It can find	So you can say
Users and groups	Exempt payroll, (where you have a group defined as “payroll”)
Connectors and categories	Block writes to any HRIS connector
The tools on a connector	Stop the delete ones on Workday
Linked accounts	Only the Acme production account
Related tool call logs	Stop this tool returning some of the fields it returned

By default, only a tool call’s tool, connector and caller are exposed.With advanced logging enabled, the assistant can read the request/response payloads to help define field related capabilities.

For example, using a prompt like:

Stop contractors deleting records

The assistant searches existing groups, sets Who it applies to to Groups and populates with Contractors.
Writes a deny on Use a tool with a *delete* pattern, with applies to set to Everything.

The assistant also flags what a rule may miss. For example, a pattern matching delete does not catch a connector whose tools are named with remove or archive, so you can ask it to add those patterns too.

Starting from logs

Policy creation can be initiated from a specific log instead of the policies page.

Go to StackOne Logs.

Select the log of a call you want to create a policy from.

Click Use in policy at the top of the panel.This takes you to the Policies page with the context of the log selected.

Either select an existing policy OR create a new policy by clicking Create policy.

The Policy AI Assistant now has the context of the selected log.Describe the policy you want. For example:

This call should not have been allowed to return salary

This person should not have been allowed to make it

See Build a policy with the Policy AI Assistant.

Testing a policy before enforcing it

Two checks come before enforcing:

Test against personas: in the create and edit panel, Test this policy against personas shows what the rule would decide for the members you choose, without making a call.
Monitored: set the policy’s Enforcement to Monitored and applicable tool calls are flagged as calls the policy would have applied to, while continuing unaffected. Value rule matches, semantic rule answers and PII detections are recorded the same way.

Only when Enforcement is set to Enforced are tool calls blocked or modified as defined by the policy.

Change a policy’s enforcement level

The Policies table displays an Enforcement column showing each policy’s current level: Enforced, Monitored, or Disabled.

Open Policies

Select the project and open Project Settings > Policies.

Select the new level

On the policy’s row in the table, click the … button and select the new level:

Enforce moves the policy to Enforced.
Monitor or Stop enforcing moves the policy to Monitored.
Disable moves the policy to Disabled.

You can also edit the policy and change the Enforcement field in the side panel.

Duplicating policies

Instead of starting with a blank new policy, an existing policy can be used as a template.

Open Policies

Select the project and open Project Settings > Policies.

Duplicate the policy

On an existing policy’s row in the table, click the … button and select Duplicate.

Review the draft

A new policy is drafted with the original policy’s details except:

Name: original name is appended with (copy).
Enforcement: set to Disabled.

Edit as needed, then click Create policy.

A policy whose rule the builder cannot read, or that holds more than one statement, cannot be duplicated.

Examples

Contractors can't delete anything, anywhere

One Use a tool deny with Applies to set to Everything and Tools matching set to *delete*, for the Contractors group. Run it in Monitored first, check the logged decisions, then switch it to Enforced.

Payments stay within limits

A Value rule deny on the payment tools for NetSuite and Xero, on the payment amount, allowing amounts between 25 and 500 in USD. A payment outside that range, or in another currency, is refused before the tool runs, and payments inside it go through as before.

Unreleased financials stay in Finance

A Semantic rule deny on the send tools for Slack, Gmail and Notion, asking Does this message contain unreleased financial results? on Inputs. It applies to Everyone, with the Finance group exempt. The agent can still summarize the month-end close for Finance, and a message that posts those numbers to a shared channel is refused.

Customer PII stays in support

Two policies for the support agent’s users:

Zendesk: a Redact PII deny on the Zendesk account, set to Redact, so responses reach the agent without email addresses, phone numbers or card numbers. The same policy adds Read a field on Zendesk, with Fields matching set to the card number’s path, so that field is always masked.
Jira and Slack: a Redact PII deny on the Jira and Slack accounts, set to Block, so a write that contains PII is refused.

The agent can still escalate the bug to Jira, without the customer’s details.

What a denied call returns

When an enforced policy refuses a tool call before it runs, the request fails with HTTP 403 and nothing reaches the underlying provider. The refusal returns to the agent as the tool result.

{
  "message": "Action 'personio_delete_person' is not permitted by project policy",
  "errorType": "POLICY_DENIED_ERROR",
  "level": "project"
}

A call refused by a value rule, a semantic rule or a PII block on its inputs fails the same way, before the provider is called. A PII block on a response refuses the call after the provider responds: the agent receives the refusal instead of the data. Masking and redaction on a response never fail the call: the agent receives the response with the denied fields masked and the detected spans redacted.

Troubleshooting

Why is a pattern matching the wrong tools, or none at all?

It matches nothing. The pattern has to cover the whole name: salary only matches a tool named exactly that, so use *salary*. ?, [a-z], and {a,b} do not perform any special matching.
It misses tools you expected. Matching is case-sensitive: *Delete* misses personio_delete_person. A pattern matches exactly rather than describing a behavior: *delete* does not catch a tool named okta_remove_user_from_group.
It matches more than you expected. * matches any run of characters, underscores included, so *create* could cover leaddocket_list_opportunities_created_since.

Why is a policy not taking effect?

Check the following in order:

The policy’s Enforcement is set to Enforced (not Monitored or Disabled).
The acting member is in its audience (and not exempt).
The call is made in the project the policy was created in.
The tool name or pattern matches exactly, including case.
The caller is a member connected through an AI platform, so the call carries their identity. A call made with a project API key alone names no member, so no policy governs it.

Can I see policy decisions in request logs?

Yes, on an action log. Open the record and select the Policy tab.

Next steps

Scoping Connectors

Set which actions each Connector Profile exposes.

Groups

Maintain the groups your policies apply to.

Connector Profile Access

Control who can link accounts on a profile.

Observability

Configure request logging and retention.

​How a policy is evaluated

A deny always wins

Policies narrow access

Policies follow the member

Policies stay in their project

​Capabilities

​Create a policy

​Build a policy with the Policy AI Assistant

​What the assistant can access

​Starting from logs

​Testing a policy before enforcing it

​Change a policy’s enforcement level

​Duplicating policies

​Examples

​What a denied call returns

​Troubleshooting

​Next steps

Scoping Connectors

Groups

Connector Profile Access

Observability

How a policy is evaluated

Capabilities

Create a policy

Build a policy with the Policy AI Assistant

What the assistant can access

Starting from logs

Testing a policy before enforcing it

Change a policy’s enforcement level

Duplicating policies

Examples

What a denied call returns

Troubleshooting

Next steps