Control Plane

Update an Identity

update_identity

DestructiveIdempotent

Update an identity's description, tags, and (optionally) replace its networkResources / nativeNetworkResources wholesale. Provider blocks can modify real resources in the connected cloud account, including AWS IAM roles, GCP service accounts, and Azure managed identities. Recommended reading before first use: get_cpln_skill("access-control") — the runbook for this tool family (read once per session).

Input Schema

TableJSON Schema

Name	Required	Description
`aws`	No	Replace the AWS cloud-identity block (full object). To switch xor-fields (roleName ↔ policyRefs), just send the new block — it replaces wholesale.
`gcp`	No	Replace the GCP cloud-identity block (full object). To switch xor-fields (serviceAccount ↔ bindings), just send the new block — it replaces wholesale.
`gvc`	Yes	GVC slug (lowercase kebab-case). Use the GVC the user named; otherwise discover with list_resources (kind="gvc") and let them choose — never guess (a wrong GVC targets the wrong environment).
`ngs`	No	Replace the NGS cloud-identity block (full object — it replaces wholesale).
`org`	Yes	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.
`name`	Yes	Resource name (lowercase kebab-case, starts with a letter, 2-64 chars). Names are IMMUTABLE — renaming = delete + recreate (loses URL, DNS, policy links).
`tags`	No	Add or update tags without replacing the full set. Submit an empty list to clear all tags.
`azure`	No	Replace the Azure cloud-identity block (full object — it replaces wholesale).
`description`	No	New description for the identity.
`removeTagKeys`	No	Tag keys to remove from the resource.
`spicedbAccess`	No	Replace the SpiceDB cluster access list (max 5).
`memcacheAccess`	No	Replace the memcache cluster access list (max 5).
`networkResources`	No	Replace the full networkResources array (wholesale).
`removeCloudIdentities`	No	Cloud-identity blocks to clear from the identity (e.g., ["aws"]). Server-side $drop semantics — use this to detach an identity from a cloud account.
`nativeNetworkResources`	No	Optional replacement for the full nativeNetworkResources array (wholesale). Each item requires name, ports, and exactly one provider block.

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes	Whether the call succeeded.
`data`	No	The full machine-readable result — list rows, the resource object, query results. Read THIS, not just the summary.
`summary`	Yes	One-line summary of the result.
`nextSteps`	No	Recommended follow-up actions for this task, in order.

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already mark destructiveHint=true and readOnlyHint=false, but the description adds critical context: 'Provider blocks can modify real resources in the connected cloud account, including AWS IAM roles, GCP service accounts, and Azure managed identities.' It also clarifies that networkResources and nativeNetworkResources are replaced wholesale, and that tags can be updated without full replacement—details beyond the schema and annotations.

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

Conciseness5/5

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

The tool description is only two sentences, yet it packs the core purpose, the dangerous side effect, and a prerequisite recommendation. There is zero fluff; every phrase earns its place, and the most important info (what it does, what's risky) is front-loaded.

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?

Given the tool's complexity (15 parameters, nested cloud blocks), the description is quite complete. It covers the action, the destructive potential, the wholesale replacement pattern, and recommends a runbook. It does not discuss return values, but an output schema exists, shifting that burden away. The only minor gap is not explaining the difference between 'tags' and 'removeTagKeys' but that is covered in the schema.

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

Parameters4/5

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

Schema description coverage is 100%, so each parameter is already well-documented. The description adds semantic value by highlighting the wholesale-replacement behavior for networkResources/nativeNetworkResources and the tag update semantics (add/update vs. clear). This goes beyond the schema's per-field descriptions, enriching the agent's understanding of parameter interplay.

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?

The description specifies the exact scope: 'Update an identity's description, tags, and (optionally) replace its networkResources / nativeNetworkResources wholesale.' It names the resource (identity) and the precise operations, clearly differentiating from create_identity and other update_* tools. The mention of cloud identity blocks further clarifies the tool's role.

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?

The description warns about the high-impact nature ('Provider blocks can modify real resources in the connected cloud account') and recommends reading a skill ('get_cpln_skill("access-control")') before first use. It provides clear context but does not explicitly enumerate when to use this tool versus alternatives, though the update-vs-create distinction is implicit from the resource name.

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

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.1/5.0

Disambiguation5/5

Every tool targets a distinct resource/action pair (e.g., get_resource vs get_resource_schema, list_deployments vs list_workload_replicas) and descriptions clearly differentiate purposes. No two tools appear to do the same thing.

Naming Consistency5/5

All tools follow a verb_noun snake_case pattern (create_gvc, update_workload, list_resources, query_metrics) with consistent verbs. The few imperative verbs (browse, build, mount) still maintain the same verb-first structure.

Tool Count1/5

With 55 tools, this server far exceeds the typical well-scoped 3-15 tool range. While each tool appears purposeful, the sheer number creates selection overhead and falls into the extreme 50+ category on the rubric.

Completeness4/5

The surface covers nearly the full Control Plane lifecycle: CRUD for GVC, workload, identity, policy, volumeset, and domain, plus observability, templates, image builds, and Terraform. Minor gaps include referenced but missing configure_workload_* tools and no secret creation/deletion (by design).