GenOffice docx patch (byte-preserving)

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

With no annotations provided, the description carries full burden and does well: it discloses that the original file is never modified (writes a new patched file), explains the byte-preservation mechanism (untouched blocks keep original bytes, only edited blocks regenerated as OOXML fragments), and states that paragraph formatting (styleId/rawPPr) is carried over. It does not disclose error conditions or edge cases, but covers the core behavioral guarantees clearly.

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 well-structured, front-loaded single paragraph starting with the primary action, followed by the key guarantee (byte-preserving), then input/output format. Every sentence adds meaningful information with zero waste. The input/output mention at the end is compact.

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

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

For a 3-parameter tool with 100% schema coverage and no output schema, this is complete: it explains the byte-preserving mechanism, the index sourcing dependency, the input format, the output behavior, and the safety guarantee (never modifies original). The sibling genoffice_docx_blocks is explicitly referenced for index sourcing, which is the key inter-tool dependency. No output schema exists, but the description clarifies the output is a new patched file.

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 beyond the schema by explaining the edits format [{index, text}] and clarifying that index refers to the 0-based visible order from genoffice_docx_blocks, which is essential meaning not fully captured in the schema alone. It also confirms that formatting is carried over, which the schema doesn't state.

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 has a specific verb+resource ('Rewrite paragraphs of a .docx using the GenOffice byte-preserving roundtrip') and clearly distinguishes from siblings by emphasizing the byte-preserving property and the 'patch' nature (regenerate only edited blocks). It names the sibling genoffice_docx_blocks for index sourcing, which differentiates it well from create/delete/watermark tools.

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

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

Explicitly states that index values come from genoffice_docx_blocks (0-based visible order), providing a clear dependency. It states when to use this tool (to edit paragraphs without disturbing other parts) and implicitly distinguishes from genoffice_docx_delete (which removes blocks). The byte-preserving guarantee gives clear context for when this is the right choice over other patch tools.

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