Tool Gateway is in beta.
organization:read permission. Creating, changing, or deleting a policy requires a personal access token or a LangSmith session, not a service key, and one of these roles:
- Organization Admin: Manages every policy in the organization, including policies that apply to every workspace.
- Workspace Admin: Manages only policies limited to the workspace they are signed in to, or that the
X-Tenant-Idheader names. A Workspace Admin cannot make a policy apply to every workspace or move it to another workspace.
How policies work
Each policy has one of two effects:
Tool Gateway applies these rules on each call:
- Allowed by default: A call that no policy matches runs.
- Block wins: If a call matches a block policy and an approval policy, the call is blocked.
- Every endpoint: Policies apply to calls through a tool kit, the me kit, and a single server’s endpoint. In search mode, they apply to the tool that
call_toolruns. - Organization or workspace: A policy applies in every workspace in the organization, or in one workspace that you choose.
- Immediate: Creating, changing, turning off, or deleting a policy takes effect on the next call.
Create a policy
This example requires approval before anyone creates a Linear issue with thesave_issue tool from the quickstart.
- UI
- API
- Go to Tools > Policies and click Create policy.
- Enter a Name, such as
approve-linear-issues, and optionally a Description. If you leave the description blank, LangSmith uses a summary of the policy. - Under When a call matches, select Ask for approval. To stop matching calls instead, select Block.
- Under Workspaces, keep All workspaces, or select one workspace. A Workspace Admin can select only the current workspace.
- Under Applies to, select Everyone, or select a kind of caller and pick the callers. See Choose who a policy applies to.
- (Optional) Under Except, pick callers that the policy should not apply to.
- Under Tools, search for and select
save_issuefrom Linear. You can also select every tool on a server, or All tools. - Click Create policy.
Choose who a policy applies to
Each entry inscope.principals and scope.except_principals is an object with a type and an id. Use "*" as the id to match every caller of that type.
Use
"*" as the id for Users, Service keys, and Agents to match all callers of that type. The UI shows these as All users, All service keys, and All agents. User groups and roles must name one ID.
User groups appears in the UI when your organization uses user groups. Except accepts the same callers, except Everyone.
Choose which tools a policy applies to
Each entry inscope.actions names a tool by its server and its name on that server:
A policy names a server you added by its ID, not by the server name that prefixes tools in a kit. For example, a kit lists
linear_save_issue, but the policy entry is <linear-server-id>_save_issue. To find a server’s ID, list servers with GET /v1/managed-tools/servers.Policy names and limits
- Name: 1 to 63 lowercase letters, digits, or hyphens. It must start with a letter, end with a letter or digit, and be unique in the organization. A duplicate name returns
409. - Callers and tools: Up to 100 entries each in
principals,except_principals, andactions. - Policies: Up to 1,000 policies that apply to every workspace, plus up to 100 policies limited to each workspace. Creating a policy past either limit returns
422.
What callers see
- Block: The call returns
403with"code": "tool_call_blocked". - Ask for approval: An MCP client that supports form elicitation shows the caller an approval form. The form names the tool, its server, the policies that require approval, and the call’s arguments. If the caller accepts, the call runs. If the caller declines, the call returns a tool error and does not run. A client that cannot show the form gets
403.
Turn off, edit, or delete a policy
Turn a policy off or on
A policy that is off stays saved but does not apply to any call.- UI: On Tools > Policies, use the policy’s On switch.
-
API: Send
PATCH /v1/agent-policies/<policy-id>.is_enabledis the only field thatPATCHaccepts.
Edit a policy
- UI: On Tools > Policies, click the policy’s edit action, change it, then click Save.
- API: Send
PUT /v1/agent-policies/<policy-id>with the whole policy, in the same format as when you created it.PUTreplaces every field and keeps the policy’s ID. If you leave outis_enabled, the policy turns on.
Delete a policy
- UI: On Tools > Policies, click the policy’s delete action, then confirm.
-
API:
The request returns
204, including when the policy is already deleted.
GET /v1/agent-policies. The response holds up to 20 policies in items. Set page_size to return up to 100, and pass the response’s next_cursor as cursor to get the next page.
Creating, changing, and deleting policies are recorded in the organization’s audit log. See Traces and audit log.
See also
- Approve a tool call
- How Tool Gateway works
- Act as users and agents
- Traces and audit log
- Role-based access control
Connect these docs to your agent of choice via MCP for real-time answers.

