list_attachments

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

With no annotations supplied, the description carries the full burden and does disclose meaningful behavior beyond the schema: inline images are included and flagged via is_inline, and attached emails and cloud links are reported as not saveable. It does not cover error behavior for an invalid message_id or whether the list is paginated, which keeps it from a 5.

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?

Three tight sentences: the first front-loads what is returned, the second adds the caveat that matters, the third gives the call condition. No filler or restatement of the tool name, and the most decision-relevant information comes first.

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?

There is no output schema, so the description must describe return values, and it does so field by field, including the derived is_inline and saveability flags. Given a one-parameter read tool, the remaining gaps (ID format, pagination, empty-result behavior) are minor rather than disqualifying.

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% for the single message_id parameter, so the description must compensate. It implies the parameter scopes the call to one message but never states the expected identifier format (e.g. an ID obtained from list_messages or search_message_ids), leaving a real gap for a required parameter.

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 (list the attachments on one message) and enumerates the returned fields: id, name, content type, size, saveability and is_inline. It also distinguishes itself from the sibling save_attachment by explaining which attachments that tool can handle, so an agent can separate listing from saving without opening either 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?

Gives an explicit trigger condition: call it when a message has has_attachments=true and the user wants to know or read what is attached. That is a clear when-to-use rule, and the save_attachment remark implies the handoff path. It stops short of naming exclusions, e.g. that message metadata itself should come from get_message.

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