> For the complete documentation index, see [llms.txt](https://www.cakewalk.security/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.cakewalk.security/docs/ai-agent-access/concepts/policies.md).

# Policies

Policies define what Agents are allowed to do, what requires human approval, and what is always blocked. They are the core governance surface in Cakewalk Agent Access.

A Policy is a rule the MCP Gateway evaluates on every tool call. The rule produces one outcome: **Auto-approve**, **Require approval** or **Deny**.

***

### 📖 Key Concepts

* **Policy**: A rule the MCP Gateway evaluates on every Agent tool call. Inputs: Action type, User attributes, Connection attributes. Output: one of three outcomes.
* **Default Policy**: One of four pre-loaded policies (one per Action type) that ship on day one.
* **Custom Policy**: A Policy authored by an Admin under Settings > Policies.
* **Action type**: Cakewalk's classification of what a tool call does: **Read**, **Write**, **Destructive** or **External**.

:bulb: *Why this matters:* The Policies you author determine what your Agents can do without asking, what pauses for review and what is blocked.

***

### 🧑 User Attributes

Policies evaluate who delegated the task. Four User attributes are available as conditions: department, job title, team and location. They come from your company's User directory, synced from your HRIS or IdP, so a Policy stays correct as people join, move and leave. One connection feeds the whole platform; see [HRIS and IdP](https://www.cakewalk.security/docs/connections-and-integrations/hris-and-idp).

A Policy might Auto-approve Read actions for Engineering, Require approval for Write actions and Deny Destructive actions for Users outside the EU: all without naming individuals. When the directory adds a new engineer, the Policy applies to them on the next sync.

***

### 📐 Action Types

Every tool call is classified into exactly one Action type. Classifications come from the MCP annotations the tool author declared.

| Action type     | What it covers                                                                                  | MCP annotation                                                      |
| --------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Read**        | No state change. Retrieving data, querying status, listing records.                             | `readOnlyHint: true, destructiveHint: false, openWorldHint: false`  |
| **Write**       | Creates or updates state. Adding records, modifying configurations. Reversible.                 | `readOnlyHint: false, destructiveHint: false, openWorldHint: false` |
| **Destructive** | Deletes or irreversibly changes state. Dropping records, removing users, purging data.          | `destructiveHint: true`                                             |
| **External**    | Interacts with systems outside the tool's domain. Sending emails, posting to Slack, publishing. | `openWorldHint: true`                                               |

A tool can carry more than one annotation. Cakewalk reads them in a fixed order: `destructiveHint` makes the tool **Destructive**, then `openWorldHint` makes it **External**, otherwise `readOnlyHint` decides between **Read** and **Write**.

**When a tool declares no annotations**, Cakewalk classifies it as **Destructive**, so the Default Policies deny it until someone looks at it. An Admin can change any tool's classification from the Connection's **Tools** tab, one tool at a time or in bulk.

{% hint style="info" %}
A classification an Admin sets by hand is preserved. Cakewalk does not overwrite it when it re-syncs the tool list from the MCP server.
{% endhint %}

***

### 🛡️ Default Policies

Four Default Policies ship on day one: one per Action type. They guarantee governance coverage from the moment an org is created.

| Action type     | Default outcome  |
| --------------- | ---------------- |
| **Read**        | Auto-approve     |
| **Write**       | Require approval |
| **Destructive** | Deny             |
| **External**    | Deny             |

Default Policies are permanent. Admins can edit the outcome to match their org's risk tolerance; the Action types and ordering are fixed.

***

### ✏️ Custom Policies

Custom Policies are the rules an Admin authors for their org. Each Custom Policy has:

* **Name** (required) and Description
* **Conditions** that compose with AND / OR
* **Outcome** (Auto-approve, Require approval or Deny)
* **Status**: Active, Draft or Archived

Each condition pairs a Type with a value or set of values to match:

| Type                      | Examples                                                        |
| ------------------------- | --------------------------------------------------------------- |
| **Action type**           | Read / Write / Destructive / External                           |
| **Connection attributes** | name, app category, risk level, server location, certifications |
| **User attributes**       | department, job title, team, location                           |

Connection attributes come from the Catalog. User attributes come from your HRIS sync. Both lists grow as the Catalog expands and as more HRIS fields are mapped.

***

### 🎨 Visual and Code Authoring

Conditions are authored in the Visual builder and shown in two views:

* **Visual**: A condition builder with property dropdowns, operators and AND/OR groups. Where you author and edit conditions.
* **Code**: A read-only view of the same conditions in Rego (the OPA policy language), generated from the Visual builder.

Both views describe the same Policy. The gateway evaluates the underlying Rego.

***

### 🔁 Policy Status

Custom Policies move through three statuses:

* **Draft**: Saved but not evaluated by the gateway.
* **Active**: Evaluated on every tool call.
* **Archived**: No longer evaluated. History preserved.

A Policy created via **Save as draft** is Draft. **Publish** moves it to Active immediately. To return an Active Policy to Draft, use **Move to draft** in the 3-dot menu; to retire it, use **Archive**.

***

### ⚖️ Conflict Resolution

When two Active Policies match the same tool call but produce different outcomes, the gateway resolves deterministically. Two rules:

1. **Custom > Default.** Any Custom Policy outranks any Default Policy.
2. **Within the same tier, more restrictive wins.** Deny > Require approval > Auto-approve.

Every tool call produces exactly one outcome. Nothing falls through.

***

### Related Concepts

* [The Tool Call Lifecycle](https://www.cakewalk.security/docs/ai-agent-access/concepts/the-tool-call-lifecycle.md): when Policies are evaluated
* [The Tool Call Record](https://www.cakewalk.security/docs/ai-agent-access/concepts/audit-log.md): what each Policy evaluation records
* [The MCP Gateway](https://www.cakewalk.security/docs/ai-agent-access/concepts/the-mcp-gateway.md): where Policy evaluation runs


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.cakewalk.security/docs/ai-agent-access/concepts/policies.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
