Mailbox MCP

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

The description goes well beyond the readOnlyHint/idempotentHint annotations by explaining the underlying email delivery model: relay acceptance is not delivery, bounces arrive later as separate messages, and bounces often land in Junk. It also discloses result semantics (PERMANENT vs TEMPORARY) and the default scan folders, which materially changes how the agent should interpret and act on results. No contradiction with annotations exists.

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?

Although the description is long, every sentence contributes substantive information about delivery timing, default folders, failure types, user guidance, or sibling-tool routing. The core purpose is front-loaded, and the additional context is dense rather than padded. This is appropriate length for a tool with nuanced result semantics.

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

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

The description is complete for a read-only lookup tool with no output schema. It explains when to call it, what it scans, how to interpret PERMANENT vs TEMPORARY results, and how to handle the complementary check_receipts case. There are no obvious gaps that would prevent an agent from invoking 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?

The input schema already documents all three parameters with clear descriptions and defaults, and schema_description_coverage is 100%. The tool description adds context about the default INBOX/Junk scan but largely mirrors the schema rather than introducing meaningfully new parameter-level semantics. Baseline 3 is appropriate because the schema carries the parameter documentation 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 opens with a specific, action-oriented statement ('Find messages that came back undelivered') that clearly identifies the resource and the operation. It also explicitly distinguishes itself from sibling tools by noting this only finds failures, while check_receipts covers the positive delivery side. This makes the tool immediately recognizable and separable from related 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 gives explicit when-to-use guidance: after sending anything important, and whenever the user asks whether a message arrived. It also provides a clear exclusion: if the user is asking whether a message arrived rather than failed, call check_receipts as well, because a missing bounce is only weak evidence of delivery. This is a model of 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?

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description adds critical behavioral context: the tool always checks the connected mailbox's own domain, takes no arguments, and requires interpreting each result's note rather than trusting a bare pass/fail. It also warns about DMARC p=none and DKIM selector edge cases, and distinguishes 'missing' from 'lookup FAILED'.

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

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

The description is front-loaded with what the tool checks, then when to use it, then the interpretation caveats. Every sentence adds necessary behavioral or usage information, and the warning about interpreting notes is essential for correct invocation and result reporting.

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 zero-parameter schema, complete annotations, and absence of an output schema, the description covers all essential operational guidance: what is checked, when to use it, what cannot be done, and how to interpret results responsibly. An agent has everything needed to invoke it correctly and avoid common misinterpretations.

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 are zero parameters, so per the baseline this dimension gets a 4. The description reinforces this by explicitly stating the tool takes no arguments and always targets the connected mailbox's domain, which prevents an agent from inventing a domain parameter.

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

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

The description states a specific action ('Check the DNS records'), a specific resource (the connected mailbox's own domain), and the deciding records (SPF, DKIM, DMARC, MX). It also explicitly distinguishes the tool from any general domain-lookup tool by stating it cannot look up anyone else's domain.

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 trigger scenarios ('when the user asks why their mail goes to spam, why a recipient did not get something, or whether their domain is set up properly') and an exclusion ('cannot look up anyone else's'). It does not name specific sibling alternatives, but the usage context is clear enough for an agent to select this tool correctly.

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 description goes far beyond the readOnly/openWorld/idempotent annotations by explaining that a missing receipt means nothing, the conditions under which read receipts exist, that a receipt only means opened not read, and that requests cannot be made retroactively. This is rich, honest behavioral disclosure that prevents serious misinterpretation.

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 long but every sentence carries essential information: tool purpose, receipt types, when to use, how to scope, and critical caveats about missing receipts. The most important scoping instruction is front-loaded, and the content is organized clearly rather than padded.

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

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

For a read-only query tool with no output schema, the description fully covers what the tool does, what the results mean, how to narrow results, and the critical prerequisite that a read receipt must have been requested at send time. Nothing essential is missing for an agent to select and 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?

The schema already provides 100% coverage with descriptions for days, mailboxes, and messageId. The description adds meaningful value by explaining how to use messageId from a send result, the default behavior when omitted, and the meaning of receipt-related statuses. This goes beyond the baseline schema-only documentation.

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: finding confirmations for messages this mailbox sent. It clearly distinguishes the two kinds of confirmations (DELIVERY vs READ) and the exact meaning of each, making the tool's purpose unambiguous relative to 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?

It explicitly states when to use the tool: after sending something important or when the user asks whether a message arrived. It also explains how to scope by messageId and the prerequisite of requesting a receipt during send. It does not explicitly name alternatives like check_bounces, but the usage context is clear enough.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important non-obvious behavior: an empty result is not an error, files sit in a draft in their own Drafts folder, and the draft is deleted automatically once files are attached or swept later. It also warns the agent not to offer deletion, which is exactly the kind of behavioral context annotations cannot convey.

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

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

The description is dense but every sentence earns its place: purpose and return value, call timing, empty-result handling, and deletion behavior. Important warnings are front-loaded enough to be noticed, and the final explanatory sentence justifies the DO NOT instruction rather than padding it.

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 one parameter, no output schema, and no nested objects, the description is complete. It explains what the tool returns (`fileRef` per file), how to respond to an empty result, and the lifecycle of the underlying draft. There is no critical missing context.

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 `uploadId` parameter is already documented as 'The `uploadId` from create_upload_link.' The description reinforces this by referencing `create_upload_link`, but it does not add new parameter-level meaning beyond the schema. A baseline of 3 is therefore 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-resource pairing: 'Look for the files an upload link put into this mailbox' and states the concrete return value, a `fileRef` for each file. It clearly distinguishes this from sibling check tools by anchoring it to upload links and the `create_upload_link` flow.

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 is explicit about when to call it: 'Call this after create_upload_link - either straight after uploading the file yourself, or once the person says they have.' It also gives a clear when-not: if nothing has arrived, do not call repeatedly; tell the person what you are waiting for.

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

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

Annotations declare idempotentHint=true, and the description goes well beyond that by explaining the case-insensitive matching behavior, the reply indicating whether anything was created, and the side effect of creating intermediate folders. It also discloses the subscription side effect, which is not visible in the annotations or schema.

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

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

The description is dense but every sentence adds critical behavior: namespace rules, hierarchy creation, idempotency, parent semantics, and refusal conditions. The most important fact (what '/' does) is explicitly highlighted, and the structure flows from common usage to edge cases without wasting words.

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 creation tool with two required/optional string parameters and no output schema, the description covers all likely unknowns: naming, nesting, idempotency, case sensitivity, subscription, parent limitations, and refusal conditions. Nothing needed to call the tool safely and correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful detail beyond the schema: it clarifies that '/' builds hierarchy, that 'parent' can be non-selectable, and that duplicate names are matched case-insensitively. This transforms the parameters from simple strings into well-understood behaviors.

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 identifies the exact action and resource—'Create an IMAP folder'—and immediately distinguishes this operation from siblings like rename_folder and delete_folder by explaining server-side namespace behavior, subscription, and hierarchy creation. It is specific about what the tool does and what it does not do (e.g., no literal '/' in names).

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 guidance on when to use `parent` versus building the path manually, explains that creating under a non-selectable parent is intentional and useful, and notes that it is safe to call twice, which conflicts with typical assumptions about creation tools. It also states when the tool refuses input, giving clear usage boundaries.

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 description goes far beyond the sparse annotations: it discloses that files land in Drafts as a holding draft, that the draft cleans itself up when files are attached, that the link requires no sign-in or password, and that check_upload provides fileRef values. This gives the agent important side-effect awareness that nothing in the annotations or schema conveys.

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 long, but every sentence earns its place: purpose, side effects, two usage modes, the mandatory follow-up, and explicit anti-usage cases. It is front-loaded with the core purpose and clearly organized, so the length is justified by the amount of behavior it must convey without an output schema.

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 zero parameters, no output schema, and minimal annotations, the description is remarkably complete. It covers what the tool returns indirectly (uploadUrl), what the user receives (a no-login link), what happens to files (draft + auto-cleanup), the follow-up call (check_upload), and the exclusion cases. An agent has enough context to decide when and how 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?

The input schema has zero properties, so there are no parameter semantics to explain. The description still references the expected returned uploadUrl and filename convention for the curl path, which is useful, but that is output/invocation context rather than input-parameter meaning. A 4 matches the baseline for a zero-parameter tool.

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

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

The description opens with a specific verb and resource: "Produce a one-off link that puts files into this mailbox." It also distinguishes itself from siblings by explicitly saying when not to use it (files already in the mailbox via read_email, or files with a URL). This makes the tool's purpose unmistakable and distinct from related tools like check_upload and read_email.

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

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

Usage guidance is exceptionally concrete: use it for files not in the mailbox and not reachable by URL, typically local files. It gives two explicit modes of use — direct curl upload versus giving the link to the person — and tells the agent to call check_upload afterwards. It also states clear exclusions: do not use for in-mailbox files or already-URL-reachable files.

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

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

Beyond the annotations (destructiveHint: true, readOnlyHint: false), the description adds critical behavioral context: messages are recoverable from Trash, the tool does not permanently destroy mail, it refuses already-Trashed messages, enforces a same-folder constraint, and operates on the whole UID set in a single call. This gives the agent a clear mental model of side effects and constraints.

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

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

Four sentences, each adding distinct value: core action, recoverability, preconditions and refusals, and batching guidance. The most important identifying information is front-loaded, with 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 two-parameter tool with no output schema, the description covers the action, side effects, preconditions, refusals, and invocation strategy. The only minor gap is the exact behavior when a mixed set is passed (e.g., some UIDs already in Trash alongside valid ones) — whether the whole call fails or just the invalid subset is skipped. This does not prevent correct selection or invocation, but slightly reduces completeness.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a cross-parameter constraint not present in the schema: all UIDs must belong to the same folder, which affects how mailbox and uids must be combined. It also reinforces the batching behavior already described in the uids parameter, slightly redundant but still useful.

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: 'Move messages to the Trash folder', then anchors it with a familiar real-world analogy ('exactly as clicking Delete in Outlook or webmail would'). It further distinguishes this from permanent deletion, making the tool's scope unambiguous and separate from related operations like move_email or a permanent-delete tool.

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 explicit when-not-to-use guidance: it 'Refuses to run on messages that are already in Trash' and explains that permanent deletion is a separate operation this tool does not perform. It also gives a clear precondition ('All the messages must be in the SAME folder') and a concrete invocation rule ('Pass every UID in one call rather than calling it once per message').

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

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

Beyond the destructiveHint annotation, the description discloses that deleted folders are not recoverable, that the folder is unsubscribed to avoid phantom mail clients, and that refusals include the message count for non-empty folders. This is exactly the kind of behavioral context an agent needs before invoking a destructive 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?

The description is dense but every sentence contributes critical operational information: empty-folder requirement, unsubscribe behavior, no-Trash consequence, refusal conditions, and alternatives. It is front-loaded with the most important constraint and avoids 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 destructive tool with no output schema, the description fully covers success conditions, failure/refusal conditions, and fallback actions. It even instructs the agent to read and relay the refusal message, which is essential for correct user-facing behavior.

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 'name' is fully documented in the schema with a clear example. The description does not add new parameter-level semantics, but with 100% schema coverage 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 tool deletes an EMPTY folder and unsubscribes it, and explicitly distinguishes it from delete_email by noting there is no Trash recovery. It also enumerates exactly what it refuses to delete, leaving no ambiguity about the operation's scope.

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 guidance and names alternatives: move_email or delete_email should be used first if the folder has messages, and then delete_folder for the empty folder. It also lists refusal conditions (sub-folders, INBOX, system folders), which helps the agent decide whether this tool is appropriate.

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 description clearly discloses the write behavior: a draft is persisted to the Drafts folder, not submitted to SMTP, and it will appear in other mail clients where it can be edited, sent, or deleted. The annotations already signal readOnlyHint=false and destructiveHint=false, so the description adds useful behavioral context without contradicting the structured metadata.

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

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

The description is three tight sentences with no filler: it states the primary behavior, the downstream visibility/lifecycle of the draft, and the key contrast with send_email. Each sentence earns its place and the most important constraints are 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 the large parameter surface and sparse annotations, the description is mostly complete: it covers what happens, where the draft goes, and how this differs from sending. It does not mention the related draft_reply/draft_forward or update_draft tools, and with no output schema it could say one line about what a successful call returns, but these are minor gaps.

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

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

Schema coverage is high at 78%, so the schema already documents most parameter meaning in detail, including attachments, from, html, plainTextOnly, and requestReadReceipt. The description adds one useful semantic note by emphasizing that `to` is required exactly as in send_email, but it does not compensate for the undocumented `cc` and `subject` 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 ('Save'), a specific resource ('the Drafts folder'), and a clear negative scope ('without sending it'). It also explicitly distinguishes itself from send_email by noting the only difference is SMTP submission, 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 clear context for when to use this tool: when the goal is to save a draft rather than send it, and it names send_email as the alternative and states the exact deciding difference. It does not explicitly rule out draft_reply or draft_forward for reply/forward drafts, but the core send-vs-draft decision is well covered.

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

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

The description goes well beyond the annotations by disclosing that the original's attachments are carried, inline images included, that oversized files are listed as skipped and must be reported to the user, and that recipients are exactly the supplied addresses, never resolved from the original. It also emphasizes that nothing is sent and nothing reaches anyone, which is crucial safety context.

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

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

The description is long but front-loaded with the core behavior and alternatives, and each major clause carries operational guidance. There is minor redundancy, such as 'Nothing is sent and nothing reaches anybody,' but overall it is dense with useful information rather than padded.

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

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

For a complex 10-parameter tool with no output schema, the description covers the central decision (draft vs. send), attachment behavior, recipient semantics, and the safety boundary. It does not explicitly state what the tool returns, such as a draft ID, but it does say the result opens in Outlook or webmail, which is likely sufficient for the agent.

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 90%, so the schema already documents most parameter details. The description adds meaningful cross-parameter guidance: recipient addresses are used exactly as supplied, and the original's attachments are automatically carried into the draft, which is not obvious from the schema alone.

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: compose a forward and save it in Drafts without sending it. It also differentiates from sibling tools by explicitly calling out draft_email, which creates a standalone message without the original, and forward_email, which would send the same content.

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

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

It explicitly states when to use this tool ('whenever the user wants to check a forward before it goes') and gives an exclusion: never use draft_email because it does not carry the original's body, files, or forwarded-message block. It also clarifies the relationship to forward_email, giving clear selection criteria.

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

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

Beyond the annotations (readOnlyHint: false, openWorldHint: true, etc.), the description discloses critical behavioral traits: nothing is sent, the original is NOT marked as answered, the draft appears in the Drafts folder with quoted original and correct threading, and it opens in Outlook or webmail for later editing, sending, or deletion. This adds substantial behavioral context that 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?

The description is four sentences, each earning its place: purpose, when-to-use with sibling contrast, exact output behavior, and explicit non-effects. It is dense but not bloated, front-loads the core purpose, and contains zero redundant phrasing.

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 (11 parameters, rich schema) and the absence of an output schema, the description covers the essential contextual gaps: what the draft looks like, where it goes, what happens to the original, and that nothing is sent. No output schema means return-value explanation isn't required; the behavioral outcomes are fully described.

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 reinforces that the quoted original is added below the body and that recipients/threading match reply_email, but it does not add new parameter-specific semantics beyond what the schema already provides in detail. It is neither harmful nor a significant value-add over the schema.

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

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

The first sentence states the exact verb, resource, and outcome: 'Compose a reply to a message and save it in Drafts WITHOUT sending it.' It explicitly distinguishes itself from draft_email, clarifying the difference between a threaded reply draft and a standalone draft. This is unambiguous and fully differentiates the tool from its nearest sibling.

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

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

The description explicitly says when to use this tool ('Use this whenever the user wants to review or edit a reply before it goes') and explicitly warns against using draft_email instead, explaining the technical consequence of that wrong choice. It also relates this tool to reply_email, telling the agent that this produces exactly what reply_email would have sent, which makes the usage decision effortless.

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 description adds substantial behavioral context beyond the read-only and idempotent annotations: results are drawn from email content and are not trusted data, weak matches may be impersonators, and the agent must confirm weak or ambiguous matches with the user before sending. This meaningfully changes how the tool should be used.

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 longer than average, but the length is earned: it front-loads the core purpose, then delivers safety-critical confidence rules and user-confirmation obligations. Some repetition and all-caps emphasis reduce polish slightly, but no sentence is filler.

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

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

There is no output schema, so the description carries the full burden of explaining results. It explains the evidence fields sentTo and receivedFrom, the strong versus weak confidence distinction, and the required follow-up behavior, leaving the agent with enough context to invoke and interpret 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 extra semantics for the mailboxes parameter by noting that Sent is the trustworthy source and that the default of Sent and INBOX is almost always right, which helps the agent reason about parameter choices without reading separate docs.

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

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

The description names a specific verb and resource: resolve a person's name to an email address, scoped to the mailbox's actual correspondents. It immediately distinguishes the tool from generic search tools by focusing on address resolution rather than message lookup.

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 an explicit invocation rule: call this BEFORE send_email whenever the user names a person instead of an address. It also tells the agent what not to do, such as guessing an address or asking the user to type one, making the usage context unmistakable.

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 indicate a mutating but idempotent, non-destructive operation. The description adds valuable behavioral context beyond that: it is purely a marker, it does not move/read/change messages, and the whole set should be passed in one call. This gives an agent a clear model of the side effect.

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

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

Three concise sentences packed with the essential semantics: what the flag is, what it does not do, and how to invoke it. Front-loaded with the core purpose and free of 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 two-parameter tool with strong annotations and full schema coverage, this description covers everything needed: semantics, non-effects, search integration, batching, and single-message use. No meaningful gap remains.

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 fully documents both parameters and the batching expectation. The description reinforces the batch behavior by saying 'Pass the whole set in one call,' but it does not add substantial meaning beyond the schema details.

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 identifies a specific verb and resource: `Flag messages` with the distinctive star/flag marker. It also differentiates this from sibling tools by explicitly stating it does not move, read, or otherwise change messages, making the operation 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 gives clear context for when to use the tool: it is purely a user-visible attention marker and is linked to search_emails's `flagged` filter. It implies when not to use it by excluding move/read/change behaviors, though it does not explicitly name sibling tools like mark_read or unflag_email as alternatives.

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

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

Annotations already mark destructiveHint=true, and the description reinforces and expands on this with 'This delivers real mail to real people and cannot be undone.' It also discloses crucial non-obvious behaviors: original attachments are carried, too-large files are skipped and must be reported to the user, user-supplied attachments are added in addition, and the forward is not threaded. 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 long but justifiably so for a 10-parameter side-effect-heavy tool. It is front-loaded with the purpose, then covers forwarding format, attachment behavior, required user notification, and irreversibility. Some sentences are run-ons, but every major block earns its place and critical warnings are visually emphasized.

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 covers the most important invocation-time facts: real mail is sent, it cannot be undone, forwarded attachments are carried, skipped files must be disclosed, and the forward is separate from the original conversation. It gives only partial return-value detail ('the result NAMES the files it sent') and does not mention draft_forward as the draft path, but overall it is sufficient for safe 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 90%, so the schema already explains most parameters. The description still adds meaning beyond the schema, particularly for `to` ('recipients here are exactly the addresses you supply and are never resolved from the original message') and `attachments` ('Files you attach yourself with `attachments` are sent IN ADDITION to the original's, not instead of them').

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: 'Forward a message to new recipients, exactly as clicking Forward in Outlook or webmail would.' It further distinguishes the tool from reply_email by stating recipients are exactly supplied, never resolved, and that the message is not threaded onto the original conversation. This makes the tool's role 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 description explicitly contrasts with reply_email ('unlike reply_email, recipients here are exactly the addresses you supply...') and notes that the forward is not threaded onto the original conversation. It also stresses that this sends real, irreversible mail. However, it does not explicitly mention draft_forward as the non-sending alternative, so sibling routing is not fully covered.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it returns only summaries, not bodies, and orders results newest first. No contradiction exists.

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 primary purpose is front-loaded, and the key limiting behavior ('summaries only, not message bodies') is stated directly and economically.

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

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

For a simple read-only list tool with zero required parameters and full schema coverage, the description is largely complete: it covers ordering, scope, and output limitation. A minor gap is not explicitly differentiating from search_emails, but the recency framing provides enough directional context.

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 both limit and mailbox are already fully documented with types, defaults, and bounds. The description adds little beyond the phrase 'in a mailbox', so the baseline score 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 uses a specific verb ('List') and resource ('messages in a mailbox') and adds meaningful scope details: 'most recent', 'newest first', and 'summaries only'. The final clause distinguishes it from read_email by explicitly saying it does not return message bodies.

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

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

The description makes it clear when this tool fits: when you need a recent, read-only overview of messages. However, it does not explicitly mention alternatives like search_emails for filtered/full-text searches, nor does it state when not 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?

Beyond the readOnly and idempotent hints, the description adds important behavioral context: identities are added by the mailbox owner outside the connector, and the mail server ultimately decides whether it will carry one. It also discloses that one address is the default, which is a meaningful detail for agents.

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 no redundancy. The first sentence front-loads the core purpose, the second explains how to use the result, and the third adds a caveat about external limitations. 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 read-only, zero-parameter tool with no output schema, the description fully covers what is returned (the addresses and the default), how to use the result (as `from` in sending tools), and external constraints (owner-managed addresses, server decision). No critical information is missing.

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

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

The tool has zero parameters, so parameter semantics are not applicable. The description appropriately focuses on output usage instead, and the baseline of 4 for zero-parameter tools applies.

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

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

The description states a specific action ('List the addresses this mailbox can send as') and identifies the resource (send-as addresses) and the default selection. This clearly distinguishes it from siblings like list_mailboxes, which lists mailboxes rather than identities.

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 by explaining that the returned addresses can be passed as `from` on send_email, reply_email, forward_email, and draft_email to override the default. It doesn't explicitly mention alternatives or when-not-to-use, but the intended usage is evident and practical.

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 description substantially exceeds the readOnly/idempotent annotations by defining what selectable:false means and stating exactly how move_email, delete_email, and create_folder treat such nodes. No contradiction with annotations exists.

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 core behavior is front-loaded in the first sentence; the remaining sentences add necessary, non-redundant behavioral context for downstream tool calls. No filler is present.

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 parameterless read-only listing tool, the description fully covers the output semantics an agent needs: it lists all folders, includes roles where available, and explains the actionable meaning of selectable:false. There is no output schema, but the description provides sufficient context.

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

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

The tool has zero parameters, so the baseline is 4. The description appropriately spends no space on parameter details.

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 ('List every IMAP folder in the account') and a distinguishing detail (special-use roles). This cleanly separates it from sibling email/list tools such as list_emails and list_identities.

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

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

Usage context is implied rather than stated: an agent can infer to call this when it needs the folder hierarchy before selecting a destination or source for move_email, but the description does not explicitly say when to use it over alternatives or when not to use it. The sibling tool references provide downstream behavioral guidance, not route-selection 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 disclose the safety profile: readOnlyHint=false, destructiveHint=false, and idempotentHint=true, all consistent with a non-destructive state-change operation. The description adds value by clarifying the subtle batch behavior (a single operation over the whole set) and the deliberate-act nature of marking, which is useful context beyond the annotations. No behavioral claims are made beyond what the annotations support.

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 terse sentences, each earning its place: the first states the core action, the second disambiguates from the read_email sibling, and the third delivers the critical batching instruction. The purpose is front-loaded in the opening words, and there is zero filler or repetition of schema 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 two-parameter mutation tool with full schema coverage and annotations carrying the safety profile, the description is nearly complete: an agent knows what the tool does, what to pass, and how to batch. The only notable absence is any mention of the return value or response behavior, and since no output schema exists, a brief note about what the call returns would have made this fully self-sufficient.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The uids schema description is especially detailed, covering source (list_emails or search_emails), batching rationale, the 500-item cap, and the one-element-array case, while the mailbox default is also stated. The tool description's final sentence reinforces the batching guidance but adds nothing beyond what the schema already conveys, so baseline 3 is appropriate.

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

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

The description uses a specific verb+resource ('Mark messages as read') and is unambiguous about the state change being performed. The sentence 'Reading a message does not mark it read - this is the deliberate act that does' implicitly distinguishes this from the sibling read_email, though it never names the sibling explicitly. Purpose is clear, but sibling differentiation is inferred rather than stated outright.

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 operational context: 'Pass every message you want marked in one call' tells the agent how to batch its invocations efficiently. However, it does not explicitly name alternatives like read_email (fetch content without state change) or mark_unread, nor does it state when not to use this tool. The read-versus-mark clarification is a semantic distinction, not a routing rule, so guidance on choosing between siblings 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?

The description adds behavioral context by explaining the state change ('restoring their unread status') and the bulk single-call behavior. This complements the annotations (idempotentHint, destructiveHint) without contradicting them, though it does not cover side effects or authorization requirements.

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

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

Two short sentences with no filler: the first states the action and effect, the second gives the key usage constraint. It is front-loaded and 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 simple two-parameter mutation with fully documented schema and annotations, the description covers the operation and the critical batching behavior. It does not describe return values, but no output schema exists and the safety profile is already carried by annotations. A brief mention of the opposite action (mark_read) would make it complete.

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

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

Schema description coverage is 100%, and the uids parameter description already explains batching limits, sourcing, and single-message usage. The tool description's 'Pass the whole set in one call' lightly reinforces the schema but adds no new parameter meaning, 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 clearly states the action ('Mark messages as unread') and the outcome ('restoring their unread status'), giving a specific verb and resource. It differentiates from the sibling mark_read mainly through the tool name rather than explicit textual contrast, so it falls just short of a 5.

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

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

The only usage guidance is the batching instruction 'Pass the whole set in one call,' which is a how-to rather than a when-to-use directive. It does not mention mark_read or other alternatives, so when to choose this tool over siblings is implied by the name rather than explicit.

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

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

Annotations already mark the tool as destructive and non-read-only. The description adds valuable behavioral context by stating that flags and original dates are preserved, and that all messages must share the same source and destination. This goes beyond what the schema and annotations convey.

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

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

Four sentences, no filler. The core action is front-loaded, followed by preservation details, constraints, and batching guidance. Every sentence contributes useful information for correct invocation.

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 annotations and fully documented schema, the description is largely complete for a simple move operation. It covers the key constraints, preservation behavior, and batching expectations. It does not spell out return values or error cases, but no output schema exists and these are secondary for this tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining batching behavior explicitly: pass every UID in one call, and make one call per destination. This helps the agent avoid inefficient or incorrect multi-destination calls.

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: 'Move messages from one IMAP folder to another.' It clearly distinguishes this from sibling operations like delete_email, flag_email, or reply_email by focusing on relocation between folders.

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: this is for backlog filing, all UIDs must be in the same source folder, and one call per destination is required. It does not explicitly name alternative tools, but it gives enough operational guidance for when to use this tool and how to structure calls.

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 indicate read-only, open-world, and idempotent behavior, so the bar is lower. The description adds substantial behavioral detail: attachment refs expire after an hour, download URLs expire after 15 minutes and are security-sensitive, HTML is sanitized, replyTo affects reply routing, and the tool must not be used to preview outgoing formatting. This goes well beyond what annotations 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?

The description is long, but every sentence carries essential operational information that an agent needs to avoid mistakes: non-marking behavior, attachment ref handling, URL expiration, replyTo routing, and HTML sanitization. Key purpose and side-effect information are front-loaded, and the warnings are actionable rather than 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?

There is no output schema, so the description must explain return-relevant behavior. It covers the body, recipients, attachments with refs and download URLs, replyTo, and the sanitized HTML caveat. For a read tool with rich attachment and security behavior, this is complete enough for an agent to invoke and interpret results 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?

The input schema already documents both parameters with 100% coverage: uid comes from list_emails and mailbox defaults to INBOX. The description does not add new parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate because the schema fully handles parameter meaning.

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

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

The description states a specific action and resource: 'Read one message in full, including its body and recipients.' It also distinguishes itself from list/search tools by emphasizing 'one message' and from mark_read by explicitly saying reading does NOT mark as read. This separates it clearly from read_thread and list_emails 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 gives clear context for when this tool is needed: to see full body, recipients, attachments, replyTo, or sanitized HTML. It notes that it does not mark messages read, which prevents confusion with mark_read. It does not explicitly compare against read_thread or list_emails, so a small gap remains, but the implied usage is strong.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that reading does not mark anything as read, that quoted copies are trimmed unless includeQuoted is set, that bodies are plain text only, and that thread completeness depends on the References header. These are valuable behavioral details not present in 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 long but every sentence carries a distinct operational concern: one-call efficiency, alternative tool routing, default mailbox scope, no-read side effect, quote trimming, plain-text limitation, and thread completeness caveat. The core action is front-loaded and the structure is dense without being redundant.

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

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

Given that there is no output schema, the description compensates by explaining the important return behaviors: oldest-first ordering, quotedTrimmed flag, plain-text bodies, and the possibility of a shortened thread. Combined with the annotations and fully documented parameters, it gives an agent enough to invoke the tool and interpret results 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?

The schema already covers 100% of parameters, so the baseline is 3, but the description adds useful nuance: the UID can be any message in the conversation, mailboxes defaults to the message's folder plus Sent, naming mailboxes replaces that default, and includeQuoted can multiply result size. This is meaningful enrichment 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 states a specific verb and resource: 'Read an entire email conversation in ONE call, oldest message first, given any one message in it.' It clearly distinguishes itself from read_email and search_emails by emphasizing the whole-thread scope and the one-call behavior.

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 tells the agent when to prefer this tool: 'USE THIS INSTEAD OF CALLING read_email REPEATEDLY' and gives a concrete user-intent example ('catch me up on this thread'). It also names the fallback case: use read_email when HTML or a full untrimmed body is needed, and warns about incomplete threads when the References header is absent.

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

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

Beyond the annotations' destructiveHint and readOnlyHint, it discloses that messages and subfolders move with the folder, that the result lists moved children, and the precise refusal behaviors with their rationale. This gives the agent exactly the operational knowledge annotations cannot convey.

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

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

The description is long, but nearly every sentence carries a distinct operational warning or clarification. It is front-loaded with the core purpose, and the warnings are grouped logically. Slightly verbose, but not padded.

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

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

For a destructive folder operation with no output schema, the description covers what moves, what refuses to rename, how to read the refusal, and what the result will show. An agent has enough to invoke it correctly and safely.

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 description adds extra meaning by clarifying that parent preserves the leaf name and that '/' in newName creates a hierarchy ('Archive/Projects' nests under Archive). It does not add much beyond the schema's property descriptions, hence not 5.

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

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

The description names the exact operation ('Rename a folder, or move it under a different parent'), explains the IMAP path semantics, and the refusal list clearly differentiates it from creating or deleting folders. It is unambiguous against sibling tools like create_folder and delete_folder.

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

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

It gives clear conditions for the parent-based reparenting path and explicitly lists special folders that will be refused, as well as duplicate names. It stops short of naming alternatives like create_folder, delete_folder, or move_email, so it earns a 4 rather than a 5.

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

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

Annotations mark destructiveHint=true, and the description goes well beyond that by explicitly warning "This delivers real mail to real people and cannot be undone." It also surfaces the Reply-To refusal behavior, the quoting and Sent-copy mechanics, and the fact that recipients never include the mailbox itself. For a destructive, open-world, non-idempotent tool, this is exemplary transparency.

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

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

The description is long, but it is almost entirely high-value for a real-mail side-effecting tool. The opening sentence carries the core purpose, and the attachment section and read-receipt warning earn their length by preventing irreversible mis-sends. A couple of parentheticals are slightly over-explained, but nothing is 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?

For an 11-parameter, destructive, real-mail tool with no output schema, the description covers the critical behaviors: recipient resolution, Reply-To refusal, quoting, HTML safety, attachment strategies with size limits, plain-text consequences, and read-receipt caveats. The only thing not spelled out is the exact success/error response shape, which is acceptable because there is no output schema and the tool's side effects are the real outcome.

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%, but the description adds essential meaning beyond the raw property comments. It tells agents which attachment strategy to prefer (fileRef over url over content), warns that `content` costs ~450k tokens per MB, explains that `uploadId` requires no check_upload call, and clarifies that html is sent literally with no escaping. This is the kind of pragmatic guidance that prevents costly mistakes.

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 — "Reply to a message" — and then thoroughly distinguishes itself from forward_email, draft_reply, and send_email by specifying the threading, quoting, Sent copy, and answered-flag behavior. The first sentence alone tells an agent exactly what this tool is for, and the body makes the distinction from siblings 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 description gives explicit when-to-use and how-to-proceed rules: recipients come from Reply-To or From; use `cc` for additional people; use `all` for reply-all; and it even explains the refusal flow involving `confirmReplyTo`. It does not explicitly name sibling tools like forward_email or draft_reply as alternatives, but the threading/quotation/Sent/answered behaviors create clear boundaries against those siblings, which is substantial 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?

Annotations (readOnlyHint, openWorldHint, idempotentHint) already establish safety, so the description's job is to add behavior, and it does so extensively: substring matching semantics with a concrete false-positive example, delivery-date (not Date: header) matching with whole-day precision, explicit cap disclosure with true match totals, and the warning that UIDs are only meaningful within their folder. These are exactly the failure modes an agent would otherwise discover by making mistakes.

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?

Longer than average, but every sentence carries operational weight — there is no filler. The structure is logical: purpose and output contract first, then the cross-folder guidance, then matching gotchas, then cap behavior. The caps-lock sentence is an intentional emphasis device for the single most cost-relevant behavior. It earns its length given the density of non-obvious semantics.

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

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

With no output schema, the description correctly carries the return-shape burden via a reference to sibling list_emails, and covers ordering, cap disclosure, and the empty-search refusal. The boolean filters (seen/flagged/answered) are left to the schema, which describes them adequately. A minor gap is that criteria combination semantics (AND vs OR) is never stated, which an agent might guess wrong with multiple criteria.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds genuine collective meaning: it unifies the substring-matching rule across from/to/cc/subject/body/text and the delivery-date rule across since/before/on, which the individual schema entries don't convey as an integrated semantic. The mailboxes one-call-cost point is also reinforced in prose. The only thing not added is how multiple criteria combine (AND vs OR), but the description clearly lifts above the schema 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 opens with a specific verb and resource — 'Search one or more IMAP folders and return summaries' — and precisely defines the output contract: the shape list_emails returns, plus the folder each result was found in, newest first, not message bodies. It explicitly names read_email as the alternative for full message bodies, making sibling differentiation immediate.

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

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

Explicit routing guidance is present: read_email is named as the tool for reading one message in full, and list_mailboxes (in the schema) is named for unknown folder names. The SHOUTED instruction to search every candidate folder in one call, with the concrete 'where is that email from Bob' example covering INBOX/Archive/Sent, gives the agent a direct decision rule tied to user intent. It also states the empty-search refusal behavior.

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 tool as destructive, but the description adds valuable real-world context: this sends real email to real people and cannot be undone. That goes beyond the bare destructiveHint and helps the agent weigh confirmation and user intent before invoking.

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

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

Two tight sentences front-load the core action and the most important consequence. No filler or repetition, and 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 an irreversible, high-stakes send action, the description gives the essential warning and the schema provides deep detail on attachments, HTML handling, read receipts, and sending constraints. The main missing piece is any mention of the return value or how to follow up on a sent message, but the rich schema largely compensates.

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 about 78%, so the input schema already documents most parameters thoroughly. The top-level description only adds a generic mention of attachments and does not meaningfully explain parameters beyond what the schema provides, making 3 the appropriate 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 states a specific action ('Send a new email'), the resource ('from the connected mailbox'), and the key consequence ('delivers real mail to real people and cannot be undone'). The word 'new' distinguishes it from reply/forward tools, and 'real mail' separates it from draft_email.

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 this is the tool for actually sending mail rather than drafting, and the irreversibility warns the agent to be careful. However, it never explicitly says when to prefer draft_email or how this differs from reply_email/forward_email, so the guidance is mostly inferred rather than stated.

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

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

The annotations already cover idempotence, non-destructiveness, and read/write behavior. The description adds the state-transition framing ('restoring their unflagged state') and the batch-call behavior, but it does not provide much additional behavioral detail such as how invalid UIDs or un-flagged messages are handled. It does not contradict 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 short, purposeful sentences with no filler. The core operation is stated first, and the important one-call batching instruction is provided second. 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 simple flag mutation with a fully documented schema and supporting annotations, the description is complete enough for an agent to invoke the tool correctly. It explains the operation and the key batching requirement, while the schema covers parameter details and limits. No critical information is missing given the tool's low complexity.

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 top-level description mostly repeats the batching advice that is already fully documented in the uids parameter description. It does not meaningfully add to the schema's parameter explanations.

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 ('Clear') and a clear resource/state ('flag/star marker on messages, restoring their unflagged state'). This makes the tool's purpose unambiguous and clearly distinguishes it from sibling tools like flag_email or delete_email.

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 communicates when to use the tool: whenever messages need to be unflagged. It also gives practical usage guidance by instructing the agent to pass the whole set in one call. It does not explicitly name flag_email as the counterpart, but the context and tool names make that evident.

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 description goes well beyond the annotations. It discloses that the UID changes after editing, that old UIDs stop working, that threading headers/attachments are preserved, that nothing is sent, and that incomplete fields are removed from the draft. These are exactly the behavioral traits an agent needs to know before calling a destructive update 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?

The description is dense but front-loaded: it states the action, the usage trigger, the replacement semantics, the side effects, and the safety guarantee in a tight sequence. A few capitalized reminders inside the schema carry the bulk of the maintenance, keeping the main description readable.

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 tells the agent everything critical: what is replaced, what survives, what changes (UID), and what does not happen (nothing sent). Given the 11-parameter schema with rich per-parameter docs and the required fields, nothing essential for a correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents every parameter. The description still adds high-value semantic warnings: 'anything you leave out is gone from the draft', the UID-change consequence, and carried-over attachments. It doesn't need to restate the schema, but it clarifies the whole-message replacement semantics that the schema alone does not emphasize.

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 ('Rewrite a draft that is already in the Drafts folder') and immediately distinguishes the operation from deleting and re-saving. It clearly names the resource (a saved draft) and lists concrete triggers (different wording, another recipient, corrected subject), so an agent can identify it accurately.

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 'Use this whenever the user wants a draft changed', frames the mutation as in-place replacement, and gives practical warnings about passing the full new version of every field. It also names sibling alternatives like draft_reply implicitly through 'a draft made by draft_reply' and explains what carries over, giving clear context for when to edit vs recreate.

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