pve_node_disks_list

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

No annotations are provided, so the description carries the full burden. It declares the tool as READ-ONLY, indicating a non-destructive operation. It also describes the return format as a list of dicts with specific keys (devpath/health/size/model/serial/used), which adds transparency beyond the schema.

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 extremely concise with three sentences: purpose and safety, verification and return info, and sibling reference. It is front-loaded and contains no extraneous 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?

Given the presence of an output schema, the description does not need to explain return values, but it still lists the keys. It references a relevant sibling. Minor gaps: no mention of error conditions or prerequisites, but for a read-only list tool, this is sufficient.

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?

The input schema has 100% description coverage for both parameters (node and proximo_target). The description adds no additional meaning beyond what is in the schema, so a baseline score of 3 is appropriate.

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 starts with 'READ-ONLY: list physical disks on a PVE node', clearly stating the action (list), resource (physical disks), and scope (on a PVE node). It distinguishes from the sibling tool pve_node_disk_smart, which provides SMART details for a single disk.

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 explicitly references the sibling tool pve_node_disk_smart for SMART details, guiding when to use an alternative. It also mentions being 'VERIFIED live (PVE 9.2)', which adds trust. However, it does not explicitly state when not to use this tool or mention prerequisites like node existence.

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