email_get_attachment

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

No annotations are provided, so the description carries full burden. It discloses that the return is base64 encoded data, which is useful, but doesn't mention whether the attachment data is large, whether there are size limits, what error conditions exist (e.g., missing attachment), or whether this requires prior sync. For a read operation that returns potentially large payloads, more behavioral detail would help.

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 sentence, zero wasted words. It communicates purpose and return format efficiently. A single sentence is appropriate for what is a straightforward fetch operation.

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 no annotations, no output schema, and 0% schema coverage, the description must do heavy lifting. It covers purpose and return format but omits how to discover attachment IDs, potential size limits, and interaction with the sync/staging tools. Adequate for a basic fetch but leaves meaningful gaps for a tool with three required parameters and no schema documentation.

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 compensates partially. It explains that attachmentId is used to identify the attachment, and the base64 encoding note helps understand the return. However, it doesn't explain how to obtain attachmentId or how attachmentId relates to the emailId parameter—whether it's nested under email or globally unique. The required trio (accountId, emailId, attachmentId) semantics are left to inference.

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?

Description states the verb (Get), resource (email attachment), identifier used (by ID), and explicitly says the return is base64 encoded data. This is clear and specific. However, it doesn't distinguish from sibling tools like email_get, email_get_thread, or the mail_attachment_* staging tools, though the base64 return detail adds useful specificity.

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?

No guidance on when to use this vs alternatives. There are sibling tools like mail_attachment_stage, mail_attachment_list, and mail_attachment_create which could overlap in purpose, but the description says nothing about when to choose this over them or about prerequisites (e.g., requiring accountId/emailId context).

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