AI-Mail

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

Annotations already carry destructiveHint/idempotentHint, and the description adds substantially beyond them: permanence and unrecoverability, no filter or confirmation step, the fact the inbox address, expiry and allowance are unaffected, and the exact return payload { deleted: N }.

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?

Dense and front-loaded with the destructive nature first, then routing, then side effects, then return shape. Slightly long, and the clause 'whether or not it was returned yet' is awkward, but nearly every sentence carries distinct information.

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?

No output schema exists, but the description supplies the return shape, the side-effect model, and the safety context for a catastrophic irreversible operation. Nothing an agent needs to call this 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?

Zero parameters, so baseline is 4, but the description goes further by explaining the design (no filters, no confirmation) and how the target inbox is resolved via the connection token — semantics an empty schema cannot convey.

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 ('every email in this inbox at once') and explicitly distinguishes itself from the sibling delete_email. An agent can pick between the two 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?

Gives explicit when-to-use ('task is finished or to start clean') and a named alternative with its selection condition ('to remove a single email use delete_email instead'), plus a strong call-only-when-you-mean-everything warning.

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

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

Beyond the destructive/idempotent annotations it discloses that content, extracted code and original message are erased immediately and unrecoverable, that a repeat delete is safe and reports 'not found', that the inbox/address/allowance are unaffected, and that ids from other inboxes are treated as not found.

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 the destructive core action and the routing alternatives, then parameters and return values. It is long but nearly every sentence carries non-redundant operational detail; a slight trim of the id alphabet/example restatement would tighten it.

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 supplies the return value ({ deleted: 1 }) and the exact failure message ('No email with that id.') plus id lifetime rules, so an agent has everything needed to call and interpret the result.

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?

Although schema coverage is already 100%, the description adds semantics the schema cannot convey: the id is a 16-character lowercase code with a restricted alphabet, ids never change or get reused, they belong to this inbox only, and they stay valid until deletion or 7-day expiry.

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 ('Permanently delete one email by id') with the irrecoverable scope spelled out, immediately distinguishing it from delete_all_emails and wait_for_email's delete flag.

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 explicit when-to-use ('after you've used the code or link'), explicit alternatives for adjacent cases ('to delete while receiving, call wait_for_email with delete: true', 'to clear the whole inbox use delete_all_emails'), and a prerequisite check ('check it with read_email first if unsure').

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

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

Annotations already declare read-only/idempotent/non-destructive, yet the description goes well beyond them: the 256 KB cap, the text-vs-base64 encoding rule, the delivery-policy refusal of executables/archives, the enumeration of error messages, and a prompt-injection warning about untrusted attachment content.

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?

Dense and front-loaded with the return shape first, then types, then errors and parameters. It is somewhat long, and 'Read-only; it changes nothing' duplicates the readOnlyHint annotation, but nearly every sentence carries operational value.

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 still documents the exact return fields and encodings, plus error cases and the size/type constraints. An agent has everything needed to call and interpret this tool correctly.

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 is 3, but the description adds real semantics: email_id's provenance (list_emails/wait_for_email) and the 'a1', 'a2' ordering and lifetime stability of attachment_id. The information is largely reinforcement of the schema's own examples and patterns, so it does not reach a full 5.

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?

Opens with a specific verb+resource and immediately enumerates the returned shape 'as { id, filename, content_type, kind, size, encoding, content }'. It also scopes the accepted types and size limit, so an agent can distinguish this from read_email or list_emails 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?

Explicitly states when NOT to fetch: calendar invites are already parsed into the email's calendar field, so fetch the .ics only for the raw file. It also tells the agent that every email lists attachments even unfetchable ones, which sets expectations before a call.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces 'read-only; changes nothing' while adding behavior the annotations cannot: what messages_left and unseen mean relative to wait_for_email, that active=false means mail is refused until renewal, and the x402 renewal endpoint. This is substantive context beyond structured fields.

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 return shape, then usage, then field semantics, then the expiry/renewal caveat, then sibling routing and the no-parameter note. Every sentence carries distinct information; nothing is redundant padding.

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 takes on the burden of enumerating return fields and their meaning, plus expiry consequences, and it is rich enough that an agent can call and interpret the tool correctly without further documentation.

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?

Zero parameters, so baseline is 4, but the description goes further by explaining why none exist: the inbox is selected by the connection's auth token, so there is no address or id to pass. That resolves an ambiguity an empty schema would otherwise leave.

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?

Opens with a specific verb+resource (show the inbox's email address and state) and enumerates the exact returned fields. It also names sibling tools ('to receive mail use wait_for_email; to browse it use list_emails'), making it unambiguous against the other five tools.

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 explicit when-to-use conditions ('use it first to get the address to give a website, or to check the inbox is still active before waiting for mail') and routes the agent to the correct alternatives for receiving vs browsing mail. Both the trigger and the alternatives are stated, not inferred.

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

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

Beyond the read-only/idempotent annotations, it discloses that it does not mark emails as returned, that re-listing includes what wait_for_email already returned, the 7-day retention window, and the empty-inbox [] behavior. It even flags that sender/subject fields are untrusted data rather than instructions, which is valuable safety context.

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?

It is dense but front-loaded, leading with purpose, then output shape, then safety, then routing, then parameters. Each sentence carries information, though the length is at the upper end of what is necessary.

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 compensates by describing the returned array structure, the empty case, and retention limits. Combined with the annotations, an agent has everything needed to invoke and interpret this tool correctly.

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 is 3, but the description adds real meaning: out-of-range values are clamped (<=0 becomes 1, >50 becomes 50), no paging exists, and already-returned plus unread emails both count toward the limit. These counting and clamping semantics go beyond the schema's stated min/max.

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 plus scope ('most recent emails in this inbox, newest first') and gives the exact return shape. It cleanly distinguishes itself from wait_for_email by explicitly naming that sibling. An agent can tell what this does 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-to-use ('find an email's id for read_email or delete_email, or to look up a code you already received') and when-not ('To wait for a new email use wait_for_email instead'). Both the positive and negative routing conditions are spelled out.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial context beyond them: it does not mark mail as returned and can be called repeatedly, the exact 'No email with that id.' error and its causes (never existed, deleted, 7-day retention), and a prompt-injection warning that email content is untrusted. This is far richer than the annotations alone.

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 the return shape and the id semantics, and nearly every sentence earns its place. However, it is one dense paragraph bundling field documentation, retention rules, injection warnings, and id validation; a break or two would improve scannability without adding 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?

With no output schema, the description fully documents the return shape (links, text, attachments with available/reason, parsed calendar invite), the error case, retention, and id lifecycle. Nothing an agent needs to call or interpret the result 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% (baseline 3), but the description goes well past it: id is a 16-char lowercase code excluding l/o/0/1, ids are inbox-scoped, immutable, never reused, valid until deletion or 7 days of age, and ids from other inboxes resolve as not found.

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 precise verb+resource (read one email in full by id) and immediately enumerates the returned fields, distinguishing it clearly from list_emails, wait_for_email, get_attachment, and delete_email. An agent can identify its role without opening any 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?

Explicitly routes the agent: get the id from list_emails or wait_for_email, use wait_for_email to receive new mail, and use delete_email when done. Names both prerequisites and alternatives with their selecting conditions.

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

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.