vision-driven-design

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable context: it clarifies the tool is read-only, returns a plan (not edits), and that the host agent applies edits and commits. It also specifies the output nature ('ordered steps') and the affected gates. This goes beyond the annotations without contradicting them.

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 description is two sentences with zero filler. The core purpose and scope are front-loaded, followed immediately by a usage directive. Every clause earns its place—no redundancy with annotations or schema, and no extraneous detail.

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

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

For a tool with 10 parameters, no output schema, and nested objects, the description provides a complete mental model: the workflow (cascade planning), the read-only contract, the primary input parameter, and the output (ordered steps and gates). It doesn't cover every parameter, but the schema already does that. The main missing element is any mention of prerequisites like project structure validity, but that's minor for a read-only planning 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 all 10 parameters are described in the schema. The description adds a crucial usage hint: 'Pass the change as description', directly identifying which parameter carries the change input. This is a meaningful semantic addition beyond the schema's generic 'Freeform description input', helping the agent know which of the many freeform fields to use.

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

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

The description states a precise verb ('Plan'), a specific resource ('requirement-change cascade'), and scopes it clearly: 'through the whole chain', identifying the highest affected level and returning ordered update steps (V→S→T→SP→PL→TK) plus affected gates. It distinguishes itself from sibling phase-build tools by explicitly contrasting 'to build a phase from scratch' with using the phase's own tool.

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?

The description gives explicit when-to-use ('when a requirement changes after artifacts already exist') and when-not-to-use ('to build a phase from scratch the first time, run that phase's own tool instead'), naming the alternative category. This leaves no ambiguity about selection.

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; the description reinforces this with 'Read-only; returns metrics without modifying files' and adds the specific metrics it checks. No contradictions. It adds context about what gets analyzed but doesn't cover edge cases or output structure; however, annotations lower the bar, and this is sufficient.

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 description is dense but every sentence contributes: purpose, checks performed, read-only guarantee, parameter instruction, and usage guidance with alternatives. It is front-loaded with the core purpose and efficiently structured, with no filler.

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

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

For a read-only analysis tool with no output schema, the description covers the main function, inputs, and usage context. It doesn't specify the exact metrics output format, but that's arguably acceptable given the tool's simplicity and the annotations covering safety. The main gap is that it doesn't address why the other 9 parameters exist, but the schema covers them, so completeness is adequate.

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 all 10 parameters, so the baseline is 3. The description adds a meaningful clarification by stating 'Pass feature (the spec directory name)', which directly maps to the primary parameter and disambiguates its role. It does not explain other parameters but the schema already does; the added focus on 'feature' lifts it to a 4.

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 clearly states the tool performs cross-artifact consistency analysis for a single feature, enumerating specific checks (AC count, unresolved markers, placeholder density, file existence). It explicitly differentiates from sibling tools by naming vdd_trace (project-wide matrix) and vdd_validate (release validation), so an agent can select the right tool without ambiguity.

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?

The description provides explicit when-to-use guidance ('Use during planning and implementation to check a spec is complete') and when-not-to-use with direct alternatives ('for the project-wide matrix use vdd_trace, and for release validation use vdd_validate'). This fully answers the selection question.

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

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

The description states 'Read-only; returns the list without editing the file', which aligns with the readOnlyHint annotation. It adds behavioral detail by listing the exact output items (markers, placeholders, ACs) and notes the host agent applies resolutions. This goes beyond simply echoing the annotation and provides useful operational 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?

The description is a few sentences that lead with the core purpose, then clarify scope and usage. It includes the workflow and an alternative tool pointer. While not overly verbose, it could be tightened—e.g., 'Read-only; returns the list without editing the file' is slightly redundant given the annotation, but it remains efficient and well-structured.

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?

It explains the input (feature directory name), the exact output (list of items to resolve), and the follow-up workflow (host agent applies resolutions). No output schema exists, so the explicit output description is valuable. However, it does not address the many other schema parameters that appear irrelevant to this tool, potentially leaving an agent unsure whether to pass them, though the guidance to 'Pass feature' implies they are optional.

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% with all 10 parameters individually described, so the description adds minimal value beyond the schema. It does clarify 'Pass feature (spec directory name)' tying it to the file path, but other parameters (taskId, statement, etc.) are not addressed. The baseline of 3 is appropriate given the schema already covers parameter meanings.

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 explicitly states it scans vdd/specs/<feature>/spec.md and returns specific items to resolve: [NEEDS CLARIFICATION] markers, [e.g.] placeholders, and ACs needing edge-case counterparts. It also differentiates from vdd_specify by explicitly saying 'to author a brand-new spec use vdd_specify instead', making the purpose unambiguous and distinct from siblings.

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

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

It provides clear when-to-use guidance ('Run after vdd_specify when a spec has unresolved markers') and when-not-to-use ('to author a brand-new spec use vdd_specify instead'). However, it does not clarify conditions relative to other siblings like vdd_analyze or vdd_validate, leaving some potential ambiguity for those tools.

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 carry openWorldHint=true and destructiveHint=true; the description reinforces both with concrete specifics: it 'Writes' the three vdd/clone-* artifacts, 'makes network requests to the target site', and explains the caching behavior where refresh=true 'bypasses a cached dataset and re-crawls'. This adds real behavioral context beyond the boolean hints and does not contradict them.

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 description is long but every sentence carries load: purpose, artifacts, parameter guidance, open-world side effect, and sibling routing. The technical detail on WordPress-aware inference and the Next.js + Payload + Postgres scaffold is relevant to what the tool produces, not padding. The core purpose is front-loaded in the first sentence.

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 an open-world destructive tool with no output schema, the description covers the essentials: what is written, cache/refresh semantics, network side effects, and when to use it. The remaining gap is the schema/description mismatch — 10 VDD-pipeline-style parameters (taskId, researchFindings, artifactFiles, etc.) are exposed for a tool explicitly outside that pipeline, and the tuning knobs mentioned in prose are absent from the schema, creating some invocation ambiguity.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by resolving the vague 'Freeform description input' schema text into actionable guidance ('Pass the domain as description'). However, the prose names tuning parameters (maxPages, timeoutMs, concurrency, crawl, browser, refresh) that do not exist anywhere in the input schema, leaving ambiguity about how an agent is supposed to supply them.

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 pair ('Crawl and capture a target domain into a clone dataset + manifest') and enumerates concrete output artifacts (vdd/clone-dataset.json, vdd/clone-manifest.json, vdd/clone.md). It also explicitly distinguishes itself from the 15 VDD siblings by stating it is 'not part of the VDD phase pipeline', so an agent can disambiguate it without opening the schema.

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

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

Gives an explicit use case ('Use for cloning an external site'), an explicit exclusion ('it is not part of the VDD phase pipeline'), and routes the agent to the alternative ('for the normal init→validate flow call those phase tools instead'), which maps directly to sibling tools like vdd_init and vdd_validate. It also flags the cost implication ('Open-world: makes network requests') so the agent can weigh side effects before invoking.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's 'Read-only' reinforces but doesn't add much. However, it adds valuable behavior beyond annotations: the effect of omitting both availableTools and capabilities (returns per-phase requirements without the present/missing comparison), and the alias relationship. No contradiction with 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?

The description is dense but every sentence earns its place: purpose, read-only nature, usage timing, alternative tool, and parameter handling. It is front-loaded with the core purpose and avoids fluff or repetition.

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 (10 parameters, nested objects, no output schema), the description covers the essential decision-making context: when to use, how to pass the critical parameters, and what happens with omissions. The return format is only described as 'capability report,' which is slightly vague, but annotations already cover the safety profile, and the schema documents all parameters. This is complete enough for an agent 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. The description adds meaning for two key parameters (availableTools and its alias capabilities) and explains the omission behavior, which is helpful. It does not elaborate on the other 8 parameters, but the schema already documents them fully. The added alias and omission context slightly exceeds the baseline, but not enough to push to 4.

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 uses a specific verb ('Report') and clearly identifies the resource: which tools/MCPs each VDD phase requires vs treats as optional, and which are present vs missing. It explicitly distinguishes from vdd_trace by purpose (capabilities vs artifacts), making it easy for an agent to select the right tool among siblings.

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

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

It states exactly when to use this tool: 'Run before vdd_strategize to plan research-subagent dispatch, or when a phase fails for lack of a tool.' It also names the alternative (vdd_trace) and the condition for choosing it, providing clear 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?

The annotations already declare readOnlyHint and idempotentHint, and the description reinforces this by stating 'Read-only; never edits tasks.md.' It adds the file path, the 'next uncompleted task' semantics, and the completion-marker behavior, which are not derivable from the annotations alone. There is no contradiction with 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?

Three sentences with no filler: the action and file path are front-loaded, the read-only caveat is explicit, and routing to siblings is compressed into the last sentence. Every clause 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?

For a read-only retrieval tool, the description covers what it reads, what it returns, when to use it, and how it differs from related tools. It is complete enough for an agent to invoke it correctly without an output schema, since it names the required input and the two possible return outcomes.

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 adds value by singling out feature as the parameter to pass and defining it as the exact spec directory name, tying it to the path vdd/specs/<feature>/tasks.md. It does not explicitly state that the other schema parameters are ignored, but the core invocation requirement is clear.

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 and resource ('Read vdd/specs/<feature>/tasks.md and return the next uncompleted task') and explicitly covers the completion-marker case. It distinguishes itself from siblings by naming vdd_tasks and vdd_implement as alternatives, so there is no ambiguity about what this tool does.

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

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

It gives an explicit usage window ('Use before each implementation session to keep context isolated') and names both the list-regeneration alternative and the follow-up execution tool. This is model routing guidance rather than a vague hint.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description reinforces this by stating 'Read-only; the tool writes nothing — the host agent performs the code edits, verification, and commit.' This adds context beyond the annotations by clarifying the division of labor between the tool and the host agent. It doesn't describe error cases or side effects, but for a read-only preparation tool the key behavioral trait 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?

The description is a single dense paragraph that front-loads the core purpose and read-only guarantee, then gives usage guidance. It's slightly long but every sentence earns its place: purpose, behavior, parameter source, and alternatives are all covered. The structure could be improved with line breaks, but the content is efficient.

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 tool with 10 parameters, no output schema, and no required parameters, the description does a good job of orienting the agent: it explains the phase, the read-only nature, the source of taskId, and the alternatives. However, it doesn't explain what the 'implementation instruction plus the impact-chain commit-message format' looks like or how the many optional parameters affect the output. Since there is no output schema, a bit more detail on the return value would improve completeness.

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 documents all 10 parameters. The description adds value by explaining the key parameter (taskId) with an example and its source ('from the task returned by vdd_get_next_task'), but it doesn't clarify the relationship between the many optional parameters (feature, statement, description, actionItemId, capabilities, artifactFiles, availableTools, researchFindings) or when each is needed. Baseline 3 is appropriate since the schema carries 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?

The description states a specific verb ('Prepare'), a specific resource ('one task for implementation'), and the exact phase ('VDD Phase 7b'). It clearly distinguishes itself from siblings by naming vdd_get_next_task and vdd_trace as the read-only inspection alternatives. An agent can tell exactly what this tool does and what it is not.

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?

The description gives explicit when-to-use guidance: 'Run one task at a time, after vdd_get_next_task'. It also names alternatives for read-only inspection ('use vdd_get_next_task or vdd_trace instead') and clarifies that the host agent performs the actual edits, verification, and commit. This is strong routing 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?

Discloses the key destructive behavior directly: 'Overwrites any existing constitution.md,' which goes beyond the destructiveHint annotation by specifying exactly what is destroyed. It also characterizes the generated file as immutable for later phases, adding 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?

The description is two dense sentences covering the artifact, contents, overwrite behavior, ordering, alternative tool, and the key parameter. It front-loads the core action before caveats and avoids 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 initialization tool with no output schema, this is complete: it names the file produced, its location, its contents, when to run it, and how to amend instead. Return-value shape is not specified, but it is not needed to call this tool correctly.

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

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

Schema coverage is 100%, so the baseline is met by schema documentation. The description adds real value for projectRoot by explaining it sets both the write location and the root that later phases resolve vdd/ artifacts against, which is beyond the schema's simple 'Path to project root directory'.

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

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

The description states a precise action and artifact: 'Generate constitution.md at the project root,' and enumerates what it contains. It clearly distinguishes this tool from the vdd_amend sibling by framing it as Phase 0 initialization rather than amendment.

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 'Run this first, before vdd_vision' and instructs using vdd_amend instead of re-running when a constitution already exists. This gives the agent both a positive trigger and a negative exclusion with a named alternative.

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 include destructiveHint=true, and the description explicitly confirms 'Overwrites these files,' naming exactly which files can be destroyed. It also discloses the precondition that a spec must already exist, adding useful behavioral context beyond the annotation flag.

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 description is a single dense sentence with all relevant content front-loaded around 'Generate the technical blueprint.' The parenthetical list is efficient, but the sentence is long enough that slightly better scannability could be achieved by splitting 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?

The description captures purpose, artifacts, overwrite behavior, and workflow ordering, which is strong for a destructive write tool with no output schema. It does not map the 10 input parameters into the workflow, though the schema descriptions cover their individual meanings, so it remains sufficient.

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?

The input schema covers 100% of parameters with descriptions, so the description does not need to restate parameter meanings. It does not add much parameter-level detail beyond the schema; the only implicit link is feature mapped to the vdd/specs/<feature>/ path.

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?

Clearly states 'Generate the technical blueprint' with exact target files (plan.md, data-model.md, contracts/). The 'VDD Phase 5' qualifier and file list distinguish it from vdd_specify (spec creation) and vdd_tasks (task breakdown).

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 gives workflow position: run after vdd_specify or vdd_clarify and before vdd_tasks. It also names a prerequisite and fallback: requires an existing spec; otherwise run vdd_specify first. This is direct when-to-use and when-not-to-use guidance.

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

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

Annotations already mark destructiveHint=true, and the description adds the specific destructive behavior: 'Overwrites the spec file.' It also discloses the skip behavior for the V/S/T chain when actionItemId or a freeform description is passed. This goes beyond the generic annotation without contradicting it.

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

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

The description is front-loaded with the core purpose and resource path, then lists the spec contents, then the overwrite behavior, then the input shortcut, then the alternative tool. Every sentence carries distinct information and there is no filler or redundancy.

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

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

For a tool with 10 parameters, nested objects, and no output schema, the description covers the essential decision points: what is generated, where, what it contains, that it overwrites, how to choose input mode, and when to use the sibling tool. It does not describe return values, but the generated file path is stated, so the main output is clear. Minor gaps remain around the meaning of the V/S/T chain, but the schema covers the remaining parameters.

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 adds meaningful parameter semantics by explaining that actionItemId or a freeform description can be used to skip the V/S/T chain, which clarifies the relationship between those inputs. It does not repeat every parameter, which is appropriate given the schema already covers them.

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

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

The description names a specific verb ('Generate'), a concrete resource ('vdd/specs/<id>/spec.md'), and a clear scope ('for one tactical action item'). It also lists the spec contents (user stories, boundaries, AC, MoSCoW, NFRs, impact verification), which distinguishes it from sibling tools. The explicit 'Use for a NEW spec' and 'use vdd_clarify instead' further differentiates it from vdd_clarify.

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?

The description gives explicit when-to-use guidance: 'Use for a NEW spec'. It also names the alternative tool and the condition for choosing it: 'to resolve leftover [NEEDS CLARIFICATION] markers in an existing spec use vdd_clarify instead.' This is direct routing guidance with no ambiguity.

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?

Despite annotations already carrying destructiveHint=true, the description adds specificity: it names the exact overwrite target (vdd/strategy.md), the prerequisite artifact (vdd/vision.md), and the two-pass behavior where a first call without arguments returns only dispatch specs. No contradiction with annotations.

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

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

Dense but efficient: the main purpose and output are front-loaded, followed by overwrite warning, prerequisite/ordering, two-pass protocol, and alternative tool. Each sentence carries a distinct, necessary piece of information.

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

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

For a 10-parameter tool with no output schema, the description covers the critical operational context: prerequisite file, execution order, destructive overwrite, the two-pass return behavior (dispatch specs), and which sibling to use instead. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description raises it by explaining the workflow role of availableTools (first-pass dispatch specs) and researchFindings (second-pass synthesis). It adds context beyond the schema's individual field descriptions, though most parameter semantics still live in the schema.

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

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

The description uses a specific verb ('Produce') with a clear resource ('research-backed strategy into vdd/strategy.md') and enumerates the contents (strategic pillars, competitive analysis, risk register). It distinguishes itself from siblings by naming its phase position ('VDD Phase 2') and explicitly routing post-artifact changes to vdd_amend.

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?

Supplies explicit when-to-use context: 'run after vdd_vision and before vdd_tactics' and 'Requires vdd/vision.md'. It names the alternative tool for the changed-strategy case (vdd_amend) and details the two-pass invocation protocol with availableTools and researchFindings.

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, but the description adds a concrete behavior: it 'Overwrites vdd/tactics.md'. This specifies exactly what is destroyed, which is meaningful beyond the boolean annotation. It also discloses the dependency on strategy.md, but doesn't detail other potential side effects like modifying repository 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?

Three sentences, each with a distinct purpose: what it produces, that it overwrites, and when to run it. Information is front-loaded, no filler, and the constraints are concise. This is tight and efficient.

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 tool with 10 parameters and no output schema, the description covers the core workflow: purpose, output file, destructive action, ordering, and hardware prerequisite. It doesn't explain how the various parameters (taskId, feature, researchFindings, etc.) interact, but those are documented in the schema. Given the complexity, this is reasonably complete but could mention input relationships.

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 all 10 parameters are already documented. The description adds a small amount of context (e.g., action item format 'A-001, A-002') that relates to actionItemId, but it does not substantially enrich parameter meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description states a specific verb ('Audit'), resource ('existing codebase'), and output artifact ('vdd/tactics.md'), and enumerates the exact contents. It also positions the tool within a phase ('VDD Phase 3') and distinguishes it from siblings by specifying its position between 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?

The description explicitly states prerequisites ('Requires vdd/strategy.md'), ordering ('run after vdd_strategize and before vdd_specify'), and a conditional check ('check with vdd_detect_environment first if the host may lack one'). This gives agents unambiguous when-to-use guidance and names the relevant sibling tool.

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

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

Annotations declare destructiveHint=true, and the description adds the critical context of WHAT gets destroyed: 'Overwrites tasks.md'. It also discloses the prerequisite (plan.md) and the output format details (references AC and contracts, sized S/M/L, marked [P]), going well beyond the annotation's bare destructive flag.

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?

Three dense sentences, each earning its place: the core action with output location and format, the destructive side-effect plus prerequisite and workflow sequencing, and the sibling-tool routing. The most important constraint (what it does) is front-loaded.

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?

The description covers the core contract well—action, output path, format, destructive behavior, prerequisites, and alternative. It loses a point because with 10 parameters and no output schema, the description never disambiguates which of the seemingly generic/shared parameters are relevant to task generation, which could mislead an agent invoking the call.

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 of 3 applies even though the description adds no per-parameter detail. However, several schema parameters (taskId, statement, researchFindings, actionItemId) appear irrelevant to generating tasks and the description does not clarify which parameters actually apply to this 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+resource: 'Break the plan into atomic test-first tasks in vdd/specs/<feature>/tasks.md'. The scope is precise (VDD Phase 6, writes to tasks.md) and explicitly differentiates from the sibling tool 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?

Provides explicit when-to-use conditions ('Requires plan.md; run after vdd_plan') and an explicit when-not-to-use alternative ('To fetch the next uncompleted task from an existing tasks.md use vdd_get_next_task 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?

The description discloses that the tool is read-only, reads all vdd/ artifacts, and does not modify files. This aligns with the annotations (readOnlyHint=true, idempotentHint=true) and adds the artifact scope. It doesn't describe the return format, but the read-only and idempotent behavior is transparent, which is sufficient given 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?

Two sentences, each carrying weight. The purpose is front-loaded, and the usage guidance follows immediately. No filler or 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?

The description covers purpose and usage, but given the tool has 10 optional parameters and no output schema, it leaves out how parameters influence behavior. It also doesn't specify the return structure (though the tool name suggests a matrix). For a read-only tool with many apparently extraneous parameters, this incompleteness could confuse an agent about what to pass. However, the core function is well explained, so it's above minimal but not fully complete.

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

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

Schema coverage is 100% (baseline 3), but the description adds no parameter-specific guidance. The schema contains many generic parameters (taskId, feature, statement, etc.) that appear unrelated to matrix generation, and the description doesn't clarify which parameters are relevant or how they affect output. This is a significant gap: an agent cannot infer whether to pass projectRoot only or other fields, leading to potential misuse.

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 clearly states the tool's function: generating a bidirectional V→S→T→SP→PL→TK traceability matrix. It names the specific resource (vdd/ artifacts) and distinguishes it from siblings (vdd_analyze for per-feature spec metrics, vdd_validate for release-readiness). This leaves no ambiguity about what the tool does.

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 when to use the tool ('any time to inspect coverage') and explicitly names two alternatives (vdd_analyze for per-feature metrics, vdd_validate for gates validation). This gives clear decision criteria for an agent choosing among siblings.

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 idempotentHint=true and destructiveHint=false. The description adds valuable context: it writes vdd/impact-report.generated.md, never overwrites a hand-authored vdd/impact-report.md, and explains artifactFiles behavior for serverless runs. It does not specify what happens when a hand-authored report exists (skip vs error), but the disclosure is still strong.

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?

Three dense sentences with no filler: scope, file behavior, usage timing, sibling alternatives, and the artifactFiles caveat are all covered efficiently. The most important information is front-loaded.

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

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

For a complex 10-parameter tool with no output schema, the description covers purpose, timing, alternatives, file output, and a special parameter. Minor gaps remain around return/result behavior and what happens when the hand-authored report exists, but overall it is nearly complete.

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 adds meaningful clarification for artifactFiles, explaining it maps artifact path to content for serverless runs and should be omitted locally. Other parameters are adequately documented in the schema itself.

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') and resource ('the full chain'), then enumerates the concrete checks: traceability matrix, drift detection, orphan detection, uncovered vision goals, impact metrics vs targets, and 28 S&T assumption checks. It also explicitly distinguishes itself from vdd_analyze and vdd_trace, so an agent can tell which tool to use.

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 'Run after implementation is complete' and names alternatives with their conditions: use vdd_analyze for a lightweight per-feature consistency check and vdd_trace for the matrix alone. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations carry destructiveHint=true, and the description elaborates on exactly what gets destroyed ('Overwrites any existing vdd/vision.md'), which is meaningful context beyond the bare flag. It also adds run-once semantics and the cascade limitation with vdd_amend. No contradiction with annotations; it just doesn't describe failure behavior if prerequisites are unmet.

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?

Three dense sentences, each carrying distinct information: what it produces, its requirements, and when to run it versus the alternative. Front-loaded with the verb and deliverable before caveats, with zero 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?

Covers the deliverable path, produced sections, prerequisites (prior vdd_init), phase ordering, revision routing, and input constraints — complete for a file-writing phase tool with no output schema. Minor gaps: no error behavior if vdd_init was skipped and no steering away from irrelevant shared schema parameters.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value by pinning down the statement format ('freeform 1-3 paragraph intent, not a title') and making it effectively required despite the schema marking all params optional. However, it does not clarify which of the 10 shared schema params (e.g., taskId, researchFindings, capabilities) are irrelevant for this 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 (Expand) and resource (freeform vision statement → vdd/vision.md), then enumerates the exact artifact sections produced: Impact Model, Stakeholder Map, Success Metrics, Constraints & Boundaries, Target Domains. Explicitly distinguishes itself from vdd_amend, so an agent can tell them apart 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 sequencing: 'after vdd_init and before vdd_strategize,' plus the 'Run once' rule. Names the alternative outright — 'use vdd_amend so the change cascades instead of re-running this' — with the condition (downstream artifacts exist) that selects it. 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.