SuperMailbox

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

Adds substantial behavior beyond annotations: the call returns a queued operation rather than a confirmed result, the polling target is named (get_mail_action), and retry safety with the idempotency key is spelled out. This async/eventual-consistency model is exactly the kind of trait annotations (destructiveHint, idempotentHint) cannot express.

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, safety-critical asynchronous behavior front-loaded. Minor waste/confusion from 'never retry an uncertain send', wording inherited from a send operation rather than an archive one.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description explains what is returned (a queued operation with an operationId) and how to resolve it. Missing only folder/permission preconditions, which keeps it short of a 5.

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 67% and the schema itself already documents messageId thoroughly and operationId as an idempotency key. The description only reinforces the operationId retry rule, adding little beyond the schema; accountId remains undocumented in both places. 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 and resource ('Archive a message from its current folder'), which is clear on its own. It does not, however, explicitly distinguish itself from the sibling move_email, which is the closest alternative for relocating a message.

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 post-invocation guidance (poll get_mail_action with the operationId, don't retry with a new operationId) but never states when to archive versus move_email or delete, nor any precondition such as required folder state. Usage context is implied rather than explicit.

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?

Annotations already declare readOnly/idempotent/closed-world, and the description adds non-obvious behavior the annotations cannot express: no provider round-trip occurs, a `found` result does not imply a complete thread body, and a `not_cached` result is not a definitive negative. It also discloses that RFC IDs are scoped to the selected mailbox, which materially affects interpretation of misses.

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 the operation and its defining constraint before the caveats. Every clause carries unique information — result states, follow-up tools, negative-result caveat, scoping — with no restatement of the name or annotations.

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 characterize return states, and it does: `found` yields cached opaque message/thread IDs while `not_cached` is a non-definitive miss. Combined with the follow-up path for completing thread bodies, an agent has enough to call this correctly and interpret both outcomes.

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?

Coverage is 50% (only rfcMessageId is schema-documented), so the description needs to carry weight, and it does by clarifying the scope semantics that accountId controls ('RFC IDs are scoped to the selected mailbox', implied in the schema description too). It does not explain format constraints or what happens if accountId does not own the cached thread, leaving one parameter thin.

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 ('Resolve an exact RFC Message-ID') and pins the scope hard with 'using only durable mailbox cache' / 'never searches the provider', which functionally separates it from find_message_by_rfc_message_id. It does not explicitly name that provider-search sibling, so the agent must infer the name from the contrast rather than being routed to it.

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 next-step guidance for the success case ('queue request_cached_thread_refresh and then poll get_cached_thread') and sets expectations for the miss case ('not_cached is not proof that the provider mailbox has no matching message'). It stops short of saying which alternative tool to call when the caller needs an authoritative provider lookup, leaving that inference to the reader.

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, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: headers are searched across folders, exact equality is verified after the IMAP search (so near-misses return nothing rather than approximations), and it returns opaque message/thread IDs that feed other tools — useful because there is no output schema.

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 dense sentences, front-loaded with the action and return value, then the mechanics and access requirement. No restatement of the name 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 two-parameter read tool with annotations and no output schema, the description covers what it does, how it searches, what it returns, and the access level. The remaining gap is the ambiguous mailbox-vs-folders scope and the unstated not-found behavior, which an agent would want to know before relying on it.

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?

At 50% schema coverage, only rfcMessageId is documented in the schema (with pattern and provenance); accountId has none. The description partially compensates by stating the search scope is limited to the supplied account/mailbox, but it does not explain the accountId format or how it is obtained (list_mail_accounts), leaving a gap the schema does not fill.

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 — find an exact RFC Message-ID and return its opaque message/thread IDs — which separates it from the fuzzy search_emails and search_threads_by_recipient siblings. The scope wording is slightly muddy, though: "one selected mailbox" sits uneasily next to "searches mailbox headers across folders," leaving it unclear whether the search is account-wide or folder-bounded.

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 word "exact" and the schema note that the ID comes from send_email/reply_to_email imply when this tool applies, and "requires read access only" sets a permission precondition. However, no sibling is named and there is no explicit when-not guidance (e.g. use search_emails when you don't have an exact Message-ID), so routing must be inferred.

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

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

Beyond the annotations (readOnly=false, destructive=true, openWorld=true), it discloses three non-obvious traits: the operation is queued/non-confirming, attachments are not forwarded, and the body is quoted. These are exactly the behavioral facts an agent needs before invoking a mutating 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?

Front-loaded with the core action, then the caveats, then the operational follow-up. Every sentence carries distinct, non-redundant information with 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 complex mutating, open-world tool with no output schema, the description covers the async return model, polling, and idempotency well. It omits guidance on senderIdentityId selection and deliverability/error handling, leaving minor gaps but nothing blocking a correct 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 coverage is only 25% across 8 parameters. The description only hints at textBody ('optional note'), and does not explain to/cc/bcc arrays, accountId, or senderIdentityId, so it fails to compensate for the large coverage gap on a complex parameter set.

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 ('Forward a message') and immediately scopes behavior with quoting and attachment exclusion. An agent can distinguish it from send_email and reply_to_email without opening the schema, and it names get_mail_action as the follow-up sibling.

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 post-call guidance ('Poll get_mail_action with the returned operationId') and an idempotency rule ('Never retry an uncertain send with a new operationId'). It does not explicitly contrast when to forward vs. reply_to_email or send_email, so it stops short of full alternative routing.

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 genuinely new behavioral context: the response payload format is base64 with an accompanying MIME type, which is not derivable from the annotations and matters because there is no output schema.

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, no filler; the purpose is front-loaded and the return-format fact follows immediately. 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?

With no output schema, the description does the minimum needed by disclosing the return shape (base64 content + MIME type), and annotations carry the safety profile. It is slightly thin on practical caveats such as size limits, whether the attachment may be unavailable, or auth requirements for the account, but nothing blocks a correct 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 coverage is only 33%: accountId and attachmentId have no descriptions anywhere, and the description adds zero parameter guidance (no mention of ID formats, scoping, or the distinction between messageId and attachmentId). Only messageId is documented, and that text lives in the schema, not the description. The description 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 clear verb and resource ('Fetch one attachment') and adds a useful scope hint ('on demand'), which implies the attachment body is not delivered inline with message reads. It reads clearly against get_email/get_thread, though it never names a sibling to route the agent 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 'on demand' implies the calling context (retrieve the binary when the agent actually needs it, rather than during listing or message fetch), but there is no explicit when-to-use, when-not-to-use, or named alternative among the 20 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 closed-world, yet the description still adds real behavioral depth: it explains that stale complete snapshots can be returned, that `not_cached`/`incomplete` are not proof of absence, and that `checkpoint.complete` measures account-wide folder watermark coverage separately from thread completeness. That is exactly the kind of non-obvious semantics an agent needs before acting on a cached 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?

The cache-only guarantee is front-loaded and every sentence carries a distinct operational caveat. It is dense and leans on bare output field names without introduction, which makes it slightly harder to parse than it needs to be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description takes on the return-value burden and does so well for the key status, staleness and checkpoint fields, including the warning to inspect `checkpoint.gaps` and freshness before CRM use. The remaining gap is input-side: nothing tells the agent where `accountId` and `threadId` come from.

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%, so the description must carry the parameter burden, yet neither `accountId` nor `threadId` is mentioned — no ID format, no source for obtaining the IDs, no note that both are required. The names are self-explanatory but that is all the agent gets.

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 opening clause states a specific verb and resource (read the durable mailbox cache) and immediately scopes it with 'never calls IMAP or another provider', which distinguishes it from the live-fetch siblings like get_thread. It stops short of naming those siblings explicitly, so the differentiation is implied rather than stated.

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 'cache-only, no provider call' framing implies this is the cheap read path versus get_thread or request_cached_thread_refresh, and the caveats about `not_cached`/`incomplete` hint at when results should not be trusted. However, there is no explicit when-to-use/when-not-to-use statement and no named alternative for getting fresh data.

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

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

Beyond the annotations, the description explains the meaning of 'supported' (bounded, read-only OpenSearch query succeeded for this exact account generation), clarifies that it does not mean the index contains messages or covers the mailbox, and warns against fallback to live provider search. This is rich behavioral context that materially helps an agent interpret results correctly.

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?

The description is three tightly written sentences, front-loaded with the tool's purpose, then defining key status semantics and constraints. Every sentence earns its place with no 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?

For a simple one-parameter capability-check tool with no output schema, the description does a good job explaining return statuses, interpretation caveats, and constraints. It could be slightly more complete by noting how to source the accountId or its explicit relationship to sibling search tools, but it is largely 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?

The schema has 0% description coverage for the single accountId parameter. The description adds some meaning by saying it targets 'one mailbox' and 'this exact account generation,' but it does not explain the expected ID format or where to retrieve a valid accountId, leaving a gap even for a one-parameter tool.

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 and resource: 'Check cache-only recipient-search capability for one mailbox.' It clearly distinguishes a capability check from an actual search operation, though it does not explicitly name the sibling search tool it relates to.

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 provides some usage guidance: 'pending' should be retried later and unsupported scopes must not fall back to a live provider search. However, it does not explicitly say when to call this tool versus search_cached_threads_by_recipient or how to obtain the accountId.

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 and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: cached copies carry freshness metadata, waitForFresh triggers a bounded provider refresh that is not guaranteed to return fresh data, and reading has no read-receipt side effect.

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 tightly packed sentences: identity of the operation, caching/freshness semantics, then the no-side-effect guarantee. The most actionable constraint comes first and nothing is wasted.

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 return-value burden and does explain that responses include freshness timestamps and stale/refreshing flags. It stops short of describing the body/attachment-metadata return shape, but for a read tool with full annotation coverage this is nearly 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 75% and the messageId parameter already carries rich guidance in the schema. The description reinforces that the ID is opaque and links waitForFresh to freshness metadata, but adds no syntax or format detail beyond what the schema provides, so the 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 and resource ('Read a message body and attachment metadata') qualified by the opaque message ID key. It implicitly distinguishes itself from get_attachment (which fetches attachment content) and get_thread (which fetches a whole conversation), so an agent can route correctly.

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 explains the cache/freshness behavior and the side-effect guarantee ('Reading does not mark the message as read'), which helps an agent choose between this and mark_email_read. However, it never states when to use get_email versus get_thread or search_emails, 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, 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 cover safety (readOnly, idempotent, non-destructive, closed-world), so the description adds real value by bounding the meaning of the answer: it is a worker-level readiness signal, not a statement about cache content. The remaining gap is that it never describes the shape of the answer (two booleans, one status, etc.), which matters because there is no output schema.

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, both earning their place: the first defines what is reported and the second defines the boundary of the claim. The positive statement is front-loaded ahead of the caveat.

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 zero-argument, read-only readiness check with annotations covering the safety profile, the description is essentially complete — it says what is checked and what should not be inferred. The only omission is the return value's form, which is not covered by an output schema and is left implicit.

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 no schema semantics for the description to supplement; the baseline for a parameterless tool applies. Nothing is missing on this dimension.

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: reports whether background mailbox ingestion is enabled and whether the scheduler heartbeat is fresh. That is clearly distinct from every sibling (all of which act on messages, threads, folders, or rules), so an agent can recognize this as the readiness probe 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?

The second sentence gives a clear exclusion — 'worker readiness only; it does not claim that any mailbox or thread cache is complete or current' — which steers the agent away from treating this as a cache-freshness or data-completeness check. It does not, however, name the alternative to call when the agent actually needs cache completeness or a refresh, which keeps it from 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, 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 cover read-only/idempotent/non-destructive, but the description adds genuinely new behavior: a `complete:true` truncation signal, a retryable error for threads past provider bounds, and accountId-scoping of RFC IDs because they are not globally unique. The `complete:true` reference is a little terse given no output schema, which keeps this 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?

Three tight sentences with the core purpose front-loaded and no filler; the truncation caveat follows immediately where an agent would look for it. Density is high enough that `complete:true` reads as jargon on first pass.

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 parameter documentation, the description carries the return-shape burden and does so reasonably: it names the `complete` flag, the RFC header fields that may appear, and the failure mode. What is missing is any hint of ordering, pagination, or message count scale.

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%, so the description must compensate. It adds important meaning for accountId (it scopes RFC Message-ID lookups because they are not globally unique) but says nothing about threadId's format or origin, leaving one of two parameters undocumented.

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 ('Fetch a complete bounded mail thread directly from the provider') and clarifies scope (whole thread, not a single message). It never names the nearest alternatives, get_email or search_threads_by_recipient, so differentiation is inferable 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?

Usage is only implied by 'Fetch ... directly from the provider' and the note that oversized threads yield a retryable error. There is no statement of when to prefer this over get_email or search_threads_by_recipient, and no prerequisites or exclusions.

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, openWorldHint=false and destructiveHint=false, so safety basics are covered. The description adds substantial context the annotations cannot: cache-only, no provider contact, no background scan, every page has complete:false and snapshot:false, late-indexed messages can be missed, and cursor exhaustion does not prove history completeness. These are genuine behavioral disclosures, but a 3 reflects that much of the framing overlaps the readOnly/cache story already signalled structurally.

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?

The description is front-loaded with the core operation and the usage gate before the caveats, and every sentence carries distinct information about scope, alternatives, or incomplete-results risk. It is dense with semicolon-chained clauses, which costs a little readability, and the cursor-continuation sentence could merge with the exhaustion warning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description carries the return-value burden, and it does so precisely by enumerating the returned fields and stating what is absent (no subject, snippet, or body). For a paginated, eventually-inconsistent read tool it also covers the termination and completeness pitfalls an agent would otherwise misjudge.

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% and after, limit, and afterCursor are already documented, so the baseline is 3. The description nonetheless adds cursor-binding semantics ('Pass nextCursor unchanged to continue the requested scan'), which reinforces the schema's stability constraint in the context of a multi-page scan; it is slightly weakened by using 'nextCursor' while the parameter is named 'afterCursor', and accountId remains undefined in both description and 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 first sentence names a specific verb and resource — a bounded, cache-only page of mailbox metadata from a partial OpenSearch subset — and the final sentence scopes exactly what is returned. It explicitly distinguishes itself from list_mailbox_changes and implicitly from the live-fetch siblings by stating it never contacts a provider.

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 narrow, explicit when-to-use condition ('only when CRM explicitly requests bootstrap or gap reconciliation'), an explicit when-not and alternative ('Use list_mailbox_changes for ongoing new arrivals'), and a procedural exclusion ('Do not restart automatically after exhaustion'). An agent has all routing information needed without inspecting the schema.

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 safety is covered. The description adds context annotations cannot: entries may carry a canSend flag per actor, and that flag is advisory because every send action re-authorizes mailbox and sender. That caveat meaningfully prevents an agent from treating canSend as a durable entitlement.

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 tight sentences with the resource scope front-loaded and the authorization caveat second. Both sentences earn their place, though the send-recheck clause is slightly indirect about what it means for the caller (a hint rather than an explicit instruction).

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 burden of hinting at return shape and does so by flagging the canSend field. For a zero-param, read-only listing with rich annotations, that plus the authorization caveat covers what an agent needs to call it correctly; only the sibling relationship remains unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so the baseline is 4; there is nothing to document and the description correctly spends its words on result semantics instead. The mention of canSend is output-level information rather than parameter guidance, which is the right allocation here.

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: listing the current user's connected and explicitly shared email accounts, with a scope qualifier ('current user's') that narrows the result set. It does not distinguish this from the close sibling list_sender_identities, so an agent may need to guess which listing tool is authoritative for a given task.

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: an agent can infer this is a discovery call to run before send-related actions, reinforced by the note about send authorization. There is no explicit when-to-use, no when-not-to-use, and no pointer to list_sender_identities or get_profile as 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real value: it never contacts a provider, it reads only the cache cursor, messages carry sender/recipient and RFC linkage headers but never body or subject, and it documents the reset_required/not-initialized states. The dangling 'bootstrap:true' reference introduces an inconsistency that keeps this 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?

Five dense sentences, front-loaded with the core action and pagination rule before edge cases. The closing sentence about comparing sender against known creator addresses is tangential, and the bootstrap reference adds noise with no matching parameter, but on the whole each sentence carries operational weight.

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 three-parameter read with no output schema, the description covers return shape (sender/recipient, RFC headers, no body/subject), cursor lifecycle, and failure modes (reset_required, uninitialized feed). The gaps are the undescribed accountId and limit parameters and the phantom bootstrap flag.

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 0%, so the description must compensate. It does so thoroughly for afterCursor (when to omit, how to persist and reuse nextCursor), but accountId (the only required parameter) and limit (capped at 100) receive no mention in the description, leaving two of three parameters undefined anywhere.

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 a bounded page from the durable forward-only mailbox feed.' The 'forward-only', 'bounded page' and 'encrypted cache cursor only, never contacts a mail provider' phrasing separates it from live-mail siblings like search_emails or get_email. It does not name any sibling explicitly, which keeps it from 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 concrete operating rules: omit afterCursor on the first call, persist nextCursor and pass it unchanged, reconcile when status is reset_required with recoveryCursor, and retry bootstrap later when no recoveryCursor is returned. A caveat: it instructs 'bootstrap:true' although no bootstrap parameter exists in the schema, so one piece of guidance cannot be acted on.

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 cover generic flags (readOnlyHint=false, idempotentHint=false, openWorldHint=true). The description adds crucial asynchronous semantics: the call returns before provider completion and success must be confirmed via get_mail_action, plus a retry/idempotency constraint. This is exactly the context annotations cannot express.

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 before the async caveat and the retry rule. Slight wording slip: 'Never retry an uncertain send' reuses 'send' terminology that reads oddly for a read-status operation.

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 mutating, non-idempotent tool with no output schema, the description supplies the important operational context: fire-and-poll behavior, the confirming tool, and idempotency-key reuse. It leaves accountId semantics and the exact meaning of isRead unstated, but nothing critical for invocation 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%: messageId and operationId carry rich descriptions, while accountId and isRead are undocumented. The description partly compensates by linking operationId to the polling step and implying the read-state target, but it never clarifies accountId or the semantics of isRead explicitly.

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'), which is clearly distinct from siblings like set_email_starred or move_email. It doesn't explicitly name an alternative, but the purpose 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?

Gives concrete operating guidance: the return is only a queued operation, poll get_mail_action with the operationId, and do not retry with a fresh operationId. It names the follow-up tool and the retry condition, though it does not contrast this tool against alternatives for other state changes.

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 flag destructive=false... rather destructiveHint=true and idempotentHint=false, but the description goes well beyond them by disclosing the async queued semantics, that the return is not provider confirmation, the required follow-up call, and the idempotency retry rule. This is exactly the behavioral context an agent needs for a mutation with delayed completion.

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 the action and then the async/retry contract. No filler; every clause carries either purpose or a behavioral 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?

For a destructive, non-idempotent, open-world mutation with no output schema, the description covers the async lifecycle and retry safety well. It omits permission requirements and the fate of the source message, but nothing essential to correct invocation 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 description coverage is 50%: messageId and operationId are documented inline, while accountId and destinationFolderId are not. The description adds meaning to operationId (it is returned and drives polling) and implies destinationFolderId via 'another folder,' but leaves accountId and the folder-ID format unexplained, so it only partially compensates.

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 ('Move a message to another folder'), which is clearly distinct in effect from sibling reads like get_email or search_emails. It does not explicitly differentiate from archive_email, which is also a folder-move operation, so an agent might hesitate between the two.

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?

Provides explicit operational rules: poll get_mail_action with the returned operationId, and never retry an uncertain send with a new operationId. These are strong usage directives, though it doesn't state when to prefer move_email over archive_email for routing decisions.

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 declare destructiveHint=true and openWorldHint=true but say nothing about the async contract. The description supplies the critical behavior: it returns a queued operation immediately, is not confirmation of provider completion, an uncertain SMTP attempt is never auto-retried, and progress must be polled via get_mail_action. This is exactly the value-add structured fields 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?

Front-loaded purpose followed by operational rules, all in five tight sentences. The final sentence ("Never retry an uncertain send with a new operationId") restates the earlier retry guidance, a minor redundancy that costs a point.

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 a complex async send path, the description covers the return contract, polling tool, and retry policy, which is most of what an agent needs. It omits the semantics of replyAll and senderIdentityId, a modest gap for a 7-parameter mutation.

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 29% (accountId, senderIdentityId, textBody, htmlBody, replyAll are undocumented in the schema). The description explains operationId semantics well (stable, retry-only reuse) and reinforces messageId handling, but leaves replyAll and senderIdentityId meaning unaddressed, so it only partially compensates.

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?

"Reply to a message" is a specific verb+resource that clearly separates it from send_email, forward_email, and create_draft among the siblings. It does not explicitly name those alternatives, so differentiation relies on the reader's 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?

It gives concrete usage context: supply a stable operationId, reuse it only for retries, and poll get_mail_action. The retry/idempotency guidance is explicit, but it never states when to prefer this over, say, forwarding or starting a new thread.

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

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

Beyond the annotations, the description discloses the key behavior that this call returns immediately without doing provider I/O, making the asynchronous, poll-later contract explicit. The annotations already cover safety and idempotency, so this addition is exactly the context an agent could not infer elsewhere.

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 action and the async contract, then the follow-up sequence, then the caveat about false negatives. Every sentence contributes information that affects how the tool is called.

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 enqueue tool with no output schema, the description explains the timing, follow-up calls, and result interpretation well. It stops short of saying what the immediate return value contains, such as a job handle or an acknowledgment, which would have closed the remaining 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 only 50%: `accountId` has no description, while `rfcMessageId` is documented in the schema. The description partly compensates by stating that RFC IDs stay scoped to `accountId`, which explains why the account must be supplied. It still doesn't say where to obtain `accountId`, such as from `list_mail_accounts`, which leaves a small 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?

The description opens with a specific verb and resource: 'Queue a durable, idempotent RFC Message-ID lookup for background provider resolution.' It clearly distinguishes this from the lookup siblings by making explicit that this only enqueues work, while the actual read is done by `find_cached_thread_by_rfc_message_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?

The description provides a full workflow: poll `find_cached_thread_by_rfc_message_id` later, then queue `request_cached_thread_refresh` if a thread is found. It also warns that a negative or not-cached result is not proof that no match exists, which prevents an agent from misreading an empty result.

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 declare readOnly/idempotent/non-destructive, and the description adds the crucial non-obvious behavior: it returns after durable queue admission and never waits for a provider read. That tells the agent the returned state is not the final data, which annotations alone could not convey.

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 redundancy: the first establishes the action and its async nature, the second gives the follow-up. Key constraint (does not wait) is front-loaded rather than buried.

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 enqueue tool with no output schema, the description covers the asynchronous contract and where results appear, which is the main risk of misuse. The only real gap is parameter meaning, which the schema also leaves empty.

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% and the description never mentions accountId or threadId, so neither parameter's meaning, format, or sourcing is explained anywhere. With two required undocumented parameters, the description should compensate and does not.

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 ('Queue an asynchronous refresh of one cached thread') and implicitly separates itself from the polling sibling get_cached_thread and the RFC lookup variant by emphasizing 'cached thread' and 'refresh'.

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 second sentence tells the agent exactly what to do next (poll `get_cached_thread` for messages and completeness state), which is effective use guidance. It stops short of stating when NOT to use it versus request_cached_rfc_thread_lookup or get_cached_thread directly.

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, closed-world, non-destructive), and the description adds behavior those annotations cannot convey: it never contacts a mail provider, results are always `status:'partial'` with `complete:false`, and an empty page is explicitly not proof of absence. Those are the exact caveats that prevent an agent from misreading an empty result as a negative answer.

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 sentences, front-loaded with the scoping constraint, and each one carries distinct information: what is searched, the partiality caveat, and the follow-up path. Minor friction from calling the input `cursor` 'the opaque `nextCursor`', which mixes request and response naming.

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 does the necessary work of describing the return shape (`status:'partial'`, `complete:false`, `nextCursor`) and the downstream workflow. It leaves parameter-level details and pagination limits unstated, but nothing critical to invoking the tool 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 description coverage is 0%, so the description must carry the load, and it only partly does. It clarifies that matching is on exact participant email and that the pagination token is opaque, but `accountId`, `limit`, and the `cursor` argument itself (referred to by the response-side name `nextCursor`) are left entirely to 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 names a specific verb and resource ('Search only the durable OpenSearch metadata subset for exact participant email matches') and scopes it to cached/durable data. It never explicitly names the sibling `search_threads_by_recipient`, but 'This never contacts a mail provider' implicitly draws the cached-vs-live boundary an agent needs to choose between 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?

Clear context is given for what to do with results: continue with the opaque `nextCursor` when present, and use `get_cached_thread` plus the asynchronous refresh request before importing a selected thread. That is actionable routing guidance, though it never states outright when to prefer this over the live sibling `search_threads_by_recipient`.

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 (readOnly/idempotent/openWorld); the description goes far beyond by disclosing that results mix indexed and provider matches, explaining nextCursor semantics (the cursor may advance provider traversal even when messages is empty), pendingAccountIds, semanticPending, and the bounded nature of waitForFresh. This is exactly the extra context 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 is front-loaded, but the body is a dense, run-on block: the retry-with-identical-filters-and-waitForFresh:false instruction is effectively stated twice, and the semanticPending/pendingAccountIds/freshness distinctions are repeated. Much of it earns its place given the async indexing model, but it is bloated and could be tightened considerably.

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 describes compact summaries, messages/nextCursor, pendingAccountIds, semanticPending, failures, and stale/refreshing flags, and warns that stale or pending results are not proof of an empty mailbox. Nothing critical for correct invocation 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 only 25%, so the description must compensate and largely does for the hardest parameters: folderId/accountId coupling, cursor continuation rules, waitForFresh and the cached/partial deadline behavior. However, the filter-style params (to, from, subject, after/before, isRead, isStarred, hasAttachments) remain undocumented in both the schema and the description, leaving a 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 ('Search connected mailboxes') and immediately distinguishes its role from the sibling get_email ('Results are compact summaries; use get_email to read a message'). An agent can tell what this returns versus what get_email returns 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?

Explicit guidance on when and how to use it: default scope is Inbox when folderId is omitted, accountId defaults to all connected mailboxes, and searching Sent/Drafts requires first calling list_mail_folders and passing that folderId with the same accountId. It also explicitly states there is no all-folders selector and tells the agent to prefer cursor continuation over a new search.

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 (which already declare readOnly/idempotent/non-destructive) by disclosing that results are metadata-only, capped at 50 threads, that Drafts/Trash/Junk are skipped, and how the complete:false flag signals partial coverage. That partial-coverage semantics is exactly the kind of behavior an agent cannot infer from schema or 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?

Three tight sentences, front-loaded with what it finds and where, followed by output shape and the caveat. Nearly every clause earns its place; the 'across selectable folders' phrasing is the one piece that adds ambiguity rather than 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 carries the return-value burden and does so partially: it states metadata-only, 50-thread cap, and the complete flag. It doesn't indicate what metadata fields come back or why folders are mentioned without a folder input, leaving minor gaps for a 3-parameter search 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 description coverage is 0%, so the schema names parameters without explaining them. The description clarifies recipientEmail must be an exact participant email and that results are capped at 50 (matching the limit maximum), but it never explains accountId directly and mentions 'selectable folders' despite no folder parameter existing in the schema, which is more confusing than clarifying.

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 (find), specific resource (thread candidates in one selected mailbox), and explicit scope constraints (exact participant email, selectable folders, excluding Drafts/Trash/Junk). It is clearly distinguishable from search_emails (recipient-exact, thread-level) and get_thread (verification, not discovery).

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 workflow instruction: verify each candidate with get_thread before importing, and warns about the complete:false case. It doesn't compare itself against search_emails or find_message_by_rfc_message_id for the same lookup need, so the alternative selection is only partially covered.

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?

Annotations only say this is a non-read-only, non-idempotent, open-world mutation. The description goes well beyond them by disclosing that the call is queued and asynchronous, that the immediate return is NOT proof of provider completion, and the exact retry discipline to follow. That is the kind of context 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?

Four short sentences, front-loaded with the core action before the async caveat and retry rule, with no filler. Minor blemish: 'an uncertain send' borrows send-oriented phrasing for a star operation, which slightly muddies an otherwise tight passage.

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 what comes back (a queued operation plus operationId) and how to resolve it. What is missing for a mutation tool is failure handling and any account/permission expectations, but the async contract itself is fully covered.

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%: messageId and operationId are well documented in the schema itself, while accountId and isStarred have no description. The description adds no parameter-level meaning, though the two undocumented params are near-self-explanatory (account string, boolean flag), so the baseline 3 holds rather than dropping lower.

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 states a specific verb and resource ('Set whether an email is starred'), so an agent knows exactly what state is mutated. It does not explicitly say how it differs from the similarly-shaped mark_email_read sibling, which keeps it 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?

It gives concrete operational guidance: use get_mail_action to poll with the returned operationId, and reuse the operationId rather than minting a new one on retry. That is clear when-and-how guidance, though it never states when not to use this tool or names an alternative for the flag-setting case.

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.