> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getunbound.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Policies

> Monitor and control terminal commands and MCP tool calls made by AI coding tools

## What are Tool Policies?

Tool Policies allow you to monitor and control actions taken by AI coding tools in your organization. Create policies to track, warn on, or block terminal commands executed by AI agents or MCP tool calls made through integrated servers like GitHub, Linear, Sentry, and more.

**Gateway URL:** [https://gateway.getunbound.ai/policies/tool-policies](https://gateway.getunbound.ai/policies/tool-policies)

## Policy Types

When you click **Create Policy**, you'll be asked to choose what you want to monitor:

### Terminal Commands

Monitor shell commands executed by AI coding tools like Claude Code, Cursor, Roo Code, and Cline.

* Select a **Command Family** (e.g., `delete_file`, `git_action`, `remote_access`)
* Define a **Target Pattern** to match specific paths, branches, or operations
* Supports exact match, glob patterns (`/etc/*`), and regex (`.*\.env$`)

**Natural language rules**: Instead of a command family and pattern, you can describe the policy in plain English — for example, "block any command that writes to the production database." The gateway evaluates these via LLM, so policy authoring doesn't require knowledge of specific command family names.

### MCP Actions

Monitor tool calls made through MCP (Model Context Protocol) servers.

* Select an **MCP Server** (e.g., GitHub, Linear, Sentry)
* Select the **MCP Tool** to monitor (e.g., `create_pull_request`, `create_issue`)
* Optionally filter by **tool action type** (e.g., read, write) to apply policies to all tools of a certain kind

**Canonical groups** offer broader targeting: select a logical service group (e.g., "code repository writes") to apply a policy to all matching tools across any connected MCP server, without naming individual servers or tools. Canonical groups and tool action types are mutually exclusive targeting modes.

<Note>
  If you are building an MCP server that calls back into Unbound for policy checks, manage your MCP credentials from **Connect → MCP Keys** in the dashboard.
</Note>

## Actions

Each tool policy has an action that determines what happens when a match is found:

| Action                     | Behavior                                                                                                                                                                                                                                                                             |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Block**                  | Reject the command or tool call entirely. The action is prevented from executing.                                                                                                                                                                                                    |
| **Warn**                   | Allow the action but flag it for review. Users receive a warning notification.                                                                                                                                                                                                       |
| **Audit**                  | Silently log the action for monitoring. No user-facing impact. Available for reporting and analytics.                                                                                                                                                                                |
| **Require Slack Approval** | Hold the command in a pending state and send an interactive Slack DM to the developer. The approver can Allow Once, Allow for 1 hour, or Deny. The agent retries automatically after a decision. Requires the [Slack integration](/integrations/slack-integration) to be configured. |

## Applying to Users

By default, a tool policy with no user groups applies to **everyone** in your organization. To restrict a policy to specific teams, assign it to one or more **user groups** during creation or editing.

* **No user groups selected** — The policy applies organization-wide
* **User groups selected** — The policy applies only to members of those groups
* When a user group is modified, policy enforcement updates automatically for all affected users

Policies can also be scoped to **specific AI tools** — for example, enforce a policy for Claude Code without applying it to Cursor or Codex. Select one or more applications during policy creation.

<Tip>
  You can manage user groups from the [User Groups](https://gateway.getunbound.ai/users/user-groups) page. Create groups based on teams, roles, or projects to apply different policies to different sets of users.
</Tip>

## Policy Coverage & Health

The **Health** view in the Tool Policies dashboard shows which command families and MCP tool categories have no active policies — coverage gaps where agent actions are completely unmonitored. Each policy also carries a health score (0–100) based on how well it matches real observed traffic.

Open it from the Tool Policies page by clicking **Health** (for terminal commands) or **MCP Health**.

## Policy Recommendations

The dashboard proactively surfaces policy suggestions based on observed agent activity. Each recommendation identifies either a **complete gap** (no policy covers this command or tool type at all) or a **partial gap** (a policy exists but doesn't match all observed variants).

Recommendations appear automatically as your agents run. You can create the suggested policy directly from the recommendation card, or dismiss it.

## Quick Example

Let's create a policy to audit when AI tools delete files in sensitive directories:

1. Go to [Tool Policies](https://gateway.getunbound.ai/policies/tool-policies) and click **Create Policy**
2. Select **Terminal Commands**
3. Fill in the form:
   * **Name**: "Audit Sensitive File Deletions"
   * **Command Family**: `delete_file`
   * **Target Field**: `path`
   * **Target Pattern**: `/etc/*` or `*.env`
4. Set **Action** to `Audit`
5. Optionally select **User Groups** to limit the policy to specific teams
6. Click **Preview Impact** to see historical matches
7. Click **Create Policy**

<Tip>
  Use **Preview Impact** when creating a policy to see how many historical commands match your pattern before deploying.
</Tip>

## Tool Policies vs Security Policies

Tool policies and security policies serve different purposes and are managed independently:

|                        | Tool Policies                                      | Security Policies                                                    |
| ---------------------- | -------------------------------------------------- | -------------------------------------------------------------------- |
| **Purpose**            | Control terminal commands and MCP tool calls       | Protect sensitive data with guardrails, routing rules                |
| **Covers**             | Terminal command families, MCP server/tool actions | PII detection, secrets detection, regex patterns, ban lists, routing |
| **User group scoping** | Directly on the tool policy                        | Directly on the security policy                                      |
| **Actions**            | Block, Warn, Audit, Require Slack Approval         | Block, Redact, Warn, Route                                           |

<CardGroup cols={3}>
  <Card title="Slack Integration" icon="slack" href="/integrations/slack-integration">
    Set up Slack for interactive approval workflows
  </Card>

  <Card title="CLI Policy Management" icon="terminal" href="/cli/policies">
    Create and manage tool policies from the terminal
  </Card>

  <Card title="Tool Policy Hooks" icon="webhook" href="/integrations/api-tool-policy-hooks">
    Integrate policy checks directly into your agent or framework
  </Card>
</CardGroup>