update_draft

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

Goes well past the annotations (which only say non-read-only, non-destructive, non-idempotent) by disclosing merge semantics (empty fields = unchanged), attachment retention and removal rules, header preservation, and notably the lossy behavior that a Gmail-written HTML body is replaced by plain text. That last point is a data-loss caveat an agent could not infer from any structured field.

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 lead paragraph is front-loaded with the core action and the most important constraint (no sending), then the merge rules. The Args block is well-structured but somewhat redundant with the prose for to/subject/cc/bcc, repeating the "empty = keep" rule twice.

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 an 8-parameter mutation with 0% schema coverage, the description covers every parameter, the merge/preservation model, attachment add/remove interplay, and where draftId comes from (create_draft or list_drafts). Return values are handled by the existing output schema, so no gap remains.

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 0%, so the description carries the full burden and largely meets it: each of the 8 args is explained, including the non-obvious "empty to keep" semantics for to/subject/cc/bcc, absolute-path attachment input, and exact-name matching for removeAttachments. It stops short of format examples (address string vs array) despite the schema allowing both.

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?

States a specific verb and resource ("Replace the text of an existing draft") and immediately scopes it with "without sending it," which separates it from send_draft, while "existing draft" separates it from create_draft. The preservation of In-Reply-To headers further pins down what kind of replacement this is.

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 "without sending it" clause gives a clear condition that excludes send_draft, and create_draft is named as the reference point for attachment rules. However there is no explicit "use this instead of X when..." statement for the edit-vs-create-vs-send decision, so the routing is implied rather than spelled out.

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