SuperMailbox

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

Adds genuinely non-obvious behavior beyond annotations: the call is queued and its return is not provider confirmation, plus the idempotency-key reuse rule on retry. Annotations supply destructive/openWorld/non-idempotent, so the remaining gap is what archiving actually does (folder destination, reversibility) for a destructiveHint tool.

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 short, front-loaded sentences with no filler; the async caveat comes immediately after the purpose. Minor blemish: 'Never retry an uncertain send' uses 'send', a copy-paste artifact for an archive tool, which slightly muddies the retry rule.

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 tells the agent what comes back (an operationId) and how to resolve it, which is the critical missing piece for an async tool. It omits what the archive operation does to the mailbox and any permission requirements.

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 33% — only operationId is documented in the schema — and the description reinforces the operationId retry semantics but says nothing about accountId or messageId. It partially compensates for the coverage gap but leaves two of three parameters unexplained.

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 ('Archive a message from its current folder'), which is more precise than a generic move and distinguishes it from delete/move siblings by naming the archival scoping. It never explicitly contrasts itself with move_email, which could also relocate a message, so it stops short of full sibling differentiation.

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 concrete follow-up guidance: poll get_mail_action with the returned operationId, and never retry with a new operationId. However, it offers no guidance on when to choose archive_email over move_email or delete, and no prerequisite/auth context.

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?

Adds substantial behavior the annotations do not carry: the call is queued and returns before provider completion, completion must be polled via get_mail_action, and the retry policy is spelled out. Note a mild tension with idempotentHint=false — the operationId/retry wording implies deduplicated retries, though the annotation can be read as 'not idempotent without a key', so this is not a clear contradiction.

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?

Five short sentences, purpose front-loaded, and every sentence conveys non-obvious operational information (async queueing, polling target, retry rule). 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?

With no output schema, the description correctly explains the return shape (an immediate queued operation) and the follow-up call, which is exactly what this async tool needs. It omits details on body requirements/permissions and leaves senderIdentityId, to and subject unexplained, so it is strong but not fully complete.

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 only 11%, so the description carries most of the burden, yet it only explains operationId. High-value required parameters (accountId, to, subject) and optional ones (senderIdentityId, htmlBody vs textBody) get no semantic guidance in either place.

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 an unsent draft') plus scope ('in one connected mailbox'). The qualifier 'unsent' is what an agent needs to distinguish this from send_email, reply_to_email, and forward_email among the siblings 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?

Gives explicit operational rules: supply a stable operationId, reuse it only for retrying that exact draft, and poll get_mail_action with the returned operationId. It does not explicitly say when to prefer create_draft over send_email or reply_to_email, so it stops short of full when/when-not/alternative guidance.

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 destructive=true, idempotent=false, openWorld=true, so the safety profile is partly carried structurally. The description adds real value beyond that: the rule only affects future incoming mail, historical mail is untouched, and evaluation precedence is first-enabled-match-wins. It does not state what happens when no rule matches or on validation failure, keeping 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?

Four sentences, zero filler, front-loaded with the core action and followed by constraints, precedence and scope limitations in descending order of importance. Every sentence carries information an agent needs to call the tool correctly.

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 5-required-parameter mutation tool with nested condition and action objects and no output schema, the description covers purpose, valid inputs, precedence, and side-effect boundaries well. It is slightly incomplete on the post-call picture: no hint of what a successful create returns (rule id?) or what happens on conflicting/duplicate rules.

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 only 20% (accountId alone is documented), so the description must compensate, and it largely does: it maps the undocumented action enum variants to behavior (move to another folder, Trash, Junk, supported Gmail label) and explains that conditions are an OR-of-required-fields with AND semantics across supplied ones. It says nothing about name length constraints or that the label variant consumes folderId, so gaps remain.

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 SuperMailbox rule") plus its temporal scope ("for future incoming mail"), which cleanly separates it from list_mail_rules, update_mail_rule and delete_mail_rule. It further disambiguates with an explicit negative: it does not create a provider-native filter or touch historical mail, so the agent can rule out adjacent interpretations without opening a 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 the key gating prerequisite (at least one sender/recipient/subject condition, all conditions must match) and the resolution rule (first enabled match wins), which is the context needed to author a rule. It offers partial when-not guidance via the provider-native-filter and historical-mail exclusions, but never points at an alternative sibling for creating native filters.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=false, so the safety profile is known. The description adds meaningful context beyond that: existing messages are untouched (clarifying the blast radius of the destructive action) and the tool remains available during offline or past-due states, which is non-obvious availability 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?

Four short sentences, each carrying distinct information, with the core action and effect front-loaded. Slightly sentence-fragmented, but no filler or repetition.

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 single-parameter delete tool with no output schema, the description covers effect, scope of impact, and availability under degraded account states, which is close to sufficient. It leaves out whether the deletion is reversible or how to recover a deleted rule, a minor gap given destructiveHint already signals irreversibility.

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% and the single 'id' parameter is documented in the schema as 'Rule ID returned by list_mail_rules.' The description adds no parameter detail beyond that, 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 (delete) and a precisely scoped resource (SuperMailbox rule), and immediately clarifies the effect ('so it will no longer act on future incoming mail'). It also disambiguates from a similar-sounding category ('not provider-native filters'), so an agent can separate it from sibling rule tools like list_mail_rules and update_mail_rule.

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 useful context: it remains usable even when the mailbox is offline or billing is past due, and it explicitly scopes the operation to SuperMailbox rules rather than provider-native filters. It does not state a when-not case or name the alternative tool to use for editing a rule instead of deleting it, so it falls short of full routing guidance.

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 (destructiveHint=true, idempotentHint=false, openWorldHint=true) by disclosing quoting behavior, attachment non-copy behavior, the queued-async return semantics, the fact that the return is not provider confirmation, and the correct recovery pattern for uncertain sends.

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 tight sentences, front-loaded with purpose then the critical async/idempotency caveats. No filler; every clause conveys a distinct operational 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?

For an 8-parameter destructive async mutation with no output schema, the description covers the lifecycle, return semantics, and retry policy well. It omits guidance on recipient fields and senderIdentityId, and the 'attachments unless selected explicitly' claim has no corresponding schema parameter, but the core invocation contract is complete.

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 only 13% (just operationId), so the description must carry the rest. It partially compensates by mapping 'optional note' to textBody and reinforcing operationId reuse semantics, but says nothing about to/cc/bcc, accountId, messageId, or senderIdentityId.

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 ('Forward a message') with the immediate scope qualifier ('with an optional note'). The verb 'forward' inherently distinguishes it from the reply_to_email and send_email siblings, so an agent can select it 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?

Gives concrete operational guidance: poll get_mail_action with the returned operationId, and do not retry an uncertain send under a new operationId. It doesn't explicitly compare against reply_to_email or send_email, but the async/idempotency routing is clear and actionable.

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 the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuinely useful behavior beyond them: the payload is base64-encoded with a MIME type, which the agent must know to interpret the result, especially since there is no output schema. It omits size limits and failure modes, keeping it from 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?

Two short sentences, front-loaded with the action and followed by the critical return-format detail. No filler; every clause earns its place.

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?

Covering the base64/MIME return shape is the right call given no output schema exists. However, with three undocumented required parameters and no mention of size limits, missing-attachment behavior, or how the attachment is located, the definition is only minimally sufficient.

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 0% with three required parameters, and the description never mentions accountId, messageId, or attachmentId or their roles. Parameter meaning must be inferred purely from names, 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?

Specific verb+resource: 'Fetch one attachment' paired with the return format (base64 + MIME type) makes it unambiguous against get_email or get_thread, which deal with message content. It does not explicitly name a sibling to contrast with, so it falls short of a 5.

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?

'On demand' implies this is a lazy/secondary fetch you call only when you actually need attachment bytes, as opposed to listing metadata via get_email. No explicit when/when-not condition or named alternative is given, so usage is only implied.

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, openWorld, so the safety profile is covered. The description adds two non-obvious behaviors an agent would otherwise guess wrong: cached copies carry freshness metadata, and reading does not mark the message as read — the latter being especially valuable given mark_email_read exists as a sibling.

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, no filler, and the core verb+identifier is front-loaded before the caching and side-effect notes. Each 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?

With no output schema and 4 parameters, the description covers the return shape at a high level ('message body and attachment metadata'), the caching/freshness contract, and the read-state side effect. It leaves error behavior and where the opaque ID comes from unstated, which is a minor but real gap.

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%: waitForFresh and maxWaitMs are documented in-schema, while accountId and messageId are not. The description compensates partially, telling the agent that messageId is 'opaque' (so it cannot be constructed) and framing waitForFresh as a 'bounded' refresh, but says nothing about accountId.

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 names a specific verb and resource ('Read a message body and attachment metadata') and constrains retrieval to an 'opaque message ID', which separates it from browse-style siblings like search_emails and get_thread. It stops short of naming an alternative tool, so differentiation is implied rather than explicit.

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 a clear conditional instruction for the refresh path ('set waitForFresh for a bounded provider refresh'), which tells the agent when to opt into the slower behavior. It does not say when to prefer this tool over get_thread or search_emails, so routing among siblings 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.

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description earns credit by decoding result semantics beyond annotations: 'completed' is the only state that confirms provider success, and 'uncertain' must not trigger an automatic resend. It does not disclose whether records expire or whether polling 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?

Two sentences, no filler. The purpose is front-loaded and the state-interpretation caveat follows it immediately; every clause carries decision-relevant 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?

With no output schema, the description must carry the full burden of describing results, and it only covers two status values. It omits the existence of non-terminal states (e.g., pending/processing), what other fields the response returns, and where operationId is obtained, all of which an agent needs to poll 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 50% — operationId carries a rich schema description (high-entropy idempotency key, reuse only on exact retry) while accountId has none. The description contributes no parameter information at all, so it fails to compensate for the uncovered half as required at this coverage level; only the obvious, inferable nature of accountId keeps this above a 1.

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: 'Get the status of an accepted mail action.' No sibling among the 20 listed tools performs status polling, so it is trivially distinguishable from send_email, forward_email, and reply_to_email, which produce the actions it reports on. The agent knows exactly what this returns 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?

It supplies one operational rule — 'uncertain means do not repeat a send automatically' — which is a when-not for the calling agent, but it never says when to invoke the tool (immediately after send, or after a delay), nor that the required operationId originates from send_email/forward_email/reply_to_email. Usage is implied by 'accepted mail action' rather than stated.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered there. The description adds useful context by naming what it returns (identity plus connected mailbox count), but says nothing about auth requirements or error/empty states.

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 with no filler. Every word earns its place.

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 it does identify the two things returned. For a zero-parameter read-only tool this is nearly complete, though it could note the shape of the identity fields.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 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 ('Return') and resource ('the authenticated SuperMailbox identity and connected mailbox count'), so the agent knows this surfaces session/account context. It does not distinguish itself from the nearby sibling list_mail_accounts, which an agent might plausibly reach for instead.

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 guidance or mention of alternatives such as list_mail_accounts or list_sender_identities. Usage is only weakly implied by the words 'authenticated' and 'identity'.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds no behavioral context at all — no message ordering, no pagination, no handling of inaccessible threads — so it contributes nothing beyond the annotations.

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 short sentence with the verb and resource front-loaded and zero waste. It is efficient, though the brevity is partly under-specification rather than disciplined conciseness.

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 tool with two undocumented required parameters and no output schema, the description is too thin. It does not say what shape the result takes (list of messages, thread metadata) or whether an empty thread behaves differently, leaving gaps an agent cannot resolve from structured fields.

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 0% for two required parameters (accountId, threadId), so the description carries the burden of explaining them and does not. It never clarifies that accountId identifies the mailbox or that threadId is the thread key, nor any format constraints.

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 ('Read messages in a mail thread'), which is clearer than a tautology. However, it does not distinguish itself from the obvious sibling get_email (single message) or search_emails, leaving the agent to infer that this retrieves the full thread by ID.

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 when-to-use guidance and no named alternative. With 20 sibling tools including get_email and search_emails, the description should state when a thread read is preferable, but it offers nothing.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the mild scoping fact that results are limited to the current user's accounts; it says nothing about ordering, pagination, or return contents.

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 no filler, and the defining scope ('current user's connected') is front-loaded. Nothing could be trimmed without losing meaning.

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 and no parameters, the description is the only place an agent could learn what a returned account looks like (address, account ID, provider, primary flag). It omits that, though for a trivial zero-arg read list the omission is not fatal.

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?

The tool takes zero parameters, so per the baseline there is no parameter semantics to document and the description cannot be faulted here. Nothing misleading is stated about inputs.

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 clear verb (list) and resource (the current user's connected email accounts), which is specific enough to identify the operation. However, it does not distinguish itself from similarly-shaped siblings such as list_sender_identities or list_mail_folders, so an agent must guess how 'accounts' differs from 'identities'.

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 description offers no when-to-use guidance, no prerequisites, and no alternatives. Given siblings like list_sender_identities and get_profile that overlap on identity/account discovery, an explicit routing cue would be valuable here and is absent.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description only adds the single-mailbox scoping constraint; it says nothing about whether a not-yet-synced mailbox, auth failure, or rate limit affects the result.

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 short sentence with the scope constraint front and center and no filler. It is efficient, though its brevity reflects under-specification rather than disciplined trimming.

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 read tool with full annotation coverage, the description is minimally viable, but it leaves return-shape questions open (flat list vs. folder hierarchy, nesting, unread counts) and gives no hint about the accountId source. No output schema exists to absorb those gaps.

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?

One required parameter (accountId) exists with 0% schema description coverage, so the description must carry the burden and does not: it never names accountId, its expected format, or where the value comes from. The phrase 'one connected mailbox' merely gestures at the concept of an account selector without adding usable semantics.

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 (mail folders) with a scope qualifier ('for one connected mailbox'). That scope distinguishes it from the workspace-wide list_mail_accounts/list_mail_rules siblings only weakly, since it never names an alternative 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?

The phrase 'for one connected mailbox' implies the tool works per-account, but there is no when-to-use guidance, no prerequisite (e.g., that a mailbox must be connected via list_mail_accounts first), and no routing to sibling tools that also deal with folders or messages.

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/openWorld=false, so the baseline is covered. The description adds genuinely useful semantics beyond that: rules apply only to new incoming mail, are evaluated in creation order, and the first enabled match wins, plus the SuperMailbox-vs-native distinction.

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, front-loaded with verb+resource. Each sentence earns its place: scope, matching semantics, and the disambiguation from provider filters. 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 one-param read tool with no output schema and full read-only annotations, the description covers identity, scope, and rule-ordering semantics well. It stops short of describing the returned rule shape or whether disabled rules are included, which are minor residual gaps.

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% for the single optional accountId, whose description already states it limits results to one connected mailbox. The description's 'for a connected mailbox' phrasing mirrors the schema without adding new syntax or format detail, so baseline 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+resource ('List SuperMailbox rules') plus scope ('for a connected mailbox'), and explicitly distinguishes these from provider-native filters. It does not explicitly name the create/update/delete rule siblings, but the read intent is unambiguous.

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 (inspect configured SuperMailbox rules), but there is no explicit when-to-use or when-not-to guidance, nor a pointer to create_mail_rule/update_mail_rule/delete_mail_rule for mutation. Adequate but leaves the agent to infer the workflow.

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, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds a bit of domain context by calling the addresses 'approved' (verified/allowed) and scoping them to one mailbox, but says nothing about ordering, pagination, or what 'approved' entails.

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 short sentence, front-loaded with the verb and resource, with no filler. Every word contributes.

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 read-only list tool with annotations covering the safety profile, this is minimally adequate. However, with no output schema and no indication of what the returned addresses look like (bare addresses vs. display names, ordering), an agent lacks a complete picture.

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 0% for the single accountId parameter, so the description must compensate. The phrase 'for one mailbox' does imply that accountId selects the mailbox, which is useful, but it adds no format, origin, or lookup guidance beyond that.

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 (approved From addresses) scoped to one mailbox, which is clearly distinct from siblings like list_mail_accounts or list_mail_folders. It does not explicitly name a sibling to contrast against, but the resource is unambiguous.

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 when-to-use guidance, no prerequisites, and no mention of alternatives. The purpose (checking which From addresses are authorized) must be inferred entirely from the phrase 'approved From addresses'.

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 only declare the safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true); the description adds substantial context beyond them by disclosing the asynchronous queued-operation model, that the return is not confirmation of provider completion, and the polling requirement. The phrase 'Never retry an uncertain send' is odd wording for a read-state tool (copy-paste from a send tool), but it does not contradict the annotations.

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 short sentences, front-loaded with the core action before the async caveats. Slight redundancy in the retry instruction, which largely restates the operationId schema description, but there is little waste overall.

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 an async mutation with no output schema and 4 parameters, the description covers the operation lifecycle and polling path well, which is the most important missing piece. It still omits the semantics of the non-operationId parameters and gives no sense of what the queued operation ultimately affects, leaving the definition only partially complete.

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 only 25% – just operationId is documented, and its idempotency semantics are already in the schema. The description references operationId for polling but never explains accountId, messageId, or the polarity of isRead (true = read vs unread), so it fails to 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 and resource: 'Set the read state of a message.' An agent can immediately tell this mutates read/unread state, distinguishing it from setters of other attributes like set_email_starred or move_email. It does not, however, explicitly name a sibling it replaces or defers to, which keeps it below a 5.

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 post-invocation guidance (poll get_mail_action with the operationId, don't retry with a new operationId) and names the correct follow-up tool, but never states when to choose this tool over alternatives or any precondition for the read-state change itself. Usage context 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.

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

Annotations already state destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered; the description then adds the non-obvious async semantics (queued, not provider-completed), the required polling follow-up, and retry discipline with the idempotency key. This is meaningful behavior an agent could not infer from the structured fields. Minor wording issue: 'an uncertain send' reads like residual copy from send_email, which slightly muddies the retry rule for a move operation.

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 short sentences, front-loaded with the core action, with a small amount of waste in the 'uncertain send' phrasing that does not fit a move tool. Nothing is repeated from the annotations or schema.

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 correctly takes on the return-value burden by stating that a queued operation is returned and that get_mail_action is the polling target. It stops short of describing what the queued operation contains or how to detect terminal failure, but an agent has enough to call and follow up 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 only 25% – only operationId is documented in the schema. The description reinforces operationId's purpose (returned to the caller, reused only for that exact retry), but adds nothing about accountId, messageId or destinationFolderId. It therefore only partially compensates for the low coverage, landing at the baseline.

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 first sentence gives a specific verb and resource ('Move a message to another folder'), which is clear and action-oriented. It does not, however, contrast the tool with its closest sibling (archive_email) or explain what distinguishes a move from an archive, so sibling discrimination is left to inference.

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 description gives concrete procedural guidance: returns a queued operation, poll get_mail_action with the returned operationId, and never retry with a new operationId. That is strong when/how guidance, though it names no alternative tool or condition under which a caller should choose archive_email or a different path instead.

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 that an uncertain SMTP attempt is never automatically resent, that the return is a queued operation and not confirmation of provider completion, and how to confirm status. This is exactly the kind of async/at-most-once behavior an agent must know before calling a destructive, non-idempotent send.

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?

Six short sentences, front-loaded with the core action and the retry contract before the polling instruction. No filler; every sentence carries a distinct operational rule.

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 correctly explains the immediate return value (a queued operation) and the next step (get_mail_action). Combined with annotations covering the safety profile, the definition is nearly complete; the remaining gap is the undocumented non-operationId parameters.

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 only 14%, so the description carries most of the burden, yet it only elaborates on operationId (idempotency-key semantics). accountId, messageId, replyAll, textBody, htmlBody, and senderIdentityId are left undocumented in both schema and description. The operationId guidance is valuable but insufficient to fully 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 and resource ("Reply to a message") that an agent can distinguish from send_email and forward_email by intent. It also reveals the operation is queued/asynchronous, which shapes expectations. It does not explicitly contrast itself with named siblings, keeping it just short of a 5.

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 rules: supply a stable operationId and reuse it only for retries of this exact reply, never retry an uncertain send with a new operationId. It also routes the agent to the follow-up tool ("Poll get_mail_action with the returned operationId"), providing clear alternatives for checking status.

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 only cover the safety profile (read-only, idempotent, openWorld); the description adds substantial behavioral context beyond them: background mailbox searching, semanticPending vs. pendingAccountIds independence, provider freshness, failures as settled errors, and the heuristic that stale/pending results do not prove a mailbox empty. This is exactly the kind of disclosure annotations cannot carry.

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?

Purpose and the get_email pointer are front-loaded, and most of the length is earned by genuinely complex asynchronous semantics. However, the semanticPending retry instructions are dense and the retry rule is restated ('repeat the same query and filters') without a cursor, plus the closing 'not proof that a mailbox is empty' caveat, adding mild redundancy.

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 names the return signals the caller must inspect (pendingAccountIds, semanticPending, failures, nextCursor, messages) and explains how to interpret them. It is close to complete for a complex tool, with residual gaps only on the undocumented filter parameters.

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 25% across 16 params, so the description must compensate. It adds real meaning for cursor (paginates existing results), waitForFresh, maxWaitMs behavior via freshness, and the accountId+folderId pairing, but leaves to/from/subject/query/after/before/isRead/isStarred/hasAttachments unaddressed. Partial compensation for a low-coverage schema lands at the baseline.

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 ('Search connected mailboxes') and immediately delineates the sibling relationship by directing the agent to get_email for reading a message and clarifying results are compact summaries. An agent can distinguish it from get_email and get_thread 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?

Gives explicit conditional guidance: accountId+folderId to search one folder, get_email to read, waitForFresh to await a provider update, and a precise retry protocol for semanticPending. The when-to-use, how-to-follow-up, and alternative tool are all spelled out rather than 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?

Adds substantial behavior beyond the annotations: the call is asynchronous and returns a queued operation that is explicitly NOT confirmation of provider completion, an uncertain SMTP attempt is never auto-resent, and operationId reuse with different content is rejected. Note a mild tension with idempotentHint=false, since the description says retries with the same operationId are deduplicated; this is best read as key-opt-in idempotency rather than an outright contradiction of the annotation.

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?

Purpose is front-loaded in the first sentence and every subsequent sentence concerns retry/async semantics. There is slight redundancy across the three operationId sentences, but each states a distinct rule (reuse, rejection on content change, never use a new key after an uncertain send).

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 correctly explains the return (a queued operation) and how to follow up via get_mail_action, which is the key gap a caller would otherwise hit. It is thin on the other eight parameters and on where the mailbox/accountId/senderIdentityId come from, but for an async send tool the critical context is present.

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 11%, so the description carries the burden, and it fully explains the most consequential parameter (operationId: high-entropy stable key, reuse only for the exact same send). It adds no meaning for the remaining eight parameters, including accountId, senderIdentityId, or the cc/bcc/htmlBody/textBody fields, so the compensation is partial.

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 ("Send email using the selected mailbox") and immediately clarifies the delivery model (queued operation, not provider confirmation). However, it never distinguishes itself from sibling tools that also produce outgoing mail such as create_draft, reply_to_email, or forward_email, leaving the agent to infer the boundary.

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 concrete operational guidance: reuse the operationId for retries of the exact message, poll get_mail_action with the returned operationId, and never retry an uncertain send with a new key. It does not, however, say when to prefer this tool over reply_to_email/forward_email/create_draft, which are the realistic selection alternatives.

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?

Adds substantial behavioral context beyond the annotations: it discloses that the call returns a queued operation immediately, that this is not provider-completion confirmation, the required polling step, and the retry rule for the operationId. These are real operational traits not covered by readOnlyHint/idempotentHint/destructiveHint.

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, front-loaded with purpose then async contract, with no filler. Each sentence carries actionable information. Minor miscue: 'uncertain send' is odd wording for a star operation, but it does not waste space.

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 async-return burden well by explaining the queued operation and pointing to get_mail_action with the returned operationId. It omits any guidance on the required accountId/messageId, so it is not fully complete for a 4-parameter tool.

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 25% – only operationId is documented in the schema. The description adds practical meaning for operationId (retry semantics) and implicitly covers isStarred via 'email is starred', but leaves accountId and messageId unexplained. Partial compensation for a low-coverage 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 precise verb and resource ('Set whether an email is starred'), which is clearly distinct from siblings like mark_email_read or archive_email. It does not explicitly name a sibling, but the purpose is unambiguous without needing to open a 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?

The description describes the post-invocation workflow (poll get_mail_action, don't retry with a new operationId) but never states when to choose this tool over an alternative or any preconditions. Usage is implied by the async workflow rather than explicitly framed.

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?

The annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, and the description genuinely adds beyond them: new-mail-only effect, first-enabled-match-wins precedence, pausing via enabled=false, pausing while billing is past due or the mailbox is offline, and the fresh boundary on re-enable (which explains the non-idempotency). It does not spell out that unmentioned fields are cleared by a replace, though 'Replace' hints at it.

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 purpose, then behavior, then the exclusions/contrast note. Every sentence carries information and none is padding. Slightly denser than needed for an update tool but well structured.

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 6-required-parameter mutation with nested objects and no output schema, the behavioral side is well covered, but the parameter side is thin: the description never explains the action union or conditions fields. Annotations carry the safety profile, but an agent still needs the schema alone to construct a valid call.

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 only 33% across 6 required parameters plus nested action/conditions objects. The description gives real meaning for 'enabled' (pause, billing, offline) but says nothing about id, name, accountId, conditions, or the move/label/trash/spam action union, so it fails to 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 and resource ('Replace a SuperMailbox rule'), which an agent can distinguish from create_mail_rule/delete_mail_rule in the sibling list. It does not explicitly name those siblings, but the replace semantics make the update role clear. The product-specific term 'SuperMailbox' adds identity but no further disambiguation.

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 only implied: the description explains runtime behavior (new incoming mail, first matching rule wins) and how to pause via enabled=false, plus a separation note ('not a provider-native filter'). There is no explicit guidance on when to choose update over create_mail_rule, delete_mail_rule, or list_mail_rules, nor prerequisites such as needing an id from list_mail_rules.

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