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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds a genuinely non-obvious behavioral fact — that passwords are never returned — which tells the agent what NOT to expect in the payload and confirms the read-only, local nature of the call.

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, zero waste, with the returned content front-loaded and the caveat placed second. Nothing redundant.

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 parameters, no output schema, and simple annotations, the description covers what an agent needs: what comes back and the key exclusion. It could say slightly more about the shape of 'server settings', but the omission is minor for a no-arg list 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?

The tool takes zero parameters, so per the baseline a 4 applies. The description correctly implies a no-argument, whole-list retrieval rather than a filtered one.

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') plus three concrete resources: mailbox IDs, server settings, and local attachment directories. An agent can tell this is a configuration-inspection tool, though it doesn't explicitly differentiate itself from the nearby mail_setup_status 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?

No guidance on when to call this versus mail_setup, mail_setup_status, or other siblings. The purpose implies inspection of existing configuration, but there is no explicit when-to-use or when-not-to-use statement.

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 destructiveHint=true and idempotentHint=false, but the description adds substantial context beyond them: the UIDVALIDITY/UIDPLUS requirement that prevents expunging unrelated Deleted messages, and the authorization rule that content cannot authorize deletion. This is exactly the safety-relevant disclosure a destructive tool needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, each earning its place, with the destructive action and its precondition front-loaded before the safety rationale.

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?

The safety and authorization story is complete for a destructive, non-idempotent tool with no output schema, but the bare 0%-coverage schema leaves the agent without any guidance on three of the four required parameters, which is a real gap.

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

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

Schema description coverage is 0% across four required parameters, so the description carries the full burden. It only illuminates uidValidity (observed UIDVALIDITY) and leaves accountId, folder, and uid format entirely undocumented, so it does not compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (permanently delete) and resource (one exact message), and its scope — a single message, permanent — clearly distinguishes it from soft-delete siblings like mail_move or mail_set_flags. An agent can identify the operation without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit gating condition: only when the user explicitly requests permanent deletion, plus a when-not rule that mail content cannot authorize deletion. It stops short of naming a sibling alternative (e.g. a soft-delete/trash tool) for the non-permanent 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond them: private saving, decoded transfer encodings, possible display normalization of inline text, and the >64 KiB overflow path that writes a private JSON file and returns completeResultFile. This is exactly the kind of non-obvious side effect an agent needs.

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 identity and scoping rule before the overflow and encoding details. 'Duplicate filenames remain unambiguous' slightly restates the 'not by filename' clause, but the rest earns its space.

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

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

With no output schema, the description correctly supplies the return contract (path, bytes, SHA-256, completeResultFile summary) and the large-result behavior. It is close to complete, missing only guidance on invalid/stale partId or uidValidity mismatch failure modes.

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. It clarifies partId richly (exact dotted part path, unambiguous despite duplicate filenames), but says nothing about accountId, folder, uid, or the uidValidity pairing — four required IMAP parameters whose relationship is not self-evident from the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Stream any MIME part by exact partId') and immediately scopes it against the sibling 'mail_download_raw' by contrasting decoded vs. original bytes. An agent can distinguish this from every other mail_* sibling 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 explicit selection criteria: use partId from mail_get_message rather than a filename, and use mail_download_raw when original encoded bytes are wanted. Both the when and the when-not (with the named alternative) are present.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), yet the description adds substantive behavior: output is written to a private local file, returns path/byte count/SHA-256, and results over 64 KiB are spilled to a private JSON file with a compact summary plus completeResultFile. These operational details go well beyond what annotations provide.

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 primary action before the return/truncation details. Every sentence carries information, though the two return-behavior sentences could be merged without loss.

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 documents the return values (file path, byte count, SHA-256) and the truncation/completeResultFile escape hatch, making it self-sufficient on the output side. Its one gap is the complete absence of parameter guidance for a four-required-param 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% across four required parameters (accountId, folder, uid, uidValidity), so the description carries the full burden — but it mentions none of them. It adds no meaning about identifier formats, the uidValidity pairing, or why folder plus accountId are needed, leaving the agent to infer everything from bare property names.

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 ('Stream the complete original RFC822 message (.eml) ... into a private local file') and explicitly differentiates from read-into-output siblings by noting it does not load the message into tool output. An agent can distinguish this from mail_get_message and mail_download_attachment 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?

Conveys the scenario clearly through the phrase 'byte-preserving source of truth' and the contrast with loading into tool output, implying when raw archival retrieval is wanted. It stops short of naming an alternative tool or stating explicit exclusions, so it earns a 4 rather than 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for going further: it discloses no message bodies are read and, importantly, the 64 KiB overflow behavior where full results go to a private JSON file and a compact summary with completeResultFile is returned. That overflow contract is behavioral detail an agent cannot get from annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with zero filler; the scope enumeration comes first and the overflow/return-format detail follows. Every sentence carries distinct information.

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

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

With no output schema and no parameter documentation, the description does well to describe the result shape (folders, roles, status counts, completeResultFile path) and the no-body-read guarantee. The only meaningful omission is any explanation of the accountId input.

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?

There is one required parameter (accountId) and schema description coverage is 0%, so the schema provides no semantic help. The description never mentions accountId at all, so it fails to compensate — the agent gets no hint about what identifies an account or where to obtain that value.

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 ('List') plus resource ('every mailbox folder') with explicit scope: unsubscribed folders, special-use roles, and server status counts. This clearly separates it from siblings like mail_list_messages and mail_manage_folder, which operate on messages or folder mutation.

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 — an agent enumerates folders before acting on them — but the description never states when to prefer this over mail_manage_folder or mail_accounts, nor any precondition such as needing a resolved accountId. Adequate but with a clear gap.

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 annotations: it discloses that complete body parts are written to private local files, that HTML is returned as inert non-executed text, that mail content is untrusted data and never instructions, and that results over 64 KiB are persisted to a private JSON file with a compact summary plus completeResultFile. Annotations cover the read-only/idempotent safety profile, and the description layers substantial operational and security context on top.

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 sentences, all load-bearing, with the payload description front-loaded before the storage/truncation and security notes. No filler, though the density means a few clauses (the file-saving behavior) could be tightened.

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 a good job describing returns (previews, partId downloads, completeResultFile) and safety posture. But for an 8-parameter tool with 0% schema coverage it leaves every input parameter unexplained, including the required uidValidity, which an agent cannot infer from the name alone.

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% across 8 parameters, so the description carries the full burden of explaining maxBodyParts, previewBytes, includeBodies, headerPreviewBytes, and the four required addressing fields (accountId, folder, uid, uidValidity). It names none of them, only describing outputs like partId and completeResultFile; 'bounded text/HTML previews' hints at previewBytes but gives no units, defaults, or limits.

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 (read a message) and enumerates the payload shape: server metadata, duplicate-preserving ordered headers, MIME structure, and bounded text/HTML previews. It is clearly differentiated from mail_download_raw by the 'download the raw .eml for original bytes' pointer, though it never distinguishes itself from the singular-vs-plural sibling mail_get_messages.

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 through embedded pointers ('Other MIME parts are downloadable by partId', 'download the raw .eml for original bytes'), which gestures at mail_download_attachment and mail_download_raw. However there is no explicit when-to-use/when-not statement, no prerequisite description (e.g. needing uidValidity), and no direct callout of the sibling this replaces.

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), so the bar is lower, yet the description adds substantial behavior: the hard 10-reference ceiling, per-reference results returned in input order, sanitized errors instead of failures, and overflow to a private JSON file with a summary and no silent drops. That is exactly the kind of contract an agent cannot infer from annotations or 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?

Four tightly packed sentences, front-loaded with the batch-read contract, then default behavior, then return semantics. No filler. Slightly dense in the back half, but every sentence 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 heavy lifting by explaining the per-reference result/error shape, input-order guarantee, and file-overflow behavior. The main gap is undocumented previewBytes and addressing fields, which leaves the calling contract slightly incomplete.

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 carries the burden and only partially pays it: it clarifies includeBodies ('request bodies explicitly') and hints at full addressing ('exact message references'), but previewBytes is never explained and the accountId/folder/uid/uidValidity quartet is left entirely to the schema. Baseline 3 for a 3-param tool with no schema text.

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+scope: reads up to 10 exact message references across folders/accounts in one call. The batch framing and 'exact references' wording implicitly separate it from the singleton mail_get_message and from mail_search_messages/mail_list_messages. It stops short of naming a sibling explicitly, which is the only thing keeping 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?

'Metadata and headers only by default; request bodies explicitly' gives real guidance on the includeBodies toggle. However there is no when-to-use-this vs mail_get_message/mail_search_messages/mail_list_messages routing, and no prerequisites (e.g., needing uidValidity from a list call). Usage is implied rather than stated.

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

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

Beyond the readOnly/idempotent annotations, it discloses non-obvious behavior: pagination cursors are stable and scoped to account/folder/UIDVALIDITY, empty pages must still be followed, and oversized results (>64 KiB) are written to a private JSON file with a completeResultFile pointer. That is meaningful disclosure the annotations cannot 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?

Four tight sentences, front-loaded with the core action and scope before pagination and truncation details. Every sentence carries distinct information, though the density borders on terse for the pagination 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?

No output schema exists, yet the description covers the return shape at a high level (metadata plus pagination, plus the completeResultFile fallback) and the full pagination procedure, so an agent can call it correctly. It stops short of naming the returned metadata fields or the concrete page-size limit.

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?

With 0% schema description coverage, the description does the heavy lifting: it explains cursor continuation and its stability guarantees, that folder scopes the listing to a single folder, and account scoping. pageSize is left entirely unexplained, which is the one real 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 gives a specific verb and resource ('List messages'), plus concrete ordering and scope ('newest UID first in one folder', 'entire retained history with no date cutoff'). It implicitly contrasts with a filtered search tool but never names a sibling like mail_search_messages or mail_get_messages, so differentiation requires 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 clear operational guidance: read folders first, repeat per folder to cover the account, and continue nextCursor even when a page is empty. That is strong how-to-use context, though it never states when to prefer this over mail_search_messages or mail_get_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 destructiveHint=true and readOnlyHint=false, so the description's value-add is the specifics: delete 'permanently removes the folder and its contents' and needs explicit user instruction. That is meaningful disclosure beyond the annotations. It does not address idempotency behavior for rename/create or error conditions.

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 action list, followed by the highest-risk behavior (permanent delete) and then the path format hint. Every sentence carries information, though the trailing 'Pass full server folder paths' is slightly abrupt and could be tied more explicitly to the folder/newPath parameters.

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?

A multi-action mutation tool with 0% schema coverage and no output schema needs to explain how newPath relates to each action and what happens on failure. The description covers the destructive delete case well but leaves the rename/create parameter contract and error behavior undocumented.

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

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

Schema description coverage is 0% across four parameters, so the description carries the burden. It clarifies only the 'folder' parameter (full server folder paths) and never mentions newPath — the parameter that distinguishes rename/create from delete — nor accountId. The action enum is self-documenting in the schema, but a key parameter is entirely unaddressed.

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 resource (mailbox folder) and enumerates all five verb-like actions that match the action enum, so the agent knows exactly what the tool mutates. It does not explicitly contrast with siblings like mail_folders (listing) or mail_move (moving messages), leaving that differentiation to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives one real usage condition — delete 'requires the user's explicit deletion instruction' — which is a useful gating rule. However, it never says when to prefer this tool over mail_folders or mail_move, nor when subscribe/unsubscribe or rename are appropriate, so usage is only partially guided.

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, readOnlyHint=false, non-idempotent, open-world. The description adds key context: it doesn't permanently delete Trash contents, and requires observed UIDVALIDITY. This goes beyond annotations usefully, though it doesn't detail permission requirements or error modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences front-loaded with the core action, then constraints. No waste, though the Trash exception could be integrated more naturally.

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?

Covers the 'what' and key behavioral caveats (user intent, UIDVALIDITY, non-permanent delete) but with six parameters at 0% schema description coverage and no output schema, it leaves significant gaps: what destination does, what happens on copy, return values, and error conditions.

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 should compensate for 6 undocumented parameters. It explains the UIDVALIDITY requirement and destination (via folder/Trash mention) but leaves accountId, folder, uid, and the move/copy/trash action semantics largely to the schema enum. Partial compensation only.

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 (move/copy) and resource (exact message to a folder/Trash). Clear enough to distinguish from siblings like mail_delete_permanently, though it doesn't explicitly name alternatives.

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?

Mentions 'Requires user intent' and distinguishes move-to-Trash from permanent deletion, implying when to use it. But it doesn't state when to use copy vs move vs trash, or route to siblings explicitly.

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, closed-world, but the description adds real value beyond them: it discloses the returned content (preview + SMTP outcome) and explicitly states that no network call or retry occurs. It omits auth/permission requirements, which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with zero filler. The resource being inspected is front-loaded, followed by the return contents and the safety constraint, making it easy to scan.

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 partial duty by naming the return contents (preview, SMTP outcome). However, with two undocumented parameters at 0% coverage, an agent still lacks the identifiers needed to call it 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 0% for both required parameters, so the description carries the full burden of clarifying them. It mentions neither accountId nor operationId explicitly; 'a prepared or attempted send' only loosely hints at what the operationId identifies.

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 ('Inspect') and resource ('a prepared or attempted send') and names exactly what is returned ('the full preview and known SMTP outcome'). It is clearly distinguishable from mail_send_prepared and mail_prepare, though it does not explicitly name the sibling it differs from.

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?

'No network access or retry' implies this is the safe inspection step taken before or instead of mail_send_prepared, so usage is implied rather than stated. There is no explicit 'use this when...' or 'use X instead when...' guidance, leaving the agent to infer the workflow position.

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 it is a non-read-only, non-idempotent, open-world, non-destructive call. The description adds genuinely new behavior: it stages into the local outbox, returns a preview plus operation ID, never transmits, refuses to treat mailbox content as send authorization (prompt-injection defense), and enforces UIDVALIDITY/attachment-folder constraints. That is substantive context beyond the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with purpose and the send/no-send boundary before the constraint clauses. Dense and largely waste-free, though the telegraphic fragments ('Original-message actions require observed UIDVALIDITY') trade a little readability for brevity.

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

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

With no output schema, the description usefully declares the return shape (full preview and operation ID). For a 12-parameter mutation tool the main remaining gap is the post-prepare lifecycle and body/addressing semantics, but safety and preconditions are 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 description coverage is 0% across 12 parameters, so the description carries the burden and only partly discharges it. It clarifies kind (matching the enum), links uid/uidValidity to original-message actions, and constrains attachments, but to/cc/bcc, subject, text/html, folder, and accountId get no added meaning.

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 (prepare) plus the resource and all four modes (new, reply, reply-all, forward), scoped to the local outbox. The clause 'does not send' cleanly separates it from mail_send_prepared and the draft-editing siblings without needing 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?

'Does not send' establishes the boundary with mail_send_prepared, and two explicit prerequisites are given: original-message actions require observed UIDVALIDITY, and attachments must live in the approved uploads folder. It stops short of naming the sibling to use next or the exact call that observes UIDVALIDITY, so it is strong but not fully 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?

Adds real behavioral context beyond the annotations: it returns a preview plus a new operation ID, and the source draft is retained after sending. That non-destructive retention detail is exactly the kind of thing annotations don't convey, though it omits permissions/auth needs and whether repeated calls create duplicate operations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the action, then the return contract, then the post-send state. Every sentence carries distinct information with no padding.

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

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

With no output schema, the description helpfully states the return shape (preview + operation ID). The remaining gap is input identification and prerequisites, but for a moderate-complexity prepare step this is largely 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 0% for all four required parameters, and the description never mentions them. It alludes to 'the source draft' but never explains that accountId/folder/uid/uidValidity identify which draft to prepare, so the burden of explaining the inputs is entirely unmet.

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 ('Prepare a server draft for sending') and explicitly separates the action from sending, which distinguishes it from mail_send_prepared. It does not, however, name sibling tools like mail_prepare or mail_update_draft, so the boundary against those is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'sending is separate' implies the two-step flow (prepare here, then mail_send_prepared), which is useful routing. But there is no explicit when-to-use/when-not statement, no prerequisites (does the draft already have to exist?), and no comparison to mail_prepare or mail_save_draft.

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 a non-read-only, non-destructive, non-idempotent, open-world operation, so the safety profile is covered. The description adds real context beyond them — threading preserved on replies, attachments preserved on forwards, return of the new UID/UIDVALIDITY, and that it never sends. However, it omits permission requirements and whether repeated calls create duplicate drafts (relevant given idempotentHint=false).

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, no filler, with the core action and the conditional prerequisites front-loaded and the never-sends guarantee placed last for emphasis. Slightly dense but every sentence carries information.

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

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

No output schema exists, and the description helpfully states the returned UID and UIDVALIDITY, which closes that gap. For a 12-parameter mutation tool with zero schema descriptions, though, important call-shaping details (required accountId, address list limits, attachment relativePath semantics) are absent.

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% across 12 parameters, so the schema documents none of them. The description compensates for the conditional parameters — folder, uid, uidValidity for reply/forward, attachments for forward, recipients/body — but is silent on accountId, cc, bcc, subject, html/text distinction, kind default, and the attachment object shape, leaving much of the surface 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?

The description states a specific verb (save) and resource (server draft) and enumerates the supported kinds: new, reply, reply-all, forward. The closing 'Never sends' cleanly separates it from mail_send_prepared, though it never names mail_update_draft or mail_prepare_draft as alternatives.

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 states concrete preconditions — reply/forward requires the original folder, UID and observed UIDVALIDITY — and notes recipients and body may be incomplete, which tells the agent this can be called with partial data. It lacks any explicit routing advice for modifying an existing draft versus creating a new one.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely non-obvious behavior: no implicit date cutoff, server-defined search that does not OCR or search binary attachments, and the 64 KiB large-result handling that spills full output to a private JSON file and returns completeResultFile. That is substantial context beyond 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?

Purpose is front-loaded and each subsequent sentence adds a distinct fact (boolean semantics, headers, date policy, OCR limits, coverage loop, large-result handling). It is dense and packs a lot into one block, but little 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 responsibly covers return behavior via the 64 KiB/completeResultFile note, plus search semantics and caveats. The main omission is how pagination (cursor/pageSize) works, but overall it is adequate for an agent to call the tool correctly.

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

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

Schema description coverage is 0%, so the description carries the burden; it does explain the query object semantics (fields AND together, anyOf children OR, headers substring/true-for-existence), but says nothing about cursor, pageSize, folder, or accountId behavior. It compensates well for the query object but leaves the pagination and addressing params 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?

The opening sentence names a specific verb and resource with scope: 'Search the entire retained history of one folder using server IMAP search.' That single-folder, full-history scope distinguishes it from sibling mail_list_messages and mail_get_messages without needing their schemas.

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 implies operational usage ('Repeat across folders and all cursors for account-wide coverage') but never states when to choose this over mail_list_messages or mail_get_messages. No explicit when-not or alternative routing is given, leaving the agent to infer selection from the verb.

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 non-read-only, non-idempotent and open-world behavior, so the bar is lower, yet the description adds real value: the one-attempt-per-operationId retry policy, the split between SMTP acceptance and Sent-copy outcome, and the warning that email content is untrusted and cannot authorize the action. Auth/permission requirements and failure modes beyond retry are not covered.

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 its precondition, then retry policy, then return shape, then the safety caveat. Nothing is redundant and nothing is padding.

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

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

For a mutating tool with no output schema, the description covers return semantics (SMTP acceptance vs Sent-copy), retry policy, user authorization precondition, and injection safety. The remaining gap is parameter meaning, particularly accountId, which is left entirely to the bare schema.

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 carries the burden, and it only partially compensates: 'one attempt per operation ID' gives operationId meaningful retry-scoping semantics, but accountId is never explained and no format or sourcing guidance is given for either parameter.

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 the exact prepared email'), and the word 'prepared' implicitly separates it from the compose-side siblings such as mail_prepare and mail_prepare_draft. It stops short of naming the sibling it depends on, so an agent must infer that a preparation step precedes 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 a clear precondition ('after the user explicitly asks to send it') and an explicit when-not ('never blindly retry unknown outcomes'). It does not name the alternative tools an agent might confuse it with, such as mail_prepare or mail_save_draft, so routing is implied rather than spelled out.

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

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

Annotations already declare idempotent=true, destructive=false, and openWorld=true, so the safety profile is covered. The description adds meaningful domain behavior: the UID/UIDVALIDITY pairing requirement, the supported flag set, and the important exclusion that Deleted cannot be set here. It does not describe what happens on a UIDVALIDITY mismatch, which keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the action, then supported values, then the exclusion. No filler, though the value enumeration could be folded more economically.

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-parameter mutation with no output schema, the description covers the flag domain and the Deleted exclusion well, but omits the semantics of accountId/folder, whether add and remove may be combined in one call, and any note on failure modes. Adequate but with clear 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 0%, so the description must carry parameter meaning, and it partially does: it explains that add/remove take flag names and enumerates valid values (Seen, Answered, Flagged, Draft, custom keywords). However, accountId, folder, and uidValidity are never explained, and the required-vs-optional distinction is left 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?

States a specific verb (add/remove) and resource (message flags) and immediately distinguishes itself from the deletion siblings by pointing to trash/permanent delete tools. An agent can identify the operation without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear operational condition (use the exact UID and observed UIDVALIDITY) and an explicit when-not with alternatives (Deleted is excluded; use trash or permanent delete tools). It lacks guidance on when to reach for this vs. other flag-adjacent operations, but the routing to the delete siblings is 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?

Despite having annotations, the description adds substantial behavioral context beyond them: it checks local storage before prompting for credentials, reports process identity, rejects known Windows Codex sandbox accounts, accepts no password, and only mutates local account settings when the user submits the form. This is consistent with readOnlyHint=false / destructiveHint=false and materially informs the agent.

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 purpose is front-loaded in the first sentence, and subsequent sentences each carry distinct behavioral or safety information (storage check, sandbox rejection, URL handling, no-password, scope of mutation). It is dense and slightly long, but no sentence is 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 must hint at the return value, and it does ('the returned URL'), plus it covers side effects and constraints thoroughly. Minor gaps remain (URL lifetime, form contents), 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?

The tool takes zero parameters, so the baseline is 4. The description reinforces this by stating 'Accepts no mailbox password,' confirming there is nothing to supply at call time.

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 gives a specific verb+resource: 'Start or reuse a private local mailbox login form in the actual MCP process.' The scope qualifier ('in the actual MCP process') and the 'start or reuse' framing make it distinguishable from a status/query tool, but it never names or contrasts with siblings like mail_setup_status or mail_accounts.

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 tells the agent what to do with the result ('Open the returned URL in the app browser or give it to the user') and states a clear prohibition ('never read the filled form'), which is genuine operational guidance. It stops short of explicit when-to-use/when-not-vs-alternative routing among the many mail_* 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 establish read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it does not read passwords, contact the mailbox, or run another storage probe, and it explains what a blocked result means and what action is required.

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 purpose and then adds usage, exclusions, and error handling. It is a bit dense but each sentence carries useful information without obvious waste.

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 no-argument diagnostic tool with rich read-only annotations and no output schema, the description covers purpose, when to call it, what it explicitly avoids, and how to handle a blocked result. Nothing essential appears to be 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?

The tool has zero parameters, so the baseline is 4. No additional parameter meaning is needed or expected.

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 read operation: local login progress, loaded connectorVersion, and MCP execution context. It does not name a sibling tool explicitly, but its scope exclusion ('Does not contact the mailbox') implicitly differentiates it from mail_* siblings.

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 clear triggers: after an upgrade to compare connectorVersion and detect a stale process, and after the user finishes the private form. It also gives failure-mode guidance ('A blocked result requires fixing the MCP host execution context, not repeating sandbox-shell login'), though it does not name alternative tools.

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 rich behavior beyond the annotations: the save-new-before-remove ordering, attachment preservation default, that supplied attachments are appended, that text/html replaces the old alternate body, and that the return is the NEW draft UID. The 'Never sends mail' guard is a valuable safety clarification for a mutation tool with destructiveHint=false.

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 verb and mechanism, then each subsequent clause carries unique information (requirements, attachment semantics, body replacement, return value, safety). No filler sentences.

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 12-parameter mutation tool with no output schema, the description covers the critical return value, preservation semantics, body-replacement behavior, and safety boundary. An agent has what it needs to call it 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 0% across 12 parameters, so the description must compensate, and it only covers about half (uid, uidValidity, preserveAttachments, text, html, attachments). accountId, folder, to, cc, bcc and subject are left entirely to their names.

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 ('Update an existing server draft') plus the underlying mechanism ('saving a new version before removing the old one'). This implicitly separates it from draft-creation siblings like mail_prepare_draft and mail_save_draft, though it does not name any 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?

Gives clear context for when the tool applies (an existing draft that must carry exact UID, observed UIDVALIDITY and UIDPLUS) and a boundary ('Never sends mail'). It stops short of naming the sibling to use instead for a new draft, so it lacks an explicit alternative path.

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