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

Annotations only declare the coarse safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false, idempotentHint=false), so the description adds substantial value: dedupe behavior for already-saved attachments, the spam and inline-image exclusions, per-file cost, and a 30-day retention on the source email. The only gap is that the partial dedupe semantics sit somewhat awkwardly against idempotentHint=false without explanation of what still repeats on a second call.

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 opening sentence and exclusions are well front-loaded, but the pricing is stated twice ('$0.001 per file saved' then 'Costs $0.001 per file saved; nothing if none are found'), which is visible duplication that should be collapsed into one clause.

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 one simple parameter, no output schema, and annotations already covering the safety profile, the description covers the important unknowns: side effects, cost, retention, exclusions, and how to read the saved files. The missing piece is how the agent learns which files were created on a given call, since there is no output schema to describe the return.

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 coverage is 0% — message_id carries only a 36-character length constraint and no description. The description compensates partially by specifying that the id must belong to a received email, but it never says where to obtain the id (email_list_messages / email_get_message) or what form it takes beyond the implicit length.

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 ('Save the attachments of one received email into the file store'), plus the resulting linkage to the email and the follow-up read path. An agent can distinguish this from sibling tools like email_get_message or files_upload 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?

Explicit when-not conditions: inline pictures such as signature logos and mail marked as spam are not saved, and only attachments of a received email qualify. It also names the concrete follow-up alternatives (files_read_text, documents_read_pdf, files_ocr) for consuming the result, leaving nothing to inference.

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