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

Annotations already declare readOnlyHint and idempotentHint, but the description still adds substantial beyond-annotation context: it returns a plan rather than editing artifacts, the host agent applies edits and commits, the plan names gates rather than rewritten artifacts, and it re-runs gates G1–G7. This is rich behavioral disclosure that goes well past the safety hints.

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 core purpose is front-loaded and the routing/scope constraints follow logically. It is dense and the trailing 'Parameter relationships' sentence partly restates the schema, keeping it shy of a 5, but no sentence is 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?

For a read-only planning tool with an output schema, annotations, and 100% param coverage, the description covers everything an agent needs: trigger condition, exclusion, return semantics, safety profile, and cross-phase parameter constraints. Nothing material 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 the baseline is 3. The description adds relationship semantics beyond the schema: 'description is the requirement change to cascade through the artifact chain' and 'projectRoot must match the root used by earlier phases', giving cross-phase consistency meaning not stated in the field descriptions alone.

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?

The description names a specific verb and resource (plan a requirement-change cascade through the artifact chain V→S→T→SP→PL→TK) and explains the output shape (ordered steps + affected gates). It is clearly distinguishable from phase-building siblings like vdd_vision or vdd_strategize, which is reinforced by the explicit contrast in the usage sentence.

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?

It states the trigger condition ('when a requirement changes after artifacts already exist') and the exclusion with the alternative ('to build a phase from scratch the first time, run that phase's own tool instead of vdd_amend'). Both when-to-use and when-not-to-use are explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds non-obvious behavior anyway: it scans a specific path, returns the list without editing, and the host agent applies resolutions — helpful context beyond structured data, though it omits the return shape details (covered by the output schema).

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 phase and action, then scope and routing. A bit dense with bracketed marker syntax and a trailing 'Parameter relationships' sentence that partly duplicates the schema, but nothing is genuinely wasted.

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?

With rich annotations, a full schema, and an output schema describing the returned items, the description covers purpose, sequencing, non-mutation behavior, and sibling routing. Nothing an agent needs to invoke it 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%, and the schema description for 'feature' already states it must reference a directory created by vdd_specify and be kebab-case. The description's restatement of that relationship adds little beyond the schema, so baseline 3 is appropriate.

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?

Specific verb+resource ('Clarify an existing spec'), names its phase, and states exactly what it returns: [NEEDS CLARIFICATION] markers, [e.g.] placeholders, and ACs lacking AC-E counterparts. It explicitly differentiates from the sibling vdd_specify by scope (existing vs brand-new spec).

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 ('Run after vdd_specify'), a triggering condition ('when a spec has unresolved markers'), and an exclusion with the alternative tool ('to author a brand-new spec use vdd_specify instead'). The agent is fully routed.

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

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

Annotations already flag openWorldHint and destructiveHint, and the description adds the crucial specifics: which files get written and that they are overwritten in place, plus the network/sitemap access and the refresh cache-bypass behavior. This goes beyond what the annotations state.

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 the core action and outputs, and every sentence carries information. It is dense and somewhat run-on in the parameter-relationships tail, keeping it just short of 5.

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?

With an output schema present, the description needn't detail return values, and it still names the output artifacts. For a 9-param open-world tool, all safety, side-effect, and usage context an agent needs is present.

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 schema baseline is 3, but the description adds real meaning: it clarifies that 'description' is the target domain and 'statement' is the desired outcome, and groups maxPages/timeoutMs/concurrency/crawl/browser as crawl tuning. That resolves the vague 'Freeform description input' schema text.

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 specific verbs (crawl, capture) and the exact resource/artifact produced (clone dataset + manifest with named files). It explicitly distinguishes itself from the VDD phase siblings by noting it is not part of the phase pipeline.

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 when-to-use ('Use for cloning an external site') and when-not, routing the agent to the phase tools for the normal init→validate flow. This is a direct alternative-selection rule.

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint=false, so the safety profile is covered; the description reinforces 'Read-only; returns a capability report without modifying files' and adds genuinely new behavioral detail in the normalized tool-name matching and the fixed-shape report. It stops short of describing response structure beyond that, so it lands just below the top.

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 and every clause carries information (scope, phases, read-only, alternatives, aliases, normalization). It is dense and slightly run-on as a single paragraph, but nothing is filler; a small trim would make it ideal.

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?

With an output schema present the description need not explain return values, and it still covers purpose, usage, aliasing, and parameter relationships. Nothing an agent needs in order to call 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% (baseline 3), but the description adds real value beyond the schema by stating that availableTools and capabilities are aliases and that omitting both yields per-phase requirements without a present/missing comparison. It also clarifies how to pass tool names given normalization.

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+resource (report required vs optional tools per VDD phase and present vs missing host tools) and scopes it precisely across the 8-phase pipeline plus cross-phase helpers. It explicitly distinguishes itself from the sibling vdd_inspect, so an agent can route 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 trigger conditions (before vdd_strategize, or when a phase fails for lack of a tool) and names the alternative to use instead (vdd_inspect for artifacts rather than capabilities). This is exactly the when/when-not/alternative shape that earns a top score.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, yet the description adds genuinely useful context beyond them: it never edits tasks.md, and it returns a completion marker rather than erroring when no tasks remain. It stops short of describing the return payload shape, but an output schema exists to cover that.

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 and the read-only guarantee, then usage, then parameter relationships in a compact block. It is slightly dense with phase labels and parenthetical restatements, but every sentence carries actionable information.

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 read-only lookup tool with full schema coverage and an output schema handling return values, the description covers purpose, safety, usage timing, alternatives, and the parameter hand-off to vdd_implement. Nothing an agent needs to invoke it 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning: it explains that feature is the exact spec directory name, that it must match a directory created earlier, and that the returned taskId (TASK-###) is the argument fed to vdd_implement — a cross-tool parameter relationship the schema cannot express.

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 ('Read vdd/specs/<feature>/tasks.md and return the next uncompleted task') including the exhaustion behavior (completion marker). It clearly distinguishes itself from the sibling vdd_tasks, which regenerates the full list, so an agent can pick the right tool 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 an explicit usage moment ('Use before each implementation session to keep context isolated') and names both alternatives with their selecting conditions: vdd_tasks to regenerate the list, vdd_implement to execute the returned task. 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.

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

Goes beyond annotations by clarifying the read/write division of labor: the tool itself writes nothing and the host agent performs edits, verification, and commit — important for a phase that conceptually produces code. Annotations already cover readOnlyHint/idempotentHint, so this adds useful context without being exhaustive about failure modes or output shape.

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-loads the phase/action, then behavior, then parameter relationships, with no filler. Slightly dense and repetitive in places (taskId format and provenance restated in both description and schema), but every sentence carries routing or constraint value.

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?

With an output schema present, the description needn't detail return values, and it doesn't over-promise. For a 2-parameter, fully documented, annotated read tool, all the information an agent needs to select and invoke it correctly is present.

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, but the description adds cross-tool semantics the schema cannot: taskId must come from vdd_get_next_task and projectRoot must stay consistent across phases. That is genuine added meaning beyond the field 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?

States a specific action (prepare one task for implementation) with explicit scope — loads constitution, spec, plan, contracts and returns the implementation instruction plus commit-message format. It clearly distinguishes itself from vdd_get_next_task and vdd_inspect, which it names directly.

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 when-to-use ('Run one task at a time, after vdd_get_next_task'), when-not-to-use ('for read-only inspection of tasks use vdd_get_next_task instead'), and the sequencing dependency on the sibling tool. 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.

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

The annotations already declare destructiveHint=true, but the description adds crucial specificity by stating exactly what is overwritten: any existing constitution.md. It also explains that the generated constitution is immutable and obeyed by every later phase, giving contextual behavioral insight beyond the annotation.

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 and efficient for most of its length, but the final 'Parameter relationships' sentence repeats what was already stated about projectRoot and its default, adding redundancy rather than new detail.

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 the output schema exists, the description need not explain return values. Combined with annotations and full parameter coverage, the description provides complete context for safely invoking this destructive initialization tool.

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%, and the schema already explains that projectRoot sets the directory for constitution.md and the vdd/ folder, including relative path resolution and cross-phase consistency. The description restates this and adds a 'parameter relationships' note, but provides no meaningful information beyond the schema.

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 as VDD Phase 0. It names the exact artifacts and rules the file contains, and clearly distinguishes itself from vdd_amend and vdd_vision by phase and purpose.

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 to run this first, before vdd_vision, and provides a direct alternative for changing an existing constitution: use vdd_amend instead of re-running this. No inference is required.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered; the description reinforces 'Never modifies files' and adds meaningful context that output is a structured object 'not prose'. It stops short of describing pagination or volume/rate behavior, so it adds value but isn't exhaustive beyond the annotations.

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?

Dense but front-loaded: the primary purpose and scope mechanics come first, then siblings and parameter relationships. Every sentence carries routing or behavioral information, though the single long paragraph could be broken up for faster scanning.

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 needn't be enumerated, and the description still signals the output shape. Combined with scope semantics, sibling routing, and parameter relationships, an agent has everything needed to select and invoke this tool correctly.

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?

With 100% schema coverage the baseline is 3, but the description adds genuine cross-parameter meaning: scope="feature" requires feature while scope="project" ignores it, and projectRoot must match the root used by earlier phases. This relational guidance goes beyond the per-parameter schema text.

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+resource ('Read-only inspection of the current project') and precisely what the two scope modes return (traceability matrix vs per-feature spec metrics). It explicitly names sibling tools (vdd_validate, vdd_specify) and distinguishes itself from them.

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 when-to-use routing: scope="project" (default) for the matrix, scope="feature" for metrics, plus named alternatives for adjacent tasks ('for release-readiness validation use vdd_validate, and to author a spec use vdd_specify'). 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.

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

Annotations already declare destructiveHint=true and openWorldHint=false, and the description reinforces this by stating it 'Overwrites these files' and specifying which ones, plus the required pre-existing spec. It does not cover permissions or failure modes, but for a destructive tool with existing annotation coverage this adds meaningful behavioral context.

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?

Single dense paragraph, front-loaded with the action and artifacts, then prerequisites and parameter relationships. Every sentence carries information, though the artifact enumeration makes it longer than strictly minimal.

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?

With an output schema present, return values need not be explained, and the description covers purpose, artifacts, ordering, prerequisites, and parameter continuity. Nothing an agent needs to invoke it 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 the baseline is 3, but the description adds a cross-tool constraint the schema does not: 'feature must match the value passed to vdd_specify and vdd_tasks'. That continuity rule is real value beyond the field-level definitions.

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+resource ('Generate the technical blueprint') and enumerates the exact artifacts produced (plan.md, data-model.md, contracts/) plus their location under vdd/specs/<feature>/. Its phase label ('VDD Phase 5') and artifact set clearly distinguish it from vdd_specify, vdd_tasks, and the other siblings.

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 guidance: 'run after vdd_specify or vdd_clarify and before vdd_tasks', plus a prerequisite and a fallback ('if no spec exists yet, run vdd_specify first'). It names both the predecessor and successor alternatives, leaving nothing to inference.

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

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

Annotations declare destructiveHint=true and openWorldHint=false, and the description specifies the exact consequence ('Overwrites the spec file'), naming the affected artifact. It also discloses the alternate invocation path that bypasses the V/S/T chain, adding context beyond the safety annotation.

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 the phase/purpose, then overwrite warning, then routing, then parameter relationships. Dense but every clause carries routing or constraint information; slightly lengthy, but not padded.

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 complex authoring tool with an output schema covering return values, the description supplies the missing pieces: overwrite behavior, alternate entry path, sibling disambiguation, and cross-phase parameter consistency.

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 already 100%, but the description adds cross-parameter and cross-tool meaning: 'feature ... must match the feature passed to vdd_clarify, vdd_plan, and vdd_tasks' and 'actionItemId ... is optional when authoring from a freeform description'. That consistency contract is not derivable from the schema alone.

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+resource+artifact: 'Generate vdd/specs/<id>/spec.md for one tactical action item' and enumerates the produced content (user stories, boundaries, ACs, MoSCoW, NFRs, impact verification). It also explicitly distinguishes itself from vdd_clarify, so an agent can differentiate it from siblings 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 routing: 'Use for a NEW spec; to resolve leftover [NEEDS CLARIFICATION] markers in an existing spec use vdd_clarify instead.' It also states an entry condition ('Pass actionItemId ... or a freeform description to skip the V/S/T chain'), leaving nothing to inference.

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

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

Annotations flag destructive and open-world behavior, and the description reinforces this ('Overwrites vdd/strategy.md') while adding context annotations cannot carry: the required vdd/vision.md precondition and the full two-pass dispatch-then-synthesize protocol, including the degenerate first-call case.

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 phase, artifact and overwrite behavior, then prerequisites, then the two-pass protocol. Dense but every sentence carries load; the final parameter-relationships sentence is slightly list-like but still adds alias information not in the schema.

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 multi-pass, destructive, open-world tool, the description covers phase ordering, prerequisite, overwrite target, alias handling, and the two-call protocol; with an output schema present, no return-value detail is needed. Nothing required to invoke it 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 the baseline is 3, but the description adds non-obvious semantics the schema omits: availableTools/capabilities are aliases (pass one) and researchFindings only takes effect on the second call. These are meaningful operational constraints beyond the field docs.

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 ('Produce research-backed strategy into vdd/strategy.md') plus the concrete contents (strategic pillars, competitive analysis, risk register). It also names the upstream source (vision target-domain primers) and distinguishes itself from siblings vdd_vision/vdd_tactics by phase ordering.

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 prerequisites and sequencing: 'Requires vdd/vision.md; run after vdd_vision and before vdd_tactics.' It also routes post-artifact edits to vdd_amend, which is exactly the when-not-to-use-this guidance.

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

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

Annotations only flag destructiveHint=true and openWorldHint=false; the description goes further by naming exactly what is destroyed ('Overwrites vdd/tactics.md') and what capability the host needs (filesystem access to scan the repo). It also names the required input file, giving the agent the full operational picture beyond the annotations.

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 and output artifact before prerequisites and caveats, so an agent can stop reading early if it only needs the gist. The final 'Parameter relationships' sentence is slightly long and partly restates the earlier requirement that vdd/strategy.md must exist, but the density is justified by a multi-step pipeline tool.

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?

With an output schema present, return values need no explanation, and the description covers sequencing, prerequisites, overwrite behavior, host capability, and the cross-phase projectRoot invariant. Nothing an agent needs to invoke this phase 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% with a single documented parameter, so the baseline is 3, but the description adds real cross-tool semantics: projectRoot 'must match the root used by vdd_init, vdd_vision, and vdd_strategize'. That consistency constraint is not derivable from the schema alone.

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 ('Audit the existing codebase into vdd/tactics.md') plus the concrete artifact contents (repo audit, debt assessment, gap analysis, MoSCoW items, dependency map). Phase labeling ('VDD Phase 3') and the output filename distinguish it cleanly from siblings like vdd_specify and vdd_plan.

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 routes the agent: 'run after vdd_strategize and before vdd_specify', requires vdd/strategy.md, and names vdd_detect_environment as the check to run first if the host may lack filesystem access. This covers when to use it, prerequisites, and a sibling alternative for the environment question.

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

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

Annotations declare destructiveHint=true and openWorldHint=false, and the description reinforces this with 'Overwrites tasks.md', clearly disclosing what is destroyed. It also adds the plan.md prerequisite and structural output details. It could go further on overwrite precondition (e.g., whether prior content is lost irreversibly), but the safety profile is well covered.

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 phase identity and purpose, then prerequisite, alternative, and parameter relationship. Every sentence carries distinct actionable information with no 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?

With an output schema present, return values need not be explained. Phase position, prerequisite, destructive behavior, alternative sibling, and parameter linkage are all covered, making it complete for an agent to invoke correctly.

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), and the description adds a genuine cross-tool relationship not in the schema: 'feature must match the value passed to vdd_plan'. That extra constraint meaningfully reduces invocation error beyond the parameter 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?

The description names a specific verb and artifact: 'Break the plan into atomic test-first tasks in vdd/specs/<feature>/tasks.md', with concrete output characteristics (AC/contract references, S/M/L sizing, [P] markers). It clearly distinguishes itself from siblings vdd_plan (prerequisite) and vdd_get_next_task (read alternative).

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 when-to-use ('Requires plan.md; run after vdd_plan') and an explicit alternative with condition ('To fetch the next uncompleted task from an existing tasks.md use vdd_get_next_task instead of re-running this'). Both routing decisions an agent needs are stated.

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

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

Annotations only cover idempotency, openWorld and destructiveness; the description adds the concrete write behavior (writes vdd/impact-report.generated.md) and a non-obvious safety guarantee (never overwrites a hand-authored vdd/impact-report.md). This is exactly the side-effect and overwrite context an agent needs beyond the structured hints.

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-loads the phase and scope, then the write behavior and alternatives, then a compact parameter-relationships sentence. It is dense and slightly run-on in the enumerated check list, but every sentence carries actionable information.

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?

With an output schema present, return values need not be explained, and the description covers scope, side effects, alternatives, and parameter interplay. Coverage is strong; only the traceability-matrix-vs-vdd_inspect boundary is left mildly ambiguous.

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 already 100%, so baseline would be 3; the description goes further by explaining the relationships (feature narrows the check to a single spec; artifactFiles maps path→content for serverless runs and is omitted when resolving against a local projectRoot). That adds semantic meaning about when each parameter matters.

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 (validate) plus the exact scope of the chain being validated (traceability matrix, drift, orphans, uncovered goals, impact metrics, assumption checks across 7 gates). It also names the sibling vdd_inspect to distinguish standalone traceability/metrics work, so an agent can separate it from siblings 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?

Explicitly says to run it after implementation is complete and redirects the traceability matrix / per-feature metrics case to vdd_inspect. The when-to-use and the alternative are both present, though the line listing 'bidirectional traceability matrix' as part of validate while also routing 'the traceability matrix' to vdd_inspect slightly muddies the boundary.

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

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

Annotations declare destructiveHint=true, and the description confirms and localizes the destruction ('Overwrites any existing vdd/vision.md'), which is exactly the kind of added context that matters. It also discloses the prerequisite state (a prior vdd_init) that annotations cannot express. It stops short of describing the write's atomicity or failure behavior, hence not a 5.

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 and artifact path, then prerequisites, then alternative routing, then parameter notes. Dense but every clause carries information; the parameter-relationship sentence is slightly redundant with the earlier 'freeform 1-3 paragraph intent' phrase.

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 no explanation, and the description covers the remaining unknowns an agent needs: overwrite semantics, ordering constraints, prerequisite phase, and revision via vdd_amend. Nothing material is missing for correct invocation.

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 already 100%, but the description still adds value beyond the schema by constraining statement to 'freeform 1-3 paragraph intent, not a title' and by requiring projectRoot to match the value used by vdd_init. These are non-obvious usage constraints rather than restatements.

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 ('Expand a freeform vision statement into vdd/vision.md') and enumerates the sections produced, so the agent knows exactly what artifact is created. The sibling set is large, and this description clearly distinguishes the vision-expansion phase from vdd_strategize, vdd_amend, and vdd_init.

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 sequencing ('Run once, after vdd_init and before vdd_strategize') plus an explicit alternative and its condition ('to revise a vision once downstream artifacts exist, use vdd_amend so the change cascades'). This is a textbook when-to-use/when-not-to-use statement.

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