get_cluster_health_snapshot

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

Annotations only say readOnlyHint=true, and the description carries substantial extra context: version and deployment-type gating, Capella being rejected without issuing a REST call, the required ro_admin role, and that the call raises on failure. It also pre-empts misinterpretation of results, e.g. orchestrator_known=false means safe_to_act_on is 'unknown' rather than 'yes', and recoveryType other than 'none' means in-progress rather than broken.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Well structured and front-loaded: purpose first, then the diagnostic questions, prerequisites, and a clearly delimited 'Reading the result' block. The result-reading section is long for a one-parameter read tool and partly re-states what the output schema already encodes structurally, but most of it adds interpretation (unhealthy vs inactive semantics, address selection) rather than restating field names.

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

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

For a diagnostic tool whose value is entirely in interpreting the returned payload, the description supplies prerequisites, failure behavior, and per-field semantics including the tricky orchestrator-unknown case and the rebalance_start vs rebalance_success counter signature. An agent could call this and correctly read the output without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one parameter (timeout, default 30) with zero schema description coverage, and the description says nothing about it at all — no unit, no guidance on when to raise it, no note on what happens when it expires. The parameter is largely self-explanatory, which keeps this at a minimum-viable 3, but the description makes no contribution here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource set: per-node service topology, membership, orchestrator and health, retrieved in one call. It goes further than most by naming the diagnostic question it answers (symptom to node/service, post-failover topology validation). The one gap is that it never distinguishes itself from the near-duplicate sibling get_cluster_health_and_services, so an agent must guess between two similarly named health tools.

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

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

Clear usage contexts are given (turning a symptom into a specific node, checking whether a topology change left a good state), plus an explicit hand-off: pair with get_cluster_tasks for what is running now. Prerequisites and hard exclusions are stated (self-managed Couchbase 7.6+ only, Capella rejected without a REST call, ro_admin role required). It misses only the direct comparison against the sibling get_cluster_health_and_services.

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