Cluster Health Report

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

With no annotations supplied, the description carries the full burden and does most of the work: it discloses the three-level status scale, that each problem appears in 'findings' with level critico/atencao/info, that monitoring blindness itself raises a warning, and that stuck commands are downgraded to 'atencao' rather than errors. It also exposes tunable thresholds and their defaults. It stops short of stating that the call is strictly read-only or noting any performance/rate considerations for a whole-cluster sweep.

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?

The purpose and coverage list are front-loaded, which is good, but the coverage sentence is a single dense run-on that stacks seven unrelated subsystems, and the trailing parameter notes are formatted as prose lines rather than a clean list. Every element is relevant, yet the block could be tightened considerably without losing information.

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-required-parameter aggregate report with an output schema available, the description supplies what an agent needs: scope, status vocabulary, the shape of findings, and threshold defaults. The two unexplained alert-limiting parameters are the only real hole, and the return format need not be described because an output schema exists.

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?

Schema description coverage is 0%, so the description must compensate and largely does: it explains cluster (default all), hours (alert window), output (json vs readable text), heartbeat_stale_seconds (max agent heartbeat age, default 120s) and stuck_command_minutes (when a command counts as stuck, default 60). Two of the seven parameters, max_alerts and latest_alerts, are left completely undefined in both schema and description. Units are given in words rather than formal types, but the meaning is unambiguous.

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 names a specific artifact — a full cluster health report with an overall status of OK/ATENCAO/CRITICO — and enumerates exactly what it inspects: non-GOOD services and failed checks, problematic roles, HA Active/Standby pairs, host disk/swap/clock-offset checks, stale agent heartbeats, Management Service blindness, windowed alerts by severity and service, pending restarts, and in-flight commands. That is far more specific than a restatement of the name. It falls short of 5 because it never distinguishes itself from the sibling cluster_health_summary, so an agent must guess which of the two to call.

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?

Usage is only implied: the breadth of coverage suggests this is the exhaustive, drill-down health call rather than a quick check, and the 'findings' level scheme hints at triage. There is no explicit statement of when to prefer this over cluster_health_summary, list_events, or list_active_commands, and no prerequisites or cost warnings. The agent must infer the selection rule from scope alone.

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