Control Plane

Update a Policy

update_policy

DestructiveIdempotent

Update a policy: metadata (description, tags), target scope (targetAll / targetLinks / removeTargetLinks / targetQuery / removeTargetQuery), and bindings (addBindings merges by permission set; removeBindings strips principals from matching bindings). Read it with get_resource (kind="policy") first.

Input Schema

TableJSON Schema

Name	Required	Description
`org`	No	Organization slug.
`name`	Yes	Resource name. Immutable: renaming is delete and recreate.
`tags`	No	Add or update tags without replacing the full set. Submit an empty list to clear all tags.
`targetAll`	No	When true sets target="all" and clears targetLinks (exclusive with targetLinks/removeTargetLinks).
`addBindings`	No	Bindings to merge in. Matching permission sets merge principalLinks; otherwise a new binding is appended.
`description`	No	New description for the policy.
`targetLinks`	No	Replace the targetLinks list with this exact set. Use removeTargetLinks for incremental removal.
`targetQuery`	No	Replace the dynamic target query (resources matching it are targeted).
`removeTagKeys`	No	Tag keys to remove from the resource.
`removeBindings`	No	Bindings to remove. Each item is { permissions: string[], principalLinks: string[] }; matching permission/principal pairs are stripped and empty bindings are removed.
`removeTargetLinks`	No	Remove these targetLinks from the existing list (mutually exclusive with full-replacement targetLinks).
`removeTargetQuery`	No	true deletes targetQuery; a stale query keeps granting on every matched resource, additively to targetLinks.

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes
`data`	No	The full result. Read this, not only the summary.
`details`	No
`summary`	Yes
`nextSteps`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed46 schema fields changedSep 30, 2026
- removedInput schema / $schema
```
Removed value: -"http://json-schema.org/draft-07/schema#"
```
- removedInput schema / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / addBindings / items / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / addBindings / items / properties / permissions / items / minLength
```
Removed value: -1
```
- removedInput schema / properties / addBindings / items / properties / permissions / minItems
```
Removed value: -1
```
- removedInput schema / properties / addBindings / items / properties / principalLinks / items / minLength
```
Removed value: -1
```
- removedInput schema / properties / addBindings / items / properties / principalLinks / maxItems
```
Removed value: -200
```
- removedInput schema / properties / addBindings / items / properties / principalLinks / minItems
```
Removed value: -1
```
- removedInput schema / properties / addBindings / maxItems
```
Removed value: -50
```
- removedInput schema / properties / description / maxLength
```
Removed value: -250
```
- changedInput schema / properties / name / description
```
Previous value: -"Resource name (lowercase kebab-case, starts with a letter, 2-64 chars). Names are IMMUTABLE — renaming = delete + recreate (loses URL, DNS, policy links)."New value: +"Resource name. Immutable: renaming is delete and recreate."
```
- removedInput schema / properties / name / maxLength
```
Removed value: -64
```
- removedInput schema / properties / name / minLength
```
Removed value: -2
```
- removedInput schema / properties / name / pattern
```
Removed value: -"^[a-z]([-a-z0-9])*[a-z0-9]$"
```
- changedInput schema / properties / org / description
```
Previous value: -"Organization slug (lowercase kebab-case). NEVER guess — if the user has not named one, ask. On org-not-found, stop and ask; do not retry variants."New value: +"Organization slug."
```
- removedInput schema / properties / org / maxLength
```
Removed value: -63
```
- removedInput schema / properties / org / minLength
```
Removed value: -1
```
- removedInput schema / properties / org / pattern
```
Removed value: -"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$"
```
- removedInput schema / properties / removeBindings / items / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / removeBindings / items / properties / permissions / items / minLength
```
Removed value: -1
```
- removedInput schema / properties / removeBindings / items / properties / permissions / minItems
```
Removed value: -1
```
- removedInput schema / properties / removeBindings / items / properties / principalLinks / items / minLength
```
Removed value: -1
```
- removedInput schema / properties / removeBindings / items / properties / principalLinks / maxItems
```
Removed value: -200
```
- removedInput schema / properties / removeBindings / items / properties / principalLinks / minItems
```
Removed value: -1
```
- removedInput schema / properties / removeBindings / maxItems
```
Removed value: -50
```
- removedInput schema / properties / removeTagKeys / items / minLength
```
Removed value: -1
```
- removedInput schema / properties / removeTargetLinks / items / minLength
```
Removed value: -1
```
- removedInput schema / properties / tags / items / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / tags / items / properties / key / minLength
```
Removed value: -1
```
- removedInput schema / properties / tags / maxItems
```
Removed value: -50
```
- removedInput schema / properties / targetLinks / items / minLength
```
Removed value: -1
```
- removedInput schema / properties / targetLinks / maxItems
```
Removed value: -200
```
- removedInput schema / properties / targetQuery / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / targetQuery / properties / kind / minLength
```
Removed value: -1
```
- removedInput schema / properties / targetQuery / properties / spec / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / targetQuery / properties / spec / properties / sort / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / targetQuery / properties / spec / properties / sort / properties / by / minLength
```
Removed value: -1
```
- removedInput schema / properties / targetQuery / properties / spec / properties / terms / items / additionalProperties
```
Removed value: -false
```
- changedInput schema / required
```
Previous value: -[
-  "org",
-  "name"
-]New value: +[
+  "name"
+]
```
- removedOutput schema / $schema
```
Removed value: -"http://json-schema.org/draft-07/schema#"
```
- removedOutput schema / additionalProperties
```
Removed value: -false
```
- changedOutput schema / properties / data / description
```
Previous value: -"The full machine-readable result — list rows, the resource object, query results. Read THIS, not just the summary."New value: +"The full result. Read this, not only the summary."
```
- addedOutput schema / properties / details
```
Added value: +{
+  "type": "string"
+}
```
- removedOutput schema / properties / nextSteps / description
```
Removed value: -"Recommended follow-up actions for this task, in order."
```
- removedOutput schema / properties / ok / description
```
Removed value: -"Whether the call succeeded."
```
- removedOutput schema / properties / summary / description
```
Removed value: -"One-line summary of the result."
```

Changed1 schema field changedAug 21, 2026

addedInput schema / properties / removeTargetQuery

Added value: +{
+  "description": "true deletes targetQuery; a stale query keeps granting on every matched resource, additively to targetLinks.",
+  "type": "boolean"
+}

First observedJun 28, 2026

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover destructive/idempotent/readOnly hints, but the description adds real semantics beyond them: addBindings merges by permission set and removeBindings strips principals from matching bindings. This clarifies the partial, merge-oriented nature of the update that a bare 'destructive' hint does not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the verb and resource, then a compact enumeration of the affected areas and a closing workflow directive. Dense but well-organized; no filler sentences, though the parenthetical lists make it heavy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be explained, and annotations carry the safety profile. The description covers the mutation semantics for each concern group plus the read-first precondition, leaving little an agent needs before invoking correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter is already richly documented in the schema, setting the baseline at 3. The description groups parameters conceptually (metadata / target scope / bindings) and restates merge semantics, which aids orientation but adds little beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Update a policy') and enumerates the three concern areas it mutates: metadata, target scope, and bindings. This distinguishes it cleanly from create_policy and delete_resource among its siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit workflow prerequisite: 'Read it with get_resource (kind="policy") first', which steers the agent to inspect before mutating. It does not state when *not* to use it or contrast with create_policy, but the read-first guidance is concrete and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Control Plane tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.