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 already declare readOnlyHint and idempotentHint, but the description adds substantive behavior beyond them: it does not edit the file (the host agent applies resolutions), and on the hosted stateless endpoint it returns a delegation envelope unless artifactFiles is supplied. That endpoint-specific failure mode is exactly the kind of context 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-loaded with phase, verb, and return payload, and every sentence carries information. The dedicated 'Parameter relationships' sentence partially restates the schema's feature description, which is the only 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, and the description still covers the delegation-envelope fallback and the read-only contract. Nothing an agent needs to call this correctly — required param, precondition, and hosted-endpoint caveat — is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a real constraint beyond the schema: feature 'must be the exact spec directory name created by vdd_specify', and it explains the consequence of omitting artifactFiles on the hosted endpoint. It stops short of clarifying how projectRoot interacts with artifactFiles resolution.

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 — scans vdd/specs/<feature>/spec.md and returns the items to resolve') and enumerates exactly what it returns (markers, [e.g.] placeholders, AC-E counterparts). It explicitly distinguishes itself from the sibling vdd_specify, 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 an explicit trigger ('Run after vdd_specify when a spec has unresolved markers') and names the alternative for the opposite case ('to author a brand-new spec use vdd_specify instead'). When-to-use, when-not-to-use, and the alternative 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?

The description directly contradicts its annotations: it states 'Open-world: makes network requests to the target site' while openWorldHint is false, and it says it 'Writes vdd/clone-dataset.json, vdd/clone-manifest.json, and vdd/clone.md, overwriting any existing versions in place' while readOnlyHint is true. These are material safety-profile conflicts that would mislead an agent about the tool's side effects and reach.

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 paragraph is dense but front-loaded: purpose first, then artifacts written, then open-world caveat, then sibling routing, then parameter relationships. Every section carries distinct information, though the single-block format could be broken up for faster scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (9 parameters, multiple file writes, open-world crawl behavior) and the existence of an output schema, the description supplies the key operational context an agent needs: what gets written, overwriting behavior, network reach, and parameter roles. It would be a 5 if it did not conflict with the annotation layer.

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 baseline is 3, but the description adds meaning beyond the schema by clarifying that 'description is the target domain' (the schema calls it only 'Freeform description input') and by explaining the relationship among maxPages, timeoutMs, concurrency, crawl, browser, and refresh. This is useful disambiguation for a 9-parameter tool.

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 ('Crawl and capture a target domain into a clone dataset + manifest') and explicitly contrasts with the sibling phase pipeline ('it is not part of the VDD phase pipeline, so for the normal init→validate flow call those phase tools instead'). An agent can identify the tool's scope and its non-use case without opening another definition.

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 guidance ('not part of the VDD phase pipeline'), and names the alternative tools to call instead (init→validate phase tools). The boundary is unambiguous.

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 readOnly/idempotent/openWorld, so the safety profile is covered. The description adds genuinely non-obvious behavior: it never edits tasks.md, returns a completion marker when no tasks remain, and returns a delegation envelope on the stateless hosted endpoint unless artifactFiles is supplied.

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 action, then layers usage, parameter relationships, and the hosted-endpoint caveat. Efficient overall, though the final sentence is dense enough that a reader must parse it carefully.

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 elaboration. The description covers purpose, when-to-use, alternatives, parameter linkage, and the stateless-endpoint edge case, leaving no gap an agent needs in order 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 baseline is 3, but the description adds cross-tool parameter relationships: feature must match the spec directory and the returned taskId (TASK-###) is the argument to vdd_implement, plus how artifactFiles must be shaped on the hosted endpoint.

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 (read), resource (vdd/specs/<feature>/tasks.md), and precise output (next uncompleted task or a completion marker). It also names sibling tools (vdd_tasks, vdd_implement) so the agent can distinguish this from adjacent operations.

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

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

Explicit when-to-use ('before each implementation session to keep context isolated') plus named alternatives: vdd_tasks to regenerate the whole list and 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, but the description adds real context beyond them: it draws the side-effect boundary (the host agent, not the tool, performs edits, verification, and commit) and discloses a degraded mode — without artifactFiles the tool returns a delegation envelope rather than real task text. That fallback behavior is not inferable from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with phase and behavior, then constraints, then parameter relationships — a sensible ordering with no filler sentences. Minor redundancy: vdd_get_next_task is invoked twice in adjacent clauses ('after vdd_get_next_task' and 'use vdd_get_next_task instead'), which 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?

For a 3-parameter, nested-object tool with an output schema, the description covers everything an agent needs: purpose, sequencing, exclusions, the stateless-endpoint requirement, and the failure mode. Since an output schema exists, it correctly does not waste space describing return values in detail.

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 earns above that by documenting parameter relationships the schema does not state — taskId's provenance from vdd_get_next_task and the TASK-### format, the requirement that projectRoot match earlier phases, and the concrete artifact list (constitution.md, spec.md, plan.md, contracts/, tasks.md) expected in artifactFiles.

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 names exactly what it loads (constitution, spec, plan, contracts) and returns (implementation instruction plus impact-chain commit-message format). It explicitly distinguishes itself from the closest sibling, vdd_get_next_task, so an agent can route between them 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 ordering ('after vdd_get_next_task'), concurrency guidance ('run one task at a time'), an explicit exclusion ('for read-only inspection of tasks use vdd_get_next_task instead'), and a conditional branch for the hosted endpoint. This is about as complete a when/when-not/alternative statement as a tool description gets.

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

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

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

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

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

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

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

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

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

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

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

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

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

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

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

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

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

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

Beyond the readOnlyHint/idempotentHint annotations, it discloses that files are never modified, that the hosted stateless endpoint requires artifactFiles and otherwise returns a delegation envelope, and that projectRoot must stay consistent across phases. These are non-obvious operational behaviors not derivable from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the scope distinction, then alternatives, then parameter relationships. It is dense and long, and the output-format sentence is somewhat redundant given an output schema exists, but every sentence carries usable routing or constraint 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 prose explanation, and the description still covers the two scopes, sibling routing, parameter dependencies, and the stateless-endpoint fallback. 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, but the description adds genuine cross-parameter semantics the schema lacks: scope='feature' requires feature while scope='project' ignores it, and projectRoot must match earlier phases. It also explains the artifactFiles path→content purpose, though it stops short of format specifics.

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

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

States a specific verb+resource ('Read-only inspection of the current project') and immediately disambiguates the two modes via the scope enum, spelling out exactly what each returns. An agent can distinguish it from vdd_validate and vdd_specify 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 routes the agent: 'for release-readiness validation with gates use vdd_validate, and to author a spec use vdd_specify,' and clarifies when to pass scope='feature' vs the default. Both the alternative tools and the selecting conditions are named.

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

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

The description says the tool 'Overwrites these files' and generates plan.md, data-model.md, and contracts/, which is a state-modifying write operation, while the annotations declare readOnlyHint=true. This is a direct contradiction that could mislead an agent into treating a destructive overwrite as a safe read; apart from this, the overwrite disclosure itself would have been valuable 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 and purpose, then artifacts, preconditions, and parameter relationships in a logical order. It is dense but every clause carries information; the long compound sentences are slightly heavy but not padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be described, and the description still covers artifacts produced, overwrite behavior, sequencing preconditions, and parameter dependencies. An agent has everything needed to call it correctly, aside from the annotation inconsistency noted above.

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 beyond the schema: 'feature must match the value passed to vdd_specify and vdd_tasks'. That relational constraint is not derivable from the schema alone and meaningfully improves correct invocation.

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

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

States a specific verb and resource ('Generate the technical blueprint') and enumerates the exact artifacts produced (plan.md, data-model.md, contracts/), placing it in a named phase (VDD Phase 5). It is immediately distinguishable from siblings like vdd_specify, vdd_clarify, and vdd_tasks.

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_specify or vdd_clarify and before vdd_tasks, and adds an exclusion/fallback ('if no spec exists yet, run vdd_specify first'). The precondition ('Requires an existing spec for the feature') is 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?

The description says it 'Generate[s] vdd/specs/<id>/spec.md' and explicitly 'Overwrites the spec file', which is a filesystem mutation, while the annotations declare readOnlyHint=true. This is a direct contradiction that would mislead an agent about the tool's side effects. The 'Overwrites' disclosure is useful on its own but is negated by the conflicting annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: the primary purpose and artifact lead, followed by contents, the overwrite warning, the alternative, and parameter relationships. Every sentence carries information, though the single long paragraph is heavier than ideal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained, and the description covers generation, overwrite behavior, alternatives, and cross-phase parameter consistency. Its one gap is the unresolved read/write conflict with the annotations, which leaves the mutation semantics ambiguous.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real cross-parameter meaning: 'feature' must match the value passed to vdd_clarify/vdd_plan/vdd_tasks, and actionItemId is the A-### id from tactics.md and is optional when authoring from a freeform description. This goes beyond the schema text.

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

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

States a specific verb and artifact: 'Generate vdd/specs/<id>/spec.md for one tactical action item', and enumerates the contents (user stories, boundaries, AC, MoSCoW, NFRs). It explicitly differentiates itself from the sibling vdd_clarify, so an agent can pick 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 when-to-use ('Use for a NEW spec') and when-not with the named alternative ('to resolve leftover [NEEDS CLARIFICATION] markers in an existing spec use vdd_clarify instead'). It also states the two input routes (actionItemId or 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?

The description states the tool produces and 'Overwrites vdd/strategy.md', which is a state-mutating file write, while annotations declare readOnlyHint=true. This directly contradicts the structured safety signal, so per the rules this scores 1 and is flagged as an annotation contradiction.

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: phase, purpose, and artifact come first, followed by preconditions and the two-pass mechanics. Every sentence carries operational information, though the parameter-relationship sentence 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?

Covers preconditions, ordering, overwrite behavior, the two-pass dispatch/synthesis flow, the amend alternative, and parameter aliasing. With an output schema present, return values need not be described, so an agent has everything required 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 real meaning: it clarifies that availableTools and capabilities are aliases (pass one) and that researchFindings only takes effect on the second call. These relationships are not obvious from the schema alone, so it earns above baseline.

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 (produce research-backed strategy), the concrete artifact (vdd/strategy.md), and the contents (strategic pillars, competitive analysis, risk register) resolved from vision primers. It is clearly distinguished from siblings by naming vdd_vision and vdd_tactics as the phases it sits between.

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 the precondition (requires vdd/vision.md), the ordering (run after vdd_vision, before vdd_tactics), and the alternative for post-artifact changes (use vdd_amend). The two-pass usage is spelled out with the condition that selects each call, 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?

The description explicitly states the tool writes and 'Overwrites vdd/tactics.md', which modifies the environment, yet the annotations declare readOnlyHint=true. This directly contradicts the annotation. The rich behavioral detail (prerequisites, hosted-endpoint delegation envelope, filesystem requirement) is otherwise valuable but cannot offset the contradiction.

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: phase and action first, then prerequisites, then parameter relationships. Slightly redundant, repeating 'requires vdd/strategy.md' twice and re-explaining the hosted/stateless limitation, but overall dense and purposeful rather than padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained. The description still covers everything an agent needs: phase ordering, prerequisites, filesystem-capability requirement, cross-tool parameter consistency, and the stateless-endpoint fallback behavior. Complete for a complex multi-mode 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 already 100%, so the baseline is 3. The description adds genuine meaning beyond the schema: projectRoot 'must match the root used by vdd_init, vdd_vision, and vdd_strategize', and it explains the purpose of artifactFiles (hosted endpoint artifact map) and codebaseAudit (host-produced repo scan) with a concrete example.

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 opens with a specific verb+resource ('Audit the existing codebase into vdd/tactics.md') and enumerates the concrete outputs (repo audit, debt assessment, gap analysis, MoSCoW action items, dependency map, infra requirements). It also places itself precisely in the workflow (Phase 3, after vdd_strategize, before vdd_specify), so it is clearly distinguished from 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?

Explicit when-to-use guidance: 'run after vdd_strategize and before vdd_specify', prerequisite 'Requires vdd/strategy.md', and a routing instruction to 'check with vdd_detect_environment first if the host may lack one'. It also states the alternative path for the stateless endpoint. Nothing is left to inference.

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

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

The description discloses useful behavior (it overwrites tasks.md, it requires plan.md, feature must match the vdd_plan value), but it directly contradicts the annotations: it describes writing/overwriting a file while annotations declare readOnlyHint=true. This is an annotation contradiction of the same class as a 'creates' tool marked read-only, so the dimension scores 1 regardless of the otherwise-good disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and artifact, and every sentence carries information (overwrite warning, prerequisite, alternative tool, parameter relationship). The first sentence is dense with output-format clauses (AC references, S/M/L sizing, [P] markers) that are useful but slightly crowded.

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 explain return values, and it covers the remaining agent-critical facts: the write/overwrite side effect, the prerequisite phase, the sibling to use instead, and the parameter coupling to vdd_plan. Nothing needed to invoke it correctly is missing—though the write behavior conflicts with the annotations.

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 stating the cross-tool relationship 'feature must match the value passed to vdd_plan', which is not encoded anywhere in the property definitions. It does not add syntax or format detail beyond that, so it lands just above baseline.

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 written to vdd/specs/<feature>/tasks.md, plus phase placement (VDD Phase 6). It differentiates itself from siblings by naming vdd_plan as the prerequisite and vdd_get_next_task as the tool for a different job. 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 explicit sequencing ('Requires plan.md; run after vdd_plan') and an explicit when-not/alernative ('To fetch the next uncompleted task from an existing tasks.md use vdd_get_next_task instead of re-running this'). The conditions that select this tool versus its closest sibling are fully spelled out.

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/idempotent/openWorld, and the description goes further: it names the exact output file (vdd/impact-report.generated.md), guarantees hand-authored vdd/impact-report.md is never overwritten, and discloses the delegation-envelope fallback when artifactFiles is omitted on the hosted endpoint. That is unusually rich behavioral detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and check list, then prerequisites, then parameter relationships. Dense but every clause carries information; only minor trimming is possible.

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. The description still covers ordering, side effects, the hosted-vs-local distinction, and file outputs, leaving nothing 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 baseline is 3, but the description adds genuine cross-parameter semantics: feature narrows the check to one spec, and artifactFiles maps artifact path to content and is omitted when resolving against a local projectRoot. These relationships are not obvious from the per-parameter 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 (Validate) plus resource (the full VDD chain) and enumerates exactly what it checks: traceability matrix, drift, orphan, uncovered vision goals, impact metrics, and 28 S&T assumption checks. It also names the sibling it is not (vdd_inspect) and the file it produces, so an agent can distinguish it from all other vdd_* tools.

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

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

Explicitly says when to run it ('after implementation is complete') and names the concrete alternative for a sub-use case ('for the traceability matrix or per-feature spec metrics use vdd_inspect'). It adds environment-specific guidance (hosted/stateless vs local projectRoot).

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

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

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

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then ordering, then parameter notes — a sensible priority order. The closing 'Parameter relationships' sentence repeats the freeform/not-a-title point already made earlier, a minor redundancy in an otherwise dense and earned description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. Prerequisites (vdd_init), ordering, overwrite behavior, and the revision alternative are all present; nothing needed to invoke this correctly is missing.

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

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

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

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

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

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

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

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

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

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