mailmcp

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

Annotations are all false (not read-only, not idempotent, not destructive), so the description carries the disclosure burden. It adds meaningful behavioral context beyond the annotations: nothing is transmitted, the draft lands in the Drafts folder, and the owner acts on it externally. This clarifies the non-destructive save nature despite readOnlyHint=false, which is valuable context the annotations alone do not convey.

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

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

Three compact sentences with the core purpose and non-sending behavior front-loaded, followed by attachments and usage preference. No filler; each sentence earns its place. Slightly verbose in the attachments clause but well organized.

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 no output schema, the description covers purpose, safety, and usage routing well, but it never hints at the return value (e.g., whether a draft uid is returned for later send_draft calls), which an agent would need to chain operations. It is adequate but leaves the output contract to inference.

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% (moderate), so the schema handles most parameters. The description adds value by enumerating attachment sources ('existing mailbox attachments, files from upload_attachment/request_upload, or inline content') and implying reply context via 'preferred way to prepare replies.' Yet it adds little beyond the schema for cc/bcc/text/html/quote, and the reply preference is largely repeated by the in_reply_to_uid field description. It does not fully compensate for the 27% undocumented 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?

States a specific verb and resource ('Saves a draft into the Drafts folder'), and distinguishes itself from siblings by explicitly saying 'Nothing is sent' (vs send_draft) and 'This is the preferred way to prepare replies' (vs reply_draft/reply_send). The purpose is unambiguous and clearly separated from the 21 siblings.

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

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

Provides clear context: it is the preferred way to prepare replies, and notes the owner will review/send it (optionally via send_draft). This routes the agent away from send_message/send_draft. However, it does not explicitly exclude reply_draft for direct replies — the in_reply_to_uid schema field carries that guidance ('Prefer reply_draft / reply_send') rather than the description, leaving a small ambiguity between create_draft and reply_draft.

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

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

Annotations already declare 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?

Beyond what readOnlyHint=false and destructiveHint=true already convey, the description adds non-obvious behavior: attachments bypass the chat transport, the comment renders above the forwarded text, recipient allowlist is enforced, and the draft path avoids actual sending. None of this contradicts 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?

Roughly 40 words across three sentences, each earning its place: core behavior with attachment routing, comment placement, and constraints/draft mode. Information is front-loaded with the highest-value fact first.

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?

Adequate for a 10-parameter compose tool: covers attachment handling, comment, draft vs send branching, and the allowlist prerequisite. The main gap is that with no output schema, the description never states what the tool returns or how an agent later references a saved draft.

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 60% and most parameters already carry descriptions. The description adds placement semantics for comment ('above the forwarded text') and clarifies include_attachments behavior via the no-chat-pass-through clause, but it does not compensate for the uncovered portion of the parameter surface (e.g., cc/bcc interaction).

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), and immediately adds distinguishing scope: attachments are included and routed directly 'without the files passing through the chat.' The comment-placement and draft-mode details further separate it from reply and send siblings, so an agent can identify which tool to use without opening the schema.

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

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

Gives actionable constraints (recipients must match send_allowlist; as_draft redirects to Drafts) but never names or positions alternatives such as reply_send, reply_draft, or send_message, which are direct siblings in the compose space. When to choose forwarding over replying is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond those: it states that the body is sanitized and truncated to a configured limit, and that the result includes an attachment list. This gives the agent a clearer picture of what the call will return without contradicting 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, tightly written sentence that front-loads the core return contents first and appends the truncation caveat. Every phrase earns its place and 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?

For a read-only, idempotent tool with simple parameters and no output schema, the description covers the essential return values and the truncation behavior. The main gap is the ambiguity of 'configured limit' versus the max_chars parameter, which could confuse an agent deciding how to control response size. Overall, though, the combination of description, schema, and annotations is sufficient for correct invocation in most cases.

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 most parameters. The description adds semantic value by explaining the truncation behavior, which gives meaning to max_chars and the 'configured limit' phrase. It doesn't fully explain the interaction between max_chars and the configured limit, but it goes beyond what the bare schema provides.

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 ('Returns') and names the exact resources delivered: headers, sanitized text body, and attachment list for one message. It clearly identifies the tool's scope as a single message reader, which is enough to distinguish it from siblings like get_attachment or get_thread even without naming them.

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

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

The description provides no explicit guidance about when to use this tool versus alternatives such as get_thread, search_messages, or fetch. There is no mention of prerequisites, exclusions, or routing conditions. Usage is only weakly implied by the phrase 'of one message' and the schema's 'uid from search_messages' parameter, not by the description itself.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by stating it returns all messages in a conversation and explaining how thread membership is determined (Gmail thread id or References headers). It does not mention ordering or pagination, but this is a minor gap for a read-only listing operation.

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

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

A single, well-structured sentence that leads with the action and resource, then provides the key implementation detail about thread identification. There is no filler, and every element 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 conversation-listing tool with annotations covering safety, the description covers the core behavior and the critical cross-system distinction (Gmail thread id vs References headers). It lacks an explicit statement about output ordering, pagination, or limits, and it could more clearly say that uid is a message identifier rather than a thread identifier, but overall an agent can correctly invoke it for the intended use.

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 67%, with account and folder documented in the schema but uid lacking a schema description. The description partially compensates by implying uid identifies the 'given message' whose conversation is returned, but it does not make the uid-vs-thread-id relationship explicit, and folder/account semantics are left solely to the schema. This is acceptable but not a strong compensation.

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 a specific resource ('all messages belonging to the same conversation as the given message'), making the tool's function immediately clear. It also distinguishes this from single-message tools like get_message by emphasizing the thread/conversation scope, and the parenthetical on Gmail thread id vs References headers clarifies how conversation identity is resolved.

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 to use the tool: when you need the full conversation around a given message rather than a single message. However, it does not explicitly name alternatives like get_message or search_messages, nor does it state when not to use this tool. The thread-id vs References distinction gives useful context but stops short of explicit 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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful contextual detail by specifying what the returned list contains, including permission information. It does not contradict the annotations, though it omits noting that check_connection may perform IMAP login tests; the schema covers that.

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, efficient sentence with no filler. It front-loads the action and resource while providing the key output details in a compact structure.

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 low-complexity read-only list tool with annotations covering safety and a fully documented optional parameter, the description is sufficient. It even explains the return contents in the absence of an output schema, leaving no critical gap for an agent to call it correctly.

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

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

Parameter schema coverage is 100%, and the optional check_connection boolean is fully described in the schema. The description itself adds no parameter-level 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?

The description uses the specific verb 'Lists' and clearly identifies the resource as 'configured mailboxes', adding the exact output contents: IDs, addresses, and permitted operations. This distinguishes it from sibling tools like list_folders and makes the tool's intent 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?

The purpose is clear enough that an agent can infer when to use it, but the description provides no explicit guidance about when to choose this over alternatives such as list_folders or search tools. There are no when-not-to-use conditions or named 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 mark the operation as read-only, idempotent, and non-destructive, so the description does not need to restate those. It adds useful behavioral detail by defining the terminology ('labels on Gmail') and specifying the returned counts (message and unseen), which goes beyond the raw 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 entire description is a single, well-structured sentence that leads with the action, then the resource, then the output detail. Every phrase earns its place, and there is 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?

For a simple read-only listing tool with a single required parameter, the description covers what it does, what it returns (counts), and the scope (one account). No output schema exists, but the description provides enough information about the result shape for an agent to use 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%, and the parameter account is already documented as 'Account id from list_accounts'. The tool description adds only that the tool works on 'one account', which is not meaningfully additional to the schema. Baseline 3 is appropriate because the schema carries the parameter semantics.

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

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

The description uses a specific verb ('Lists') with a clear resource ('folders (labels on Gmail)') and explicitly scopes it to a single account. It also tells the agent what data is returned (message and unseen counts), making the tool's purpose unambiguous and distinct from generic sibling tools.

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 implies the tool is for retrieving folders/labels for one specific account, which is the natural context for use. It does not explicitly discuss alternatives or when not to use it, but no sibling tool appears to duplicate this function, so an exclusionary note is less critical.

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 that this is a mutating yet non-destructive, idempotent operation. The description adds concrete examples of those mutations, but it does not disclose deeper behaviors such as Gmail-only label restrictions, the relationship between folder and move_to, or whether modifications must be specified one at a time.

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, tightly worded sentence that front-loads the verb and action list. There is no filler or repetition, and every operation mentioned maps to a real parameter or side effect.

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 nine parameters and no output schema, the description is too terse for reliable invocation. It leaves unclear how folder, move_to, and archive interact, whether at least one modification must be selected, and which operations are Gmail-only. An AI agent would still face significant ambiguity when constructing a 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?

The description loosely maps 'read/unread' to seen and 'star/unstar' to flagged, which adds some meaning for parameters that lack schema descriptions. However, most parameter meanings are already covered by the schema, and the description does not clarify ambiguities like the difference between folder and move_to, so it does not substantially exceed schema 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 begins with specific verbs and a clear resource: it can mark read/unread, star/unstar, add/remove Gmail labels, and move/archive a message. This concrete action list makes it easy to distinguish from siblings like get_message, search, or trash_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?

There is no explicit guidance on when to use this tool versus alternatives. It does not mention, for example, that trash_message should be used for deletion, or that folder paths can come from list_folders. Usage context must be entirely inferred from the action list.

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?

With annotations offering no safety profile (all false), the description carries the burden. It discloses that the operation creates a draft (not a send), that the server sets the reply headers and quote, and that recipients depend on reply_all. It does not mention permission requirements or idempotency, but the core behavior is clearly and fully described.

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 with zero filler. The first sentence front-loads the key action and server behavior, the second gives the usage trigger with useful language examples, and the third delivers the essential negative constraint ('Nothing is sent'). Each 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 9-parameter tool, the schema covers most parameter semantics. The description supplies the high-level operation, the server-side behavior, and the intended trigger. It does not need to explain return values (no output schema) and adequately complements the structured schema, though it could mention permission requirements.

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

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

Schema coverage is 89%, so the baseline is 3. The description adds value by explaining the effect of reply_all ('recipients (sender, or everyone with reply_all)') and that the quoted original is automatically set, which clarifies the text and quote parameters. These details go beyond the schema's descriptions.

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: 'Saves a reply to a specific message into Drafts, in the same thread.' It also enumerates the server-set fields (In-Reply-To/References, Re: subject, recipients, quoted original) and explicitly says 'Nothing is sent,' clearly distinguishing it from reply_send and other sending tools.

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 provides an explicit trigger: 'Use this whenever the owner says "reply / answer / write a draft"' with language examples. It does not explicitly name alternatives like reply_send or create_draft for the 'when not' case, but the phrase 'Nothing is sent' and 'into Drafts' imply when not to use it.

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 this as destructive and non-read-only, so the description doesn't need to restate that. It adds valuable context beyond annotations: the server sets headers/subject/recipients/quote, and sending requires owner-enabled permissions plus allowlist compliance. This helps an agent predict outcomes and preconditions. Minor gap: no mention of what happens on failure or whether sending is irreversible beyond the destructive hint.

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 written sentences with zero filler: purpose first, behavioral consequences second, conditional usage rule third. Every sentence earns its place and the most decision-critical information (when NOT to use) is front-loaded.

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 sending tool with no output schema, the description covers the essential context: what the server does automatically, prerequisite conditions, and the alternative tool. It doesn't explain return values or error behavior, but annotations carry the destructive-safety profile and the intended usage is clear. Slightly more could be said about expected confirmation or receipt, but it's not a major 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 89%, so the structured schema already documents all parameters thoroughly. The description adds no parameter-specific semantics—it explains behavior and routing rather than the meaning of uid, text, or attachments. Baseline 3 is appropriate given high schema 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 names a specific action ('Sends a reply to a specific message in the same thread') and immediately clarifies what the server handles automatically (threading headers, 'Re:' subject, recipients, quoted original). It also implicitly distinguishes from reply_draft by describing the send path, so an agent can tell the tools apart.

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 conditions: only when the owner enabled sending AND all recipients match send_allowlist, otherwise use reply_draft. It further restricts use to explicit owner consent ('send' / 'pošli' / 'odešli'). This is concrete, actionable routing guidance with the alternative named directly.

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

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

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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds behavior beyond that: it searches across all readable mailboxes, returns document identifiers intended for `fetch`, and interprets queries differently based on account type. It also exposes a scoping mechanism via the account prefix. This is rich behavioral context without contradicting annotations.

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

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

Three sentences, each carrying a distinct purpose: main behavior, syntax rules, and scoping. No filler, and the most important fact (cross-mailbox search returning IDs) is front-loaded.

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-only search tool, the description covers the query format, scoping, and the relationship to `fetch`, and annotations cover safety. It could be slightly more explicit about what type of documents are returned (e.g., messages) or how it differs from search_messages, but that is minor.

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 only says 'Search query' for the sole parameter, while the description provides critical semantics: Gmail syntax with concrete examples, fallback to plain words, and the account-prefix syntax. This far exceeds the baseline for a 100%-covered 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'), a clear resource scope ('all readable mailboxes'), and a concrete outcome ('returns documents with ids for `fetch`'). This distinguishes it from siblings like fetch (which consumes those ids) and search_messages (by its cross-mailbox scope). The verb 'Searches' plus resource makes the purpose unambiguous.

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

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

Gives direct usage rules for the query parameter: Gmail search syntax for Gmail accounts with examples, plain words for others, and an `account:<id>` prefix to narrow to a single mailbox. It does not explicitly compare against search_messages or state when not to use this tool, so it falls short of full alternative routing. The guidance is still clear enough for correct invocation.

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. The description adds valuable behavioral context: it states results are returned newest first and that the response includes uid and folder needed by other tools. It also explains the Gmail vs non-Gmail query behavior. These details go beyond the annotation-only information, so the description earns 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?

The description is three concise sentences with no filler. It leads with the primary purpose, then adds the critical Gmail syntax nuance, and ends with return ordering and required fields. Every sentence earns its place and is front-loaded for quick comprehension.

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 search tool with 13 parameters but only one required, the description covers the essential behavioral aspects: account scope, query syntax, return ordering, and the uid+folder requirement. It does not explain pagination details (offset/limit) or when to use this over sibling 'search', but the schema covers pagination constraints and the overall usage is clear. Given the tool's complexity, the description is reasonably 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 62%, and the description clarifies the key parameters 'account' (with the special 'all' value) and 'query' (Gmail syntax vs full-text). It also refers to 'structured filters' implying the other fields act as filters. However, it does not add meaning to parameters like offset, limit, since, before, etc., which rely on the schema descriptions. The description adds moderate value beyond the schema but does not fully compensate for the 38% uncovered.

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: 'Searches one account (or all accounts with account="all")'. It clearly distinguishes itself from generic search by specifying account scope, and differentiates Gmail query syntax from elsewhere. This makes the tool's purpose unambiguous and distinct from siblings like 'search'.

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 when to use account="all" and contrasts Gmail query syntax with plain-text elsewhere, giving context on usage. However, it does not explicitly mention when to prefer this tool over sibling tools like 'search', 'fetch', or 'get_message', nor does it state any exclusions. Usage guidance is present but not comprehensive.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's statement that it 'removes it from Drafts' aligns with and reinforces the annotation. The description adds value beyond annotations by disclosing that attachments are included and that recipients must match send_allowlist. It does not contradict 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 core action and the most important side effect (removal from Drafts) are front-loaded, and the recipient constraint is stated clearly. 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 destructive send operation, the description covers the key facts: what is sent, what happens to the draft, and the recipient constraint. It does not describe the return value or error cases, but there is no output schema and the annotations cover the safety profile. The description is complete enough for an agent to invoke 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 schema already documents all three parameters. The description adds context that the uid comes from create_draft or search_messages in the Drafts folder, which is already in the schema. The description does not add much beyond the schema, but the baseline of 3 is appropriate because the schema carries the full burden.

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 ('Sends'), a specific resource ('a draft exactly as stored in the Drafts folder'), and key behavioral details (includes attachments, removes it from Drafts). It clearly distinguishes this from siblings like send_message (which sends a new message) and reply_send (which sends a reply).

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 to use this tool: when you have a saved draft and want to send it exactly as stored. It also notes that recipients are taken from the draft and must match send_allowlist, which is a critical usage constraint. It does not explicitly name alternatives or say 'use send_message instead when...', but the context is clear enough for an agent to select it.

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=false and destructiveHint=true, but the description adds context: it sends via SMTP, supports attachment types, and is gated by a send_allowlist. It doesn't detail side effects beyond sending, but the send action itself plus the allowlist preconditions is meaningful behavioral context 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?

Two sentences with dense, relevant content: the core action, attachment scope, and a clear precondition plus alternative. No wasted words and the critical gating condition is front-loaded.

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 11 parameters, the schema covers 73%, and the description clarifies the gating condition and the use-vs-draft alternative. It doesn't explain return values, but there is no output schema, and for a side-effectful send action that is acceptable. The description plus schema provide enough 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 73%, and the schema documents most parameters well (to, attachments, account, html, etc.). The description adds high-level attachment semantics ('existing mailbox attachments, uploaded files, inline content') and the allowlist gating that maps to the recipient parameters. Some parameters like cc/bcc/quote have no schema description, but the tool description compensates reasonably by framing what sending entails.

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?

Description states a specific verb ('sends'), a resource ('an email via SMTP'), and the optional capability ('attachments'). It distinguishes itself from create_draft by naming when sending is disallowed and what alternative to use instead.

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

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

Explicitly states when the tool can be used ('only allowed when the owner enabled sending for the account AND every recipient matches send_allowlist') and names the alternative ('Otherwise use create_draft'). This gives clear routing guidance and 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 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 declare destructiveHint=true and idempotentHint=true. The description adds that it moves to trash and never permanently deletes, which is useful. However, it doesn't disclose potential side effects like moving to trash might overwrite an existing trash folder entry or require specific permissions. The description aligns with annotations, so no contradiction.

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

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

The description is two short sentences with no filler. The key behavior (moves to trash, not permanent) is front-loaded. This is appropriately concise for a simple tool.

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 simplicity, the output schema absence is not a major gap. The description covers the main behavioral intent and safety. It lacks details on required permissions, but annotations already flag destructiveness. For a tool with this complexity, it's reasonably 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 coverage is 67% on a 3-parameter schema. The description adds no parameter-specific details beyond what the schema provides, which already covers two parameters (uid and account). The folder parameter is described in the schema with defaults. The description's mention of 'Trash folder' implies the folder parameter, but it doesn't add new 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 clearly states that the tool moves a message to the Trash folder and explicitly mentions it never permanently deletes. This distinguishes it from potential delete-type operations. However, it doesn't explicitly differentiate from modify_message or other siblings that might handle message states.

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 use for trashing messages without permanent deletion, which provides some context. However, it doesn't provide explicit guidance on when to use this over other message manipulation tools like modify_message or when not to use it (e.g., if permanent deletion is desired).

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.