Get an email attachment

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

Goes well beyond the readOnly/idempotent annotations by disclosing the ~5 minute link expiry, the lack of an auth header requirement on the returned URL, and the exact error shape for unknown ids. These are the operational traits an agent must plan around and none are derivable from structured fields.

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?

Front-loads the purpose, then layers provenance, return shape, expiry, and error behavior in a compact block with no filler. Slightly redundant to spell out the return shape when an output schema exists, but it is short enough to earn its place.

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 a rich annotation set and an output schema present, the description still adds the pieces that matter: expiry window, auth-free fetching, and not-found behavior. The only missing element is the meaning of the required email_id parameter.

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 carries the burden. It fully documents attachment_id's provenance but never explains email_id's role or why both are required — an agent may wonder whether attachment_id alone would suffice. Partial compensation for a real coverage gap.

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 — returns a fetchable URL for one inbound email attachment — and explicitly links the input to ``get_email``'s attachments list, distinguishing it from sibling tools like get_email and get_email_raw. An agent knows exactly what it gets back without opening the 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?

Clearly establishes the trigger path: the attachment_id must come from an item in get_email's attachments list, which effectively tells the agent to call get_email first. It also explains what to do with the result (fetch bytes directly with no auth header). It stops short of naming an alternative to use instead or stating when the tool should not be used.

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