safe-docx

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

Annotations establish this is a destructive write operation. The description adds critical behavioral context: 'preserving formatting' (distinguishes it from raw text replacement) and 'Supports DOCX and Google Docs' (scope). However, it omits error behavior (missing old_string), occurrence handling (first vs all), and whether it creates tracked changes.

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?

Extremely concise single sentence with zero fluff. Front-loaded with action verb. However, given the high complexity (7 parameters, destructive operation, dual file-type support), the brevity becomes underspecification rather than efficient communication.

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?

Inadequate for a 7-parameter destructive mutation tool with no output schema. The description omits required context: the 'instruction' parameter's purpose, error handling, return value indicators, and guidance on obtaining paragraph IDs. Given the destructiveHint and low schema coverage, the description should provide significantly more safety and usage context.

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 only 43% with 0% coverage for required parameters (target_paragraph_id, old_string, new_string, instruction all lack schema descriptions). The description hints at target_paragraph_id format via '_bk_* id' but fails to document the critical 'instruction' parameter or clarify the mutual exclusivity of file_path vs google_doc_id. Insufficient compensation for schema gaps.

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?

Clear verb 'Replace' and resource 'text in a paragraph'. Distinguishes from siblings by specifying '_bk_* id' targeting mechanism and 'preserving formatting' (vs clear_formatting/insert_paragraph). Would be 5 if it explained the cryptic '_bk_*' notation for users unfamiliar with the bookmark ID format.

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 when-to-use guidance or alternative recommendations. While 'by _bk_* id' implies specific targeting capability, it doesn't contrast with sibling tools like insert_paragraph (for new content) or grep (for searching), nor does it mention prerequisites like obtaining the paragraph ID first.

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