Skip to main content
Glama

Cluster search

cluster_search
Read-only

Postgres full-text search over 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. Use it for fuzzy keyword lookups: 'find anything mentioning prometheus', 'workloads using the nginx image', 'recent warning events about scheduling'. Returns top-K ranked hits with citations. Every hit 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 hit is older than K8S_CACHE_MAX_STALENESS_SECONDS (default 300). Treat a hit as a pointer: read the object itself with cluster_describe, or through the agent (describe_resource) when you need it live. No external API; runs entirely in Postgres. Reads ONE cluster: the conversation's, or the one cluster_name / cluster_id names; off-cluster with several readable clusters it refuses and lists them.

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": {
      "query": "<query>",
      "cluster_id": "<cluster_id>"
    },
    "name": "cluster_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindsNoOptional kind filter to scope the search.
limitNoMaximum hits to return (default 20, max 100).
queryYesSearch query - websearch_to_tsquery syntax (quoted phrases, AND/OR, NOT supported).
cluster_idYesAnkra cluster id (UUID) the call targets. Discover ids with list_clusters.
namespacesNoOptional namespace filter to scope the search.

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?

Beyond readOnlyHint=true it discloses non-obvious behavior: results come from a cache with a heartbeat refresh (K8S_LAST_SEEN_REFRESH_SECONDS, default 480), staleness is measured since last confirmation rather than change, and the payload carries an advisory stale_fallback_required flag tied to K8S_CACHE_MAX_STALENESS_SECONDS. It also scopes reads to exactly one cluster and describes the multi-cluster refusal.

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 core identity and use case before the staleness mechanics, and every paragraph is substantive rather than filler. It is dense with parenthetical environment-variable detail that reads more like internal documentation than agent-facing guidance, costing some scannability.

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, and the description compensates fully: top-K ranked hits with citations, per-hit last_seen_at and staleness_seconds, and the stale_fallback_required advisory. An agent has everything needed to call it, interpret freshness, and decide whether to re-read live.

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%, so kinds/namespaces/limit/query syntax are already fully documented structurally, which sets the baseline at 3. The description does clarify cluster targeting semantics (defaults to the conversation's cluster, refuses off-cluster with multiple readable clusters), but it also references a "cluster_name" parameter that does not exist in the schema, which adds noise rather than meaning.

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 mechanism and resource: "Postgres full-text search over the agent's synced resource index (the k8s_resources cache)". It immediately distinguishes itself from live-read siblings by declaring it is "a Postgres read, NOT a live cluster read" that "never contacts the agent".

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 an explicit use case ("fuzzy keyword lookups") with three concrete example queries, and names the handoff path: "Treat a hit as a pointer: read the object itself with cluster_describe, or through the agent (describe_resource) when you need it live." It also states the refusal condition (off-cluster with several readable clusters), so the agent knows when the call will fail rather than return hits.

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.