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

Annotations declare readOnlyHint/idempotent/openWorld=false, but the description adds non-obvious behavior: it returns a cascade plan "without editing artifacts" and the host agent applies edits and commits. It also discloses that downstream gates must be re-run, which no annotation conveys.

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 purpose, scope, and behavioral note before the when-to-use and parameter notes; no filler sentences. It is dense and a touch long with the trailing parameter-relationships clause, but every sentence carries routing or behavior 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-value detail is unnecessary, and the description still covers the operation, its read-only nature, who performs the writes, when to use it vs. alternatives, and parameter constraints. Nothing needed 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 baseline is 3, but the description adds a real constraint beyond the schema: projectRoot "must match the root used by earlier phases." It also clarifies that description is the change payload to cascade, not an artifact description.

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 ("Plan a requirement-change cascade") and enumerates the affected artifact chain V→S→T→SP→PL→TK and gates G1–G7. It is immediately distinguishable from sibling phase tools like vdd_vision or vdd_specify, which build individual phases rather than cascade a change.

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 triggering condition ("when a requirement changes after artifacts already exist") and an explicit exclusion with the correct alternative ("to build a phase from scratch the first time, run that phase's own tool instead of vdd_amend"). The agent has no inference to make about routing.

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 safety is covered structurally. The description adds real value beyond that: it discloses that the file is not edited and that resolution is delegated to the host agent, which is a non-obvious division of labor the agent must know for the workflow to function.

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 verb, then what it returns, then usage and the parameter constraint. Every sentence carries information, though the dense marker/placeholder/AC enumeration makes it slightly heavy for a tool with only one meaningful parameter.

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-value explanation is not required, yet the description still names the three categories of findings, and it covers read-only behavior, the host-agent handoff, sequencing versus vdd_specify, and the feature parameter's origin. Nothing needed 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. The description goes further by specifying that 'feature' must be the exact spec directory name created by vdd_specify, tying the parameter to a provenance constraint that the schema text ('Feature name (spec directory name)') does not convey.

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 ('Clarify an existing spec') and enumerates exactly what the scan returns: [NEEDS CLARIFICATION] markers, [e.g.] placeholders, and ACs lacking an AC-E counterpart. It explicitly distinguishes itself from the sibling it is most likely to be confused with, vdd_specify.

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 after vdd_specify when a spec has unresolved markers') and when-not ('to author a brand-new spec use vdd_specify instead'). The alternative tool is named and the selecting condition is stated, 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 cover openWorldHint and destructiveHint, and the description adds real context beyond them: it names the exact files written, discloses that network requests hit the target site, and explains the cache-bypass behavior of refresh. It stops short of noting that writes may overwrite existing artifacts, which would be the natural complement to destructiveHint=true.

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 information-dense, but the closing 'Parameter relationships' sentence largely restates the earlier 'Pass the domain as description; tune maxPages…' sentence, duplicating parameter guidance rather than adding anything. Some trimming would sharpen 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?

An output schema exists, so return values needn't be spelled out, and the description still names the emitted files. For a zero-required-param, open-world destructive tool it covers invocation adequately; the only soft spot is not framing the destructive/overwrite implication of writing into vdd/.

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 meaning the schema lacks: it clarifies that description is the target domain (schema only says 'Freeform description input') and that statement is the desired outcome, plus groups the crawl-tuning knobs. This resolves genuine ambiguity the schema leaves open.

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 (crawl and capture a target domain into a clone dataset + manifest) and immediately names the deliverables (vdd/clone-dataset.json, clone-manifest.json, clone.md). It explicitly distinguishes itself from siblings by stating it is not part of the VDD 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 ('for the normal init→validate flow call those phase tools instead'), naming the alternative tool family. Nothing about tool selection 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 readOnlyHint/idempotentHint, so the 'read-only, no file modification' line is somewhat redundant. The description does add non-annotation context: what the report contains (per-phase required vs optional tools, present vs missing) and what changes when availableTools is omitted. It stops short of describing format or scope limits, so 4 rather than 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?

The core purpose and usage are well front-loaded, but the alias/omission behavior is stated twice in near-identical language ('Parameter relationships: availableTools and capabilities are aliases; omit both to get the per-phase requirements without a present/missing comparison'). That duplication wastes space without adding 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?

An output schema exists, so return values need no further explanation, and the description still covers purpose, trigger conditions, the alternative tool, and all three parameters' behavior. Nothing an agent needs to call 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. The description goes beyond the schema by spelling out the alias relationship and the behavioral consequence of omitting both params (requirements returned without the present/missing comparison), which the schema does not state.

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?

Names a specific verb+resource (report per-phase tool/MCP requirements vs optional, plus present/missing host tools) and scopes it to the 8-phase pipeline and cross-phase helpers. It explicitly distinguishes itself from vdd_inspect, so an agent can route correctly without opening a 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?

States exactly when to call it (before vdd_strategize to plan subagent dispatch, or when a phase fails for lack of a tool) and where to go instead for artifacts (vdd_inspect). Both the trigger and the alternative 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 readOnly, idempotent and closed-world, but the description adds useful behavioral context: it reads (not edits) tasks.md, and returns a completion marker when no tasks remain. It does not mention pagination or failure modes, but for a simple read tool this is close to complete.

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 the read behavior, then routes to siblings and explains the parameter relationship. Dense but each sentence earns its place; the run-on 'Parameter relationships' clause could be tightened.

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 documented, yet the description still flags the completion-marker case. The read-only/idempotent profile, sibling routing and the taskId hand-off to vdd_implement cover everything an agent needs to call it 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%, so the schema already documents feature and projectRoot, but the description adds cross-tool semantics the schema lacks: feature must match the spec directory name exactly, and the returned taskId (TASK-###) is the argument fed to vdd_implement.

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 tasks.md, return next uncompleted task) and explicitly distinguishes itself from siblings vdd_tasks (regenerate list) and vdd_implement (execute task). An agent can select it without opening any 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 the when ('use before each implementation session to keep context isolated') plus two named alternatives with their selecting conditions. 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 readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond them: the tool itself writes nothing and the host agent performs the code edits, verification and commit — resolving the natural 'implement = write' misconception. It stops short of describing failure modes or what happens if the task id is stale.

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 scope, then sequencing, then parameter relationships. Tight and information-dense, though the 'writes nothing' point is restated in slightly different form ('Read-only; the tool writes nothing') and the parenthetical example duplicates the schema example.

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-value detail is unnecessary, and the description still summarizes what is returned. For a two-parameter, single-task tool with sequencing rules and parameter provenance covered, 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 real semantic value: taskId must come from vdd_get_next_task and follow the TASK-### format, and projectRoot must match the root used by earlier phases. That provenance/coupling 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 (prepare one task for implementation), names the phase (VDD Phase 7b), and describes the payload (loads constitution, spec, plan, contracts; returns the implementation instruction plus impact-chain commit-message format). It explicitly distinguishes itself from the closest sibling, vdd_get_next_task.

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 one task at a time, after vdd_get_next_task') and an explicit exclusion with the alternative named ('for read-only inspection of tasks use vdd_get_next_task instead'). The agent knows when to pick this tool and when not to.

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; the description confirms and enriches this by naming exactly what is destroyed ('Overwrites any existing constitution.md') and the immutability contract every later phase obeys. It also discloses the cross-phase root-resolution coupling that annotations cannot express.

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, and overwrite warning, then ordering, then parameter notes. Slightly redundant in restating projectRoot's default and consistency twice across the body and the 'Parameter relationships' sentence, but no sentence is 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 an output schema present, return values need no explanation, and annotations cover the safety profile. The description supplies the remaining essentials: phase ordering, alternative tool, destructive overwrite, and cross-phase param coupling.

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 projectRoot definition is already documented; the description adds meaning beyond it by explaining that the root must remain consistent across all later phases and that all vdd/ artifacts resolve against it. The added value is real but the schema already carries the basic semantics.

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 constitution.md at the project root') and enumerates its content (tech stack, conventions, security constraints, naming rules, banned patterns). Clearly distinguished from siblings vdd_vision (runs after) and vdd_amend (used for changes).

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 this first, before vdd_vision') and an explicit when-not with the named alternative ('to change a constitution that already exists, use vdd_amend instead of re-running this'). 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 readOnlyHint and idempotentHint, so 'Never modifies files' is largely redundant, but the description adds real value by disclosing what each scope returns (traceability matrix vs per-feature metrics) and the cross-phase coupling via projectRoot. No mention of performance or auth, 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 the core purpose and scope semantics, and every clause carries routing information. It slightly over-repeats the scope routing by restating 'Choose vdd_inspect for the traceability matrix or per-feature metrics' after already contrasting with vdd_validate.

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 explained, and the description covers scope selection, parameter coupling, and sibling alternatives. Nothing required to invoke the tool 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 goes beyond it: it encodes the dependency that scope="feature" requires feature while project scope ignores it, and that projectRoot must match the root used by earlier phases. These relationships are not expressible in 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 ('Read-only inspection of the current project') and immediately distinguishes itself from siblings by naming vdd_validate and vdd_specify. The two scopes are enumerated with concrete outputs, so an agent knows exactly what it will get.

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: 'for release-readiness validation with gates use vdd_validate, and to author a spec use vdd_specify.' It also states which scope to choose and when, 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 already flag destructiveHint=true and openWorldHint=false; the description adds specifics by naming exactly which files are overwritten and stating the hard prerequisite of an existing spec. This goes beyond the annotations, though it still doesn't describe failure modes or partial-write behavior on a missing spec.

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 artifact list, then prerequisites, then parameter constraints. Dense but every sentence earns its place; slightly long artifact enumeration but justified since it defines the tool's output footprint.

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 destructive, multi-file generator with an output schema, the description covers output footprint, ordering prerequisites, overwrite behavior, and the feature-name coupling. 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 baseline is 3, but the description adds a cross-tool constraint not present in the schema: 'feature must match the value passed to vdd_specify and vdd_tasks'. That value-coupling meaning is genuinely useful and 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 (generate the technical blueprint) and enumerates the concrete artifacts written (plan.md, data-model.md, contracts/). Positions itself as Phase 5 in a named workflow, so it is clearly distinct from vdd_specify, vdd_tasks, and 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: 'run after vdd_specify or vdd_clarify and before vdd_tasks', plus a fallback ('if no spec exists yet, run vdd_specify first'). Both when-to-use and the prerequisite are stated outright, nothing 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 declare destructiveHint=true and openWorldHint=false; the description reinforces this with 'Overwrites the spec file,' which is the key risk an agent needs. It also discloses the dependency that feature must match the value used in vdd_clarify/vdd_plan/vdd_tasks, adding context beyond 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 phase, output path, and overwrite warning come first, followed by alternatives and parameter relationships. Every clause carries information, though the parameter-relationship sentence is somewhat packed and could be split.

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. The description covers phase purpose, destination file, destructive behavior, sibling alternative, and cross-tool parameter constraints — everything needed 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 description coverage is 100%, so the baseline is 3, but the description adds real meaning: feature names the vdd/specs/<feature>/ directory and must match the other VDD phases, and actionItemId is the A-### id sourced from tactics.md and optional when a freeform description is supplied.

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 — generates vdd/specs/<id>/spec.md for one tactical action item — and enumerates the artifacts produced (user stories, boundaries, AC, MoSCoW, NFRs, impact verification). It clearly distinguishes itself from vdd_clarify, so an agent can pick it 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?

Explicitly routes: 'Use for a NEW spec; to resolve leftover [NEEDS CLARIFICATION] markers in an existing spec use vdd_clarify instead.' It also states when to pass actionItemId versus a freeform description (to skip the V/S/T chain), which is actionable when-to-use 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 declare destructiveHint=true and openWorldHint=true; the description backs this up with concrete detail — 'Overwrites vdd/strategy.md' — plus the required input file and the non-obvious two-pass dispatch/synthesis protocol. This is behavioral context beyond what annotations and schema give.

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 purpose and dependency info is well front-loaded, but the two-pass behavior is stated twice — once in the 'Two-pass' sentence and again in 'Parameter relationships' — which is genuine redundancy in an already dense 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?

For a multi-phase, two-pass tool with an output schema present (so return values needn't be explained), the description covers purpose, prerequisites, ordering, destructive behavior, the sibling alternative, and the call protocol. 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. The description rises above it by explaining how the parameters interact as a protocol: pass availableTools on the first call to obtain dispatch specs, then re-call with researchFindings to synthesize, and that availableTools/capabilities are aliases. This adds flow semantics the schema alone doesn't convey.

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 ('Produce research-backed strategy into vdd/strategy.md') and enumerates the concrete deliverables (strategic pillars, competitive analysis, risk register). It situates itself as 'VDD Phase 2', which cleanly distinguishes it from the other vdd_* 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 constraints ('run after vdd_vision and before vdd_tactics'), a stated prerequisite ('Requires vdd/vision.md'), and an explicit alternative for a different intent ('To change strategy after artifacts exist, use vdd_amend'). When-to-use and when-not-to-use are both covered.

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; the description corroborates and enriches this by naming the destroyed target ('Overwrites vdd/tactics.md') and adding prerequisites (strategy.md must exist) and a host-capability constraint (filesystem access needed to scan the repo). This goes well beyond what the annotations convey.

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 overwrite warning, prerequisites, ordering, and parameter notes in a logical sequence. Slightly redundant — the strategy.md dependency is stated twice ('Requires vdd/strategy.md' and again at the end), and the density of clauses makes it feel like a run-on, but little is 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?

An output schema exists, so return values need no explanation, and the description covers everything else an agent needs: ordering, prerequisites, destructive overwrite, host capability, and parameter consistency with sibling phases. Nothing material is missing for a single-parameter pipeline step.

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 one parameter at 100% schema coverage, the schema already carries the baseline. The description adds cross-tool consistency semantics not present in the schema: projectRoot must match the root used by vdd_init, vdd_vision, and vdd_strategize, which is genuinely useful to avoid mismatched-root failures.

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?

Names a specific verb and resource ('Audit the existing codebase into vdd/tactics.md') and enumerates the concrete artifacts produced (repo audit, debt assessment, gap analysis, MoSCoW items, dependency map, infra requirements). The 'VDD Phase 3' label plus the ordering notes make it unambiguous against siblings like vdd_strategize and vdd_specify.

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 states sequencing ('run after vdd_strategize and before vdd_specify'), a hard prerequisite ('Requires vdd/strategy.md'), and a conditional gate ('check with vdd_detect_environment first if the host may lack one'). This is exactly the when-to-use / when-not-to-use guidance the dimension asks for.

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 usefully spells out the consequence ('Overwrites tasks.md') plus the plan.md dependency. It does not add much else about failure modes or partial overwrite behavior, but for an annotated tool this meaningfully enriches the safety picture rather than contradicting it.

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: purpose first, then artifact/format, then the destructive warning, then prerequisites, then the sibling alternative. Slightly packed with pipe-separated clauses, but no sentence is 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 an output schema present, return values need no explanation, and the annotations plus description together cover safety, prerequisites, artifact location, and the alternative tool. An agent has everything needed to invoke it 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%, so the baseline is 3, but the description adds a real cross-tool constraint: 'feature must match the value passed to vdd_plan,' which is not derivable from the schema alone and prevents a mismatched-run error.

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 (break the plan into tasks), the exact artifact produced (vdd/specs/<feature>/tasks.md), and its position in the VDD pipeline (Phase 6). It is trivially distinguishable from siblings such as vdd_plan and vdd_get_next_task.

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 ('Requires plan.md; run after vdd_plan') and an explicit exclusion routing to the alternative ('To fetch the next uncompleted task ... use vdd_get_next_task instead of re-running this'). When-to-use and when-not-to-use are both covered.

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 cover safety (idempotentHint, destructiveHint=false, closed world), and the description goes well beyond them by disclosing side effects: it writes vdd/impact-report.generated.md and guarantees it never overwrites a hand-authored vdd/impact-report.md. It also explains the serverless vs. local execution mode difference, which no annotation conveys.

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 and check inventory, which is good, but the artifactFiles/projectRoot relationship is explained twice (once inline, once again under 'Parameter relationships'), making the last third redundant. The sentence about which tool to choose also repeats the routing advice already given earlier.

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, and the description still covers scope, timing, side effects, execution modes, and parameter interaction. For a no-required-parameter validation tool with nested artifactFiles, nothing needed for correct invocation 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 genuine relational semantics: feature narrows the check to a single spec, and artifactFiles is omitted when resolving against a local projectRoot. This disambiguates when each optional parameter is needed rather than just restating 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 ('Validate the full chain') and enumerates the exact artifacts produced: bidirectional traceability matrix, drift detection, orphan detection, uncovered vision goals, impact metrics, and 28 S&T assumption checks. It explicitly distinguishes itself from vdd_inspect, so an agent can select it without opening the 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 timing prerequisite ('Run after implementation is complete') and names the alternative with the selecting condition ('for a lightweight per-feature consistency check or the project-wide matrix use vdd_inspect'). The closing sentence reinforces the routing decision: vdd_validate for the release-readiness gate report.

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 spelling out 'Overwrites any existing vdd/vision.md' plus the vdd_init prerequisite and the one-time ordering constraint. This adds genuine behavioral context (idempotency posture, dependency chain) beyond the annotations, though the overwrite disclosure partly overlaps destructiveHint.

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?

Well front-loaded with the phase and output artifact first, then prerequisites, then ordering, then parameter notes. Dense but each sentence carries routing or constraint value; the statement requirement is stated twice (once in the main body, once in the parameter-relationships line), a minor redundancy.

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-1 artifact generator with an output schema already present, the description covers everything an agent needs: what is produced, the overwrite behavior, the prerequisite chain, the ordering relative to siblings, and the fallback tool for revisions.

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 real meaning beyond the schema: statement must be 'freeform prose (1-3 paragraphs), not a title' and projectRoot 'must match the root used by vdd_init'. It goes beyond restating the field descriptions, which only say 'Freeform vision statement' and 'Project root'.

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 states a specific verb (Expand) and resource (freeform vision statement into vdd/vision.md) and enumerates the exact sections produced, so the agent knows precisely what this tool creates. It also differentiates itself from sibling vdd_amend by naming it as the alternative for revisions.

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 gives explicit ordering ('Run once, after vdd_init and before vdd_strategize'), a clear when-not ('to revise a vision once downstream artifacts exist, use vdd_amend so the change cascades instead of re-running this'), and prerequisites ('a prior vdd_init'). Nothing about routing 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.