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

Annotations carry destructiveHint=true, and the description elaborates on exactly what gets destroyed ('Overwrites any existing vdd/vision.md'), which is meaningful context beyond the bare flag. It also adds run-once semantics and the cascade limitation with vdd_amend. No contradiction with annotations; it just doesn't describe failure behavior if prerequisites are unmet.

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?

Three dense sentences, each carrying distinct information: what it produces, its requirements, and when to run it versus the alternative. Front-loaded with the verb and deliverable before caveats, with zero 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?

Covers the deliverable path, produced sections, prerequisites (prior vdd_init), phase ordering, revision routing, and input constraints — complete for a file-writing phase tool with no output schema. Minor gaps: no error behavior if vdd_init was skipped and no steering away from irrelevant shared schema parameters.

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%, so the baseline is 3; the description adds real value by pinning down the statement format ('freeform 1-3 paragraph intent, not a title') and making it effectively required despite the schema marking all params optional. However, it does not clarify which of the 10 shared schema params (e.g., taskId, researchFindings, capabilities) are irrelevant for this tool.

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?

States a specific verb (Expand) and resource (freeform vision statement → vdd/vision.md), then enumerates the exact artifact sections produced: Impact Model, Stakeholder Map, Success Metrics, Constraints & Boundaries, Target Domains. Explicitly distinguishes itself from vdd_amend, so an agent can tell them apart without opening either schema.

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 explicit sequencing: 'after vdd_init and before vdd_strategize,' plus the 'Run once' rule. Names the alternative outright — 'use vdd_amend so the change cascades instead of re-running this' — with the condition (downstream artifacts exist) that selects it. Nothing is left to inference.

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