Skip to main content
Glama

Roll cluster to version

roll_cluster_to_version
Destructive

Roll a cluster's whole definition back to an earlier resource version (the twin of ankra cluster roll-to) and let the reconcile re-apply it. Take the version id from get_stack_history. This moves every stack at once; rollback_addon rolls one addon. Not reversible except by rolling forward again.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "version_id": "<version_id>"
    },
    "name": "roll_cluster_to_version"
  }
}

Input Schema

NameRequiredDescriptionDefault
cluster_idNoUUID of the target cluster. Optional when a cluster is selected.
version_idYesThe resource version id to roll to (from get_stack_history).
cluster_nameNoExact name of the target cluster. Optional when a cluster is selected.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare destructive=true and idempotent=false, but the description adds what those hints don't: the blast radius (whole cluster definition, every stack at once), the mechanism (reconcile re-applies it), and the recovery path ('not reversible except by rolling forward again'). That is exactly the operational context an agent needs before firing a destructive call.

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?

Three short sentences, front-loaded with what the tool does, then the prerequisite, then the disambiguation and the irreversibility warning. No filler; the CLI-twin aside is compact and aids recognition.

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?

Covers purpose, input provenance, sibling differentiation, and reversibility with no output schema required. The only remaining gap is whether the roll is asynchronous and how to observe completion (e.g., via reconcile_cluster or cluster status), which an agent might want before assuming success.

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 coverage is 100% and the schema descriptions already say version_id comes 'from get_stack_history' and that cluster_id/cluster_name are optional when a cluster is selected. The description repeats the get_stack_history pointer without adding new meaning to any parameter, so the baseline 3 applies.

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 and resource with scope: 'Roll a cluster's whole definition back to an earlier resource version'. The sibling clause ('rollback_addon rolls one addon') plus the CLI twin reference makes it unambiguous against the many other roll/upgrade/apply tools in the list.

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

Usage Guidelines5/5

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

Explicitly routes the agent to get_stack_history as the source of version_id and names rollback_addon as the narrow-scope alternative with the discriminating condition ('every stack at once' vs 'one addon'). The agent can pick the right tool without opening either schema.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.