Vision Driven Design (VDD) MCP Server

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 non-derivable context: it does not edit artifacts, it returns a plan and the host agent applies edits and commits, and the return is an ordered step list naming gates rather than rewritten artifacts. It stops short of describing failure modes or partial-plan behavior, so 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, then output semantics, then usage routing, then parameter relationships. Dense but every clause carries information; the only mild redundancy is restating the read-only/plan-only nature twice, which is defensible given it is the key behavioral trait.

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 enumerate return fields, and it appropriately summarizes the return shape (ordered step list naming gates). Combined with annotations covering safety and idempotency and 100% schema coverage, nothing an agent needs to call this 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 parameter descriptions already carry the load (baseline 3). The description still adds relational meaning the schema does not: 'description is the requirement change to cascade' and 'projectRoot must match the root used by earlier phases', which is a cross-phase constraint not captured per-field.

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 through the whole chain'), names the concrete output (ordered steps V→S→T→SP→PL→TK and affected gates G1–G7), and explicitly contrasts with the sibling pattern of running a phase's own tool. An agent can identify this tool 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 an explicit trigger ('Use when a requirement changes after artifacts already exist') and an explicit exclusion with the alternative ('to build a phase from scratch the first time, run that phase's own tool instead of vdd_amend'). This is textbook when/when-not 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 cover readOnlyHint, idempotentHint, and openWorldHint, providing safety and idempotency. The description adds useful context: it returns the list without editing the file, and the host agent applies resolutions. It doesn't mention rate limits or auth, but for a read-only local file scan those are less critical. The added clarification about the host workflow goes 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?

Concise single paragraph with all key information front-loaded: phase, action, return items, behavior, usage guidance, and parameter relationship. Every sentence earns its place with no 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?

Complete for a read-only tool with a defined output schema. The description covers purpose, when-to-use, behavior, and parameter relationships. Since an output schema exists, it needn't detail return format. Nothing an agent needs 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 schema already documents both parameters thoroughly, including examples and constraints. The description adds a parameter relationship note ('feature must be the exact spec directory name created by vdd_specify'), which is useful but reiterates what the schema implies. Baseline 3 is appropriate when schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'Clarify an existing spec' and details exactly what it scans (vdd/specs/<feature>/spec.md) and what it returns (NEEDS CLARIFICATION markers, placeholders, ACs needing edge cases). Distinguishes itself from sibling vdd_specify by naming it and stating the opposite use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use ('Run after vdd_specify when a spec has unresolved markers') and when not to ('to author a brand-new spec use vdd_specify instead'). Also implies the host agent applies resolutions afterward.

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=true and destructiveHint=true; the description goes further by naming the exact files written and that they are 'overwriting any existing versions in place' (matching destructiveHint), plus the open-world behaviors: network requests to the target site, sitemap reads, and same-origin link following, and the cached-dataset/refresh behavior. Nothing contradicts 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-loads the core action and artifacts before the constraints, and each sentence carries information (outputs, write semantics, open-world behavior, routing, parameter relationships). It is dense but not padded, with only mild redundancy in the trailing parameter summary.

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 9-parameter, destructive, open-world tool with an output schema, the description covers what an agent needs: writes and overwrites, network access, cache bypass, local-vs-hosted parameter applicability is handled in schema, and parameter relationships are summarized. Return values are covered by the output schema.

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 would be 3; however the description adds genuine meaning by clarifying that 'description is the target domain and statement is the desired outcome (both optional)' — the schema only says 'Freeform description input' for description, so this is real added value — and that refresh=true bypasses a cached dataset.

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 concrete verb and resource ('Crawl and capture a target domain into a clone dataset + manifest') and names the artifacts produced (vdd/clone-dataset.json, vdd/clone-manifest.json, vdd/clone.md). It explicitly distinguishes itself from the vdd_* siblings by declaring 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 both positive and negative routing: 'Use for cloning an external site; it is not part of the VDD phase pipeline, so for the normal init→validate flow call those phase tools instead.' The alternative (phase tools) and the condition selecting it are stated outright.

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 a closed-world scope; the description adds real context on top: 'read-only; returns a capability report without modifying files', fixed-shape output, and normalized tool-name matching so the caller knows exact-string matching is not required. It does not cover failure modes or matching edge cases, keeping it short of 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?

Purpose and scope are front-loaded, and every sentence carries information (scope, safety, routing, output shape, parameter relationships). It is dense and somewhat long, but no sentence is filler; minor tightening could improve 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?

With an output schema present, the description needn't detail return values, and it still notes the report is fixed-shape. Scope, safety, routing, and parameter aliasing are all covered, so 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 would be 3, but the description adds meaning beyond the schema: it discloses that availableTools and capabilities are aliases and that omitting both yields per-phase requirements without a present/missing comparison. That omit-both behavior 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: reports which tools/MCPs each VDD phase requires vs treats as optional across the 8-phase pipeline and cross-phase helpers. It explicitly distinguishes itself from the sibling vdd_inspect ('to inspect artifacts instead of capabilities use 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 when-to-use conditions ('run before vdd_strategize to plan research-subagent dispatch, or when a phase fails for lack of a tool') and names the alternative tool with the condition that selects it (vdd_inspect for artifacts). Exclusions and alternatives 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 already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description still adds value beyond them: it reinforces 'never edits tasks.md' and discloses the completion-marker return behavior when no tasks remain. It stops short of describing pagination or ordering of tasks, keeping it at a 4.

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 tag and the core action, then constraints, then routing to siblings. Dense and mostly earned, though the closing 'Parameter relationships' sentence is slightly redundant with material already stated inline.

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. The description covers purpose, safety, usage timing, sibling routing, and parameter linkage — everything an agent needs to call it correctly in this multi-phase workflow.

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. The description goes further by documenting cross-tool parameter relationships: 'feature must match the spec directory' and 'the returned taskId (TASK-###) is the argument to vdd_implement', 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?

States a specific verb and resource ('Read vdd/specs/<feature>/tasks.md and return the next uncompleted task'), including the edge case of a completion marker. It names sibling tools (vdd_tasks, vdd_implement) so an agent can distinguish it from near-neighbors 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?

Explicitly says when to use it ('before each implementation session to keep context isolated') and names the 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered and the description stays consistent with it ('Read-only; the tool writes nothing'). It goes beyond the annotations by clarifying the division of labor — the host agent performs code edits, verification, and commit — and by naming the artifacts loaded and returned, which is genuinely useful 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?

Front-loads the phase, action, and read-only nature, then covers sequencing and parameter relationships with no filler sentences. Slightly dense in the final parameter-relationships clause, but every sentence carries 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?

Output schema exists, so return-value documentation is not required, yet the description still names what comes back. Combined with sequencing, the alternative tool, and parameter provenance, an agent has everything needed to invoke it correctly in the workflow.

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 provenance for taskId ('from the task returned by vdd_get_next_task', format TASK-###) and a constraint for projectRoot ('must match the root used by earlier phases'). That is real meaning beyond the schema's own 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 and resource ('Prepare one task for implementation') and enumerates exactly what it loads (constitution, spec, plan, contracts) and returns (implementation instruction plus impact-chain commit-message format). It is clearly distinguishable from siblings like vdd_get_next_task and vdd_inspect.

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 one task at a time, after vdd_get_next_task') and an explicit exclusion ('for read-only inspection of tasks use vdd_get_next_task instead'). Nothing about when to reach for this tool versus an alternative 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 declare destructiveHint=true and openWorldHint=false, and the description earns credit by specifying exactly what is destroyed: it 'Overwrites any existing constitution.md'. It also conveys the immutability convention that all later phases obey, though it adds nothing about permissions or failure behavior.

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 action and its output, and the routing guidance is placed right after. The closing 'Parameter relationships' sentence restates the projectRoot default and consistency rule already given earlier, a mild 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?

An output schema exists so return values need no explanation, and the description covers phase ordering, overwrite semantics, the alternative tool, and the parameter's cross-phase role. 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% for the single parameter, so the baseline is 3; the description goes further by tying projectRoot to the cross-phase resolution contract ('later phases resolve every vdd/ artifact against' it). It is slightly redundant with the schema text, which already covers the default and consistency requirement.

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+artifact ('Generate constitution.md at the project root') and enumerates its contents (tech stack, conventions, security constraints, naming rules, banned patterns). It is clearly distinguished from siblings vdd_vision (runs after) and vdd_amend (for changing an existing constitution).

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 ordering ('Run this first, before vdd_vision') and an explicit alternative with its condition ('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 the 'Never modifies files' line mostly reinforces structured data. The description does add real behavioral context, however: the output is a structured matrix/metrics object rather than prose, and it discloses the scope/feature parameter dependency.

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 semantics, then routing and parameter relationships, with no filler sentences. It is fairly dense in a single block, but every clause carries information an agent needs.

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 explained, annotations cover the safety profile, and the description covers both scopes, routing to siblings, and cross-parameter dependencies. Nothing required 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 baseline is 3, but the description goes beyond the schema by stating the parameter relationships explicitly: scope="feature" requires feature, while the default project scope ignores it, and projectRoot must match the root used by earlier phases. That is genuine semantic value the schema's per-field text does not fully spell out.

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 (inspect) and resource (current project) and immediately enumerates the two views scope selects between, including exactly what each returns (traceability matrix vs per-feature spec metrics). An agent can distinguish this from the other vdd_* siblings purely from the description.

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: use vdd_validate for release-readiness validation with gates and vdd_specify to author a spec, implying this tool is for read-only inspection/status. That is a clear when-to-use and when-not-to-use pairing with named alternatives.

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?

'Overwrites these files' directly reinforces the destructiveHint annotation by naming what is destroyed, which is valuable beyond the boolean flag. It also discloses cross-tool state coupling (the spec must already exist). It stops short of covering failure behavior or whether the whole directory is replaced vs. individual files, so it earns a 4 rather than 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-loads the phase and outputs before the prerequisites, and every sentence carries information (artifact list, overwrite warning, ordering, parameter linkage). It is a single dense paragraph rather than a broken-out structure, which slightly hurts scanability for a multi-part rule set.

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 explained, and the description already covers prerequisites, ordering, side effects, and parameter coupling. Remaining gaps (error/failure cases, whether a partially-specified feature is valid) are minor for a generate-a-blueprint 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 coverage is 100%, so the baseline is 3, but the description adds relational meaning the schema cannot express: `feature` must match the value passed to vdd_specify and vdd_tasks, and projectRoot consistency across phases is emphasized. That cross-parameter, cross-tool constraint is genuine added value.

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 (generate the technical blueprint) plus the exact artifacts produced under vdd/specs/<feature>/ (plan.md, data-model.md, contracts/), and places itself in the phase sequence. This is distinguishable from vdd_specify, vdd_clarify, and vdd_tasks 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 an explicit prerequisite (an existing spec for the feature), the required ordering (after vdd_specify/vdd_clarify, before vdd_tasks), and a fallback routing instruction ('if no spec exists yet, run vdd_specify first'). Nothing about when-to-use 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; the description corroborates by stating 'Overwrites the spec file', which tells the agent prior content is lost. It does not discuss permissions or failure modes, 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-loads the phase, output artifact and content, then usage routing, then parameter relationships. Dense but every clause carries information; the trailing parameter-relationships sentence is borderline long but earns its place.

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?

Output schema exists so return values need no explanation, and the description covers overwrite behavior, alternative tooling, the ID format and cross-phase consistency. 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 cross-tool semantics the schema lacks: feature must match the value passed to vdd_clarify/vdd_plan/vdd_tasks, and actionItemId is optional when authoring from a freeform 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+resource (generate vdd/specs/<id>/spec.md) and enumerates the artifacts produced (user stories, boundaries, AC, MoSCoW, NFRs). It places itself explicitly as 'VDD Phase 4' and distinguishes itself from vdd_clarify for leftover clarification markers.

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 ('for a NEW spec') and when-not ('to resolve leftover [NEEDS CLARIFICATION] markers use vdd_clarify instead'), plus a shortcut path (pass actionItemId or a freeform description to skip the V/S/T chain).

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=true, and the description concretizes the destruction ('Overwrites vdd/strategy.md') — exactly the kind of 'what gets destroyed' context that earns credit. It also discloses non-obvious behavior the annotations cannot convey: the two-pass protocol, the effect of a first call with neither input, and the write precondition on vdd/vision.md.

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: artifact and contents first, then overwrite/prereq, then workflow, then alternative, then parameter relationships. Length is justified by the multi-step protocol, though it reads as a single long block rather than clearly segmented sentences.

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-pass, open-world tool with 4 params, an output schema, and rich annotations, the description covers preconditions, sequencing, overwrite semantics, the two-phase invocation, and the post-hoc alternative. 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 still adds meaning beyond the schema by stating the availableTools/capabilities alias relationship and that researchFindings has effect only on the second call — genuine cross-parameter semantics an agent cannot infer 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 artifact: 'Produce research-backed strategy into vdd/strategy.md', plus the concrete outputs (strategic pillars, competitive analysis, risk register) and the source of truth (vision target-domain primers). This clearly distinguishes it from vdd_vision (upstream) and vdd_tactics (downstream).

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_vision and before vdd_tactics'), a stated precondition ('Requires vdd/vision.md'), and an explicit alternative for a distinct case ('To change strategy after artifacts exist, use vdd_amend'). When-to-use and when-not 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?

Goes well beyond the destructiveHint=true annotation by naming exactly what gets destroyed ('Overwrites vdd/tactics.md'), stating the hard prerequisite file, and disclosing the environmental requirement (filesystem-capable host, scan of the repo). This is the mutation-safety context an agent needs before invoking.

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, action, and artifact, then prerequisites and routing. The trailing parameter-relationships sentence partially duplicates the schema text and the earlier prerequisite mention, which is slight redundancy but not damaging.

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 and annotations exist, so return values and the safety profile are covered structurally; the description fills in the sequencing, prerequisite, and host-capability gaps. Nothing needed to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single projectRoot parameter is already fully documented in the schema, including the 'keep the same value across every phase' consistency rule. The description's note that projectRoot must match vdd_init/vdd_vision/vdd_strategize largely restates the schema, so baseline 3 applies.

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 (audit) plus resource (existing codebase) and names the exact artifact produced (vdd/tactics.md) with its contents enumerated. It is trivially distinguishable from siblings like vdd_strategize or vdd_specify by the phase label and output file.

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_strategize and before vdd_specify'), an explicit prerequisite (requires vdd/strategy.md), and a routing hint to vdd_detect_environment when the host may lack filesystem access. When/when-not and alternatives are all present.

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 with 'Overwrites tasks.md', telling the agent exactly what is destroyed. It also discloses ordering and cross-tool parameter coupling. It stops short of describing output/return behavior or whether a partial run leaves the file in a bad 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 action and target file, then prerequisite, then alternative, then parameter coupling. Every sentence carries a distinct piece of information; 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?

For a destructive write tool with an output schema already present, the description supplies everything an agent needs: what it writes, that it overwrites, the prerequisite phase, the correct sibling for read-style access, 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 100%, so the baseline is 3, but the description adds a genuine cross-tool constraint beyond the schema: 'feature must match the value passed to vdd_plan'. It adds no further format detail because the schema already documents kebab-case and projectRoot 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 and artifact: 'Break the plan into atomic test-first tasks in vdd/specs/<feature>/tasks.md', including the phase number and file written. It also names the sibling it must not be confused with (vdd_get_next_task), so an agent can distinguish it 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?

Gives an explicit prerequisite ('Requires plan.md; run after vdd_plan') and an explicit alternative with the selecting condition ('To fetch the next uncompleted task from an existing tasks.md use vdd_get_next_task instead of re-running this'). Nothing about when to use it 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 establish idempotent=true, destructiveHint=false, openWorldHint=false, so the safety profile is largely covered. The description still adds valuable behavior beyond that: it writes vdd/impact-report.generated.md and explicitly never overwrites a hand-authored vdd/impact-report.md, which materially informs the agent about side effects on existing files. It does not discuss runtime cost or permissions, keeping it short of 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 phase label and the scope list, then behavior, then the alternative, then parameter relationships — a sensible ordering. It is dense with long enumerations and the parameter-relationship sentence is crowded, but essentially every clause carries information an agent needs.

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 the check scope, phase ordering, the written artifact and its overwrite guarantee, the alternative tool, and the two-parameter interaction. Nothing needed to call this correctly appears to be 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 semantics on top: 'feature narrows the check to one spec' and artifactFiles is 'omitted when resolving against a local projectRoot', which clarifies the interaction between the two optional parameters that the schema documents only in isolation.

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 ('Validate the full chain') and enumerates exactly what is validated — traceability matrix, drift, orphans, uncovered vision goals, impact metrics, assumption checks. It also names the sibling vdd_inspect as the tool for a narrower subset, so an agent can distinguish it 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?

Gives an explicit precondition ('Run after implementation is complete') and an explicit routing rule to an alternative ('for the traceability matrix or per-feature spec metrics use vdd_inspect'). This is when/alternatives guidance in full.

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 adds concrete context beyond them: it overwrites any existing vdd/vision.md, requires a prior vdd_init, and is a run-once step. That is exactly the destructive/permission context an agent needs.

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, artifact, and file contents, then prerequisites and alternatives. It is dense but mostly earns its length; the freeform/not-a-title constraint is stated twice (in the prose and again under 'Parameter relationships'), which is mild 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?

With an output schema present, return values need no explanation; the description covers prerequisites, overwrite behavior, ordering, and the amend-vs-rerun decision. An agent has everything needed to call this correctly in the VDD workflow.

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: statement must be freeform prose of 1-3 paragraphs and specifically not a title, and projectRoot must match the root used by vdd_init. This goes beyond the schema's terse one-line param 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 precise verb and artifact ('Expand a freeform vision statement into vdd/vision.md') and enumerates exactly what the file contains (Impact Model, Stakeholder Map, Success Metrics, Constraints, Target Domains). It also names the sibling it is not (vdd_amend), so an agent can distinguish it without opening another 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 sequencing ('run once, after vdd_init and before vdd_strategize') and a named alternative with the condition that selects it ('to revise a vision once downstream artifacts exist, use vdd_amend so the change cascades'). Nothing about when/when-not 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.