Edit a Google Doc in place

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

Annotations already mark destructiveHint=true, but the description adds essential context beyond that: it explicitly warns that rewrite is destructive, explains the confirm flow, and reveals the failure reporting behavior (zero matches reported as failure, never silent success). It also justifies the index-free design, which helps agents understand constraints. No contradiction with annotations.

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 long but each sentence carries meaningful operational detail. It front-loads the core purpose and then systematically explains both modes and their warnings. While not maximally terse, the density of useful information justifies the length; a minor deduction for being more verbose than strictly necessary.

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?

With six parameters, two operation modes, and a destructive rewrite path, the description covers all essential usage guidance: prerequisites (read_doc first), confirmation workflow, error behavior, and the rationale behind index-free edits. Since there is no output schema, the description appropriately focuses on invocation and side effects, making it complete for an agent to call correctly.

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 83%, but the description substantially enhances parameter meaning: it explains the two distinct call shapes (replacements array vs rewrite string), clarifies that rewrite:"" empties the document, gives the role of confirm and confirmCells, and notes matchCase:false ignores case. This goes well beyond the bare schema and aids correct invocation.

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 'EDIT a Google Doc' and explicitly characterizes it as 'the correction append_to_doc cannot make', naming the sibling it differs from. It further distinguishes two concrete modes (replacements and rewrite), so an agent can immediately grasp the verb, resource, and scope without ambiguity.

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 explicit step-by-step usage: for replacements it instructs to call read_doc first and match text exactly, including matchCase:false semantics; for rewrite it dictates the two-phase confirm flow (call without confirm to get character count, then confirm:true + confirmCells). It also names the alternative append_to_doc and clarifies when each mode applies.

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