mail_attachment_create

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

With no annotations provided, the description carries the full burden. It mentions size preflight and per-file limits in the schema sub-definitions (bounded size, per-file limit) which adds some behavioral context. However, it doesn't disclose what the tool returns (attachment ID? reference?), whether creation is reversible, or storage implications. The schema definitions do add some value regarding encoding validation but the description itself adds minimal behavior beyond 'store this content'.

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?

A single sentence that efficiently conveys the action and purpose. There is zero waste, and the description is front-loaded with the verb and resource. No filler or redundant phrasing.

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 creates attachment content but the description doesn't explain the returned artifact (how the agent references this attachment later in email_send or email_draft_create), the content size limits, or whether content_type defaulting behavior matters. Given it has an output schema and 3 params with zero schema coverage, more detail about the return value reference and size constraints would improve completeness.

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 compensate. The description says files are 'text/base64' which maps to the two content kinds (text/base64), and the sub-definitions provide descriptions of encoding and validation. However, filename semantics (extension handling, uniqueness) and content_type behavior are not explained in the description, and the schema itself has no descriptions for those fields.

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 clearly states the verb (create), the resource (agent-generated text/base64 file), and its purpose (for later send or draft attachment). It distinguishes this from mail_attachment_stage and mail_attachment_list by focusing on creating inline content rather than listing/staging. Lacks explicit mention of what makes it different from email_draft_create but is adequate for the core verb+resource.

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 implies usage context (creating an attachment for later use in send or draft) but doesn't explicitly state when to prefer this over mail_attachment_stage or how results connect to email_send/email_reply. It names a sibling tool implicitly ('later send or draft attachment') but doesn't provide explicit exclusions or alternative guidance for the sibling attachment tools.

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