Skip to main content
Glama

SSH diagnose node

ssh_diagnose_node
Read-only

Diagnose one Kubernetes node of an Ankra-provisioned cluster (Hetzner, OVH, UpCloud, DigitalOcean, Scaleway, AWS, or Ankra Cloud) at the OS level over SSH-via-bastion, for failures below the Kubernetes layer that kubectl-style tools cannot see: a NotReady node whose kubelet stopped posting status, a node the reconcile history reports as ssh_unreachable, a crash-looping k3s/kubelet service. Returns a read-only diagnostics snapshot (systemd unit state, recent journal, kubectl node view, network and listener state, apiserver firewall drops) plus any node-recovery symptoms detected. If the node cannot be reached over SSH at all, the report instead carries a path_diagnosis naming the hop that failed (bastion or node), the cause class (connect_timeout, connection_refused, no_route, auth_rejected, handshake_failed, tunnel_prohibited, ...) and the verbatim dial error - use it to tell a dead bastion from a dead node from a rejected SSH key before recommending anything. Hetzner diagnoses of an unreachable node additionally include a firewall_inspection: which Hetzner Cloud Firewalls are applied to the bastion and node servers and whether they admit inbound TCP 22 (these firewalls filter the public interface only, so they can block the platform's hop to the bastion but never the private bastion-to-node hop). Runs nothing that changes the node. Identify the node with node_id (preferred, from list_cluster_nodes) or node_name; the bastion/gateway has no kubelet - use diagnose_bastion for it. Use this before ssh_repair_node. Not available for imported or managed-Kubernetes clusters, nor (yet) Proxmox/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": "ssh_diagnose_node"
  }
}

Input Schema

NameRequiredDescriptionDefault
node_idNoUUID of the node to diagnose. Preferred when known (from list_cluster_nodes).
node_nameNoExact name of the node to diagnose. Alternative to node_id.
cluster_idNoUUID of the cluster the node belongs to. Optional when a cluster is selected.
cluster_nameNoExact name of the cluster the node belongs to. Optional when a cluster is selected.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare readOnlyHint, so the description carries real weight and does: it states it runs nothing that changes the node and enumerates the snapshot contents (systemd unit state, journal, kubectl node view, network/listener state, apiserver firewall drops). It further discloses the failure-mode output (path_diagnosis with hop, cause class such as connect_timeout or auth_rejected, verbatim dial error) and the Hetzner-only firewall_inspection, including the important caveat that those firewalls filter only the public interface and can never block the private bastion-to-node hop.

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?

It is one dense paragraph, but the core purpose and the pre-repair ordering are front-loaded and nearly every clause adds distinguishing information. Length is justified by the tool's complexity, though the firewall_inspection detail could be tighter.

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?

There is no output schema, so the description must describe returns, and it does thoroughly for both the success case (diagnostics snapshot plus recovery symptoms) and the unreachable case (path_diagnosis with hop, cause class, dial error). Combined with the usage ordering and exclusions, nothing an agent needs before calling is missing.

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 coverage is already 100%, so the baseline is 3, but the description adds selection logic beyond the schema: node_id is preferred and sourced from list_cluster_nodes, node_name is the alternative, and the bastion has no kubelet so it must go to diagnose_bastion. It stops short of explaining how cluster_id/cluster_name interact with the node identifiers, leaving that to the schema.

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 (diagnose one Kubernetes node at the OS level over SSH-via-bastion) plus the provider scope and the exact class of failures it targets. It explicitly separates itself from siblings: kubectl-style tools cannot see these failures, diagnose_bastion handles the bastion/gateway, and list_cluster_nodes supplies the node_id.

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?

Gives concrete triggering symptoms (NotReady node with a kubelet that stopped posting status, ssh_unreachable in reconcile history, crash-looping k3s/kubelet) and an explicit ordering rule: use this before ssh_repair_node. It also names exclusions (imported and managed-Kubernetes clusters, Proxmox/HPE Morpheus) and the sibling to use instead for the bastion.

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.