mail_bodies

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

Goes well beyond readOnlyHint/destructiveHint=false: discloses that unreadable ids land in `missing` rather than returning empty bodies, that bodies are truncated with an explicit marker, that oversized batches REFUSE with output_overflow, that it reads files at rest without launching Mail, and that Full Disk Access is required. That is a rich behavioral profile; a 5 would need detail on the actual per-body budget size.

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 verb, resource and batch limit, then layers failure modes and storage semantics in short, scannable clauses. Dense but nearly every sentence earns its place; the parenthetical about 'the sender wrote nothing' and the FTS-index comparison slightly pad an already-long block.

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?

Covers what an agent needs to call correctly and recover from failure: batch cap, truncation, overflow refusal with a remedy ('ask for fewer ids'), missing-id semantics, permission prerequisite, and freshness versus the index. An output schema exists, so the extra return-shape prose is surplus but harmless.

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% and the single `ids` array is undocumented in the schema, so the description carries the burden — it supplies the meaningful constraint (up to 20 ids) and defines what happens to invalid/unreadable ids. It does not say what id format is expected (RFC message-id vs Mail's internal id), which leaves one real 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 ('Plaintext bodies for up to 20 message ids in ONE call') with an explicit scope limit and a use-case gloss ('the bulk read behind "catch me up on this thread"'). The batch framing plus the mail_body sibling name differentiates it from the single-message reader 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?

Prescribes the exact call path (mail_search -> mail_thread -> mail_bodies) and notes the shorter path via mail_thread(snippets=True), plus the opt-in/bounded framing. It also contrasts itself against the mail_search(body=) FTS index, telling the agent which source is fresher.

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