Introduction
Sana connects to 100+ connectors and 1000+ tools, letting users read and write data across external systems. That's a lot of powerful functionality - and with it comes real risk if those tools run without the right guardrails. By default, read tools are allowed without human approval and write tools are not allowed without human approval, since they can create, update or delete data in external systems. Tool controls give both workspace owners and workspace members more granular control over which tools that are allowed without approval, allowed with approval or not allowed - enabling two key use cases:
Safe gradual rollouts: Workspace owners can limit a new connector to only the tools they’ve reviewed as safe and useful, letting them gradually roll out new capabilities.
Ambient agents without a human-in-the-loop: Workspace owners can designate trusted tools to run without approval, letting agents act autonomously in the background.
Background
Tools
A connector is made up of tools that we divide into two groups:
Read tools: Let you find and read data.
Write tools: Let you create, update, or delete data in external systems.
Tool permissions
A connector’s tool in Sana can have one of three types of tool permissions:
No limit: Sana can use this tool without human-in-the-loop approval
Approval required: Sana needs human-in-the-loop approval to execute this tool
Blocked: Sana cannot execute this tool at all
Important note - By default, read tools are configured to have no limit, and write tools require approval. |
How tool controls are governed top-down from the workspace settings
Tool controls cascade top-down through two levels and follow one simple rule: each level can only make a tool's permissions stricter than the level above it, never looser.
Workspace settings: workspace owners set the loosest permission any tool is allowed to have across the whole organization - this is the ceiling everyone else works under.
User settings: workspace users can tighten the permissions for a tool further for themselves, but never loosen it beyond what the workspace settings allow.
Whichever way a tool gets used - through chat or through an agent - Sana applies the same permission from the user’s settings.
Example If a workspace owner sets a tool to "Approval required”, a workspace member can tighten it to be "Blocked" for themselves in the user settings - but not loosen it to "No limit," since that would fall below the workspace ceiling. Conversely, if a workspace owner sets a tool to "No limit", a workspace member can tighten it to "Approval required" or "Blocked" since both stay within the ceiling. |
Set up instructions
For workspace owners
Workspace owners can configure which tools are available for a connector both before and after the connector has been added, as described in the two respective sections below.
Configuring tools before enabling a new connector:
Go to Workspace settings > Connectors > Add connector.
Select the connector you want to add and configure, e.g. Salesforce.
Select who the connector should be available for: everyone or specific users.
Configure the tools either by:
Configure the tool group default behavior: Select “No limit”, “Approval required”, or “Blocked” on the top-level tool group row of either read- or write tools.
Configure individual tools to override the tool group defaults: Select “No limit”, “Approval required”, or “Blocked” on the individual tool.
Click Enable at the bottom.
Configuring tools after enabling a connector:
Go to Workspace settings > Connectors
In the list of enabled connectors, click the one you want to modify
Scroll down to the Tools section:
To configure the tool group default behavior: Select “No limit”, “Approval required”, or “Blocked” on the top-level tool group row of either read- or write tools.
To configure individual tools to override the tool group defaults: Select “No limit”, “Approval required”, or “Blocked” on the individual tool.
Click Save at the bottom.
For workspace members
Pre-requisite: The connector must already be enabled for you by your workspace owner, and you must connect your own account for it before configuring your own permissions. |
Go to User settings > Connectors
Click on the connector in the list of enabled connectors
Scroll down to the Tools section:
To configure the tool group default behavior: Select “No limit”, “Approval required”, or “Blocked” on the top-level tool group row of either read- or write tools.
To configure individual tools to override the tool group defaults: Select “No limit”, “Approval required”, or “Blocked” on the individual tool.
FAQ
Q: How can I build a fully autonomous agent that does not require my approval?
A: Set the tools your agent uses to "No limit" in your user settings for that connector. This removes the human-in-the-loop step whenever the agent runs. However, a tool can only be set to "No limit" for your agents if your workspace owner has allowed that tool to be called without approval in the workspace settings.
Q: What happens if a user or agent tries to use a tool that is not allowed?
A: Sana enforces this at the platform level: the tool is disabled for both the user and the agent, so it cannot be called.
Q: What happens if a new tool is added?
A: When a connector adds a new tool, it inherits the default of its group. E.g. if you rely on write tools not being allowed, leave the group default for Write tools to be “Blocked” rather than overriding tools one by one.
Q: What happens if a workspace owner tightens a tool's permission after I've already configured my own settings?
A: The workspace-level setting is a ceiling - if it's lowered, any more permissive user-level setting is automatically capped to match, and Sana starts asking for approval if the tool permissions are changed to “Approval required” or refuses to run the tool if it is changed to “Blocked”.
Q: Do tool controls apply retroactively to agents I've already built?
A: Yes. Permissions are evaluated each time a tool is used, not when an agent is built, so a permission change takes effect the next time the agent runs - no rebuild needed.
Q: How do I revert an overridden tool to the group default?
A: In the tool settings page (whether that is workspace settings or user settings in your case), click on the cross icon next to the selected tool permissions to reset to group default.
Q: My workspace owner requires approval for everything, how do I get them to grant me more access?
A: Reach out to the team owning rolling out Sana at your company. Enabling this is not something Sana owns, it is the workspace owners in your workspace and we do not know how your company’s internal processes work for changing these permissions as it varies by company.
Q: Can I as a workspace owner customize tool permissions so that some users have access to some tools while other users do not?
A: No - workspace owners can not configure custom tool permissions for different users - each user who got access to connect to the connector will follow the same tool permissions.
Known limitation
Workspace users can not configure tools during connector set up, only after a connector has been set up.
Calling tools that include file uploads to 3rd party systems will always trigger a human-in-the-loop approval to mitigate security risks.
There are limits in the number of skipped approvals, after hitting that limit the user may have to approve actions in the agent or chat to continue.
Tool controls are not available for the Workday connector.