Read mail attachment

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

Annotations only indicate readOnlyHint, but the description goes far beyond by detailing content-type dispatch (pdftotext, Pandoc/LibreOffice, etc.), image handling with downscaling/refusal, error behavior for unsupported formats, and calendar invite summary rendering. This is rich behavioral context with no contradiction.

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 concise yet complete, starting with a clear summary, followed by necessary technical details, and ending with parameter definitions. No sentence is wasteful; the structure is logical and front-loaded.

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 covers expected return formats (text, image, summary) and error cases. It also notes prerequisites and limitations, making the tool's behavior fully comprehensible for an agent.

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?

Although schema coverage is 0%, the description includes an 'Args' section that explains both parameters. message_id is tied to specific sources ('as seen in mail_search/mail_read_thread output') and part_index is defined as '1-based part index from mail_list_attachments', adding meaning the schema lacks.

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 opens with a clear, specific statement: 'Read one attachment: text, PDF, image, office document or calendar invite.' This identifies the verb, resource, and scope, and distinguishes it from sibling tools like mail_list_attachments and mail_read_message by focusing on attachment content.

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?

Explicit guidance is provided: 'Call mail_list_attachments first to get a valid part_index.' It also clarifies unsupported types ('Archives and other binary formats are not supported') and explains the prerequisite, making the when-to-use and when-not-to-use clear.

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