List drafts

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

The annotation readOnlyHint=true already declares the safety profile, and the trailing "Read-only." merely restates it. What the description genuinely adds beyond structured data is the returned field set (draftId, message id, thread id, date, recipients, subject, snippet) and the linkage that draftId is required by send_draft — but with no output schema, this still leaves the exact response shape to inference.

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?

Three short sentences, front-loaded with the action and result contents, then usage, then the handoff to read_email. Nothing is padded; the only near-redundancy is the two-word "Read-only." closing.

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 no output schema, the description compensates well by enumerating the fields returned and flagging the one field (draftId) that unlocks a sibling tool. For a two-optional-parameter read tool, an agent has everything needed to select and call it 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 coverage is 100% and both parameters are fully documented in the schema, so the baseline applies. The phrase "in one mailbox" hints at the account parameter's role but adds no detail on alias/local-part handling or result-limit behavior beyond what the schema already says.

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 ("List the drafts saved in one mailbox") and immediately differentiates scope: listing only, not reading full text. An agent can distinguish it from send_draft, create_draft, and read_email without consulting any schema.

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?

Gives two concrete use cases ("check what is waiting to be sent" and "find a draft made earlier with create_draft") and an explicit alternative with its trigger condition ("To read a draft's full text, pass its message id to read_email"). The routing decision is fully determined.

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