pve_ceph_osd_metadata

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

With no annotations, the description carries the full burden. It explicitly marks the tool as READ-ONLY, describes the adversarial aspect of the osd{} sub-object, and notes that the shape is not live-verified. This provides essential behavioral context beyond input schema and enables informed agent decisions.

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 composed of two paragraphs that front-load critical info (READ-ONLY, per-OSD details) and then provide important caveats (adversarial, smoke-confirm). While slightly dense, it avoids unnecessary repetition and earns its length with meaningful content. A minor trim could improve conciseness, but it's well-structured.

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?

An output schema exists, so return values need no explanation. The description covers purpose, behavioral safety (read-only), adversarial trust concerns, and endpoint information. It even includes a caution about shape verification. Given the tool's moderate complexity and absence of annotations, this description provides comprehensive context for agent decision-making.

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% for 3 parameters, so the baseline is 3. The description adds no substantive meaning beyond what the schema already describes for parameters (e.g., 'per-OSD details' implies the osdid parameter, but schema already defines it). It does not elaborate on the role of node or proximo_target beyond schema text. Hence, sufficient but not additive.

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 it's a READ-ONLY tool for per-OSD details, listing the returned structures (devices[] and osd{} identity/address block). It distinguishes itself from sibling pve_ceph_metadata by calling it a 'single-OSD drill-down'. This meets the highest standard of purpose clarity.

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 warns about the adversarial nature of the data (self-reported identity fields) and advises caution with 'Smoke-confirm: shape not live-verified'. It implies use when detailed per-OSD info is needed and you accept potential data staleness. However, it does not explicitly state when to use this tool versus alternatives like pve_ceph_osd_tree or pve_ceph_metadata, missing a clear when-not-to.

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