read_mail

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds meaningful context: it uses BODY.PEEK specifically to preserve unread state, and warns that returned content should be treated as untrusted (security context). These add value beyond the annotations. Strong disclosure of the unread-preservation behavior and security caution.

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?

Two sentences, zero wasted words. Front-loaded with the primary action, then adds behavioral and security context. Every word earns its place. Extremely efficient and complete for its length.

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?

The tool has an output schema, so return-value explanation isn't required. The description covers core purpose, unread behavior, and security posture. With 4 parameters at 0% coverage, not addressing parameters represents a small gap, but the parameter names (uid, folder, max_chars, max_download_bytes) are reasonably self-explanatory. The output schema and annotations fill remaining gaps. Relatively complete for a moderately complex tool with an output schema.

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%, meaning no parameter is described in the schema, so the description should compensate. However, the description does not mention any parameters (uid, folder, max_chars, max_download_bytes). The max_chars and max_download_bytes limits are not trivial to infer from names alone, though they are somewhat self-explanatory. With 0% coverage, the description should have addressed at least the limits parameters. Description adds zero parameter semantics; the names carry the meaning but limits purpose is not explained.

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?

Description states a specific verb+resource ('Read one message') and distinguishes from siblings by mentioning BODY.PEEK to keep it unread, which differentiates it from set_read_state and trash_mail. Could be clearer about the object being an email/mail, but 'one message' is unambiguous enough. Purpose is clear: read a single message without marking it as read.

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?

The BODY.PEEK detail implies this is for reading without changing read state, giving context about when to use it vs set_read_state. However, it doesn't explicitly name alternatives (e.g., for batch reading use search_mail_headers, or that read_mail is for a single message), though the tool name and single-uid required parameter make the scoping clear. Clear context lacking explicit exclusions or named siblings.

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