mailmcp

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

Annotations already say readOnly, idempotent, openWorld, and non-destructive, so the behavioral bar is lower. The description adds meaningful context beyond annotations: it discloses the auth/plan requirement and explains that items distinguish proved no-reply from unknown. It does not cover pagination, rate limits, or broader operational caveats, so 4 is appropriate.

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 tight sentences, front-loading the filtering rule before the output status and auth requirement. Every clause earns its place by adding selection criteria or invocation context. There is 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?

Given the output schema exists, the description need not explain return values, and the annotations cover safety. It provides the core filtering semantics, the unknown/no_reply_found caveat, and auth/plan requirements, which is nearly complete for a list-style tool. It leaves within_days semantics and some parameter interactions to the schema, so 4 rather than 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 description coverage is 100%, so the schema already documents all five parameters. The description adds real semantic value for older_than_days by defining it as the threshold for the owner's newest message being too old, but it does not clarify within_days, limit, account, or exclude beyond the schema. That is enough for a 4 but not a 5.

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 precise verb and resource: it lists threads where the owner wrote last and no reply exists. The criteria, including older_than_days and the no_reply_found/unknown distinction, make the tool's purpose clear. It does not explicitly name a sibling such as list_followups, so it gets a 4 rather than 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?

The description gives the core condition for use: sent mail waiting for a reply based on owner-last-written threads and older_than_days. It does not state when to prefer this over list_followups, search_messages, or triage, nor does it state when not to use it. The prerequisite wording 'Needs read; every plan' helps, but usage guidance remains 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?

Goes well beyond the annotations by disclosing the bounded behavior ('fewer if some changed; never more'), the required scopes ('read and modify (trash: delete)'), and per-call limits ('50 Free, 500 paid'). These are exactly the operational facts the annotations (destructive/idempotent hints) do not 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?

Densely front-loaded: the core action leads, followed by bounded-scope, safety, auth, and quota clauses. Every sentence carries a distinct constraint 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?

With an output schema present, return values need not be described. It covers safety, idempotency, auth, and quota well; the only slight gap is the undo path, which relies on the schema description.

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 the description should compensate, and it clarifies the batch's origin and the trash scope, but leaves the meaning of count, confirm, and undo to the schema. Adds marginal value, so baseline 3.

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 (Applies) and resource (the batch a bulk_preview sealed), and implicitly contrasts itself with the sibling bulk_preview. An agent can immediately tell this commits what preview proposed.

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 workflow is clear: it must follow a bulk_preview and 'after the owner agreed,' which conveys the required precondition. It does not explicitly state when-not to use it or name alternatives beyond the preview relationship, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, and the description reinforces 'Changes nothing' while adding genuinely new behavior: required permissions ('Needs read and modify (trash: delete)') and per-call quota limits (50 Free / 500 paid). These are operational facts the 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?

Four dense sentences, front-loaded with the core action and effect, then workflow, then permissions and limits. Every sentence carries information, though the permission/quota sentence is tightly packed.

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

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

For a read-only preview of a 9-param, nested-schema tool, the description covers action, effect, routing to bulk_apply, owner-facing workflow, permissions and rate limits. An output schema exists so return-value detail is not required, yet the description still sketches the payload.

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 78% schema coverage the schema does most of the work, but the description adds meaning beyond it: the explicit-vs-criteria selection modes, the 'oldest first' ordering, and the scan_from continuation implied by 'a sample and a confirm ref'. It stops short of documenting every field (e.g. the batch param).

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 ('Selects the exact messages a bulk action would act on') plus the selection modes (explicit uids or criteria, oldest first) and the return shape (count, senders, sample, confirm ref for bulk_apply). This clearly separates it from bulk_apply (the executor) and search_messages (the uid source).

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 workflow directive: use this before bulk_apply, then 'Show the preview to the owner.' The confirm ref tied to bulk_apply makes the pairing explicit. No explicit when-not-to-use or alternative, so it stops short of a 5.

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

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

Annotations already declare a non-destructive write, but the description adds the crucial nuance that nothing is transmitted until the owner reviews and sends it, plus the permitted attachment sources. This is meaningful behavioral context beyond the annotations, though it omits any note on return values or permission/scope requirements.

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, all front-loaded and each earning its place: purpose, send behavior, attachment sourcing, reply preference. No filler or 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 13-parameter write tool with no output schema, the description covers purpose, non-sending behavior, attachment sources, and reply intent adequately. It could say more about the account requirement and reply-context parameters, but nothing critical to a correct call 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?

With 69% schema coverage and nested attachment objects, the schema carries most of the burden. The description adds the tool names that feed attachments (upload_attachment/request_upload) but says nothing about the reply parameters (in_reply_to_uid, quote, vars) or how they interact, so it only marginally extends 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 with location ("Saves a draft in the account's Drafts folder") and immediately distinguishes the outcome from its siblings ("Nothing is sent... or asks you to send_draft"). An agent can tell this apart from send_draft and reply_draft 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 clear context ("The preferred way to prepare replies") and names the alternative for sending (send_draft). It does not, however, address when to prefer reply_draft/reply_send for replies, so the routing is only partially complete.

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. The description adds behavior beyond them: cursor chaining semantics, the 24-hour default window when no cursor is supplied, and the authorization/plan requirement ('Needs read; every plan') — useful operational context that annotations do not 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 compact sentences, front-loaded with the purpose and scope before the cursor mechanics. Every clause carries information; slight density of 'Needs read; every plan' and 'Reports coverage per account' reads as terse notes rather than flowing prose, but 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?

An output schema exists, so return values need no explanation, and the description covers the remaining gaps an agent needs: scope, cursor lifecycle, default window, per-account coverage reporting, and auth requirements. Nothing required to invoke or chain the tool 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 100%, so the baseline is 3; the description earns an extra point by explaining cursor pass-back behavior and the no-cursor fallback ('without one it covers 24 hours'), which clarifies the cursor parameter beyond 'From the previous digest; or an ISO date-time'. It adds nothing for limit/folder/account, which the schema already documents.

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 ('Read-only summary for scheduled runs') and enumerates the exact buckets it covers (reply candidates, calendar, lists, automated mail, threads waiting on others, follow-ups, snoozes). It does not explicitly position itself against overlapping siblings such as awaiting_replies or list_followups, which cover some of the same ground, so an agent must infer the distinction.

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 the usage context clearly ('for scheduled runs') and gives operational guidance on the cursor: pass the returned cursor back next time, otherwise it covers 24 hours. It also states the access requirement ('Needs read; every plan'). No explicit when-not-to-use or sibling alternative is named, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds one genuinely useful trait beyond them — the returned text is 'sanitized' and 'full' — but says nothing about truncation, size limits, or failure modes when the id is stale or invalid.

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 sentence, front-loaded with the return value and ending with the input constraint. Nothing is redundant or padded.

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 1-parameter read tool with rich annotations and no output schema, this is minimally sufficient. But with close siblings like get_message, get_thread, and get_attachment, the absence of any statement about how this differs is a real completeness 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 100% and the single id parameter is already documented as 'Document id from search'. The description restates the same origin of the id without adding format, validation, or scope details, 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?

The description states a specific verb and resource: returns the full sanitized text of one email, identified by an id. It also scopes the input source ('by the id returned from `search`'). However, it never distinguishes itself from the sibling get_message, which an agent would reasonably assume does the same thing.

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 rather than stated: the mention that the id comes from `search` tells the agent this is a follow-up call after a search. There is no explicit when-to-use/when-not guidance and no mention of when get_message or get_thread would be preferred instead.

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

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

Adds real context beyond the annotations: attachments bypass the chat, the comment is placed above the forward, and recipients are constrained by send_allowlist. This is meaningful behavioral disclosure for a destructive/openWorld tool, though reversibility and failure modes are not addressed.

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 clauses with zero filler, and the core action plus its distinguishing trait (attachments not passing through the chat) is front-loaded before the constraints.

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 salient behaviors for a 10-parameter send tool and annotations carry the safety profile, but with no output schema and 30% of parameters undocumented, an agent gets no help on recipient limits or the folder default.

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 70% schema description coverage the schema already documents comment, as_draft, subject, folder, and include_attachments. The description mostly restates comment placement and as_draft rather than extending them, and says nothing about the cc/bcc/to recipient arrays or their 50-item cap. Baseline 3 is appropriate.

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 (forwards) and resource (a message) plus its full payload (all its attachments). 'Forward' is clearly distinct from the send_message/reply_send/create_draft siblings, so an agent can route to it without opening another 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 hard precondition ('Recipients must match send_allowlist') and explains the as_draft variant, but never states when to prefer this tool over reply_send, send_message, or create_draft. Usage is implied by the verb rather than explicitly framed as a routing decision.

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, openWorld), yet the description still adds substantial behavioral context: text-like files and text-layer PDFs return as text while others return a one-hour download link, plus a byte cap on inline. These return-format and expiry traits are not in any structured field.

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 purpose, then behavior and parameter guidance in a single tight passage with no filler. It is dense but every clause carries information the agent needs.

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 well by describing both result shapes (text vs. one-hour link). Combined with 100% schema coverage for parameters, an agent has enough to invoke 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 coverage is 100%, establishing a baseline of 3, but the description earns above that by explaining when to set inline and the max byte size, which the schema's terse 'Embed the bytes instead of a link' does not convey. It adds real decision value beyond the schema.

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

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

States a specific verb+resource ('Returns an attachment') and immediately characterizes the two return modes, so an agent knows exactly what it gets. This clearly distinguishes it from siblings like get_message or fetch, which return message bodies rather than attachment content.

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

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

Gives explicit conditional guidance for the inline parameter ('Pass inline=true only when the content itself is needed here') and tells the agent to hand the link to the user rather than read the file. It doesn't name an alternative sibling tool, but the when/when-not logic for inline is clear.

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, so the safety profile is covered. The description adds genuinely useful behavior not in annotations: the body is sanitized and truncated to a configured limit, and an attachment list is returned, telling the agent to expect possibly incomplete content.

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 payload description front-loaded and the truncation caveat immediately after; no filler, no repetition of schema fields.

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?

An output schema exists, so return values need not be explained, and the description still sketches the payload plus the truncation behavior. The main omission is how to retrieve untruncated body content or which folder the read defaults to in non-Gmail accounts, which the schema only partially covers.

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 80%, so uid, folder, account, and include_quoted are already documented in the schema (max_chars is not). The description's only parameter-relevant contribution is the implicit link between truncation and max_chars; it adds no syntax, defaults, or range detail beyond the schema, 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 concrete verb and resource ('Returns headers, sanitized text body and the attachment list of one message'), which is specific enough to separate it from get_thread and get_attachment by payload shape. It does not, however, explicitly name the sibling tools it is distinct 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?

The phrase 'of one message' implicitly scopes usage to single-message reads, and the required uid parameter (documented in the schema as 'uid from search_messages') implies the search-then-fetch flow. But there is no explicit when-to-use or when-to-prefer-get_thread/get_attachment 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, and openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: the two-tier resolution logic (folder message first, token fallback) and the returned content shape (HTML with inline images vs plain text). It stops short of saying what happens when no signature exists at all.

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

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

A single front-loaded sentence that leads with the verb and resource, then qualifies the resolution path. The quoted folder name and parenthetical format note are dense but each earns its place; there is 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 carries the burden of describing the return value, and it does so in detail (source folder, HTML vs plain text, inline images). The only real gap is behavior when neither signature source exists, which an agent would want to know.

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 sole parameter (account) is documented in the schema as a "list_accounts id". The description adds nothing about the parameter — e.g. that it selects which account's signature is resolved — 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 ("Returns") and resource (the signature appended under replies), and goes further by explaining where the value comes from — the newest message in the "mailmcp-signature" folder or the plain-text token fallback. It implicitly contrasts with the write-side set_signature but never names it, so sibling differentiation is left to inference.

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

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

The description explains what the tool returns but gives no when-to-use, when-not-to-use, or alternative guidance, despite set_signature being an obvious sibling. An agent must infer that this is the read counterpart to set_signature.

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 read-only, idempotent, open-world, non-destructive behavior, so the safety profile is covered. The description adds real value beyond that: ordering (oldest first), provider-specific folder search scope, the meaning of the `coverage` field, and an important caveat that thread grouping 'does not prove who replied to whom'.

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

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

Three dense sentences that are front-loaded with the core purpose, with the provider-specific parenthetical kept compact. Every sentence earns its place, though the provider enumeration adds some length.

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 a full output schema, return values need not be re-explained, and the description still usefully flags the `coverage` field and ordering. Together with 100% schema coverage and clear annotations, the definition is complete enough for correct invocation, with the only gap being explicit alternative-tool routing.

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

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

Schema description coverage is 100%, so all four parameters (uid, folder, account, include_bodies) are already documented in the schema, including the default folder and body-text limits. The description adds no parameter-level syntax or constraints beyond that, 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?

The description uses a specific verb ('Lists') and resource ('the conversation of a message'), and specifies the folder scope per provider (Gmail All Mail, other IMAP folder/INBOX/Sent/Archive, Outlook whole mailbox). It is clearly distinguishable from get_message. However, it never names a sibling tool (e.g. get_message or search_messages) to contrast against, so it falls short of the explicit differentiation a 5 requires.

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 context is implied rather than stated: the schema ties 'uid' to search_messages and the description explains which folders get searched, so an agent can infer this is the thread-expansion step after a search. But there is no explicit when-to-use/when-not guidance or mention of alternatives like get_message.

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, so safety is covered. The description does add genuinely useful behavioral context the annotations cannot: that 'graph' backends are Outlook with string ids and category labels, that reauth_by signals re-authentication via a setup page, and notably that 'protection' hides verification emails from the agent. That is real disclosure, though it is framed as output-field semantics rather than operation 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?

Purpose is front-loaded in the first clause, but the remainder is a dense backtick glossary whose phrasing is uneven (e.g. '`plan`: the mailmcp plan and, near expiry, how to renew'). It is compact but cryptic in places.

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?

An output schema exists, so the description need not have spent most of its length re-explaining return fields, and it leaves the actual gap — when to call this tool and when to enable check_connection — unfilled. Adequate but with clear gaps for a read-only listing 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 100% for the single check_connection parameter, so the schema fully documents it ('Also test every login (slower)'). The description says nothing about this parameter and adds no syntax or timing 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?

The opening sentence gives a specific verb and resource ('Lists the mailboxes: ids, addresses and permitted operations'), which is clearly distinguishable from sibling list_* tools such as list_folders or list_templates. However, it never explicitly frames itself as the accounts-level listing versus those siblings, so differentiation is inferred 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?

There is no when-to-use guidance at all: nothing says when to call list_accounts, when to prefer list_folders, or when to set check_connection=true. The rest of the text is a field glossary, so the agent gets no routing help.

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, covering the safety profile. The description adds that results carry message and unseen counts and explains the Outlook path-vs-name relationship, which is useful cross-provider context, though return-format detail is largely delegated to the 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 tight sentences, front-loaded with the core purpose and followed by the one cross-provider nuance that matters. No filler, though the parenthetical Gmail/Outlook framing is slightly dense.

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 read tool with an output schema and full annotation coverage, the description supplies what is needed: purpose, terminology mapping, and what the results contain. Missing explicit usage guidance keeps it just 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 100% and the single input param (account) is fully documented, so baseline is 3. The description's mentions of `path` and `name` refer to folder fields used by other tools rather than this tool's inputs, so it clarifies surrounding semantics but adds nothing to the account parameter itself.

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 ('Lists folders') and adds a valuable cross-provider clarification that Gmail calls these 'labels' and includes message/unseen counts. It does not distinguish itself from any named sibling (e.g. list_accounts, search), 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?

The description never says when to call this versus alternatives such as search or list_accounts, nor any prerequisites. The second sentence addresses parameter semantics across tools, not usage selection, so an agent gets no 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuine context beyond them: it discloses the required auth scope ('Needs read') and that the tool self-reports incomplete coverage ('reports what it could not cover'), which is unusual and useful.

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 compact clauses with the resource and scope front-loaded and no filler. 'Needs read; every plan' is terse to the point of being slightly cryptic, but it still earns its place as a permission note.

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 should carry more of the return-shape burden. It hints at partial results ('reports what it could not cover') but never explains the continue/pagination flow, which is material for a tool with a 4096-char cursor parameter.

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 80% and the schema already documents each parameter, but the description adds behavioral meaning: 'optionally later ones' ties include_later to intent, and 'across one or all mailboxes' clarifies the account parameter's scope. It doesn't cover the continue token, 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?

States a specific verb+resource (lists follow-ups and snoozed messages) and scopes it to one or all mailboxes. It clearly differs from write-side siblings like set_followup and wake_snoozed, though it never names those alternatives 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 description implies when the tool applies ('due follow-ups', 'optionally later ones', 'snoozed messages'), but gives no explicit when-to-use vs. when-not guidance relative to siblings such as wake_snoozed or set_followup. Usage must be inferred from the scope clause.

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 value beyond that: it states the auth requirement ('Needs read') and scopes the samples output to 'tone, length and language only', which is useful behavioral context. It omits pagination behavior for 'continue', keeping it from a 5.

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

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

Three tight sentences with the primary listing behavior front-loaded and no filler. The terse phrasing is efficient, though the quoted internal name 'mailmcp-templates' is unexplained and slightly opaque.

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 some burden for describing what comes back; it covers templates and the samples style profile reasonably but does not explain the template structure, pagination via 'continue', or how list-mode and samples-mode relate. Adequate but with clear gaps for a 7-parameter tool.

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

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

Schema coverage is 71% and the schema already documents n, to, continue, and max_chars. The description adds meaning for samples=true and for retrieving one template by name, but does not explain the other parameters beyond what the schema provides, so the baseline 3 is appropriate.

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 (lists) plus resource (templates in 'mailmcp-templates') and a second mode ('one in full by name'), and clarifies that samples=true returns a style profile rather than templates. It does not name or contrast with any sibling such as save_template, so it stops short of 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?

'samples=true returns...' implies the condition for the alternate mode, and 'Needs read; every plan' hints at when it is expected to be consulted. However, there is no explicit when-not guidance and no routing to alternatives like save_template, leaving usage largely 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?

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely new context beyond that: the storage folder name, the ordering guarantee (newest first), and the shape of the returned identifiers used for attaching. It does not mention pagination or limits, 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?

One sentence, front-loaded with the resource and its location, then the provenance and the return payload. No filler or redundant restatement of the tool name.

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

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

With no output schema, the description usefully sketches the returned identifiers ({folder, uid, part}) and the ordering, and annotations cover the safety profile. It leaves other return fields and any result-size limits unspecified, so it is nearly but not fully complete for a one-parameter listing tool.

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

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

Schema coverage is 100% and the single parameter (account, described as a "list_accounts id") is fully documented in the schema. The description only restates "of an account" without adding format or sourcing detail beyond what the schema already 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 (list files waiting in the "mailmcp-uploads" folder of an account) and names the originating operations (upload_attachment or an upload link), which cleanly distinguishes it from siblings like upload_attachment and request_upload. It also states ordering (newest first) and the key fields returned.

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 makes the usage context clear: this is where you look to find files that have been uploaded and are waiting, and it gives the reason to call it (to obtain the {folder, uid, part} needed to attach them). It does not explicitly name an alternative tool or state a when-not-to-use condition, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so safety is covered. The description adds real value beyond that by warning that a move can change the message id and that moved_uid from the result should be used going forward, plus noting Gmail vs Outlook label semantics. It omits permission requirements, but this is strong added context.

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: the first front-loads the full operation set, the second delivers the critical id-change caveat. No wasted words and the most important behavioral warning is not 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 9-parameter mutation tool with no output schema, the description covers the primary operations and the important id-mutation side effect. It could say more about conflicting-parameter behavior and permissions, but the agent has enough to invoke 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 coverage is 78%, so the schema already documents most parameters including uid, account, folder, archive, and label arrays. The description implicitly maps operations to parameters (read/unread to seen, star to flagged) but does not name them, adding only marginal meaning over the schema.

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

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

The description states a specific verb (modify) and enumerates the exact operations (read/unread, star/unstar, labels, move/archive), so an agent can distinguish it from get_message or trash_message. It is clear and concrete, though it does not explicitly name which sibling to use for deletions or bulk operations.

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 lists what the tool can do but gives no when-to-use guidance, no exclusions, and no routing to alternatives such as bulk_apply for batch changes or trash_message for deletion. The agent must infer the appropriate tool from operation names alone.

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 write/non-destructive/non-idempotent/open-world, so the bar is lower; the description still adds real value by disclosing that the server auto-populates threading headers, the 'Re:' subject, recipients and the quoted original, and by confirming nothing is sent. It omits what the call returns and whether repeat calls create duplicate drafts.

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 action and scope; the server-side behavior list and the trigger phrase each earn their place, and there is 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 an 11-parameter tool with nested attachment objects, no output schema and annotations covering safety, the description covers purpose, threading behavior and non-send semantics adequately. Minor gaps remain around the response shape and duplicate-draft behavior on repeat calls.

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 91%, so the schema already documents uid, reply_all, quote, lang, folder and the attachment shapes. The description only restates reply_all and the quoted original, adding no format or syntax detail beyond the structured fields; 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 (Saves) and resource (a reply to a message into Drafts) with the key differentiator 'in the same thread' and 'Nothing is sent', which separates it from reply_send, send_draft and create_draft 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 a clear trigger ('Use whenever the owner says "reply / write a draft"', with localized examples), so an agent knows when to reach for it. It stops short of naming reply_send or create_draft as the alternatives, so the routing is implied by 'Nothing is sent' rather than stated.

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

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

Annotations already declare destructiveHint=true, non-idempotent and open-world, so the safety profile is covered. The description adds genuinely new behavioral context: server-side header/recipient/quote handling and the sending-enabled plus allowlist gating. It stops short of describing failure modes or what a rejected send looks like, so not 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 sentences, front-loaded with the action, then the gating conditions. The parenthetical about server-set headers is somewhat long but earns its place by clarifying what the caller need not supply.

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 send operation with no output schema, the annotations carry the safety profile and the description carries preconditions and routing to reply_draft. The remaining gap (result/error reporting after a send attempt) is minor given there is no output schema to document.

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 89%, so the schema already documents uid, account, text, lang, quote, reply_all, attachments and folder. The description adds no parameter-level syntax or format detail beyond what the schema provides, making the baseline 3 appropriate.

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 ('Sends a reply to a message in the same thread') and explicitly distinguishes itself from the sibling reply_draft ('otherwise use reply_draft'). An agent can identify the operation and its alternative 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?

Gives explicit preconditions: only when the owner enabled sending AND every recipient matches send_allowlist, otherwise use reply_draft, and only when the owner says 'send'. It names the alternative and the exact conditions that select it, leaving little to inference.

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

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

Annotations cover safety (readOnly=false, destructive=false), and the description adds real behavioral context beyond them: the link expires in one hour, anyone holding it can upload, and the resulting file surfaces in list_uploads. That is valuable operational detail the annotations don't 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?

One dense paragraph, front-loaded with what is returned, followed by invocation mechanics and the routing decision. Every clause carries information; 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?

No output schema is needed because the description already explains the return value (a one-hour URL), how to consume it, and the side effect (file appears in list_uploads). For a one-parameter tool this is fully 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?

With a single parameter and 100% schema description coverage, the schema already explains 'account' as the list_accounts id. The description adds no further parameter meaning, 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 resource and outcome: returns a one-hour HTTPS upload link, where the file lands ("mailmcp-uploads"), and that it shows up in list_uploads. An agent can distinguish this from siblings like upload_attachment 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?

Gives an explicit conditional: upload it yourself if you can run commands, otherwise hand the link to the user. It doesn't name the alternative sibling (e.g. upload_attachment) explicitly, so the routing is clear but not tied to a named tool.

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 idempotentHint=true; the description adds genuinely useful context by explaining that delete=true routes to Trash (not permanent), that a draft is required, and that templates are paid while profiles/deletes are free. This enriches the behavioral picture beyond the structured hints.

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?

It is a single run-on sentence cramming save, profile, storage location, delete behavior, prerequisite, and pricing into one breath. No filler, but the density hurts front-loading and parseability.

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?

An output schema exists, so return values need not be described, and the pricing/prerequisite details are helpful. Still, for a 6-parameter tool the description omits what name/subject do and gives no hint that it writes into a specific 'mailmcp-templates' location for the profile case beyond the quoted folder name.

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%, so the description must compensate. It does explain kind (profile = tone-only style) and delete semantics, but leaves account, name, and subject entirely undocumented in prose. Partial compensation justifies the baseline 3.

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 ('Saves a text template'), names the kind=profile variant, and covers the delete path via 'delete=true moves one mailmcp saved to Trash'. It clearly differs from the read-oriented list_templates sibling. It loses a point only because the phrasing is dense and the profile vs template distinction is squeezed into a single clause.

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 offers real context ('Needs draft; templates are paid, profiles and deleting free') that implies the prerequisites for calling it. However, it never states when to choose this over siblings like create_draft or list_templates, so usage guidance remains 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?

Annotations already declare readOnly, idempotent, non-destructive, and open-world. The description adds valuable behavioral context beyond that: the scope of mailboxes searched (Outlook Inbox only, Gmail All Mail) and the fact that results feed into fetch. It does not discuss result caps or pagination, keeping it short of full transparency.

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?

Dense but front-loaded: scope and return flow come first, then syntax rules, then folder caveats. Every clause conveys distinct information, though the packing of multiple rules into semicolon-separated fragments is slightly heavy.

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-param, no-output-schema tool with rich annotations, the description covers scope, syntax, alternatives, and result routing sufficiently. Minor gaps remain around result limits and pagination, but the essential context for correct invocation 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 100% but the schema itself only says 'Search query'. The description meaningfully enriches the parameter's semantics by documenting syntax variants (from:, newer_than:7d, has:attachment), the plain-words fallback, and the account-prefix mechanism, which is real added meaning over 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 (searches) and resource (every readable mailbox) with scope (one query) and the downstream tool (returns documents for fetch). It also distinguishes itself from the sibling search_messages by contrasting folder behavior ('search_messages with a folder looks elsewhere').

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 usage conditions: Gmail syntax on Gmail, plain words elsewhere, and the 'account:<id> ' prefix for a single mailbox. It points to search_messages for folder-scoped searches, implying the alternative, though it does not spell out a full when/when-not decision between the two.

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 safety, and the description adds real behavioral value: result ordering ('newest first'), Backend-specific quirks ('Outlook: total counts returned results only; from is exact'), and Gmail query support. It does not disclose pagination interaction with offset/limit beyond what schema 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?

Information-dense and front-loaded, with the account scope leading. The backtick-laden, semicolon-joined style is telegraphic, and the 'uid + folder and header hints' clause slightly duplicates the output schema, but no sentence 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?

An output schema exists, so return values needn't be detailed, and the description correctly focuses on the ambiguous parts (account scoping, per-backend query semantics). For a 13-parameter search tool it is largely complete, though it omits guidance on combining filters.

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 69%, and the description adds genuine meaning: `query` semantics differ per backend (Gmail syntax vs. full text), `account="all"` is explained, and Outlook `from`/`total` behavior is clarified. It leaves less-obvious params like `offset` interplay with `limit` 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?

States a clear verb+resource ('Searches' messages) and immediately scopes it ('one account, or all with account="all"'). It never names the sibling 'search' or explains how it differs from get_message/fetch, so it falls short of full sibling differentiation.

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

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

Usage is implied through the account and query scoping, and it explains Gmail vs. non-Gmail query behavior, but there is no explicit when-to-use vs. when-not, nor any named alternative (search, fetch, triage) to route the agent.

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 non-idempotent, and the description reinforces the mutation by explaining the draft leaves Drafts (to Sent on Outlook). It adds context annotations cannot carry: attachments are sent as stored and the recipient allowlist constraint. Remaining gaps (failure behavior when the allowlist rejects) are minor.

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 dense sentence that front-loads the core action and folds side effects and the allowlist constraint into parentheticals — no filler, nothing that fails to earn 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 and strong annotation coverage of the safety profile, the description supplies what an agent still needs: attachments included, the draft's removal from Drafts, and the allowlist precondition. It could say more about what happens when the send is refused, but it 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 100%, so all four parameters are already documented in the schema, including expect_fingerprint's refusal-on-change semantics. The description adds only the indirect point that recipients are not parameters but come from the draft; baseline 3 applies when the schema does the heavy lifting.

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 ('Sends a draft exactly as stored in the Drafts folder') plus scope details (attachments included, leaves Drafts, moves to Sent on Outlook), which clearly separates it from send_message and reply_send 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?

It gives a real precondition — recipients come from the stored draft and must match send_allowlist — and the schema notes the uid comes from create_draft or a Drafts search, implying this is the follow-up to composing. It never explicitly routes the agent away from send_message/reply_send, so it is clear context rather than full when/when-not 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 destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds non-obvious policy gating (per-account send enablement, send_allowlist recipient matching) that the annotations cannot express, plus the range of attachment sources. It stops short of describing delivery failure behavior or rate limits.

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

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

Two sentences, zero filler, with the action front-loaded and the escape hatch pushed to the end. Every clause carries load: mechanism, optionality, preconditions, alternative.

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-output-schema send tool whose annotations already flag it as destructive and open-world, the description covers the critical invocation gates and the correct alternative. It does not address what a rejected send returns or how partial-recipient failures behave, a minor gap against the complexity of an 11-parameter tool.

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

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

Schema coverage is 64% (moderate), so the schema carries much of the burden already; the inline attachment-object description in the schema largely duplicates the description's mention of mailbox attachments, uploads, and inline content. The description adds little format-level detail for the 11 parameters 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?

Opens with a specific verb+resource ("Sends an email via SMTP") and immediately scopes the capability around attachments. It also names the sibling it is not (create_draft), so an agent can distinguish it from the draft/reply family 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?

States the two hard preconditions for use (owner enabled sending for the account AND every recipient matches send_allowlist) and gives the explicit fallback ("Otherwise use create_draft"). This is a clear when/when-not/alternative statement rather than implied 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 the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), so the bar is lower, yet the description still adds real context: the read+modify scope requirement, the paid-when-setting / free-when-clearing cost model, and the persistent record plus star/flag side effect. It does not explain the destructive path the annotation implies (the trash-unverified behavior, which only appears in the schema), leaving a small gap.

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 clauses pack purpose, lifecycle, and auth/cost into roughly two sentences with the primary action front-loaded. Slightly dense but no filler; every clause carries information.

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

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

An output schema exists, so return values need not be described. Given that, the description covers side effects, lifecycle, auth, and cost, which is enough to call this correctly. The only omission is any routing against snooze/wake_snoozed, a minor completeness gap rather than a blocker.

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 88%, so the schema already documents account, uid, due, folder, tz, and if_no_reply. The description adds only that clear=true removes the follow-up and that a due date drives the mark, which does not meaningfully exceed the schema. Baseline 3 is appropriate.

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: marks a message to come back to by a date, and also clears it. It even names the storage mechanism (a record in "mailmcp-state" plus a star or flag), which is unusually concrete. It does not distinguish itself from the close sibling snooze, so it falls short of the top mark.

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 resurfaces when list_followups or a scheduled task runs" explains the lifecycle, and clear=true removes it, so the set/clear duality is implied. However, there is no explicit guidance on when to choose this over snooze, which occupies the same conceptual space and is likely the main source of agent confusion.

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 the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true, openWorldHint=true), so the description only needs to add context. It does so meaningfully: the signature is persisted as a message in the 'mailmcp-signature' folder, photo/logo signatures take a different path, and two capabilities must be enabled first. It stops short of explaining what the destructive hint actually overwrites.

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 core action before the edge-case path and prerequisites. It is slightly diluted by implementation detail (storing as a message, mailing to self) that is not essential for tool selection.

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 mutation tool the safety profile is covered by annotations and all parameters are documented, so the essentials are present. The notable gap is that destructiveHint=true is never explained – the agent is not told that an existing signature is replaced rather than appended.

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 schema already documents maxLength, script stripping, and the html-derived default for text. The description only restates 'HTML and/or text' and adds nothing about the required 'account' parameter, so baseline 3 is correct.

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 concrete verb (stores) and resource (the mailbox signature) and even names the storage location, so the agent knows this writes a signature. It does not explicitly contrast with the sibling get_signature, which would have earned 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 states real preconditions ('Needs the mailbox signature enabled on the setup page and the draft capability') and describes a photo/logo branch, which is useful context for when the call will succeed. However it never explicitly routes the agent against alternatives such as get_signature, leaving the read-vs-write choice 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 declare destructive/non-idempotent/open-world, and the description adds context those do not carry: the destination folder, that origin is noted, the required read+modify scopes, and the cost model ('paid (cancel free)'). That is meaningful behavioral disclosure beyond the structured hints.

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 core action and scope before the reversal and permission details. No wasted words, though the cost/permission clause is slightly tacked on.

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

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

An output schema exists, so return values need not be explained. The description covers scope, destination, reversal, permissions, and cost, leaving only the when-to-use-vs-alternatives dimension thin.

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 86%, so the schema already documents nearly every parameter. The description adds only a little (cancel=true is the reversal switch, until is the target time), which is consistent with the baseline 3 when the schema does the heavy lifting.

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 ('Moves one message') plus a crucial scope qualifier ('not its thread') and the destination ('mailmcp-snoozed'). An agent can distinguish this from sibling mutation tools like modify_message or trash_message immediately.

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

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

Explicitly names the reversal path ('wake_snoozed or cancel=true brings it back'), giving clear guidance on how to undo. It does not, however, say when to prefer snoozing over related scheduling tools like set_followup, so it stops short of full when/when-not 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is largely covered. The description adds the recoverability nuance 'Never deletes permanently,' which is genuinely useful context beyond the annotations. However it says nothing about permissions, behavior when the message is already in Trash, or side effects on labels/threads.

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

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

Two sentences, zero waste, with the primary action stated first and the non-permanence caveat immediately after. Nothing could be cut without losing information.

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

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

For a simple 3-parameter mutation with full schema coverage and annotations declaring its destructive/idempotent nature, the description plus structured fields give an agent enough to call it correctly. The gap is the absence of usage routing against similar siblings, which is minor for a tool this narrow.

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% — uid, folder, and account are each documented in the schema, including the default-folder rule. The description adds no parameter meaning whatsoever, 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: 'Moves a message to the Trash folder.' An agent can immediately tell this relocates a message rather than deleting it or modifying labels. It does not name any sibling (e.g. modify_message, bulk_apply) for differentiation, so it stops 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?

There is no when-to-use guidance and no alternatives named, even though siblings like modify_message, bulk_apply, and delete-adjacent flows exist. The only hint is the implicit 'trash a message' context carried by the name and title.

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, open-world). The description adds genuinely useful behavior beyond that: classification is done 'from headers only (no bodies)', items carry reasons, and coverage is reported per account, plus the permission requirement 'Needs read; every plan'. This meaningfully informs the agent about data access and output character.

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, front-loaded with what the tool does and its category output. The telegraphic final sentence 'Needs read; every plan.' is slightly terse but carries real prerequisite information without 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 an output schema present, the description need not explain return values, and it covers purpose, category buckets, header-only scope, and the read requirement. For a read-only classifier this is nearly complete; only explicit sibling routing is 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 80%, so the schema already documents limit, since, folder, and account. The description only echoes 'recent mail' and 'per account' without adding format or default details beyond what the schema provides, so the baseline of 3 is appropriate.

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 (sorts) and resource (recent mail) and enumerates the exact output categories, so the agent knows precisely what it produces. It does not explicitly differentiate itself from siblings like awaiting_replies or digest, whose output overlaps with the waiting_on bucket, so it falls just short of a 5.

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

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

Usage is implied (triage recent mail to decide what needs a reply) and the prerequisite 'Needs read; every plan' is stated, which is useful context. However, there is no explicit when-to-use versus awaiting_replies/digest/search, and no exclusions or conditions for choosing this over 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 declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, but the description adds substantive context beyond them: the dry run is the default, the one-click POST only fires when the provider verified the signer's DKIM and the link is on its domain, and it requires the 'execute: unsubscribe' read permission on every plan. This is meaningful workflow and auth disclosure.

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?

Very compact with every clause carrying information (default behavior, condition for POST, fallback, usage restriction, permissions). The telegraphic, run-on phrasing ('else the manual link. Only when the owner asks.') is dense and slightly disjointed but front-loads the dry-run behavior.

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 an output schema present, return values need no explanation, and the description covers the dry-run workflow, the conditions for the automated POST, and the required permission. For a destructive, open-world tool the safety posture is adequately conveyed, though a hint about reversibility or irreversibility of the POST could add more.

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

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

Schema coverage is 100%, so the schema already documents all five parameters including account, uid, folder, confirm, and dry_run defaults. The description reinforces dry_run's default and the confirm-from-dry-run flow but adds little syntax or format detail beyond what the schema already provides, so baseline 3 is appropriate.

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 title and description together establish that this tool unsubscribes from mailing lists, and the text names the specific mechanism (RFC 8058 one-click POST vs manual link). However, the lead sentence 'Reads unsubscribe headers' foregrounds the dry-run read behavior rather than the destructive unsubscribe action, which could momentarily confuse an agent about what the tool actually does.

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?

'Only when the owner asks' is an explicit, restrictive when-to-use condition, and the dry-run-default design implicitly guides the intended two-step workflow. It does not name alternative tools (e.g. modify_message, trash_message), 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely non-obvious behavior: the file is a temporary staging artifact that is removed once attached, plus the one-shot return tuple despite there being 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?

A single front-loaded sentence: purpose, encoding rule, size limit, and return value, followed by a one-clause routing note. Dense but every clause carries information; only the heavy compression of the return tuple is slightly terse.

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 only 40% schema coverage, the description still covers the return shape, the size ceiling, the one-shot lifecycle, and the sibling alternative. Remaining gaps are the unexplained account/filename/content_type parameters rather than anything that would cause a wrong invocation.

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 40%, so the description must compensate. It clarifies the content parameter (UTF-8 text or base64 for binary) and the implied utf8/base64 encoding enum, but account, filename, and content_type receive no added meaning 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 (stores a file), names the storage location ("mailmcp-uploads"), and gives the return contract {folder, uid, part}. It also names the sibling request_upload as the alternative, so an agent can separate it from other upload-related tools 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?

Explicitly routes large or local files to request_upload and states the size cap (policy.max_upload_bytes), which is real usage guidance. It does not, however, explain when the text-vs-base64 branch should be chosen or any prerequisites tied to the required account parameter.

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: restored messages are marked unread, the operation is safe to repeat and to run concurrently, the orphan fallback targets INBOX, and it declares the permission model ("Needs read and modify; every plan"). This exceeds the idempotent/destructive hints already provided.

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?

Dense and front-loaded: the core move happens first, then caveats. Every sentence carries weight, though the final permission clause is slightly clipped ('every plan') in a way that reads as shorthand rather than intent.

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?

An output schema exists so return values need not be described, and the description covers the mutation's permission model, idempotency, and orphan edge case. Remaining gap is the undocumented `dry_run`/`account` parameters for a tool that is safe to invoke without required args.

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 50% schema coverage, the description compensates partially by explaining `orphans` (schema gives it no description) and the unread/restore semantics tied to `uid`. It says nothing about `dry_run` or `account`, leaving half the parameters undocumented in both places.

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: "Moves due messages from 'mailmcp-snoozed' back where they were, unread." The folder name and 'due' qualifier make it unmistakably distinct from its inverse sibling `snooze` 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?

Gives one conditional gateway ("orphans=true ... only when the owner asks"), which is real when-to-use guidance, but never states the general trigger or explicitly contrasts with `snooze`. Usage 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.