edit_office_document

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

The description explicitly warns that omitting output_path overwrites the input file in place, using all-caps emphasis. It also discloses the backup safety net ('pass options {"backup": true} to keep a .bak copy'). This adds significant behavioral context beyond the annotation's destructiveHint=true, which the description fully supports.

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 three sentences with no filler. The first sentence states the core function and operation types, the second warns about the critical overwrite behavior, and the third names the alternative tool. Each sentence earns its place and the most important safety information is front-loaded.

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 complex mutation behavior, destructive annotation, and no output schema, the description covers all essential aspects: what it modifies, what operations it supports, output path behavior, backup mitigation, and the alternative for creating new documents. The schema fills in all remaining parameter details, making the description complete for correct invocation.

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 each parameter already has a meaningful description. The tool description adds value by clarifying the consequence of omitting output_path (overwrite) and mentioning the backup option in options, which supplements the schema's default-value note. It also emphasizes the 'ordered list' nature of operations, which is not explicit 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 opens with a specific verb+resource ('Modify an existing Office document') and lists the exact operation types (replace, delete, modify, style, add, clear). It explicitly differentiates this tool from create_office_document, stating 'To generate a new document, use create_office_document.' This leaves no ambiguity about 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 clearly indicates this tool is for modifying existing documents and directs users to create_office_document for generating new documents. However, it does not discuss other sibling tools like fill_template, convert_document, or extract_document_data, so the guidance is partial rather than comprehensive.

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