Skip to main content
Tool Gateway is in beta.
A policy is a rule that Tool Gateway checks on every tool call. It matches calls by who is calling and which tool, and either blocks them or requires the caller to approve each one before it runs. Use policies to stop agents from calling tools that write, delete, or send data, or to add a confirmation step before they do. Policies control what a caller may invoke. Tool kits control only which tools an agent sees. Therefore, do not rely on a kit to restrict access. See Tool kits curate, policies enforce. Viewing policies requires the 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-Id header names. A Workspace Admin cannot make a policy apply to every workspace or move it to another workspace.
For the roles, see Role-based access control.

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_tool runs.
  • 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.
Policies check calls, not tool lists. A blocked tool still appears in the tools that a kit lists. An agent can call with an API key bound to its agent environment. Tool Gateway then checks the policies for the key and the policies for the agent. A block from either one blocks the call. Policies can only restrict a call, so a policy on the agent never lifts a block on the key.

Create a policy

This example requires approval before anyone creates a Linear issue with the save_issue tool from the quickstart.
  1. Go to Tools > Policies and click Create policy.
  2. 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.
  3. Under When a call matches, select Ask for approval. To stop matching calls instead, select Block.
  4. Under Workspaces, keep All workspaces, or select one workspace. A Workspace Admin can select only the current workspace.
  5. Under Applies to, select Everyone, or select a kind of caller and pick the callers. See Choose who a policy applies to.
  6. (Optional) Under Except, pick callers that the policy should not apply to.
  7. Under Tools, search for and select save_issue from Linear. You can also select every tool on a server, or All tools.
  8. Click Create policy.
The tool picker lists servers in the current workspace. To pick another workspace’s server, switch to that workspace first.A new policy is on. The Policies tab lists each policy with an On or Off switch.

Choose who a policy applies to

Each entry in scope.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 in scope.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.
A policy can name a tool on any server, including a server that no kit includes yet. The policy applies as soon as a caller can reach that tool.

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, and actions.
  • 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 403 with "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.
The caller approves the call, not a separate reviewer. Approval confirms each call before it runs, but it does not route calls to an admin. An agent that runs with no one present cannot approve calls. To stop such an agent from calling a tool, use a block policy. For the responses and how callers handle them, see Approve a tool call.

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_enabled is the only field that PATCH accepts.

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. PUT replaces every field and keeps the policy’s ID. If you leave out is_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.
To find a policy’s ID, list policies with 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