> 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, category, risk level | | **User attributes** | department, title, location, user category | 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 can be authored in two views: * **Visual**: A condition builder with property dropdowns, operators and AND/OR groups. The default authoring surface. * **Code**: Rego (the OPA policy language). Use for conditions the visual builder does not yet express. Once a Policy is switched to Code, it stays in Code. 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](/docs/ai-agent-access/concepts/the-tool-call-lifecycle.md): when Policies are evaluated * [The Tool Call Record](/docs/ai-agent-access/concepts/audit-log.md): what each Policy evaluation records * [The MCP Gateway](/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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://www.cakewalk.security/docs/ai-agent-access/concepts/policies.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.