mailmcp

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

Annotations already indicate this is not read-only, not idempotent, and not destructive. The description adds valuable behavioral context: nothing is sent, the owner reviews and sends it, and attachments can come from multiple sources. It also notes that scripts are stripped from HTML, which is a useful behavioral detail beyond the 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?

The description is compact and front-loaded with the most important fact (saves a draft, nothing is sent). Every sentence earns its place: the non-sending behavior, attachment sources, and the preferred-use guidance. No fluff or repetition of schema details.

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

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

For a tool with 11 parameters and no output schema, the description covers the essential context: what the tool does, what it doesn't do, how attachments work, and when to prefer it. It doesn't explain return values, but with no output schema that's less critical. The main gap is not explaining what happens after saving (e.g., whether a draft ID is returned), but the description is otherwise complete for an agent to decide when to use it.

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

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

Schema coverage is 73%, so the schema already documents most parameters. The description adds meaning by explaining the overall purpose of the draft (preparing replies), clarifying that attachments can be existing mailbox attachments, uploaded files, or inline content, and noting that the owner sends it later. It doesn't repeat every parameter but adds context for the key ones.

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 ('Saves a draft'), a specific resource (Drafts folder of the account), and clarifies the non-sending behavior. It also distinguishes itself from send_draft and reply_draft, making it clear this is the preparation step, not the sending step.

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 explicitly says 'This is the preferred way to prepare replies' and mentions that the owner reviews and sends it from their mail client or asks you to send_draft. It also names alternatives (send_draft, reply_draft) and attachment sources, giving clear context for when to use this 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 readOnlyHint and idempotentHint, so the description's addition of 'sanitized' and 'full' provides extra behavioral context. No contradiction with annotations.

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

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

Single sentence with no fluff, front-loaded with the purpose and source of id. Perfectly concise.

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 low complexity (one parameter), annotations covering safety, and no output schema, the description sufficiently explains what the tool does. It doesn't cover error cases, but that's acceptable for a simple fetch.

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% with the parameter described as 'Document id from search'. The description repeats this information without adding new meaning, so it provides no added 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 (Returns) and resource (full sanitized text of one email) and specifies that the id comes from search. It doesn't explicitly differentiate from sibling get_message, so it's clear but not fully distinguishing.

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 clear context that the id must come from `search`, implying usage after search. However, it doesn't specify when not to use this tool or name alternatives, so no explicit exclusions.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the description does not need to repeat mutation. It adds meaningful context: attachments bypass chat, recipients must match allowlist, and as_draft changes the behavior to saving a draft. This goes beyond annotations without contradicting them.

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 sentences with no filler. The core action and key differentiators are front-loaded, and every sentence earns its place. It is efficiently structured for quick parsing.

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 10 parameters and no output schema, the description covers the most important behaviors (attachment handling, allowlist, draft behavior). It does not explain the sending mechanism or default subject, but the schema covers many defaults. The description is sufficient for an agent to make a correct call.

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

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

Schema description coverage is 70%, so many parameters already have descriptions. The description adds context for comment ('goes above the forwarded text') and as_draft ('saved to Drafts'), and notes the allowlist requirement for recipients. This provides some extra meaning but does not comprehensively cover all parameters.

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 ('Forwards a message') and highlights a key differentiator: 'without the files passing through the chat.' It also mentions optional comment and as_draft behavior, distinguishing it from send_message and reply_send. This is clear and 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 implies usage (forwarding a message) but does not explicitly contrast with alternatives like reply_send or send_message. It mentions the send_allowlist constraint and as_draft, but no 'use this when' or 'instead of' guidance. The context is implicit 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?

All annotations are false (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), so the description carries the full burden. It discloses size limits, the two modes (inline vs save_to), and text/binary return behavior. It does not mention error conditions or permission requirements, but it covers the main behavioral traits well.

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 two sentences, front-loaded with the primary action, and includes all essential details without redundancy. Every sentence contributes meaningful information, making it efficient and easy to parse.

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 6 parameters and no output schema, the description explains the return behavior (text, embedded binary, or path when save_to is used) and the key size constraints. It does not explicitly address the 'inline' parameter or error conditions, but overall it covers the essential context an agent needs to call the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining size limits, the save_to effect (write to disk, returns path), and the text/binary distinction, which enriches the understanding of parameters like part and save_to.

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 ('Downloads') and resource ('one attachment'), and immediately provides differentiating details: size limits, text vs. binary handling, and the save_to alternative. This clearly distinguishes it from sibling tools like upload_attachment and makes its scope 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 clearly explains the tool's core function and provides conditional guidance: use save_to to write to disk instead of returning content. It does not explicitly name alternatives or exclusions, but the purpose is clear enough that an agent can infer when to use it. Slight deduction for lacking explicit 'when not to use' 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 establish read-only and idempotent behavior, so the description's added notes about sanitized text and body truncation provide useful behavioral context beyond the annotations. It transparently discloses that the body may not be complete.

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 no filler. The most important information—what is returned and the truncation caveat—is front-loaded and each sentence contributes meaning.

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

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

For a read-only single-message tool, the description plus schema and annotations cover essential invocation needs. The absence of an output schema is partially mitigated by specifying the return categories, though the exact format of headers and attachments is left implied.

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 high at 80% and most parameters are already described. The description adds general context about body truncation, which relates to max_chars, but it does not explicitly link the configured limit to the max_chars parameter. It adds modest 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?

The description names a specific operation ('Returns headers, sanitized text body and the attachment list') on a specific resource ('one message'). It clearly distinguishes this from fetching a thread or an attachment, and the singular scope prevents confusion with list/search 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?

The description does not state when to prefer this tool over siblings like get_thread, search_messages, or fetch. The uid parameter schema hints it comes from search_messages, but the description itself offers no explicit usage context or exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds valuable behavior: the conditional return source (newest message in a specific folder with HTML inline images vs. plain text from token), which goes beyond the annotations. It does not mention error cases, but for a read-only tool this is adequate.

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 a single sentence that is front-loaded with the primary purpose, but it is a bit dense with a conditional structure. It could be split into two sentences for clarity, but it remains efficient and contains no filler.

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

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

For a simple read-only tool with one parameter and no output schema, the description explains exactly what is returned in both scenarios and references the relevant sources (folder and token). It does not elaborate on return format details beyond the content type, but that is sufficient given the simplicity.

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

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

The schema has 100% coverage for the single 'account' parameter, described as 'Account id from list_accounts'. The description adds no additional parameter semantics, 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 states a specific verb ('Returns') and resource ('the signature mailmcp appends under replies'), and distinguishes two retrieval paths (folder-based HTML vs. token-based plain text). It clearly separates this from the sibling set_signature, which is the write counterpart.

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 usage — call it to read the current signature — and the sibling set_signature is obviously the inverse. However, it does not explicitly state when to use it vs. alternatives or any exclusions, 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, and destructiveHint, so the safety profile is covered. The description adds value by explaining how threading is determined (Gmail thread id vs References headers) and that it lists all messages in the thread, which is behavior beyond the annotations.

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

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

The description is a single, well-structured sentence that states the purpose and the key threading detail up front. There is no waste or redundancy; every clause earns its place.

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

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

For a read-only, idempotent tool with fully documented parameters and no output schema, the description provides the essential behavioral context (what it returns and how threads are identified). It does not specify ordering or pagination, but for this type of list tool that is not a critical gap given the annotations.

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

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

The input schema has 100% coverage with each parameter (uid, folder, account) described in detail, including defaults and provenance. The description itself adds no additional parameter-level semantics beyond what the schema already 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?

The description clearly states the verb 'lists' and the resource 'all messages belonging to the same conversation', and distinguishes itself from get_message by focusing on the thread. It also notes the threading mechanism (Gmail thread id or References headers), which helps differentiate it from search_messages.

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

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

The description implies usage: when you have a message and need the whole conversation. It does not explicitly name alternatives or exclusion conditions, but the phrasing 'same conversation as the given message' makes the context clear. Given the simplicity of the tool and the sibling set, this is adequate 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 establish read-only, idempotent, non-destructive behavior. The description adds valuable context beyond that: how to interpret `backend` (IMAP vs Graph), what Graph-specific message ids/labels mean, and the practical consequence of `reauth_by` expiring. This meaningfully supplements the annotations.

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

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

Two sentences, no filler. The first sentence states the core function immediately, and the second adds only necessary clarification about backend-specific fields. Every clause earns its place.

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

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

Although there is no output schema, the description names the essential returned fields (ids, addresses, permitted operations, backend, reauth_by) and explains their meaning. For this tool's complexity, nothing critical is missing for an agent to invoke it correctly and interpret its results.

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

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

The only parameter, `check_connection`, is fully documented in the schema with type and behavior, so the description does not need to repeat it. Schema coverage is 100%, and the description focuses on output fields rather than parameters, which is acceptable.

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') with a concrete resource ('configured mailboxes') and names the key output elements: ids, addresses, and permitted operations. This distinguishes list_accounts from siblings like list_folders or get_message without ambiguity.

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 purpose is clear enough that an agent can infer when to call it: any time it needs to enumerate configured mailboxes or understand account capabilities. It does not explicitly name alternatives or exclusions, but for a simple listing tool the context 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it returns counts, describes provider-specific differences (path as opaque id vs name as hierarchy), and clarifies that it operates on a single account.

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 with no wasted words. The core function is front-loaded, and the second sentence provides a valuable provider-specific caveat. Every sentence earns its place.

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

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

There is no output schema, so the description's mention of counts, path, and name partially compensates. It also gives cross-provider context and clarifies the relationship to other tools. It doesn't mention pagination or error conditions, but for a simple read-only list tool with one parameter, the description is nearly complete.

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

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

The single parameter 'account' is fully documented in the schema with 'Account id from list_accounts' (100% coverage). The description doesn't add extra parameter-level detail; the provider-specific path/name semantics relate to the output, not the input. 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 uses a specific verb ('Lists') and resource ('folders (labels on Gmail)') and scopes it to 'one account' with 'message and unseen counts'. This clearly distinguishes it from sibling list tools like list_accounts and list_uploads, and even clarifies the Gmail vs Outlook naming nuance.

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

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

The description gives concrete guidance on how the returned values should be used by other tools ('either one can be passed to the other tools as a folder'), and explains the meaning of path and name for Outlook. It doesn't explicitly state when not to use it or name an alternative, but the usage context is clear and the sibling set makes the purpose obvious.

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, and non-destructive behavior. The description adds useful behavioral context beyond that: it lists only files in a specific folder, orders them newest first, and discloses the return payload needed for later attachment.

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 a single compact sentence that front-loads the object and scope, then adds ordering, return fields, and practical purpose. Every part earns its place with 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?

This is a simple, well-annotated, one-parameter tool with no output schema, and the description compensates by stating the return fields and ordering. It also names the source and prerequisite relationship to attachment, so an agent has enough context 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?

There is only one parameter, account, and the schema already describes it as 'Account id from list_accounts', giving 100% schema coverage. The description adds little parameter-specific detail, but none is needed because the schema fully documents the source of the value.

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

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

The description states a specific verb and resource: listing uploaded files waiting in 'mailmcp-uploads' of an account. It also adds ordering and output-field details, which distinguishes it from related sibling tools like upload_attachment or get_attachment.

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 wording clearly implies when to use it: to retrieve files staged from upload_attachment or an upload link, and to obtain the {folder, uid, part} identifiers needed to attach them. It does not name alternative tools explicitly, but the context is clear and no exclusions are 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 convey mutation and idempotence, so the description adds a valuable non-obvious behavioral detail: a move can change the message id and callers must use moved_uid thereafter. This goes beyond the schema and annotations.

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

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

Two sentences carry all essential information with no filler. The operation list is front-loaded, and the important moved_uid caveat is placed at the end without disrupting the main purpose.

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 tool's 9 parameters, the description covers the full operational scope and the critical output caveat. The schema handles the remaining parameter details, and annotations cover the mutation safety profile, so the description is sufficiently 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?

With schema coverage at 78%, the description compensates for the undocumented boolean parameters by mapping 'read/unread' to seen and 'star/unstar' to flagged. It also clarifies that add/remove labels correspond to Gmail labels or Outlook categories.

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

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

The description names a concrete set of operations on a message resource: marking read/unread, starring, label changes, and moving/archiving. This clearly differentiates it from siblings like trash_message, send_message, and fetch.

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 usage context is implied by the enumerated operations: use this tool when you need to change flags, labels, or folder placement. However, it does not explicitly state when not to use it or point to alternatives such as trash_message for deletion.

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 are all false, so the description carries the behavioral disclosure burden. It does this well: it reveals this is a draft-creating operation that never sends ('Nothing is sent'), states that In-Reply-To/References, 'Re:' subject, recipients, and quoted original are set by the server (versus by the caller), and implies the quote is automatic. These are genuinely useful behavioral disclosures beyond what annotations provide. No contradiction with annotations.

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

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

Two sentences with no filler. The first sentence front-loads the core action, destination, and server-set fields; the second adds concrete trigger phrases and a safety note ('Nothing is sent'). While dense, every clause earns its place. Slightly packed — a reader must parse several comma-separated facts — but not verbose.

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 tool with no output schema, the description covers the essential behavioral context: where the draft is saved, that nothing is sent, that headers/quote are auto-set, and when to trigger it. The remaining parameters (folder defaults, attachments, html, lang) are adequately documented by the 89% schema coverage. The lack of an output schema is partially offset because the description clarifies the 'no send' guarantee, so an agent understands the expected effect.

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 high at 89%, so the schema documents most parameters thoroughly, making the baseline 3 appropriate. The description adds modest semantic value by telling the agent that recipients are 'sender, or everyone with reply_all' — mapping to the reply_all parameter — and that the quoted original is auto-set, relating to the quote parameter. But it doesn't cover the remaining parameter nuances in depth, which the schema handles.

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: 'Saves a reply to a specific message into Drafts, in the same thread.' It enumerates what the server sets (In-Reply-To/References, 'Re:' subject, recipients, quoted original), which clearly distinguishes it from siblings like reply_send (which would send) and create_draft (which creates a blank draft rather than a threaded reply). The closing 'Nothing is sent' removes any ambiguity about side effects.

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

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

Provides explicit trigger phrases for when to use: "Use this whenever the owner says 'reply / answer / write a draft' ('odpověz', 'napiš koncept')." This gives clear activation context. However, it does not name alternatives or state when NOT to use it — notably, it doesn't distinguish itself from reply_send (when the user wants to send rather than draft) or from create_draft. Clear context but no explicit exclusions.

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

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

Annotations indicate destructiveHint=true, but the description goes beyond by explaining that the server sets threading headers, subject, and recipients, and that the original is quoted automatically. It also discloses the important precondition of the owner's permission, which is not in the annotations. A small gap is that it doesn't mention whether the action is reversible, but it covers key behavioral aspects.

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 a single, dense paragraph that front-loads the critical information: it defines the tool, states the exclusivity condition, points to the alternative, and gives the consent gate. Every sentence earns its place with high information density and no fluff.

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 tool's complexity (9 params, no output schema), the description is quite complete. It covers the key trigger condition, differentiates from siblings, and clarifies some parameter nuances. It could mention what the return value is, but with no output schema that's not strictly required. The description does enough for the agent to use 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 89%, so the schema already explains most parameters. The description adds value by clarifying that the 'text' parameter should be plain text without greeting-to-quote artefacts, and that the original is quoted automatically, which helps the agent avoid duplication. It also clarifies that 'attachments' can be mailbox attachments, inline content, or local files, which is important for correct invocation.

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 clearly states this tool sends a reply to a specific message, and explicitly differentiates it from reply_draft and other send-related tools by mentioning the threading and quoting handled by the server. It uses a specific verb ('sends') and names the target resource ('a reply to a specific message').

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

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

The description gives explicit when-to-use vs when-not-to-use: 'Only when the owner enabled sending for the account AND every recipient matches send_allowlist; otherwise use reply_draft.' It also includes the critical consent gate: 'Use this only when the owner says "send".' This is exceptional usage 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?

Despite all annotations being false, the description discloses critical behavioral traits: the link expires in one hour, anyone with the link can PUT/POST a file, the file lands in 'mailmcp-uploads' and appears in list_uploads. It also clarifies that the tool itself does not upload; it only returns a link. This goes well beyond the annotations.

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

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

The description is concise, two sentences, front-loading the core purpose, then providing actionable details on usage, expiry, and alternatives. Every sentence adds value 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 no output schema, the description fully explains the return value (a link) and its behavior, including expiry, upload method, destination, and visibility in list_uploads. It also covers the decision between self-uploading vs. handing the link to the user. Nothing essential 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% and the single parameter 'account' is already described as 'Account id from list_accounts'. The description does not add additional parameter-specific detail, but given high coverage, a 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?

The description clearly states the verb 'Returns' and the resource 'a one-hour HTTPS upload link for an account', and further explains what the link does. It distinguishes itself from siblings by explicitly mentioning 'files too big for upload_attachment' and referencing list_uploads for the result.

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 explicit usage guidance: use it for files on the user's disk or files too big for upload_attachment, and provides a conditional directive to upload yourself if you can run commands, otherwise give the link to the user. This clearly differentiates from 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?

The annotations already cover read-only, idempotent, and non-destructive traits, and the description adds significant behavioral context: it returns ids for `fetch`, explains scope differences between Gmail (All Mail) and Outlook (Inbox only), and clarifies query syntax. This goes beyond what annotations provide and helps the agent predict 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?

The description is dense but every sentence earns its place: core functionality, syntax rules, account restriction, and platform-specific scope. It is front-loaded with the essential outcome and then layers necessary details. No redundant or filler content.

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

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

There is no output schema, so the description correctly states that results are 'documents with ids for `fetch`,' telling the agent how to use the results. It also covers platform-specific behavior and the alternative tool for folder-scoped searches. This is complete for the tool's complexity and one-parameter schema.

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

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

Schema coverage is 100% (the `query` property is documented), so the baseline is 3. The description enriches this by explaining the query format (Gmail syntax vs plain words) and the `account:<id> ` prefix, which is valuable additional semantics for the single parameter. This moves it above the baseline.

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

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

The description clearly states the tool's function: 'Searches all readable mailboxes with one query string and returns documents with ids for `fetch`.' It specifies the verb, resource, and output, and differentiates from the sibling `search_messages` by noting its folder-specific use case. The distinction is explicit and actionable.

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

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

The description provides detailed usage guidance: Gmail syntax vs plain words, account prefix to limit scope, and the Outlook/Gmail folder behavior with an explicit pointer to `search_messages` when a specific folder is needed. It tells the agent when to use this tool and when to use an alternative, leaving no ambiguity.

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 this as read-only, idempotent, and non-destructive, so the description only needs to add behavioral context beyond safety. It adds strongest-first ordering, the uid+folder contract needed by downstream tools, and two important Outlook result semantics. No contradiction with annotations.

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

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

The description is compact and front-loaded: scope, query syntax, return contract, then Outlook caveats. Every sentence contributes, with only slight redundancy in the two Outlook clauses. It is dense but not bloated.

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 read-only search tool with no output schema, this covers the essential call semantics: account scope, query syntax, ordering, and return fields. The schema supplies defaults like folder and limit, so the remaining gaps are minor and unlikely to cause misinvocation.

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

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

The schema already documents most parameters, and the description adds meaning for the highest-ambiguity ones: query syntax on Gmail, account='all', and Outlook's exact vs. partial 'from' matching. Self-explanatory parameters like 'to' and 'subject' need no extra elaboration, though a few interactions are left implicit.

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?

Clearly states it searches messages, with scope controlled by account (one or all). The Gmail-vs-elsewhere query behavior and 'uid + folder needed by other tools' make it specific. It does not explicitly contrast itself with the sibling 'search' tool, so differentiation from siblings is incomplete.

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

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

Provides clear when-to-use guidance by platform: full Gmail syntax on Gmail, full-text plus structured filters elsewhere, and account='all' for searching every readable account. It also explains Outlook-specific matching behavior for 'from'. It stops short of naming alternative tools or exclusion scenarios, so it is not fully 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 mark it destructive, but the description adds meaningful behavior: includes attachments, leaves Drafts, moves to Sent on Outlook, and enforces send_allowlist on recipients. This goes beyond what annotations provide and warns about state-changing effects.

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 concise sentences convey the core action, side effects, attachment behavior, and recipient constraint with no filler. The key distinction is front-loaded before the details.

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 description covers the action, attachments, folder side effects, and recipient authorization constraint. No essential operational detail is missing for an agent 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 description coverage is 100%, so the schema already explains the account, uid, and folder parameters. The description adds operational context about recipients and allowlist, but no additional parameter-specific semantics 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?

The description uses a specific verb and resource: 'Sends a draft exactly as stored in the Drafts folder', including its attachments, and clarifies the side effect of leaving Drafts/moving to Sent. This clearly distinguishes it from siblings like send_message or create_draft because it is about submitting an existing saved draft unchanged.

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 precise context: use when sending a saved draft as-is, with recipients taken from the draft and subject to send_allowlist. It does not explicitly name alternative tools or when-not-to-use cases, but the context is clear enough for an agent to select it over send_message or create_draft.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds an auth requirement (owner-enabled sending and send_allowlist), which is exactly the kind of behavioral context that goes beyond annotations. It does not detail rate limits or permanent side effects, but the authorization disclosure earns it a 4.

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 with no filler. The core action is front-loaded, the attachment capability is summarized, and the usage condition follows immediately. Every sentence earns its place.

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

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

For a tool with 11 parameters and complex attachment semantics, the description covers the essential purpose, the authorization gate, and the fallback tool. It does not mention return values, but no output schema exists and the missing details (e.g., local path restrictions, reply preferences) are already present in the input schema. The description is sufficient for an agent to invoke the tool correctly in most scenarios.

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 73%, so most parameters are already documented in the schema. The description adds a useful high-level grouping of attachment types ('existing mailbox attachments, uploaded files, inline content'), but otherwise it does not materially extend the schema's parameter documentation. A baseline of 3 is appropriate given the moderate coverage.

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 an email via SMTP') and clearly distinguishes itself from create_draft by name. It also summarizes the optional attachment capability, making the tool's scope unambiguous even among siblings like send_draft and reply_send.

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 states the precondition for use ('Only allowed when the owner enabled sending... AND every recipient matches send_allowlist') and names the alternative ('Otherwise use create_draft'). This gives the agent a clear decision rule, going beyond implied context.

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

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

Annotations already cover mutability and idempotency. The description adds genuinely useful behavior beyond them: the storage location, how images become embedded, and the required setup/draft prerequisites. It stops short of describing side effects or failure behavior, but it is transparent about the key operational conditions.

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

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

Three focused sentences with no wasted words. The main action is front-loaded, followed by usage guidance and an alternative workflow. Every sentence contributes new, relevant information.

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

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

For a 3-parameter write tool with rich annotations, the description is nearly complete: it explains storage, usage, alternatives, and preconditions. The only minor gap is that it does not describe what a successful call returns or how errors surface, but no output schema exists and this is not critical for invoking the 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%, so the schema already documents all three parameters. The description only loosely maps to html/text with 'HTML and/or text' and adds no new parameter-level detail, which matches the baseline for fully-covered schemas.

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: it stores the signature as a message in the 'mailmcp-signature' mailbox folder. This concrete mechanism distinguishes it from sibling tools like get_signature and create_draft, making its purpose unmistakable.

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 explicitly says when to use the tool ('when the owner pastes or dictates their signature') and gives an alternative workflow for photo/logo signatures. It also names prerequisites (mailbox signature setup and draft capability), so an agent knows when this tool is applicable.

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 mark the operation as non-read-only, destructive, and idempotent. The description adds meaningful behavioral context by clarifying that the action is reversible in the sense that it never permanently deletes the message, and it names the Trash folder as the destination. No contradiction with annotations.

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

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

Two short sentences with no filler. The core action is front-loaded, and the critical non-permanence qualifier is included immediately after.

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 mutation tool with full schema coverage and annotations already describing read/write, destructiveness, and idempotency, the description plus schema provide enough information for an agent to select and invoke the tool correctly. Return behavior is not essential here.

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

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

Schema description coverage is 100%: uid, folder, and account each have descriptions, including the important guidance to pass uid back exactly as returned. The description itself adds no parameter-specific detail, 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?

The description opens with a specific verb and resource: 'Moves a message to the Trash folder.' It also adds the key distinction 'Never deletes permanently,' which clearly separates this tool from any permanent deletion operation and leaves no ambiguity about what the tool 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?

The description implies the tool is for soft-deleting a message, but it does not explicitly state when to use it versus sibling tools like modify_message or when not to use it. There is no direct alternative routing or exclusion guidance, so usage context is only implied.

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

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

Annotations are all false, so the description carries full burden. It discloses key behaviors: the file is stored in a specific folder, the return structure {folder, uid, part} for the attachments parameter, and the file is removed once attached. It also mentions the size limit (policy.max_upload_bytes). It does not cover error handling or permissions, but the disclosed lifecycle is a significant behavioral detail.

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 with no filler. The primary purpose and behavior are front-loaded, and the alternative is given in the second sentence. Every word adds value.

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 provides the return structure and usage context (attachments parameter). It also explains the file's lifecycle. Missing details include error cases (e.g., exceeding the byte limit) and any prerequisites like account setup, but these are minor for this tool. Overall, it is quite complete for an agent to invoke correctly.

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

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

Schema description coverage is low (40%). The description clarifies content and encoding by explaining text vs base64, and mentions the size limit. However, it does not add meaning for account, filename, or content_type parameters. It partially compensates for the schema gaps, but not fully.

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 clearly states the verb (Stores), the resource (a file), and the purpose (to be attached to a draft or sent message). It also distinguishes itself from the sibling tool request_upload by explicitly naming the alternative for large files, making it unambiguous which tool to select.

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 explicit when-to-use guidance: when you already have the file content as text or base64 and want to attach it. It also provides a clear when-not: for large files or files on disk, use request_upload. This directly routes the agent to the correct tool.

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