send_mail

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

Annotations include readOnlyHint=false and destructiveHint=false, but idempotentHint=false indicates non-idempotent operations. The description mentions 'Requires user approval' and 'matching digest' which adds context, but doesn't explain what the digest is, how to obtain it, or behavioral details like email delivery semantics, rate limits, or failure modes. For a tool that actually dispatches emails, the description should disclose side effects more clearly.

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?

One concise sentence that packs essential usage constraints (approval, confirm value, digest matching). Zero waste, front-loaded with the core action. Could be slightly more structured but is efficient.

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 0% schema coverage and 8 parameters, the description leaves significant gaps. The digest parameter is mentioned in passing but its purpose/source is unexplained (it must come from preview_send presumably, but this isn't stated). The 'previewed draft' reference implies a workflow dependency on preview_send but doesn't make it explicit. With an output schema present, return values are covered, but the input semantics are underspecified for an 8-parameter send operation.

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 full burden. It mentions 'confirm='SEND'' and 'matching digest' — these are critical parameter semantics (the confirm const and digest matching requirement). However, it doesn't explain to, subject, body_text, cc, bcc, or attachments, which the schema itself only labels with names and types. With 8 parameters and 0% coverage, the description should compensate more.

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 says 'Send the previewed draft,' which identifies the verb (send) and resource (previewed draft). However, it doesn't clearly distinguish this from preview_send or other mail actions, and 'previewed draft' is somewhat vague without explaining the preview→send workflow connection.

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 implicitly conveys when to use this tool (after previewing, requires approval, confirmation token 'SEND', and matching digest). It implies a workflow context with preview_send but doesn't name sibling tools explicitly or describe when NOT to use it.

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