gmail_create_draft

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly states the tool never sends anything, which is a critical safety behavior. It also explains the reply_to_message_id side-effect on In-Reply-To/References/threadId. It does not cover auth requirements, error handling, or return values, but for a draft creation tool, the primary behavioral trait (non-sending) is well disclosed.

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 two sentences long, with the most important information (purpose and non-sending) front-loaded. Every sentence earns its place: the first establishes the core behavior, the second explains the reply use-case. No filler or redundancy.

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 tool's moderate complexity (6 params, no output schema, no annotations), the description covers the essential context: what it does, what it does not do, and how to use the reply feature. It does not describe return values or error scenarios, but for a draft-creation tool, an agent can infer that the draft is created successfully without explicit return details. The description is adequate 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 0%, so the description must add meaning to parameters. It does this for reply_to_message_id by explaining its function, which is a meaningful addition. The other parameters (to, subject, body, cc, bcc) are self-explanatory given their names and types, so they need no elaboration. The description adds value where needed but does not comprehensively document all parameters, hence a baseline of 3.

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 states a clear verb-resource pair ('Create a Gmail draft') and immediately clarifies the key distinction: 'Never sends anything, the draft sits in Drafts.' This makes the tool's purpose unambiguous and separates it from sending actions. It also hints at a specific use case (replying in a thread) without naming siblings, but the core purpose is explicit.

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 provides a concrete usage guideline for the reply_to_message_id parameter, explaining that it sets the draft as a reply in an existing thread. It implicitly tells the agent when to use this tool (when a draft is needed) versus sending, but does not explicitly name alternatives or state when not to use it. The non-sending behavior is a strong contextual cue.

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