Specky

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

Annotations are all false, so the description carries full burden. It discloses that validation and transition occur, and the lgtm condition, but omits important behavioral details such as what happens on validation failure, reversibility, or permission requirements. Adequate but not comprehensive.

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 concise sentences that front-load the core action and follow with a conditional nuance. Every word contributes meaning, no redundancy.

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

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

For a simple phase advancement tool, the description covers the key functionality and a notable conditional. However, it lacks explanation of what constitutes the 'current phase,' required files, or return behavior, leaving some gaps for new users. Still adequate for familiar users.

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. The description adds value by explaining the conditional requirement for the 'lgtm' parameter, which is not fully captured in the schema description alone. Other parameters are sufficiently documented 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 clearly states the tool validates required files and transitions the state machine, with a specific condition about lgtm. It effectively distinguishes this phase-advancement tool from its many siblings (e.g., sdd_checkpoint, sdd_implement) by naming the exact action and resource.

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 implies usage (when you want to advance a phase) but does not specify when not to use it or suggest alternatives. Given the large sibling list, explicit guidance on when to prefer this tool over others would improve clarity.

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 clearly states that the tool modifies CONSTITUTION.md by appending a changelog entry and updating frontmatter. With annotations all set to false, the description adequately conveys the write behavior without destructive side effects.

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

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

Single sentence, front-loaded with the core action, no filler. Every word provides value.

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

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

While the output behavior is clear, the description omits prerequisites (e.g., whether CONSTITUTION.md must exist) and does not mention return values (no output schema). Given the tool's role in a workflow, more context 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?

All 5 parameters are described in the input schema (100% coverage). The tool description does not add new meaning beyond the schema, so it meets the baseline but does not exceed it.

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 specific verbs ('appends', 'updates') and identifies the exact resource ('CONSTITUTION.md'). It clearly distinguishes this tool from its many siblings by focusing on constitutional amendments.

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?

No explicit guidance on when to use this tool versus alternatives (e.g., sdd_write_spec). The description is purely functional, leaving the agent to infer context from the tool name and purpose.

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 creates multiple files and lists them, which adds behavioral context beyond annotations. Annotations indicate non-destructive and non-idempotent, which aligns. No contradiction detected.

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 concise with two short paragraphs, front-loading the key purpose and listing outputs in a clear structure. Every sentence adds value without 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?

Given the rich schema and annotations, the description covers the main purpose, outputs, and formats. It could mention the pipeline steps or output structure, but for an AI agent, the description is sufficient to understand what the tool achieves.

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 description adds context to parameters beyond the schema, such as associating file formats with source applications (Teams, Zoom) and clarifying that raw_text is an alternative to file_path. With 100% schema coverage, the description still provides value.

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

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

The description clearly states the verb (reads, extracts, runs), the resource (meeting transcript), and the output (complete SDD pipeline with five files). It distinguishes from siblings by emphasizing full automation and end-to-end pipeline, unlike more specific tools like sdd_import_transcript or sdd_generate_all_docs.

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 implies when to use: when you have a transcript and want all SDD documents generated. It does not explicitly state when not to use or provide alternatives, but the context of siblings makes the differentiation implicit.

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, destructiveHint=false, idempotentHint=true. The description adds behavior context: compressed files are counted as failed with reason, and only uncompressed ones convert natively. No contradiction detected.

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, front-loaded with the primary action, no wasted words. Every sentence adds value.

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

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

Given 3 parameters, no output schema, and moderate complexity, the description is complete. It covers input format support, a known limitation, and an alternative tool. No gaps remain for effective use.

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 three parameters. The description adds no additional meaning beyond the schema for parameters, but the provided context about compression is relevant to tool behavior, not parameters.

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 scans a directory for supported documents and converts each to Markdown, returning conversion results. It uses specific verbs ('scans', 'converts', 'returns') and distinguishes from sibling tools like sdd_import_document via the batch nature.

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 not to use it: compressed files are not supported natively and provides an alternative (MarkItDown MCP integration) for full Office/PDF support. 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 indicate potential state changes (readOnlyHint=false) and non-destructive nature (destructiveHint=false). The description adds that it runs an 'auto-pipeline' and creates 'feature spec packages' but does not detail side effects, resource usage, or error behavior. The description adds moderate value beyond annotations.

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

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

The description is two sentences, front-loaded with the core function followed by context. Every sentence earns its place with no redundancy or fluff.

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 no output schema, the description hints at output ('each transcript becomes its own feature spec package') but does not explain return format, error handling, or limitations. For a batch tool, more details on concurrency or file size limits would improve completeness. The description is adequate but not thorough.

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 has 100% description coverage with clear parameter descriptions. The description adds no further parameter meaning beyond stating that each transcript becomes a spec package. Baseline 3 is appropriate as schema already provides sufficient semantics.

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

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

The description clearly states it scans a folder for transcript files and runs the full SDD auto-pipeline for each, with specific file types listed. It provides context about Power Automate and OneDrive workflows, making the purpose clear. However, it does not explicitly distinguish from sibling tools like sdd_auto_pipeline, though 'batch' implies multiple files.

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 mentions a typical use case (Power Automate + OneDrive workflows) but does not specify when to avoid using this tool or mention alternatives. It implies batch processing but lacks explicit guidance on prerequisites or when to choose batch over single-file 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?

No annotations are provided, so the description carries the full burden. It describes the output (role, tool access, summary) and the role priority order, which implies it is a read-only diagnostic tool. However, it does not explicitly state that it is non-destructive or require authentication, leaving some behavioral aspects implicit.

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, front-loading the purpose and output, with no redundant or irrelevant information. Every word 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?

Given the tool's simplicity (2 optional parameters, no output schema), the description is complete: it explains what the tool returns, the role priority, and the use case. No critical information 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 description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds context by explaining the overall behavior and the role priority order, but it does not provide significant additional meaning beyond the schema.

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

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

The description clearly states the verb 'Check RBAC access' and the resource 'current caller', specifying what is returned (role, tool access, summary). It distinguishes itself from sibling tools like sdd_check_ecosystem or sdd_check_sync by focusing on access control.

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 mentions it is 'useful for diagnosing permission issues in enterprise deployments', providing clear context. However, it does not explicitly state when not to use it or list alternatives.

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

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

Annotations already cover readOnly, idempotent, non-destructive. The description adds functional behavior (what it reports) but no new behavioral traits beyond the annotations. It does not contradict 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, front-loaded with main action 'Reports which external MCP servers', each sentence adds value without redundancy. Highly concise and 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?

Given no output schema, the description covers what the tool reports but lacks details on the output format or structure. For a discovery tool, it is adequate but could be more complete by hinting at the list nature of the output.

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?

There are zero parameters, so schema coverage is 100%. The description adds no parameter details because none exist. Baseline 4 is appropriate as no compensation needed.

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 it reports recommended MCP servers, their functions, enhancements, and installation steps. It explicitly says 'Run this first' which distinguishes it from sibling check tools like sdd_check_access and sdd_check_sync that focus on different aspects.

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 advises to run this first to understand integrations, providing clear when-to-use guidance. However, it does not explicitly state when not to use it or mention alternatives, though for a discovery tool the guidance is sufficient.

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 reads SPECIFICATION.md and DESIGN.md and writes CHECKLIST.md. Annotations (readOnlyHint false) are consistent with writing behavior. The force parameter is covered in schema but not in description, but overall transparency is good.

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, front-loaded with the core action, no redundant information. Every word serves a purpose.

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 main inputs (domain, files) and output (CHECKLIST.md). It lacks mention of prerequisites (e.g., existence of SPECIFICATION.md) or error conditions, but for a checklist generation tool with clear schema, it is largely 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?

Input schema coverage is 100% with descriptions for all 4 parameters. The description does not add additional parameter semantics beyond mentioning domains. Baseline 3 is appropriate as schema already documents parameters sufficiently.

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?

Description clearly states the tool generates a domain-specific quality checklist by analyzing SPECIFICATION.md and DESIGN.md and writes CHECKLIST.md. The verb 'generates' and resource 'quality checklist' are specific, and the tool differentiates from siblings by focusing on checklists.

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 implies the tool should be used to generate quality checklists, but it does not provide explicit guidance on when to use this tool versus alternatives like sdd_generate_all_docs or sdd_generate_docs. No exclusions or alternative recommendations are given.

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 are all false, and description states it creates a snapshot (mutation). It does not disclose whether overwriting occurs if a checkpoint with the same label exists, nor does it detail side effects like pipeline state changes. Adequate but not thorough.

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, front-loaded with purpose, then usage. Every word earns its place — no fluff.

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 no output schema, the description does not explain return values. It adequately covers what is captured and when to use it, but lacks details on rollback mechanism or pipeline state components. Sufficient for a simple snapshot tool.

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

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

Schema description coverage is 100%, so parameters are well-documented in the schema. The description only adds minimal context (e.g., label examples) beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it 'Creates a named snapshot of all spec artifacts... and the current pipeline state', using a specific verb and resource. It distinguishes from sibling tools like sdd_restore (rollback) and sdd_list_checkpoints (list).

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 'Use before making major changes so you can rollback if needed', providing clear context for when to use. However, it does not mention when not to use or list alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds context that output is a drift report, consistent with annotations. No contradictions.

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

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

Single sentence that is clear and to the point. No wasted words 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?

No output schema, but description mentions drift report. Additional detail about report format or contents 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?

All three parameters have schema descriptions (100% coverage). Description does not add new semantic information beyond the schema.

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

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

Description clearly states the tool compares specification requirements against implementation files and returns a drift report. This specific verb+resource combination distinguishes it from sibling check tools like sdd_check_access or sdd_check_ecosystem.

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?

Implies usage for checking spec-code sync, but no explicit guidance on when to use vs alternatives like sdd_scan_codebase or sdd_run_analysis. No when-not-to-use conditions mentioned.

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 idempotentHint=true, and description confirms it only reads and returns questions. It adds 'up to 5' limit and targeting ambiguity, which is helpful but minimal beyond annotations.

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

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

One sentence, 14 words, front-loaded with action and output. Very concise and clear, though could include brief usage hint without harming conciseness.

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 simple tool with full schema descriptions and annotations, the description adequately covers purpose, input, and output. It could mention no side effects, but annotations already cover idempotency.

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 covers both parameters with descriptions (100% coverage). The description adds no additional meaning beyond what the schema already provides.

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 reads SPECIFICATION.md and returns disambiguation questions. It uniquely targets ambiguous or incomplete requirements, distinguishing it from siblings like sdd_figma_to_spec or sdd_generate_docs.

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 implies usage for clarifying ambiguous requirements but does not explicitly state when to use vs. alternatives or provide exclusions. Sibling tools exist for other spec stages, but no direct alternative is mentioned.

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 COMPLIANCE.md, which contradicts the annotation readOnlyHint=true. This is a serious inconsistency, as a write operation cannot be read-only.

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, concise sentence that front-loads the key action and scope. It is efficient but could be slightly more structured without adding length.

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 main action but does not explain the return value, error handling, or prerequisites (e.g., existence of spec files). Given the absence of an output schema, more information would be beneficial.

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

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

Schema description coverage is 100%, and the description does not add additional meaning beyond what the schema already provides for each parameter. The 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 explicitly states the tool validates specification and design against specified compliance frameworks and writes a COMPLIANCE.md file. This clearly distinguishes it from other sibling tools like generic validation or generation 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?

The description implies usage for compliance checking but does not specify when to use this tool versus alternatives, nor does it mention prerequisites or when not to use it.

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 indicate readonly, nondestructive, and idempotent behavior. The description adds valuable context: it specifies the output includes Hot/Domain/Cold tiers and token load savings. It does not contradict annotations (annotation_contradiction is false).

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 concise sentence that front-loads the purpose and includes all key outputs. No wasted words.

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?

Despite no output schema, the description fully explains what is returned: context tier assignments (Hot/Domain/Cold), token load estimates for current session vs universal loading, and savings percentage. This is complete for a status 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% as both parameters have descriptions. The description does not add meaning beyond the schema beyond mentioning 'active feature' which implies a default behavior. Per guidelines, with high schema coverage baseline is 3.

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 says 'Return the context tier assignment and token load estimates'. The verb is specific ('Return'), the resource is well-defined ('context tier assignment' and 'token load estimates'), and it distinguishes from siblings by focusing on context management, which is unique among the many sdd_* 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?

The description implies the tool is for checking context tiers, but it lacks explicit guidance on when to use it versus alternatives or when not to use it. Given the large number of siblings, more context (e.g., 'Use this to check the performance impact of context loading') would improve the score.

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

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

Annotations already indicate read-only and idempotent behavior. The description confirms non-execution and adds that it returns a command_hint, providing transparency beyond annotations.

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

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

Two short sentences that are front-loaded with the core purpose, followed by a critical usage caveat. No wasted words.

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 low complexity and the absence of an output schema, the description sufficiently explains what the tool does and what it returns. Complete for its purpose.

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?

Input schema has 100% description coverage for all 4 parameters. The description does not add any additional semantic meaning beyond what the schema already provides, so baseline score 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 clearly states it generates a branch name following SDD conventions and returns a command_hint. It differentiates from sibling tools like sdd_create_pr by focusing on branch naming rather than PR creation.

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 it does not execute git commands, guiding the AI to use it for generating commands rather than executing. Could be improved by mentioning when to use this versus other branching tools, but still clear.

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 indicate readOnlyHint and idempotentHint. The description adds transparency by naming the input files (SPECIFICATION.md, TASKS.md) and the output's contents (spec summary, requirements, task progress), which aligns with annotations and provides valuable context without contradictions.

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 long, front-loaded with the primary action, and every word is necessary. No redundant or vague phrasing.

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 purpose (generating a payload for another tool), the description provides complete context: input files, output nature (routing_instructions), and the intended downstream use. No gaps are evident.

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

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

With 100% schema description coverage, the baseline is 3. The description does not add additional meaning beyond what the schema provides, as the schema already documents all five parameters with descriptions and defaults.

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 generates a pull request payload from SPECIFICATION.md and TASKS.md and returns routing_instructions for another tool. It distinctly specifies the verb (generates) and resource (PR payload), differentiating it from sibling tools like sdd_create_branch.

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 implies usage context by mentioning the routing_instructions for GitHub's create_pull_request tool, but it does not explicitly state when to use this tool versus alternatives or provide when-not guidance. This leaves room for 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?

The description claims 'Writes CROSS_ANALYSIS.md', indicating a file creation side effect, which contradicts the readOnlyHint=true annotation. This is a serious inconsistency. Additionally, no further behavioral traits (e.g., permissions, rate limits) are disclosed, and annotations already cover safety but are contradicted.

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 with direct, front-loaded content: purpose, artifacts checked, findings, and output file. No redundant or extraneous information.

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

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

With no output schema, the description should explain what the tool returns or how to interpret the analysis result. It only says 'Writes CROSS_ANALYSIS.md' but does not describe the tool's return value or behavior if files are missing. Adequate for core function but incomplete on response format.

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

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

Schema coverage is 100%, so the schema fully documents both parameters. The description does not add any extra meaning beyond the schema (e.g., no usage tips or format details), resulting in baseline value.

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

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

The description clearly states the specific verb 'checks alignment' and identifies the specific resources (SPECIFICATION.md, DESIGN.md, TASKS.md) along with the outcomes (orphaned requirements, missing designs, untraced tasks) and output file (CROSS_ANALYSIS.md). This distinguishes it from sibling tools like sdd_verify_tasks or sdd_validate_ears.

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 implies usage when cross-artifact consistency is needed, but does not explicitly state when to use vs alternatives or when not to use. The context is clear enough for an agent to infer typical use cases, but lacks explicit exclusion criteria.

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 indicate idempotentHint=true and destructiveHint=false, but readOnlyHint=false, which is ambiguous. The description does not clarify side effects (e.g., whether it modifies state or is purely read). 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?

Two sentences, front-loaded with key purpose, no redundant information. Efficient and clear.

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 explains the output structure but lacks details on how auxillary parameters (spec_dir, codebase_summary, feature_number) influence the questions or behavior. With no output schema, more context on return value could 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 coverage is 100% with descriptions for all 4 parameters. The tool description adds context about output categories but does not elaborate how each parameter affects the questions. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns 7 structured discovery questions tailored to the project idea, covering specific categories. This distinguishes it from siblings that handle later phases or different 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?

The description implies use during initial project discovery but does not explicitly state when to use it versus alternatives like sdd_clarify or sdd_research. No exclusions or when-not-to-use guidance provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it honors include_subtasks, preserves traceability, and importantly returns routing_instructions rather than creating items directly. This goes beyond annotations without 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?

The description is concise with three sentences. The first sentence immediately states the primary functionality and output shapes, front-loading critical information. No redundant or unnecessary words.

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 complexity (three platforms with different structures), the description provides complete context: input source, output shapes for each platform, key parameter behavior, and return value. Since no output schema exists, the description adequately explains what the tool returns (routing_instructions).

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 explicitly noting that 'project_key' is required for Jira (even though not marked required in schema) and that 'include_subtasks' is honored. This provides necessary linkage between parameters and platform-specific behavior.

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 action (transforms TASKS.md), the specific outputs (platform-specific payloads for GitHub, Jira, Azure Boards), and distinguishes it from sibling tools (no other export tool). The verb 'transforms' and resource 'TASKS.md' are precise.

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 implicitly indicates when to use the tool (when needing to export work items to one of the listed platforms). It provides detailed output shapes, but does not explicitly exclude scenarios or mention alternatives. However, given no sibling tools perform a similar function, the guidance is clear.

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 convey read-only and idempotent behavior. The description adds value by specifying the output contains routing_instructions, which is beyond the annotations.

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

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

The description is a single sentence with no wasted words, but could be clearer about the 'routing_instructions' concept.

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 absence of an output schema, the description partially explains the return value (structured data with routing_instructions), but remains somewhat vague.

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. The description does not add parameter-specific details beyond what the schema already provides.

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 it generates a FigJam-ready diagram payload from DESIGN.md with routing_instructions, which distinguishes it from sibling tools like sdd_generate_diagram (likely direct generation) and sdd_figma_to_spec (reverse).

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 implies use as a preparatory step for calling Figma MCP's generate_diagram tool, but lacks explicit when-to-use directives or exclusions compared to 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 readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds that it produces routing_instructions but does not elaborate on side effects or what the payload contains. With annotations present, the bar is lower, but the description could add context about file creation (given spec_dir and force parameters) which is absent.

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: the first states the purpose, the second provides usage instructions. It is appropriately sized, front-loaded, and every sentence adds value. No redundancy.

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

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

Given 5 parameters with full schema coverage and annotations, the description is somewhat complete but lacks explanation of the tool's output format and the fact that it likely generates files (given spec_dir and force parameters). No output schema exists, so the description should provide more behavioral context. Adequate but has gaps.

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

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

Schema coverage is 100% with each parameter having a description. The description does not add significant meaning beyond the schema; it mentions the concept of routing_instructions but doesn't tie into specific parameters. Baseline 3 is appropriate since the schema covers most details.

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 it prepares a structured payload for extracting design context from Figma, which is a specific verb+resource. It distinguishes itself from siblings by mentioning the production of routing_instructions for another tool, though it doesn't explicitly contrast with similar tools like sdd_figma_diagram.

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 implies the tool is a preparatory step before calling Figma MCP's get_design_context, but it does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it. Context is provided but lacks exclusions or conditional logic.

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 that it 'writes the full set to DIAGRAMS.md' and groups by source artifact. Annotations already indicate idempotency and non-destructiveness, and description adds meaningful output context beyond annotations.

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

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

Two concise sentences. Main action in first sentence, output detail in second. No filler, front-loaded, easy to parse.

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 simple tool with 2 params, no output schema, and safe annotations, description is complete. It explains output file and diagram types. Minor gaps: doesn't explicitly state dependency on existing artifacts or batch behavior.

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% (both params documented). Description does not add additional parameter-level meaning, but baseline 3 is appropriate as schema provides sufficient detail.

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 it generates ALL diagram types for a feature, listing specific types (architecture, sequence, ERD, flow, dependency, traceability). Distinguishes from sibling tools like sdd_generate_diagram by emphasizing the 'all' aspect.

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 clear context ('Generates ALL diagram types for a feature in one call') implying use when complete set is needed. However, does not explicitly state when not to use, nor mention alternatives like sdd_generate_diagram for single diagrams.

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 are uninformative (all false). Description adds context: parallel generation and output to docs/ directory. However, it does not disclose idempotency, overwrite behavior, or resource usage beyond 'fastest'.

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, no fluff. First sentence states core purpose and lists types, second specifies output location, third gives value proposition. Front-loaded 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?

Provides key expectations: parallel generation, output directory, coverage of all doc types. However, lacks details on error handling, prerequisites, or whether files are overwritten. Given simplicity, still 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 description coverage is 100% with both parameters documented. The tool description adds no additional parameter information beyond the schema, so baseline score applies.

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

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

The description clearly states the tool generates 'ALL documentation types in parallel' and lists specific types: full docs, API docs, runbook, onboarding guide, and SDD journey. It distinguishes from siblings like sdd_generate_api_docs by emphasizing 'ALL' and 'parallel'.

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 implies use for comprehensive doc generation ('fastest way to generate complete project documentation'), but does not explicitly state when to avoid or prefer alternatives. Sibling tools for individual doc types exist without exclusion 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 description clearly states that the tool writes to a file (side effect) and specifies the input source (DESIGN.md). Annotations are all false, so the description adds behavioral context beyond annotations. However, it does not discuss error handling or prerequisites beyond the input file existence.

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 extremely concise at two sentences, front-loading the core action and then specifying the output. Every sentence adds value with no redundancy.

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

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

For a tool with 2 parameters (both documented in schema) and no output schema, the description adequately explains what the tool produces (structured API documentation with examples) and where it writes the output. It is sufficiently complete for an agent to use without confusion.

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 provides no additional meaning for the parameters beyond what the schema already provides (feature_number pattern and spec_dir default).

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 that the tool extracts API endpoints from DESIGN.md and generates structured API documentation. It specifies the output file pattern (docs/api-{feature}.md), which distinguishes it from sibling tools like sdd_generate_docs and sdd_generate_all_docs that generate more general documentation.

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 implies when to use this tool (when API documentation needs to be generated from DESIGN.md), but it does not explicitly provide guidance on when not to use it or suggest alternatives such as sdd_generate_docs for non-API documentation.

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 that the tool 'writes the file to disk', which is consistent with a non-destructive write. However, it does not mention overwrite behavior or potential side effects like modifying existing configs without confirmation. Given annotations cover safety profile, the description provides adequate but not exceptional transparency.

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 long, front-loaded with the primary action and source. Every sentence adds value without redundancy. It is concise and well-structured for quick understanding.

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 explains the output file's contents (base image, features, extensions, port forwarding) and the detection mechanism. Without an output schema, this is sufficient for an agent to understand what the tool produces. However, it could mention that the tool creates the .devcontainer directory if 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% as all four parameters have descriptions in the input schema. The description adds minimal extra meaning beyond the schema, only implying that features and base_image are configurable. Baseline 3 is appropriate since the description does not significantly enhance parameter understanding.

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 generates .devcontainer/devcontainer.json from the detected tech stack. It specifies the verb 'generates', the resource 'devcontainer config', and the source 'codebase manifests, falling back to DESIGN.md'. This is specific and distinct from sibling tools like sdd_generate_dockerfile.

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 mentions the output is for local use with VS Code Dev Containers or GitHub Codespaces, which implies usage context. However, it does not explicitly state when to use this tool versus alternatives (e.g., sdd_generate_dockerfile) or when not to use it. No comparison or exclusion criteria are provided.

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 convey read-only, non-destructive, idempotent behavior. The description does not contradict annotations but adds minimal behavioral context beyond what annotations provide. It does not disclose any side effects or additional constraints.

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, front-loaded with action, no unnecessary words. However, could be slightly more concise by integrating diagram types list into 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?

With no output schema, the description could mention return value. It adequately covers purpose and diagram types but lacks guidance on usage and output. Adequate for a 4-parameter read-only tool.

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

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

Schema description coverage is 100%, so the schema itself documents parameters well. The description lists diagram types but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a single Mermaid diagram from a specification artifact, and lists all 17 supported diagram types. It distinguishes from sibling tools like sdd_generate_all_diagrams which generates all diagrams.

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?

No guidance on when to use this tool vs alternatives. There is no mention of when to use a single diagram vs generating all diagrams, or when to use different source artifacts. Missing context for appropriate usage.

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 indicate idempotent (idempotentHint=true), non-destructive (destructiveHint=false), and modifying (readOnlyHint=false). The description adds context that the tool uses multi-stage builds for smaller production images, which is beyond annotations. No contradictions.

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, no wasted words. Front-loaded with action (Reads... generates...). Every sentence adds essential 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 generation tool without output schema, the description covers inputs (DESIGN.md or scan results), output (Dockerfile, optionally compose), and key feature (multi-stage). Missing details like format of output or idempotency behavior, but overall 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?

Input schema has 100% description coverage, explaining all four parameters. The description does not add significant meaning beyond the schema, so baseline score 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 clearly states the tool reads DESIGN.md or uses sdd_scan_codebase results to detect tech stack and generates a Dockerfile (optionally docker-compose.yml). This distinguishes it from sibling generate tools like sdd_generate_devcontainer or sdd_generate_iac.

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 implies prerequisites (DESIGN.md or sdd_scan_codebase results) but does not explicitly state when to use this tool versus alternatives. No exclusion criteria are provided, and the alternatives are not 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?

Annotations lack behavioral hints (readOnlyHint=false, destructiveHint=false, etc.), so the description must carry the burden. It mentions writing a file but does not disclose overwrite behavior, failure conditions if input files are missing, or error handling. The agent cannot infer side-effect risks.

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, no fluff. The first sentence states the purpose and inputs, the second the output location. Perfectly front-loaded 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?

With 2 parameters and no output schema, the description covers inputs and output location adequately but lacks details on side effects (overwrite, error on missing files). It is minimally complete but leaves behavioral gaps.

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 both parameters. The description adds little beyond what the schema provides; 'feature_number' pattern and 'spec_dir' default are already clear. 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 clearly states the verb 'generates' and the resource 'comprehensive feature documentation', listing specific input files and output location. It distinguishes from sibling doc generation tools by specifying the exact inputs and output.

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?

There is no guidance on when to use this tool versus other doc generation siblings like sdd_generate_api_docs or sdd_generate_all_docs. The description implies a context but does not provide explicit when/when-not or alternative recommendations.

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?

IdempotentHint clarifies safe to retry; description details output (files, variables, diagram) aligning with read-only generation.

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 concise sentences with no fluff; front-loaded verb and resource.

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 input source, output contents, and diagram generation; lacks error conditions but adequate for generation 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 covers 100% of parameter descriptions; description adds no extra parameter meaning beyond existing 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?

Description clearly states the tool reads DESIGN.md and generates Terraform or Bicep files, distinguishing it from siblings like sdd_validate_iac.

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?

Implies use after DESIGN.md exists, but no explicit guidance on when to use vs alternatives like sdd_generate_all_docs.

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 indicate not read-only and not destructive. The description adds that it writes to a specific file path, implying a side effect, but does not disclose overwrite behavior or permissions. Minimal additional context beyond annotations.

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

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

The description is concise (two sentences) and front-loaded with the tool's purpose and output. Every word adds value with no redundancy.

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

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

Given the tool's low complexity (2 params, no output schema), the description covers the core functionality and output location. However, it lacks details on input sources (e.g., whether it requires an existing spec) and file handling behavior.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The tool description adds no extra semantic meaning beyond the schema, so baseline score 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 clearly states that the tool generates a developer onboarding guide with specific content (feature overview, architecture summary, etc.) and writes to a file. It distinguishes itself from sibling tools like sdd_generate_docs and sdd_generate_runbook by specifying its unique output.

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 no guidance on when to use this tool versus alternatives, nor any prerequisites or conditions. Siblings like sdd_generate_docs and sdd_generate_runbook exist but no differentiation is given.

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 indicate the tool is not read-only, not destructive, and not idempotent, which aligns with generating test files. The description adds that it extracts properties and generates files, but doesn't mention file overwrite behavior or output structure, so it adds modest value beyond annotations.

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

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

The description is two sentences, front-loading the core action and differentiation, with no wasted words. It efficiently conveys the purpose and key distinction.

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 4 parameters, no output schema, and the complexity of PBT generation, the description covers the essential purpose, source (EARS), and output (test files with specific frameworks). It could mention where files are created or that output_dir is used, but the schema covers that; overall it is sufficiently 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?

100% schema coverage means the schema already describes each parameter. The description does not add further explanation or usage hints for parameters, so it meets the baseline without additional value.

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

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

The description clearly states it extracts universal properties from EARS requirements and generates PBT files using fast-check or hypothesis, and explicitly differentiates from example-based tests, distinguishing it from sibling tools like sdd_generate_tests.

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 contrasts PBT with example-based tests and specifies the applicable frameworks, giving context for when to use this tool. However, it does not explicitly list when not to use it or mention any prerequisites like the presence of EARS requirements.

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 are all false, so description carries full burden. It mentions generating and writing a file but lacks details on idempotency (overwrite vs. append), side effects, or prerequisites. Minimal behavioral 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?

The description is a single sentence that efficiently conveys purpose and output. No unnecessary words 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?

No output schema exists, but the description does not clarify what the tool returns (e.g., confirmation, file path). It also omits behavior when the target file already exists. Incomplete for a file-generating 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% and both parameters are described in the schema. The description adds no extra semantic information beyond what is already 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 clearly states it generates an operational runbook with specific sections (deployment, monitoring, troubleshooting, rollback) and specifies the output file pattern. This distinguishes it from sibling generation tools like sdd_generate_docs.

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 implies usage for creating runbooks for features but provides no explicit guidance on when to use this tool versus alternatives like sdd_generate_docs or sdd_generate_api_docs. No when-not or alternative examples.

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 (readOnlyHint=false, destructiveHint=false) provide no safety info. The description mentions 'generates', implying file creation, but does not disclose potential side effects like overwriting existing files, or permissions needed. This is a significant gap for a mutation tool.

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 efficient sentences: first defines action and source, second adds frameworks and traceability. No wasted words; ideal length.

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 core purpose and framework support, but lacks details on output format, when to use relative to siblings like sdd_generate_pbt, and expected behavior when spec files are missing. Given no output schema, more context would be valuable.

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 'traces to a requirement ID', which is not in the schema, but this is marginal. The parameter descriptions in the schema already adequately convey meaning.

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 'Generate test stubs from acceptance criteria in SPECIFICATION.md and TASKS.md.', which provides a specific verb and resource. It distinguishes from siblings by focusing on test stubs and mentioning traceability, making it clear 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?

The description implies usage when test stubs are needed, but does not explicitly guide when to use this tool vs alternatives like sdd_generate_pbt or sdd_verify_tests. No exclusions or conditions are given.

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 (readOnlyHint, destructiveHint, idempotentHint) already cover behavioral safety. Description adds no further behavioral details (e.g., output format, side effects). With rich annotations, this is adequate but not exceptional.

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, front-loaded with action verb, no redundant information. Every word 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?

Given full schema coverage and rich annotations, description is nearly complete. It specifies input and output (user stories, acceptance criteria, Mermaid diagrams). Minor gap: does not clarify whether output is returned directly or written to disk, but annotations imply read-only.

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%; each parameter already has clear description. The tool description adds no additional parameter semantics, so baseline 3 is appropriate.

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

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

Description clearly states verb 'generates' and resource 'user stories with acceptance criteria and flow diagrams' and specifies input file 'SPECIFICATION.md'. It distinguishes from sibling tools like sdd_generate_docs and sdd_generate_diagram by focusing on user stories.

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?

Description provides context by specifying input from SPECIFICATION.md, implying use when generating user stories from that file. However, no explicit when-to-use or when-not-to-use guidance, nor alternatives cited amidst many sibling 'generate' 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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, establishing it as a safe, read-only operation. The description adds value by detailing the return content (phases, files, percentage, next action), but does not disclose any additional behavioral traits (e.g., whether it requires a running pipeline, rate limits, or side effects). 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 a single, well-structured sentence that lists key return fields. No redundant or extraneous information. It is front-loaded with the core purpose ('Returns the current pipeline status') and efficiently details the content. Every word 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?

Given the tool's simplicity (2 optional params, no output schema), the description adequately covers the return fields and intended use. It could be more complete by noting the return format (e.g., JSON) or potential error conditions, but for a basic status query, it provides sufficient context for an AI agent to use it correctly. Annotations cover safety fully.

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 has 100% description coverage for both parameters (spec_dir and feature_number), each with clear, self-explanatory descriptions. The tool description does not add any further semantic information beyond what the schema already provides. Baseline score of 3 is appropriate when schema does the heavy lifting.

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

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

The description explicitly states the tool returns 'current pipeline status' and lists specific fields (current phase, completed phases, etc.). It clearly distinguishes this from siblings like sdd_advance_phase (which advances the pipeline) and sdd_context_status (which might return context rather than pipeline status), making the purpose specific and unambiguous.

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 no guidance on when to use this tool versus alternatives (e.g., sdd_checkpoint, sdd_context_status). It only states what it does, without mentioning preconditions, exclusion criteria, or when not to use it. This lack of usage context limits its utility for an AI agent choosing between similar 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 declare readOnlyHint, idempotentHint, and destructiveHint; the description adds that templates are returned with placeholders intact and that no files are written, reinforcing the safe, idempotent nature without 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?

The description is two sentences: the first states the core action, the second clarifies a key behavioral qualifier. It is front-loaded, efficient, and contains no superfluous 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 simple retrieval tool with one parameter and no output schema, the description sufficiently conveys what is returned (raw Markdown with placeholders) and what is not done (file writes). It is complete enough for agent use.

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 schema covers the single parameter (template_name) with an enum and description. The tool description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns a raw Markdown template with placeholders intact and explicitly notes it does not write files. It uses a specific verb (returns) and resource (template), distinguishing it from sibling tools that generate or write content.

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 implies usage for previewing templates without side effects via 'Does not write any files,' but lacks explicit when-to-use or when-not-to-use guidance or alternatives 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 readOnlyHint=true and idempotentHint=true. The description reinforces that it reads a file and generates a plan, which is consistent. No additional behavioral traits beyond what annotations indicate.

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 concise sentences, front-loaded with the primary action and outcome. Every phrase adds essential information without redundancy or fluff.

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?

Despite lacking an output schema, the description effectively communicates what the tool produces (ordered implementation roadmap with details). The constraints (reads a specific file, does not write code) are clear, making the tool's function fully understandable.

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?

Input schema has 100% coverage with descriptions for all 4 parameters. The description adds context about the output (phases, parallel groups, dependency resolution, checkpoints), which relates to the 'checkpoint' parameter and overall purpose, adding value beyond 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 explicitly states it reads TASKS.md and produces an ordered implementation roadmap, and clearly distinguishes itself from code generation. Among 50+ sibling tools, this purpose is unique and unambiguous.

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 clearly states what the tool does and does not (does not write code), providing usage context. However, it does not explicitly mention when to use versus alternatives or when not to use.

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