GenOffice docx create

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

With no annotations, the description carries the full transparency burden. It discloses key creation semantics: builds a new file, writes to outPath, each string becomes a paragraph, enables line breaks within a paragraph. This behavioral detail (paragraph mapping and line-break handling) goes beyond what the schema states. Missing info about overwrite behavior or return values, but the write-target is explicit.

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, focused and front-loaded with the core purpose. The paragraph interpretation detail is valuable but the parenthetical is slightly dense. Overall efficient with 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?

For a simple 2-param creation tool with 100% schema coverage and no output schema, this is largely complete. The paragraph-to-paragraph mapping is explained, line-break handling is documented, and the write target is specified. Could mention what it returns or overwrite behavior, but for a straightforward creation tool the coverage is adequate.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real value beyond the schema: it maps array elements to paragraphs, explains that strings map 1:1 to paragraphs, and details handling for line breaks within paragraphs. The outPath parameter gets additional clarity as the write destination. This exceeds what the schema alone 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?

Clear verb+resource: 'Create a NEW .docx from scratch' distinguishes it from siblings like genoffice_docx_patch and genoffice_docx_watermark which modify existing files. Names the engine function (buildBlankDocx), adding implementation context. The 'NEW' emphasis explicitly differentiates from patch/delete/watermark siblings.

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

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

States when to use it (creating from scratch) and what optional content can be passed. Doesn't explicitly name alternatives or state when NOT to use, but 'Create a NEW .docx from scratch' effectively implies it's the creation tool versus the sibling modification tools. Could be stronger with explicit exclusion guidance towards patch tools.

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