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

The description states the tool writes vdd/vision.md and 'Overwrites any existing vdd/vision.md' — an environment-mutating, destructive write. The annotations declare readOnlyHint=true, which asserts the tool does not modify its environment. That is a direct contradiction, so transparency is scored 1 regardless of the otherwise useful prerequisite and overwrite disclosure.

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 purpose, then ordering, then parameter notes — a sensible priority order. The closing 'Parameter relationships' sentence repeats the freeform/not-a-title point already made earlier, a minor redundancy in an otherwise dense and earned description.

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 not be described. Prerequisites (vdd_init), ordering, overwrite behavior, and the revision alternative are all present; nothing needed to invoke this correctly is missing.

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 baseline is 3, and the description genuinely adds meaning: 'statement must be freeform prose (1-3 paragraphs), not a title' constrains a parameter the schema only calls 'Freeform vision statement'. The projectRoot consistency requirement largely restates the schema, so it is additive but not fully novel.

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 artifact ('Expand a freeform vision statement into vdd/vision.md') and enumerates the exact sections produced. It also names the siblings it is not (vdd_init, vdd_strategize, vdd_amend), so an agent can separate it from the rest of the vdd_* family without opening schemas.

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?

Explicit ordering ('Run once, after vdd_init and before vdd_strategize') plus a named alternative with its selecting condition ('to revise a vision once downstream artifacts exist, use vdd_amend so the change cascades instead of re-running this'). This is close to an ideal when/when-not pair.

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