Storage hardware health

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuine substance by listing exactly what is checked (pool state, data errors, scrub age, SMART, SSD wear, bad sectors), which tells the agent what a clean result actually certifies.

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 sentence is front-loaded and the checklist and usage clause follow in a logical order. The coverage list is long but each item is a distinct diagnostic signal rather than filler.

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?

With an output schema, full annotation coverage and a single well-documented parameter, the description carries what it needs to. The only gap is not relating itself to ceph_health for non-ZFS storage, which matters in a cluster with both.

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 coverage is 100% with a single optional 'node' parameter already documented as 'Only this node. Default: all.' The description adds no scoping detail beyond the schema, so the baseline 3 applies.

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?

Names a specific verb and resource ('Check ZFS pools and physical disks') and enumerates the concrete signals it inspects. Naming ZFS implicitly separates it from the ceph_health sibling, though the description never says so outright.

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?

Gives clear triggering contexts: 'whether the storage underneath the guests is healthy' and 'before maintenance on a node.' It stops short of explicit exclusions or pointing at ceph_health for non-ZFS storage, so the agent must infer the split.

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