gmail_create_draft

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, meaning the agent knows this is a non-destructive write operation (creating a draft is not destructive). The description adds the useful 'never sends anything' behavioral trait, which is valuable context beyond annotations. However, it doesn't mention persistence behavior, quota implications, or return value details beyond what the output schema provides. With annotated safety profile, a 3 is appropriate.

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?

Extremely efficient - two short paragraphs, three sentences total. The first sentence states core purpose and the critical 'never sends' caveat. The second paragraph adds the thread_id operational detail. Zero wasted words, 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?

The tool has an output schema (which handles return-value documentation) and moderate complexity with 5 params. The description covers the primary behavior (creating drafts), the non-sending guarantee, and the thread reply mechanism. Remaining gaps are minor - the account parameter is undocumented and there's no explicit statement about how the created draft becomes usable with gmail_send_draft, though this is implied by the sibling relationship. For a draft-creation tool, this is reasonably complete.

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 0%, so the description carries the full burden for parameter meaning. The description explicitly explains thread_id semantics (for replies within a thread, auto-header generation), which the schema alone wouldn't convey. The required params (to, subject, body) are self-evidently named, but the optional thread_id and account parameters benefit from the explanation. The description partially compensates for the 0% coverage, though it doesn't address the account parameter.

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 verb 'Create' plus resource 'a draft email' is specific and clear. It explicitly notes 'This never sends anything', which distinguishes its scope from send operations. The sibling tool gmail_send_draft exists, and the description clearly differentiates this tool's purpose of only drafting, not sending.

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 explicitly states when to use it (to create drafts that never send). It even provides guidance on the optional thread_id usage for replies within existing threads, including the benefit it provides (auto In-Reply-To/References headers). While it doesn't explicitly name gmail_send_draft as the alternative, the 'never sends anything' statement clearly signals this is the drafting counterpart and distinguishes use versus the send tool.

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