Skip to main content
Glama

Cluster query

cluster_query
Read-only

Structured SQL-backed lookup against the agent's synced resource index (the k8s_resources cache): a Postgres read, NOT a live cluster read - it never contacts the agent and never escalates on its own. Sub-50ms. Use it for exact lookups, label selectors, and JSONB-path filters, and prefer it over the get_pods / get_deployments / get_services / get_configmaps wrappers for inventory and filtering questions. When you need the live object - verifying a change you just made, or confirming state a write depends on - read through the agent with those wrappers or describe_resource. Every item carries last_seen_at and staleness_seconds: seconds since the sync last CONFIRMED the row, not since it changed (unchanged rows are re-confirmed on a heartbeat, K8S_LAST_SEEN_REFRESH_SECONDS, default 480, so a few hundred seconds is healthy). The payload carries an advisory stale_fallback_required, set when any returned row is older than K8S_CACHE_MAX_STALENESS_SECONDS (default 300). Reads ONE cluster: the conversation's, or the one cluster_name / cluster_id names. It never spans the organisation; off-cluster with several readable clusters it refuses and lists them. A list that names no namespace reads every namespace of the cluster and says so in a note; pass namespace to narrow it. Returns one summary row per match - name, namespace and the kind's status fields (phase, ready, restarts, node and reason for a Pod; ready/desired and the first unmet condition for a workload; type, reason, object and message for an Event) - failed and not-ready objects first, with total (every match, before the limit), returned, truncated, scope and a citation marker. Labels, annotations and the full status are one cluster_describe away.

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": {
      "kind": "<kind>",
      "cluster_id": "<cluster_id>"
    },
    "name": "cluster_query"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindYesKubernetes Kind (e.g. 'Pod', 'Deployment', 'Service', 'CustomResourceDefinition').
nameNoOptional exact resource name.
limitNoMaximum rows to return (default 100, max 500).
namespaceNoNamespace filter. Omit it to read every namespace, and for cluster-scoped kinds.
cluster_idYesAnkra cluster id (UUID) the call targets. Discover ids with list_clusters.
all_namespacesNoSet true to read every namespace on the cluster. A list with neither namespace nor this flag reads every namespace too, and its payload carries a note saying so.
field_selectorNoOptional exact-match field filters against the resource index. Each dotted path is routed to the column that stores it: 'status.<field>' reads the status document (example: {"status.phase": "Running"}), 'spec.<field>' and a bare '<field>' read the spec document (example: {"spec.nodeName": "worker-1"}), and 'metadata.name' / 'metadata.namespace' match the identity columns. Nested fields keep their dots ({"spec.template.spec.serviceAccountName": "api"}). Any other path is rejected with an error; filter on labels with label_selector.
label_selectorNoOptional label selector (k8s syntax: 'app=foo,tier=frontend').

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 supply readOnlyHint=true; the description adds substantial context the agent could not otherwise infer: it never contacts the agent, never escalates, sub-50ms, reads exactly one cluster, refuses and lists clusters when scope is ambiguous, and defaults to all namespaces with a note in the payload. It also explains the staleness model precisely (last_seen_at is last CONFIRMED sync, not last change, with the heartbeat env var and default), which prevents a serious misreading of the returned data.

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 single most decision-relevant fact (cache read, not live read) and every sentence carries information. However it is a dense single-paragraph wall of text with parenthetical env-var asides, and the return-payload detail near the end could be tightened.

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?

Given 8 parameters, no output schema, and the ambiguity of cache-vs-live reads, the description covers the missing pieces: staleness interpretation, the advisory stale_fallback_required flag, per-kind summary fields, ordering (failed/not-ready first), total vs returned vs truncated, and the single-cluster scope limit.

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 100%, so the baseline is 3; the description earns above that by explaining the practical consequence of omitting namespace (reads every namespace and says so in a note) and by tying cluster choice to conversation scope. Minor inconsistency: it mentions a `cluster_name` parameter that does not appear in the input schema, which weakens the otherwise precise scope semantics.

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?

"Structured SQL-backed lookup against the agent's synced resource index (the k8s_resources cache)" states a specific verb and resource, and immediately contrasts it with the live-read path ("a Postgres read, NOT a live cluster read"). An agent can distinguish it from get_pods / cluster_describe without opening any schema.

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 explicit when-to-use ("exact lookups, label selectors, and JSONB-path filters", inventory/filtering questions) and when-not ("when you need the live object - verifying a change you just made, or confirming state a write depends on") with named alternatives (the get_* wrappers, describe_resource). It also names the routing rule for off-cluster multi-cluster ambiguity.

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.