host_health_rca

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it excels. It explicitly states that hosts being installed/rebooted are 'reported as in progress, not failed', and that alert 9000 is 'informational on hosts without fencing hardware.' It also instructs to 'Report findings in rank order and quote their signal,' covering output expectations. These are non-obvious behaviors that an agent must know to interpret results correctly.

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 description is efficiently structured: a one-sentence purpose statement, a compact behavioral note, and a concise parameter list. Every sentence adds value; there is no fluff. The key purpose is front-loaded, and the parameter details are clearly separated. It is appropriately sized for the tool's complexity.

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?

The description is complete for an agent to use the tool correctly. It defines the output contract (each finding has signal, cause, action, rank), explains special cases (in-progress vs failed, informational alert), and documents all parameters. Although there is no output schema, the description provides sufficient detail on return semantics. It also mentions 'eventsOutsideWindow' implicitly, covering the window behavior. Nothing essential is missing.

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 fully compensate. It does: the 'Args' block explains each parameter with its range, default, and purpose (e.g., 'events_limit: Recent warning-or-worse events to correlate, 1-1000 (default 200)'). This adds significant semantic meaning beyond the bare schema types and defaults, making the tool safely callable.

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 clearly states the tool's purpose: 'What needs attention on KVM hosts, ranked worst first, in one call.' It names the resource (KVM hosts), the verb (needs attention), and the ranking. It distinguishes itself from sibling tools like host_list (simple listing) and host_get (single host) by emphasizing the composite, prioritized RCA output. It also stands apart from other RCA tools (engine, storage, vm) by explicitly scoping to KVM hosts.

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?

The description implies when to use this tool: when you need a consolidated health assessment of KVM hosts in one call, combining status, events, and reinstall/update flags. It does not explicitly name alternatives or exclusions, but the 'in one call' phrasing and the composite nature strongly signal it's the go-to for host-level RCA. Given the presence of sibling RCA tools, a more explicit comparison would have pushed this to 5.

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