pve_sdn_dry_run

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

No annotations provided, so description carries full burden. It clearly states it is READ-ONLY, describes the behavior as showing rendered diff, and explains the per-node vs cluster-scope nuance. No contradictions.

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?

Two sentences, front-loaded with key purpose, second sentence adds critical nuance. No wasted words. Highly efficient.

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 output schema exists (so return values not needed), this description is complete. It covers purpose, readonly nature, what diff includes, and per-node behavior. No missing critical context.

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% (baseline 3). Description adds value by explaining that node is required by PVE even though schema marks it optional, and why the result is per-node. This goes beyond schema descriptions.

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?

Description clearly states it is a read-only preview that shows the diff between current and pending SDN configuration, specifically comparing to pve_sdn_apply. This distinguishes it from sibling tools like pve_sdn_apply and pve_sdn_rollback.

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?

Implicitly suggests usage before pve_sdn_apply to preview changes, but lacks explicit when-to-use or when-not-to-use guidance. Sibling tools include pve_sdn_apply and pve_sdn_rollback, so additional direction would be beneficial.

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