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

Goes well beyond the annotations: it discloses the consume-on-read semantics ('marks it as returned, so the next call gives the next email'), the exact-erase behavior of delete including the no-arrival case ('when nothing arrives, nothing is deleted'), the 55s clamp against MCP client timeouts, the 7-day retention when delete is false, and a prompt-injection warning about untrusted email content. These details align with destructiveHint=true / idempotentHint=false rather than contradicting them.

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-loaded with purpose and routing, then payload, edge cases, safety, exclusions, parameters. Every sentence carries load, but the exhaustive enumeration of the return shape and calendar fields is long; a return schema would have let it be trimmed. Dense rather than padded, so still strong.

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 no output schema, the description carries the full return-value burden and does so completely: top-level fields, attachments shape with the available:true fetch rule, calendar invite shape, and the literal 'No new email yet.' sentinel for timeout. Combined with the retry/timeout and delete semantics, nothing needed to call it correctly is missing.

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 100%, so the baseline would be 3, but the description adds real operational meaning: timeout_seconds is an upper bound rather than a delay (returns immediately if a matching email already exists, including one from before the call), 0 means check-without-waiting, values above 55 are clamped, and delete scopes only to the email this call returns. None of that is in the schema.

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+resource with scope: 'Return the next email you haven't received yet, waiting up to timeout_seconds.' It also explicitly frames itself as the main tool for the verification-code workflow, and names the siblings it is not (list_emails, read_email). An agent can distinguish it from every sibling without reading 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?

Gives an explicit when-to-use scenario (give the inbox address to a website, trigger sign-up/login, then call this for otp/verify_link), an explicit when-not-to-use exclusion ('Do not use it to look at mail you already received: use list_emails or read_email'), and the retry condition ('call again to keep waiting'). Alternatives are named, not implied.

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