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

Annotations include destructiveHint=true, and the description explicitly confirms 'Overwrites these files,' naming exactly which files can be destroyed. It also discloses the precondition that a spec must already exist, adding useful behavioral context beyond the annotation flag.

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 a single dense sentence with all relevant content front-loaded around 'Generate the technical blueprint.' The parenthetical list is efficient, but the sentence is long enough that slightly better scannability could be achieved by splitting it.

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?

The description captures purpose, artifacts, overwrite behavior, and workflow ordering, which is strong for a destructive write tool with no output schema. It does not map the 10 input parameters into the workflow, though the schema descriptions cover their individual meanings, so it remains 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 covers 100% of parameters with descriptions, so the description does not need to restate parameter meanings. It does not add much parameter-level detail beyond the schema; the only implicit link is feature mapped to the vdd/specs/<feature>/ path.

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?

Clearly states 'Generate the technical blueprint' with exact target files (plan.md, data-model.md, contracts/). The 'VDD Phase 5' qualifier and file list distinguish it from vdd_specify (spec creation) and vdd_tasks (task breakdown).

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?

Explicitly gives workflow position: run after vdd_specify or vdd_clarify and before vdd_tasks. It also names a prerequisite and fallback: requires an existing spec; otherwise run vdd_specify first. This is direct when-to-use and when-not-to-use guidance.

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