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

The description plainly describes a write: 'Generate constitution.md' and 'Overwrites any existing constitution.md.' This directly contradicts the annotation readOnlyHint=true, which claims the tool does not modify state. This is a serious inconsistency between the description and the declared safety profile.

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?

Front-loaded with 'VDD Phase 0' and the artifact produced, and the ordering/alternative guidance is compact. The final 'Parameter relationships' sentence largely repeats the parenthetical about projectRoot, so there is minor redundancy but no real bloat.

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?

For a phase-0 initialization tool with an output schema available, the description covers purpose, overwrite behavior, ordering, and the sibling to use for changes. The one significant gap is that its stated write behavior conflicts with the readOnly annotation, leaving the agent uncertain about the tool's actual side effects.

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 description coverage is 100%, so the schema already fully documents projectRoot, its default, and path-resolution behavior. The description restates the same facts ('projectRoot sets the directory...') and adds only the cross-phase consistency note, which the schema also mentions. Baseline 3 is appropriate when the schema does the heavy lifting.

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 and resource ('Generate constitution.md at the project root') and enumerates exactly what the artifact contains (tech stack, conventions, security constraints, naming rules, banned patterns). It also distinguishes itself from siblings by naming vdd_vision (run after) and vdd_amend (for modifying). An agent can identify this tool's role immediately.

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 says when to run it ('Run this first, before vdd_vision'), when not to re-run it, and which alternative to use instead ('to change a constitution that already exists, use vdd_amend'). Both the ordering constraint and the sibling routing are stated without inference.

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