receivemail.dev

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

Annotations only cover the safety profile (readOnly=false, destructive=false, idempotent=false), so credit goes to the description for disclosing that the call provisions a new real address, returns address/expiresAt/secret, and that the secret is required to read the mailbox later. The free-tier 60-minute vs. paid 1440-minute distinction and OTP extraction are genuinely extra context. It stops short of saying what happens on expiry or whether mailbox creation is rate-limited.

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 dense sentences, front-loaded with the core action and the returned fields, then tier limits. No filler, though the parenthetical tier clause is slightly compressed and could read as one run-on.

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 return-value burden and does so — it names every returned field and explains the secret's role. Combined with the tier limits on ttlMinutes, an agent has everything needed to invoke and then consume 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?

Schema coverage is 100% and the single ttlMinutes parameter is fully documented (default 15, cap 60 free). The description reinforces the tier caps but adds no syntax or behavioral detail beyond what the schema already says, so the baseline of 3 applies.

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 ('Create a disposable receivemail.dev email address that receives real mail') with the key property that makes it useful — real inbound mail delivery. The action is unambiguous and clearly distinct from the sibling read/wait tools list_messages and wait_for_email.

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?

Usage is implied by the resource (spin up a throwaway inbox, then read with the secret), and the free-vs-paid tier notes help an agent reason about the ttlMinutes choice. However, there is no explicit 'use this when…' framing, no mention of when not to use it, and no routing advice relative to the siblings.

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, and non-destructive. The description adds the useful window (last 50) and ordering (newest first), but doesn't say whether results are truncated, paginated, or what an empty mailbox returns.

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?

A single sentence with the scope and ordering front-loaded; nothing superfluous.

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 simple two-parameter read tool with rich annotations and full schema coverage, the definition is nearly sufficient. Only minor gaps remain, such as pagination behavior and empty-inbox return semantics.

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% and both parameters are documented as coming from create_mailbox, so the description only repeats that provenance. Baseline 3 applies since the schema carries the parameter detail.

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 (List), resource (emails received by a mailbox), and scope (last 50, newest first), and ties the mailbox to create_mailbox, which clearly separates it from wait_for_email.

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?

Usage is implied by the description — fetch the recent inbox after creating a mailbox — but there's no explicit when/when-not guidance or a pointer to wait_for_email for waiting on new mail.

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 cover readOnly/idempotent/non-destructive, so the bar is low, yet the description adds real behavior: the blocking duration, the retry loop on timeout, and a full literal return shape including the timed_out discriminator. It omits error/failure conditions (bad address, expired secret), which keeps it short of a 5.

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 tight sentences, each carrying distinct information: cap, return shape, retry rule, filtering parameter. No repetition of the title or annotations, and the return shape is front-loaded after the timeout constraint.

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 contract itself (both the success message fields and the timeout case), plus the retry and filtering behavior. That is everything an agent needs to drive a polling loop 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 description coverage is 100%, so all four parameters are already documented and the baseline is 3. The description reinforces `since` semantics ('ignore mail you've already seen') and the 25s cap, but adds little beyond what the schema fields already say.

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 ('Wait ... for an email') plus the scope constraint ('up to 25 seconds') and ties itself to a sibling ('a mailbox made with create_mailbox'). An agent can distinguish this from list_messages 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?

Explicitly tells the agent to 'call again on timeout', which is the key usage pattern, and explains when to pass `since` ('to ignore mail you've already seen'). It never explicitly contrasts itself with list_messages, so the alternative-selection guidance is implied rather than stated.

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