Skip to main content
Glama

Get cluster machine inventory

get_cluster_machine_inventory
Read-only

Compare every server and bastion record the platform keeps for an Ankra-provisioned cluster (Hetzner, UpCloud, DigitalOcean, AWS, or Ankra Cloud) with what the cloud provider and the Kubernetes Node list say, and classify each record. Use it when a node group counts a worker that is not in the Node list, when unregistered_workers or a stale node / server record / phantom worker is suspected, when a worker sits in creating or stopping for days, or when a stopped cluster's kept machine may have been deleted at the provider. Each row carries name, resource_id, kind, role, node_group, state, parked (a kept row of a stopped cluster), machine_id, provider_answer (present, absent, unknown, or not_asked), node (registered, missing, unknown, or not_applicable) and classification: 'consistent'; 'phantom' (a live row whose machine the provider answered 404 for while answering another machine of the cluster as present in the same pass); 'gone_kept' (the same proof for a parked row); 'no_node' (the machine exists but no Node registered for it past a 30-minute grace); or 'unknown' (no recorded machine id, the provider did not answer, a 404 with no present machine to confirm it, or past the lookup cap). Unknown is never gone: report it as unknown. retirable_resource_ids lists the phantom and gone_kept rows; pass them to retire_gone_machine_rows. nodes_without_row lists Nodes no live record registers as. At most 40 machines are looked up per call, 4 at a time; rows_total and machines_looked_up say when the cap was reached. Runs nothing that changes the cluster or the provider. Not available for imported or managed-Kubernetes clusters, nor (yet) OVH, Scaleway, Proxmox or HPE Morpheus.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_cluster_machine_inventory"
  }
}

Input Schema

NameRequiredDescriptionDefault
cluster_idNoUUID of the cluster. Optional when a cluster is selected.
cluster_nameNoExact name of the cluster. Optional when a cluster is selected.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.6/5.0
Behavior5/5

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

Beyond readOnlyHint=true, it discloses that the tool runs nothing that changes the cluster or the provider, plus concrete throughput limits (at most 40 machines looked up per call, 4 at a time) and the rows_total / machines_looked_up signals for cap detection. It also defines the semantics of each classification and the safety rule that 'unknown is never gone', which materially affects how an agent should act on results.

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?

Purpose and trigger conditions are front-loaded, and nearly every clause carries operational meaning. The classification enumeration is dense and the long compound sentences make it harder to scan than it needs to be, but trimming further would lose decision-relevant detail.

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

Completeness5/5

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

With no output schema, the description carries the full burden of describing returns, and it does: it lists every row field (name, resource_id, kind, role, node_group, state, parked, machine_id, provider_answer, node, classification), the aggregate fields retirable_resource_ids and nodes_without_row, and the cap indicators. For a read-only diagnostic tool with two optional selectors, nothing an agent needs to interpret or act on results is missing.

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% for both cluster_id and cluster_name, so the schema already documents them adequately. The description adds no selector syntax or precedence rules between the two identifiers, leaving that entirely to the structured fields.

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 opens with a precise verb-and-resource pair: it compares every server and bastion record kept for an Ankra-provisioned cluster against provider and Kubernetes Node data, then classifies each record. It also scopes the provider list (Hetzner, UpCloud, DigitalOcean, AWS, Ankra Cloud), which distinguishes it from generic cluster-getter siblings like get_cluster_details.

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?

It enumerates concrete triggering conditions: a node group counting a worker absent from the Node list, suspected unregistered_workers / stale records / phantom workers, workers stuck in creating or stopping, and a stopped cluster's kept machine possibly deleted upstream. It names the downstream consumer (retire_gone_machine_rows) and states explicit exclusions (imported or managed-Kubernetes clusters; OVH, Scaleway, Proxmox, HPE Morpheus).

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.