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

Annotations declare a non-readonly, non-destructive, non-idempotent, closed-world write. The description adds genuine context beyond that: mail is forwarded to the user's inbox, the call returns the new address, and `note` shapes the generated address. It does not address collision behavior when `local` is supplied or whether the alias is enabled on creation, so it is not fully transparent.

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?

Four sentences, front-loaded with the core action and purpose before the parameter guidance. The final sentence is somewhat long but every clause carries usable information; no filler or repetition of schema text.

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 zero required parameters, no output schema, and simple flat inputs, the description covers what the tool does, its side effect (forwarding), and its return value. Missing only edge-case behavior around duplicate `local` values or default alias state, which are minor for a create tool of this simplicity.

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 meaning the schema does not: it shows the concrete address shape produced by `note` (github.k3f9@domain) versus a random address when omitted. That directly informs how to choose between `note` and `local`, which the schema only describes abstractly.

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 new forwarding email alias on the user's own domain") and immediately grounds it in a concrete scenario (signing up to a website without revealing the real address). It is clearly distinguishable from siblings like list_aliases, set_alias_enabled, or send_from_alias, none of which create aliases.

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 a clear use case (masking the real address for site signups) and a decision rule for the optional `note` param: pass it for a readable address, omit it for a random one. It does not explicitly state when-not-to-use or name a sibling alternative, which keeps it short of a 5.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds non-obvious behavior: extraction from subject/body, the null-result case, and the recommended retry after waiting. It doesn't mention rate limits or how it disambiguates when multiple codes exist beyond 'most recent'.

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 short sentences, front-loaded with what is returned, followed by when to call and the retry fallback. No filler or redundant restatement of the tool name.

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?

There is no output schema, and the description covers the return contract (extracted code, null when nothing arrived) as well as the timing constraint and retry pattern. For a two-parameter read tool with annotations present, nothing an agent needs to invoke 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 50%: `alias` is documented in the schema including the omit-to-search-all behavior. The description only restates `since_minutes` as a time window and omits the documented default of 15 and the 1440-minute cap, so it adds little beyond 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 and resource ('Return the most recent one-time verification code (OTP)') and narrows the scope with the alias and since_minutes window plus the extraction source (email subject/body). This clearly separates it from sibling tools like recent_messages, which returns messages rather than extracted codes.

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 trigger ('Use right after triggering a sign-up or login email') and polling guidance ('Returns null code if none arrived yet; wait and call again'). It does not name an alternative sibling or state exclusions, which keeps it below a 5.

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 readOnlyHint=true and openWorldHint=false, and the description adds real value on top: the result ordering (newest first) and the exact fields each record carries, which matters because there is no output schema. It stops short of describing pagination behavior or what happens at the 200-item cap.

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 waste, with the core listing behavior and ordering front-loaded before the optional filter. Every clause carries 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?

For a read-only list tool with no output schema, enumerating the returned fields and their order is exactly the missing piece, so the description is largely complete. The one gap is pagination/truncation semantics tied to `limit`, which an agent would need to page results 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 50%: `query` is already documented in the schema and the description only restates it ('filters by address or note'). The more important `limit` parameter (default 50, max 200) gets no mention at all, so the description does not compensate for the coverage 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 (list) and resource (the user's aliases) plus ordering (newest first) and the fields returned (note, enabled state, forwarded/blocked counts). It is clearly distinguishable from siblings like create_alias or set_alias_enabled by the verb alone, though it never names those siblings explicitly.

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: this is the read/enumerate path for aliases, and `query` is optional. But there is no explicit when-to-use guidance, no mention of the sibling get_latest_code/recent_messages alternatives, and no statement about what to do when the result set is truncated.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the exact metadata surface returned and explicitly rules out message bodies, which sets data-scope expectations. It stops short of describing ordering (recency) semantics or pagination behavior.

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?

One compact sentence with the core capability front-loaded, followed by the negative scope and the filter. No filler, no repetition of the tool title.

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 usefully compensates by naming the returned fields and excluding bodies. For a read-only two-parameter list tool that is nearly sufficient, though it leaves the `limit` control and result ordering undocumented.

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 only 50%: `alias` is documented in the schema, while `limit` carries only structural constraints (default 20, max 100). The description confirms `alias` is optional and acts as a filter, but says nothing about `limit` or how result volume is controlled.

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 ('Show') and resource ('recent mail activity') and enumerates the returned fields (sender, subject, code, direction), which makes the tool's scope unambiguous. It implicitly separates itself from siblings like get_latest_code by returning metadata lists rather than a single code, though no sibling is named explicitly.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative (e.g. when to use get_latest_code instead). The 'optional alias filter' hints at scoping, but the agent must infer the selection 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?

Annotations already declare readOnlyHint=false and openWorldHint=true, but they do not convey that this produces irreversible real-world side effects. The description adds that it 'sends real mail' and names the required credentials (RESEND_API_KEY or Cloudflare Email Sending), which is meaningful context an agent cannot infer from the annotations. It stops short of describing the response payload or failure modes.

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 short sentences, front-loaded with the action and scope, then prerequisites, then the safety guard. No redundant restatement of the title and no filler.

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 4-required-parameter tool with annotations and no output schema, the description covers purpose, credentials, and the irreversibility warning. It omits what a successful call returns (e.g., a message id) and whether the alias must pre-exist, which would fully close the loop.

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 75%, so the schema already documents to, text, and alias; only subject lacks a description. The description adds the semantic point that alias is the visible sender identity while the real address stays hidden, but offers no format or constraint details. Baseline 3 is appropriate with the schema doing most of the work.

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 (send) and resource (plain-text email) with a distinguishing scope: FROM one of the user's aliases so the real address stays hidden. This is clearly separable from the sibling tools (create_alias, list_aliases, set_alias_enabled, recent_messages), none of which send mail.

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 precondition/exclusion: 'only call it when the user asked to send this exact message,' which guards against an agent inventing outbound mail. It does not discuss ordering relative to create_alias or what to do if the alias doesn't exist, but the core when-to-use guidance is strong.

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 idempotentHint=true and destructiveHint=false, so the bar is lower; the description still adds real value by explaining the consequence ('mail to it is rejected as if it never existed') and clarifying that the change is reversible ('or back on'). It stops short of stating auth requirements or whether the alias configuration is retained for re-enabling.

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 front-loaded sentence that delivers the action, its effect, and a use case with no filler. The nested parenthetical with the spam example is slightly dense but each clause carries 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?

For a two-parameter, non-destructive, idempotent toggle with no output schema, the description covers effect and reversibility, which is the essential gap the structured fields leave. Only minor gaps remain (permissions, alias-format handling) and those are low-stakes here.

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 50%: 'alias' is documented in the schema, while 'enabled' has no schema description. The description's on/off framing effectively conveys what the boolean toggles, but it adds nothing about accepted alias formats or the numeric-id alternative mentioned only 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?

The description states a specific verb ('Turn an alias off ... or back on') applied to a named resource, and the title confirms it. It is clearly distinguishable from siblings like create_alias or list_aliases, though it never explicitly names them.

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?

It gives one clear use case ('use this to stop spam'), which implies when to reach for the tool. However, it names no alternatives and states no when-not conditions, so routing versus siblings such as create_alias is left to inference.

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