find_large_messages

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

With no annotations, the description carries the full burden and does well: it discloses that only the newest `scan` messages are examined (default 1000, capped at 5000), that sizes include attachments and inline images, and that ids are returned. It does not state that this is a read-only operation or what happens when fewer than `top` messages qualify.

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 short lines, purpose front-loaded, then scan/return semantics, then the cutoff. No filler and no repetition of the schema's defaults except where the cap (5000) adds information the schema lacks.

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?

For a read-only scan tool with no output schema, the description covers the sampling window, returned fields, and filtering well enough to invoke correctly. Minor gaps remain around read-only safety and what the returned ids are useful for downstream.

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%, so the description must compensate, and it gives meaning to every parameter: `top` is the returned count, `scan` is the newest-N window with default and max, `min_size_mb` is a lower cutoff, and `folder` is implied by "in a folder." It never explains the `folder` default (inbox) or what folder identifiers are accepted.

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 names the specific resource (largest messages in a folder) and the goal (freeing storage), which distinguishes it from listing/search siblings. It doesn't contrast against near-neighbors like find_bulk_mail or mailbox_overview, so the differentiation is implicit rather than explicit.

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?

"For freeing storage" implies the use case, and describing the scan window implies this is a sampling tool rather than an exhaustive search. However, there is no explicit when-to-use/when-not guidance and no named alternative for mailbox-wide size analysis.

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