word_generate_sow

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so no contradiction. Description adds behavioral context: requires a template, fills placeholders/tables but not prose, strips boilerplate, returns status with next_tools suggestions. Exceeds annotation coverage.

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 well-structured with important notes in caps, a numbered workflow, and an example. Every sentence adds value; 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 states return type (status dictionary with file path and next_tools suggestions). Covers all four parameters (three required with detail, mode mentioned in schema but not described; however, enum suffices). Explains constraints and integration with sibling tools.

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 75% (mode missing description). Description adds value beyond schema by detailing the sow_data structure with an example, and explains template_path must come from copy_template. The Args section maps to schema but provides additional context.

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 SOW document from a template and structured data, and explicitly notes it fills placeholders and tables but does not generate prose sections. This distinguishes it from siblings like word_patch_with_track_changes and word_create_sow_from_markdown.

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 a step-by-step workflow (copy_template -> generate_sow -> patch_section -> audit_completion -> cleanup_sow), explicitly tells when to use this tool (after copying template, before patching sections), and what it does not do (generate prose). Also includes an example.

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