cat_nodes

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

Annotations already cover safety with readOnlyHint=true and destructiveHint=false, so the description only needs to add non-obvious context. It adds the list of exposed fields and the intended diagnostic uses. It does not disclose additional behavioral details such as how results are sorted, whether the response is sampled, or any default node filtering—though output schema may cover return format. It is adequate, not exceptional.

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?

Two sentences with no filler. The first sentence states what the tool returns; the second states why it is useful. Every phrase earns its place, and the description is front-loaded with the list operation.

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 zero-parameter read-only listing tool with an output schema present, the definition is largely complete. It covers the result content and the motivating scenarios. A small gap is the lack of explicit disambiguation from the overlapping sibling cluster_info or cluster_health, but that is minor relative to the complexity of this tool.

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?

This tool takes zero parameters, so there is nothing to clarify. Per the rubric, a 0-parameter tool earns a baseline of 4. The description appropriately spends no words on input semantics.

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 uses a specific verb and resource: 'List cluster nodes' and enumerates the exact attributes returned (role, version, heap/RAM/CPU/load, master flag). This clearly separates it from sibling tools like cluster_health or cluster_info, which operate at cluster level rather than node level.

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?

It provides explicit use cases: 'spot a hot node, a version mismatch across nodes, or which node is master.' This is actionable guidance. It does not explicitly name alternative tools or exclusion criteria, but the scenarios are specific enough to guide selection.

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