Mailbox MCP

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

Beyond the annotations, the description discloses that a missing archive folder is created and subscribed, that already-archived messages are refused, that flags and dates are preserved, and that the reply identifies the folder and new UIDs. This gives the agent a complete behavioral model beyond readOnly/destructive hints.

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

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

The description is long but appropriately so for a tool with non-obvious semantics. It front-loads the core purpose and the critical move_email distinction, then adds necessary caveats about folder creation, refusals, preservation, and batching without digressing.

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 no output schema, the description explains what the reply contains, including the folder used and new UIDs. It also covers failure modes, provider differences, creation behavior, and constraints. Nothing essential for calling the tool 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 coverage is already 100%, but the description adds substantial practical semantics: all UIDs must belong to the same source folder, every UID should be passed in one call, and the mailbox parameter defaults to INBOX. This transforms schema-level fields into actionable usage guidance.

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

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

The description states a specific verb and resource: it archives messages into the mailbox's own Archive role folder, distinguishing it clearly from move_email. It also explains what archiving means across providers, so the tool's purpose is unambiguous.

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

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

The description explicitly instructs using this tool rather than move_email for archiving, explains why move_email is the wrong choice, and redirects to move_email when the user wants messages moved elsewhere. It also covers edge cases like messages already archived and requirements like same source folder and one-call batching.

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 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 only encode readOnly=false, openWorld=true, idempotent=true, destructive=false. The description goes further by disclosing the verification behavior (flags are read back and per-message failures are named), the folder-scoped meaning of uids, idempotency behavior for already-flagged messages, and the lack of read/move/delete side effects. It also flags unflag_email as the more dangerous counterpart, making the safety profile clearer.

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 every sentence carries a distinct purpose: definition, safety scope, batch usage, verification/failure reporting, uid scoping, idempotency, and sibling comparison. It is front-loaded with the core meaning and uses punctuation to keep related concepts tightly grouped.

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 only two parameters, no output schema, and the mutating-but-idempotent behavior, the description covers the essential contexts an agent needs: what the flag represents, what side effects do not occur, how batch calls should be made, how to scope uids to folders, how failures are surfaced, and how it relates to unflag_email. Nothing material is left for the agent to guess.

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 real value beyond the schema by explaining that uids are only meaningful in the folder they came from and that mailbox must be supplied when they did not originate from INBOX. The 'pass the whole set in ONE call' guidance reinforces the uids schema, though some of it repeats the schema's own description.

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

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

Description opens with a specific verb and object ('Flag messages') and defines the exact semantic: a star/flag marker matching Outlook/webmail and the state search_emails's flagged filter reads. It also distances itself from sibling operations by saying it does not move, read, or otherwise change messages, so an agent can reliably distinguish it from mark_read, archive_email, move_email, and 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?

Gives explicit operational guidance: pass the whole set in one call, supply mailbox when uids did not come from INBOX, and expect no error when flagging an already-flagged message. It names the direct alternative unflag_email for clearing, and clarifies that this tool does not mark anything read, steering selection away from mark_read-like use cases.

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?

Beyond the read-only, open-world, and idempotent annotations, the description discloses preview behavior, the ~200-character nature, null cases for empty or image-only bodies, and that previews are not the full message. It even warns that preview text comes from other people and must be treated as data, not instructions. This adds substantial protection and behavioral clarity.

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 longer than average, every sentence earns its place: scope, preview purpose, read_email boundary, null behavior, and security caveat. It is front-loaded with the core result definition and remains structured and 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?

With no output schema, the description still explains the essential return element, preview, and how to interpret it. Combined with fully described parameters and safety annotations, the agent has everything it needs to select and invoke the tool correctly.

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

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

The input schema already covers both parameters fully, including defaults and constraints for limit and mailbox. The description does not need to restate them and adds no parameter-specific semantics beyond the schema. 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 states a specific verb and resource: it lists the most recent messages in a mailbox, newest first. It also distinguishes itself from read_email by clarifying that list_emails returns previews, not full message content. The scope and function are immediately clear and cannot be confused with the sibling tools.

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

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

The description gives explicit when-to-use guidance: use the preview to triage incoming mail instead of reading every message. It also names the alternative, read_email, and specifies the exact conditions for switching to it (full content, recipients, attachments). This is exemplary routing 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?

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?

Beyond the destructiveHint annotation, the description discloses substantial behavioral detail: the junk folder is resolved by server role rather than name, a missing junk folder is created and subscribed, already-junk messages are refused, flags and original dates are preserved, and the operation teaches the spam filter. This goes well beyond the annotation surface.

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?

Every sentence carries substantive information about behavior, constraints, or edge cases. The description is long but dense and front-loaded with the core action, and the additional paragraphs explain exactly the exceptional behaviors an agent needs to anticipate.

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 state-changing mail operation with no output schema, this description covers the action, side effects, folder resolution, folder creation, refusal condition, preservation guarantees, reversibility, and batching rule. It is remarkably complete for safe invocation and expectation-setting.

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 uids and mailbox with 100% coverage, so the baseline is 3. The description adds meaningful operational constraints beyond the schema, notably that all messages must be in the same source folder and that UIDs should be passed together in one call. This pushes it above baseline, though some of this guidance is also echoed in 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 opens with a specific action on a specific resource: 'Move messages into the junk folder.' It immediately ties this to the familiar 'report spam' concept and explicitly names the reverse operation, not_junk, which distinguishes it from sibling tools. This is a clear, unambiguous purpose statement.

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 strong operational guidance: use not_junk to reverse, pass all UIDs in one call, and ensure messages are in the same source folder. It does not explicitly compare against move_email or archive_email, so the when-not-to-use guidance is not fully exhaustive, but the intended usage context is very clear.

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

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

The description adds substantial behavioral context beyond the annotations: the deliberate no-read side effect of read_email, verified read-back rather than assumed success, partial batch failure with individually named messages, and idempotent behavior for already-read messages. These details are crucial for an agent to reason about side effects and outcome reliability, and they do 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?

The description is long but every sentence earns its place: purpose, intentional read behavior, batching, verification, folder scoping, idempotency, and undo. It is front-loaded with the core purpose and then layers caveats in a logical order with no fluff or redundant 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 two-parameter mutation with no output schema, the description covers all essential operational context: when to use it, how to batch uids, how to handle non-INBOX mailboxes, partial-failure possibilities, and idempotency. An agent can confidently select and invoke the tool correctly without needing additional information.

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 schema already documents both parameters thoroughly. The description adds genuine beyond-schema semantics by explaining that a UID only means something in the folder it came from, so mailbox must be passed for non-INBOX uids. It also reinforces the single-call batching guidance, but the uids semantics mostly mirror the schema, which is why this is a 4 rather than a 5.

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

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

The description opens with a clear specific verb-resource statement: 'Mark messages as read.' It distinguishes itself from read_email and mark_unread by explaining that reading through the connector deliberately does NOT mark read, and naming mark_unread as the undo. There is no ambiguity about what this tool does or how it differs from its siblings.

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

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

It explicitly states when to invoke the tool: when the person asks for it, never because you have looked at something. It instructs passing every message in ONE call and warns about the common mailbox pitfall when uids did not come from INBOX. It also names mark_unread as the undo, giving clear alternative and exclusion 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 indicate readOnlyHint=false, idempotentHint=true, openWorldHint=true; description goes well beyond them: it explains verification behavior by reading flags back off the server, names failure behavior (a message that could not be changed is named), says already-unread messages change nothing without error, and confirms non-interference with other message states. It does not annotate response structure, but no output schema exists and the added behavioral detail is substantial.

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 efficient and front-loaded: the core purpose appears in the first sentence, and operational guidance follows in short, focused sentences. It is slightly long, but nearly every sentence earns its place by addressing a concrete decision or expectation. No fluff, no repetition of schema basics.

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

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

For a mutating tool with no output schema, the description covers the essential operational contract: intended result, batching, mailbox scoping, idempotency, failure verification, and non-interference. It does not state the return type or exact response fields, but the tool's verification semantics are explained. Given sibling context, the description is one of the strongest in the set.

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 both parameters have schema descriptions. The description still adds meaning: it explains why to pass the whole set in one call, the 500 limit implication, mailbox's role when uids did not come from INBOX, and that a one-element array is valid for a single message. This is meaningful semantic 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?

Description states a specific verb and resource: 'Mark messages as unread', then immediately clarifies the intended state restoration semantics. It explicitly distinguishes itself from mark_read by framing this as the undo operation. The title also aligns, making the purpose unmistakable.

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

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

The description explicitly says this is the undo for mark_read and 'the one to reach for when a triage pass marked more than the person meant'. It also tells the agent to pass the whole set in ONE call and to pass mailbox when uids did not come from INBOX, with clear guidance for already-unread messages. This is direct usage guidance and scenario-based routing.

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

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

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

Beyond the annotations, it discloses important behavioral details: there is no source folder parameter because the tool always reads from the junk folder, it refuses a `to` pointing at the junk folder, it refuses mailboxes without a junk folder instead of creating one, and it preserves flags and original dates. This gives the agent a clear model of what will and will not happen.

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 every sentence carries operational meaning, and the most important constraint (no source folder) is front-loaded. Some repetition exists in explaining that the tool only acts on the junk folder, but the emphasis is useful rather than pure padding.

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

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

For a two-parameter action tool with no output schema and destructive annotations, this description is highly complete. It covers how to obtain IDs, the meaning of those IDs, destination behavior, error/refusal cases, preservation of message properties, and batching expectations. No critical operational detail needed to invoke the tool 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 coverage is 100%, so the schema already documents both parameters. The description adds meaningful extras: UIDs are folder-scoped and only meaningful in the folder they came from, `to` defaults to INBOX, and `to` cannot be the junk folder. It reinforces but does not merely repeat the schema's batching guidance.

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

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

The description uses a specific verb and resource: 'Take messages back out of the junk folder and return them to the inbox.' It also explicitly frames the tool as what 'not spam' does and the reverse of mark_junk, which distinguishes it clearly from the sibling tool that performs the inverse operation.

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 strong usage context: get UIDs from list_emails or search_emails against the junk folder, pass every UID in one call, and use `to` to redirect elsewhere. It names mark_junk as the inverse concept, but it does not explicitly name move_email as the alternative for moving from non-junk folders, so an explicit exclusion for a sibling tool is missing.

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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses substantial behavior: substring vs exact matching, delivery-date semantics, whole-day date precision, per-result mailbox/UID caveats, result capping with true total reporting, and refusal of empty searches. This goes far beyond what annotations alone convey and sets accurate expectations for the agent.

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

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

The description is long but every sentence carries high-value information: purpose, return shape, non-body warning, multi-folder call strategy, UID caveat, required-criterion rule, substring warning, date semantics, and truncation behavior. It is front-loaded with the core purpose and then layers warnings in a logical order. There is minimal 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?

With no output schema present, the description explains the return shape in enough detail: summaries like list_emails plus a mailbox field, preview text, newest-first ordering, and explicit truncation signaling. It covers matching semantics, date semantics, required criteria, folder handling, and actionability of results via the mailbox field. The tool is exceptionally well specified for an agent to call correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds crucial semantic detail beyond the schema: from/to/cc/subject/body/text are substring matches rather than exact matches, date params are based on mailbox delivery time rather than the sender's Date header at whole-day precision, and mailboxes can be batched into one call. These clarifications directly prevent common misuse.

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: searching one or more IMAP folders and returning summaries, not full bodies. It also distinguishes itself from read_email by explicitly saying that tool is for reading a single message in full, and references list_emails' shape as a frame of reference. An agent can immediately understand what this tool does and how it differs from key siblings.

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

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

The description gives explicit when-to-use guidance: search can usually answer a question without a follow-up read_email, and read_email is the alternative for full message bodies. It also instructs agents to search every plausible folder in one call, warns that an empty search is refused, and references list_mailboxes for unknown folder names via the schema. This is strong, actionable routing guidance.

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

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

Goes far beyond the destructiveHint annotation by exposing non-obvious behaviors: dual plain-text/HTML construction, signature duplication risk, sent-folder filing failure that can accompany a successful send, partial recipient rejection, identity requirements, and the 10 MB whole-message cap. These are critical for correct agent behavior.

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

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

Front-loaded and dense with material warnings, but it is a long all-caps-heavy block that could be restructured for quicker scanning. Every sentence carries risk-relevant meaning, so the length is mostly justified.

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 high-stakes irreversible send with no output schema, the description explains the important return behaviors — sent-folder filing result, rejected recipients, partial success — along with identity, attachment, and formatting caveats. Combined with the rich input schema, an agent has everything needed 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 already describes most parameters in detail, so the baseline is solid. The description adds useful cross-parameter behavior such as plainTextOnly's role, the list_identities prerequisite for the from field, and the whole-message attachment total, while leaving self-evident parameters like subject and cc to their names.

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

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

States a concrete action — send a new email from the connected mailbox — and clearly identifies the resource and scope. The phrase 'delivers real mail to real people and cannot be undone' distinguishes it from draft-style siblings and makes the side-effectful nature 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?

Clearly positions the tool as the final, irreversible send action, warning against manual signatures and describing partial-failure reporting. It gives rich when-to-use guidance inside parameters, though it does not explicitly name alternatives such as draft_email for non-final composition.

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, the description discloses irreversibility of the user's flag decision, verification by reading flags back from the server, mailbox-scoped uid semantics, and idempotent behavior when clearing an already-cleared flag. The warning that 'there is nothing to restore it from except their memory' adds meaningful behavioral context that annotations do not capture. No contradiction with annotations is apparent; destructiveHint false likely refers to not destroying the message content, while the description responsibly explains the state change.

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 each sentence serves a purpose: scoping, caution, verification behavior, mailbox semantics, and idempotency. The key warning is front-loaded and emphasized. No filler or redundant restatement of the schema 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?

Even without an output schema, the description explains how results are verified and that failures are reported by message name. All parameters and special cases are covered, including vague requests, one-call batching, mailbox meaning, and the no-op case. The description is fully sufficient for an agent to invoke the tool correctly in 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%, so the schema already documents both parameters well. The description adds important cross-parameter semantics: the whole set must be passed in one call, uids are tied to the folder they came from, and mailbox must be supplied when uids did not originate from INBOX. This goes beyond the schema's basic descriptions.

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

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

The description opens with a specific verb and resource: 'Clear the flag/star marker on messages, restoring their unflagged state.' This clearly distinguishes it from the sibling flag_email and mark_unread tools. The title and description align, and there is no ambiguity about what operation is performed.

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-to-use guidance: pass the whole set in one call, clear only the messages the user asked about, and check the set if the request was vague. It also directly contrasts the tool's caution level with mark_unread, and explains mailbox handling for uids not from INBOX. This is strong, actionable routing and scoping 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?

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.