Mailbox MCP

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

Annotations already flag destructive/openWorld/non-idempotent, but the description adds substantial context beyond them: exact fidelity of the send (same recipients, subject, text, attachments, threading onto the conversation), the once-only Sent filing, removal from Drafts, and the fact that this delivers real irreversible mail. This is the kind of disclosure an agent needs before calling a mutating tool.

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-loads the core action, then preconditions, then refusals, then the irreversibility warning. Four sentences, nearly all earning their place, though the 'as any mail client does' clause and the refusal enumeration push it slightly past the minimum needed.

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 one-parameter mutating tool with no output schema, the description covers action, preconditions, failure modes and irreversibility fully. Nothing an agent needs to invoke it 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% and the single parameter already documents its source (list_pending_approvals), so the schema does the work. The description explains the draft's contents but adds no parsing or format detail about the uid itself; baseline 3 applies.

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

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

States a precise verb+resource ('Send a draft that a colleague marked with request_approval') and immediately differentiates itself from siblings like send_email and request_approval by scoping to already-approved drafts. An agent can tell exactly which operation this is without opening the schema.

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

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

Explicitly routes the agent: 'Read it first with read_email on the Drafts folder,' and the uid comes from list_pending_approvals. It also enumerates the when-not cases (not_pending, missing requester record, Bcc/Reply-To present) and notes each refusal explains remediation.

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 destructiveHint:true, but the description explicitly says messages go 'out of the inbox but not deleted,' preserves flags and dates, and returns new UIDs so messages can be put back. This directly contradicts the destructive hint, so an agent cannot reliably know whether this operation is safe or destructive.

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, covering core behavior, the move_email distinction, folder creation, refusal behavior, preservation guarantees, batching, and response contents. It is front-loaded with the most important operational facts and has no filler.

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

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

With no output schema, the description still explains what the reply contains (folder actually used and new UIDs), side effects (folder creation and subscription), refusal cases, and cross-parameter constraints. An agent can invoke this tool correctly and communicate the outcome, including the possibility of a newly appearing folder.

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 in detail with high coverage, so the baseline is 3. The description adds a meaningful constraint beyond the schema: all messages must come from the same source folder, and it reinforces that every UID should be passed in a single call.

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 ('Archive messages') and explains exactly what archiving means: filing messages where the mailbox's own Archive button files them, out of the inbox but not deleted. It also clearly distinguishes itself from move_email by explaining that the archive is a server-assigned role, not a folder name.

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 RATHER THAN move_email FOR ARCHIVING' and explains why move_email with a folder named 'Archive' can be wrong. It also states when to use move_email instead, and gives batch and same-source-folder requirements, leaving no ambiguity about when this tool should be selected.

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?

Far beyond the annotations: it states the message is not moved, not marked read, and appears unchanged in Outlook, discloses that assignment takes over an existing claim and reports whose claim was replaced, describes the 'someone' degraded-claim state, and explains downstream warnings in reply/forward/draft tools. No contradiction with readOnlyHint=false/idempotentHint=true/destructiveHint=false.

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

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

Purpose and the claim concept are front-loaded, and most sentences carry non-obvious behavior. It is dense and long for a 3-parameter tool, with slight redundancy ('It moves nothing and marks nothing read: the message stays exactly where it is'), but little is truly disposable.

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

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

No output schema exists, so the description must carry results and edge cases — and it does: it specifies what the result reports (whose claim was replaced), the ambiguity failure mode, the orphaned-claim state, and the visibility of the marker in other tools. An agent can call this correctly with no further 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 baseline is 3, but the description adds real meaning for `person` (email address, or a name as the owner entered it, with ambiguity refusal semantics). It also references a `force: true` argument that does not appear in the input schema, which is mildly confusing but signals behavior rather than mislabeling a documented param.

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

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

The description states a precise verb and resource — 'Hand messages to a named person on this mailbox' — and defines what 'assigned' means (a claim marker the mail server keeps). It clearly differentiates this from sibling operations like list_emails/search_emails/reply_email by describing how those tools surface the heldBy state.

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?

Strong contextual guidance: it says to ask the user and re-call when a name is ambiguous or matches nobody, explains when `force: true` is needed (orphaned marker after a client move), and restricts who can be assigned to (owner plus active people). It never names a sibling that should be used instead in a given situation, so it stops short of a 5.

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

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

The description adds substantial behavioral context beyond the annotations: bounces arrive as separate messages after the send tool reports success, it scans INBOX and Junk by default, and results distinguish permanent vs. temporary failures with implications for resending. This is far more than the readOnly/idempotent hints already 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 earns its place: purpose, timing, default behavior, result interpretation, user-facing obligation, and sibling routing. It is front-loaded with the core purpose and then layers in actionable guidance without redundancy.

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

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

For a read-only tool with no output schema, the description is remarkably complete. It explains when to use it, what it scans, what the results mean, how to interpret permanent vs. temporary failures, and how to combine it with check_receipts. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters with defaults and examples. The description reinforces the defaults and explains why Junk is scanned, but it does not add significant new parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Find messages that came back undelivered.' It clearly distinguishes this tool from check_receipts by stating that this tool only finds failures, while check_receipts covers the positive delivery/read side.

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

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

Explicit usage guidance is provided: 'USE THIS AFTER SENDING ANYTHING IMPORTANT, and whenever the user asks whether a message arrived.' It also gives a clear exclusion: if the user asks whether a message arrived rather than failed, call check_receipts as well. This is model behavior for routing an agent to the correct sibling.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the description builds on that. It adds crucial interpretation guidance: read the `note` on each result, DMARC p=none passes checks but does nothing, DKIM may be published under an unknown selector, and 'FAILED' does not mean 'missing'. This goes far beyond what annotations provide and prevents common misinterpretations.

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 well-structured: purpose first, then when to use, then critical caveats and interpretation rules. Every sentence adds value; there is no fluff. The critical warning about reading notes and interpreting FAILED vs missing is front-loaded within the paragraph, making it hard to miss.

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 has no parameters and no output schema, the description fully equips the agent to use it correctly. It explains what the tool does, when to use it, and how to interpret results (the note field, DMARC p=none, DKIM selector issues, and the FAILED/missing distinction). The annotations cover safety, so the description is complete for a zero-argument 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?

The tool has zero parameters, so the schema is trivially complete. The description states 'It takes no arguments', which is redundant but reinforces the schema. Since there are no parameters to explain, the baseline for 0-param tools is 4, and the description doesn't need to add anything more.

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 checks DNS records (SPF, DKIM, DMARC, MX) for the connected mailbox's own domain, which is a specific verb and resource. It distinguishes itself from all siblings (none are deliverability-related), so there's no ambiguity about what it does.

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

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

It explicitly lists when to use it: when the user asks why mail goes to spam, why a recipient didn't get something, or whether the domain is set up properly. It also clarifies a key limitation: it cannot look up anyone else's domain. This gives clear guidance on when and when not to use it.

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

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

The description thoroughly explains the meaning of missing receipts, the conditions under which read receipts exist, and the semantics of a 'deleted' status. This goes well beyond the readOnlyHint annotation and provides critical 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 well structured, starting with purpose, then usage, then caveats. It is somewhat lengthy, but every sentence carries important operational nuance, so the verbosity is 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?

The description covers the conceptual output and edge cases, but since there is no output schema, it does not explicitly enumerate the returned fields or format. This leaves a small gap, though the mention of statuses like 'deleted' gives some indication.

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 already covers all parameters at 100%, and the description adds valuable context for messageId by referencing send results and explaining the default behavior when omitted. Days and mailboxes are well covered by schema descriptions, though the tool description does not add much beyond that.

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

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

The description clearly states the tool's purpose: finding delivery and read confirmations for sent messages. It distinguishes between the two receipt types and differentiates this tool from related siblings like check_bounces and list_emails.

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

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

Explicit guidance is given for when to use the tool: after sending something important or when the user asks whether a message arrived. It also explains when not to expect results, noting that receipts must have been requested at send time and cannot be requested retroactively.

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 (readOnly, idempotent, non-destructive), the description explains the tool returns fileRefs for each file, reports emptiness as a normal state rather than an error, and clarifies that the draft folder is auto-removed. 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 somewhat wordy but every sentence serves a purpose: it explains the return value, the correct call timing, how to handle an empty result, and the lifecycle of the draft folder. It is well-structured and not 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?

Without an output schema, the description covers expected output (fileRefs), the edge case of no files yet, and the draft folder's automatic removal. This gives an agent all necessary context to call the tool correctly and interpret results.

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

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

The only parameter uploadId is fully described in the schema as 'The uploadId from create_upload_link.' Since schema coverage is 100%, the description adds no additional meaning beyond what is already provided, so baseline 3 applies.

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

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

The description clearly states the tool's purpose: to look for files uploaded via an upload link and return fileRefs for each, which distinguishes it from sibling check tools like check_bounces or check_deliverability.

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

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

Provides explicit when-to-use guidance: call after create_upload_link, either immediately after self-upload or after the user confirms. It also advises not to poll repeatedly and what to tell the user when no files have arrived yet, plus a warning about not offering deletion of the temporary draft folder.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) by explaining what a claim actually is (a server-side marker), that nothing moves or is marked read, that Outlook users see no difference, what happens to a stale marker after a client-side move, and how force behaves. That is unusually rich behavioral disclosure. Minor gap: no mention of failure modes such as a missing uid or mailbox-level auth requirements.

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

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

Front-loads the core purpose in the first sentence, then layers behavior, edge cases, and alternatives in a logical order. It is longer than typical, and a couple of sentences (the Outlook-visibility aside) are close to optional, but every sentence carries information an agent could act on.

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

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

With no output schema, the description compensates by describing return behavior ('the result names them', 'the result says whose claim was taken'). Combined with force semantics, idempotency, and sibling routing, an agent has everything needed to call this correctly and interpret the 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%, so the baseline is 3, but the description adds meaning the schema does not: it clarifies the takeover semantics of force (the result names whose claim was taken) and the 'someone' edge case for stale claims, plus the conflict-resolution flow. It leaves mailbox semantics to the schema, which is reasonable.

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 precise verb (claim) on a specific resource (emails/messages) and clearly frames it as a shared-mailbox coordination marker. It distinguishes itself from siblings by naming release_email and assign_email as the follow-up alternatives, so an agent can place it in the workflow without opening any schema.

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

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

Explicit when-to-use ('so colleagues... know you are dealing with it'), explicit when-to-release and when-to-hand-off (release_email, assign_email), and explicit guidance on the optional force flag ('Leave it out unless the user has said to'). Alternatives and exclusions are both 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 far beyond the annotations. It discloses that the folder is automatically subscribed, that '/' builds hierarchy rather than appearing literally, that the operation is idempotent with case-insensitive matching, that the reply indicates whether something was created, and that blank path segments are refused. This is exactly the kind of behavioral context an agent needs.

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. It front-loads the core purpose, then covers hierarchy, idempotency, parent constraints, and validation rules in a logical order. The length is justified by the number of non-obvious behaviors an agent must know to call the tool correctly.

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?

Despite having no output schema, the description tells the agent what the reply indicates ('whether it actually created anything'), covers error conditions (blank segments), explains idempotency, and clarifies the relationship with list_mailboxes via selectable: false. The tool is fully specified for correct invocation.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema. It explains the literal-slash prohibition, the case-insensitive matching behavior, the parent parameter's role with non-selectable folders, and the refusal of blank segments. This transforms the parameters from simple strings into well-understood inputs.

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: 'Create an IMAP folder.' It clearly distinguishes this from sibling tools like delete_folder and rename_folder by focusing on creation semantics, and adds concrete details about namespace rules and subscription behavior that make the tool's 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 gives strong contextual guidance: it explains when to use the parent parameter, how slash-based hierarchy works, and that creating under a non-selectable parent is the intended way to make it a real folder. It does not explicitly name alternatives or say 'use this instead of X,' but the sibling list and clear creation focus make the intended use obvious.

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

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

Annotations only cover safety flags (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description carries the real behavioral burden and does so well: files land in Drafts, check_upload yields a fileRef per file, the holding draft self-cleans and must not be offered for deletion, the link needs no sign-in and accepts multiple files, and sandbox network failures must not be retried with a fallback to `content`. This is exactly the extra context annotations cannot supply.

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

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

Longer than typical, but front-loaded with the purpose and then ordered by decision (mode choice, injection guardrail, sandbox caveat, follow-up call). Nearly every sentence is safety- or workflow-critical, though the emphatic capitalization and some restatement make it feel denser than strictly necessary.

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 tool with no output schema, the description fully closes the loop: it explains where files land, how they become attachable (fileRef via check_upload), what to do the person-side, and the failure mode to expect. Nothing an agent needs to invoke and follow up 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?

Zero parameters, so the baseline of 4 applies; there is no schema to contradict or compensate for. The description usefully documents the non-parameter syntax the agent must construct (the `?filename=` query on the uploadUrl), which is arguably the only parameter-like semantic in play.

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

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

States a specific verb and resource: produce a one-off upload link that puts files into this mailbox. It explicitly distinguishes itself from siblings, naming read_email and the URL-as-attachment path as the cases this tool is NOT for, so an agent can route correctly without opening other schemas.

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 when-to-use (file not in mailbox and not reachable by URL, typically a file on the person's own computer) and when-not-to-use (already in mailbox → read_email's ref; has a web address → pass as attachment url). It also tells the agent how to choose between the two link modes and mandates calling check_upload afterwards.

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 recoverability, same-folder requirement, refusal on already-trashed messages, and single-operation batching. This gives a solid behavioral picture, though some edge-case details (e.g., error behavior) are absent, so it falls short of a perfect 5.

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

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

The description is concise yet comprehensive, with each sentence serving a purpose—behavior, constraint, batch instruction, and parameter clarification. No fluff or redundancy; it is well-structured for easy parsing.

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

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

Given the absence of an output schema, the description fully covers what the tool does, its constraints, and how to invoke it correctly. It answers likely questions (what happens to messages, what if already in trash, how many UIDs) without needing extra 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?

The schema covers both parameters with descriptive comments (100% coverage), and the description adds meaningful context about batching and the one-element array for a single message. Since the schema already provides high coverage, the extra description elevates it above baseline but not to the top tier.

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

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

Clearly states the tool moves messages to the Trash folder, with an explicit analogy to clicking Delete in Outlook. It also distinguishes itself from permanent deletion, making its purpose unambiguous relative to siblings like move_email or 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?

Provides explicit usage and prohibition guidance: refuses to run on messages already in Trash (because permanent deletion is a separate operation) and instructs to pass all UIDs in one call. This leaves no doubt about when and how to use the tool.

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

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

Beyond the destructiveHint annotation, the description details refusal conditions, the permanent nature of deletion (no Trash recovery), and the expected response behavior (read refusal and tell the user). This fully discloses the tool's edge-case behavior and consequences.

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 somewhat verbose but every sentence adds critical operational detail (refusal cases, recovery guidance, system folder exclusions). The structure flows logically from action to constraints to fallback instructions, making it efficient despite its length.

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

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

Given the tool's destructive nature and multiple refusal scenarios, the description covers all relevant cases (non-empty, subfolders, INBOX, system folders) and provides clear next steps. It even specifies how to handle the output (read the refusal and tell the user), making it fully self-contained for an 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?

The single parameter 'name' is fully described in the schema with an example ('Old projects'). The description adds no additional semantic information beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

Clearly states the tool deletes an empty folder and unsubscribes it, distinguishing it from delete_email by noting the lack of a Trash recovery option. The scope is specific and the resource (folder) 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?

Explicitly instructs when to use this tool versus alternatives (move_email, delete_email) and warns about refusals for non-empty, subfoldered, or system folders. Tells the agent to read the refusal and relay it to the user, leaving no ambiguity about proper usage.

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

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

Annotations already indicate a non-read-only, non-destructive mutation, and the description adds the key behavioral facts that no SMTP submission happens and that the draft persists in the Drafts folder where it can later be edited or deleted. This goes beyond the annotations without contradicting them. It does not discuss error handling, but the safety profile is already clear from 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 short and front-loaded with the core behavior, which is good. However, the final instruction, 'Prefer an address a find_contact result marked confidence book,' is grammatically garbled and likely to confuse an agent. With only two sentences, that unclear sentence is a noticeable structural defect.

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 covers what the tool does, where the draft goes, and how it differs from send_email, while the schema richly documents the parameters. There is no output schema, but stating that the draft is stored for later editing, sending, or deletion is sufficient for an agent to understand the outcome. The omitted draft_reply/draft_forward distinction is more of a usage-guideline nuance than a completeness gap.

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

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

Schema description coverage is 78%, so the schema already documents most parameters well. The description adds useful guidance for `to` – that it is required and that a find_contact result marked confidence book should be preferred – but it does not add meaningful semantics for other parameters. This is baseline-plus, not a major contribution.

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 'Save a message to the Drafts folder without sending it' – a specific verb and resource that immediately identifies the tool's core job. It also explicitly differentiates from send_email by stating the only difference is that this tool does not submit to SMTP, so an agent can correctly tell them 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?

It gives clear when-not-to-use context: use this when the message should not be sent via SMTP, and names send_email as the alternative. It also advises preferring a find_contact result marked confidence book for the recipient address. However, it does not mention when to choose draft_reply or draft_forward instead, which is a small gap in sibling differentiation.

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

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

Annotations already mark this as non-read-only and non-destructive, and the description adds substantial behavioral context beyond that: 'Nothing is sent and nothing reaches anybody,' attachments are carried and named, oversized files are skipped and must be reported, and recipients are never resolved from the original. This fully prepares the agent for side effects and caveats.

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 earned: it covers purpose, exclusions, recipient rules, attachment behavior, and failure modes for a complex 10-parameter tool. It is front-loaded with the core use case. A little redundancy ('Nothing is sent and nothing reaches anybody') and heavy capitalization prevent a perfect score, but every sentence carries operational value.

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

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

For a tool with no output schema, the description is remarkably complete: it explains what the draft contains, where it lands, how it differs from sending, what happens to attachments, how recipients are chosen, and what the agent must tell the user about skipped files. Nothing necessary for correct invocation is left to guesswork.

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 90%, so the schema already documents most parameters. The description still adds genuine semantic value beyond the schema: recipients are exactly as supplied, a find_contact result marked confidence='book' should be preferred, and the original's attachments ride along with the draft, with skipped files needing user notification.

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: 'Compose a forward and save it in Drafts WITHOUT sending it.' It explicitly distinguishes itself from draft_email, which 'composes a standalone message and carries none of the original,' and ties its behavior to forward_email, so an agent can tell them apart immediately.

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

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

The description gives an explicit when-to-use trigger ('Use this whenever the user wants to check a forward before it goes'), names the sibling to never use (draft_email), and clarifies the relationship to forward_email. It also adds selection guidance for recipients via find_contact confidence='book'.

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 reveals meaningful behavioral facts: the original is NOT marked as answered, nothing is sent and nothing reaches anybody, and the draft is placed in Drafts where it can be edited, sent, or deleted. These side effects are not visible in the annotations or schema and are exactly what an agent needs to know.

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

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

The description is a single paragraph but every sentence earns its place: purpose, sibling distinction, resulting draft content, side effects, and a contact-preference hint. It is front-loaded with the core action and does not repeat schema details.

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

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

Given a complex tool with 11 richly described schema parameters and no output schema, the description fully covers what the tool does, when to use it, what it does not do, and what the draft looks like. An agent has enough context 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?

Schema description coverage is 100%, so the schema already documents all 11 parameters thoroughly. The description adds a useful behavioral hint about preferring a find_contact result marked with high confidence, but it does not need to compensate for missing parameter 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 first sentence names a specific verb and resource: compose a reply to a message and save it in Drafts without sending it. It further distinguishes itself from draft_email and aligns its produced draft with reply_email's output, so an agent can tell exactly what this tool does.

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

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

It gives an explicit when-to-use rule: whenever the user wants to review or edit a reply before it goes. It also gives an exclusion ('never draft_email') with a concrete reason, and clarifies what this tool produces compared to reply_email, making the selection decision unambiguous.

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 discloses the confidence model (book, strong, weak), the impersonation risk, the truncation behavior (3,000 messages per folder, historyTruncated flag), and the fact that results are 'not trusted data'. This goes far beyond the readOnlyHint and openWorldHint annotations, giving the agent critical safety context without contradiction.

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

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

The description is long but front-loaded with the core purpose and usage guidance. Every sentence adds value—explaining confidence levels, evidence fields, and safety rules. However, it could be trimmed without losing critical information; a more concise version might be slightly easier to parse. Still, the structure is logical and effective.

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 there is no output schema, the description fully explains the return fields (sentTo, receivedFrom, book, strong, weak, historyTruncated) and how to interpret them. It also covers edge cases (impersonation, multiple plausible matches) and the data source limitations. An agent has everything needed to call 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?

Schema description coverage is 100%, so all three parameters are already documented. The description does not add new parameter-level meaning beyond what the schema states; it reinforces defaults (Sent/INBOX) but provides no additional syntax or semantics. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Resolve a person's name to their email address') and clarifies the scope ('out of who this mailbox actually corresponds with'). It distinguishes itself from siblings like search_emails or list_emails by focusing on identity resolution, and explicitly ties to send_email workflow.

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 instructions ('Call this BEFORE send_email whenever the user names a person rather than an address'), states what not to do ('do not guess an address and do not ask the user to type one'), and provides conditional behavior for weak or ambiguous matches. It clearly names the sibling tool (send_email) and sets 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds operational details: it's purely a marker, doesn't mark as read, verifies flag changes by reading back from the server, and names individual failures. This exceeds the annotation coverage.

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 each sentence contributes unique operational or safety information. It is well-structured, starting with what the tool does, then what it doesn't do, then usage guidance, then verification and mailbox handling, then idempotency and sibling contrast. No unnecessary 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 tool with no output schema, the description covers all essential usage aspects: batching, parameter semantics, side effects (it's a marker, doesn't change content), verification behavior, and how to handle edge cases (already flagged, non-INBOX uids). It also situates the tool among its siblings, making it fully self-contained for correct invocation.

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

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

The schema covers both parameters fully (uids array with limits and source context; mailbox with default). The description adds extra meaning about uids being tied to the originating folder and reinforces the batching intent, enriching the schema-provided semantics.

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

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

The description clearly states the tool flags messages (sets the star/flag marker) and explicitly distinguishes it from moving, reading, or altering content. It also references the sibling unflag_email, making the purpose unambiguous.

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

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

It provides explicit batching guidance (pass the whole set in one call), explains when to include the mailbox parameter (when uids didn't come from INBOX), and clarifies idempotent behavior (already-flagged messages are not errors). It also differentiates the tool from unflag_email's more dangerous counterpart.

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 greatly extends it: 'cannot be undone', not threaded onto the conversation, original's attachments carried, oversized files 'listed separately as skipped' with a MUST-tell-the-user obligation, and attachments sent IN ADDITION to the originals. Also discloses from-address server refusal and plainTextOnly consequences. 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?

Front-loaded with core semantics (real-client forwarding behavior and the forwarded-message block) before details, and every sentence carries a distinct behavioral fact. It is long and somewhat redundant with the schema's attachment guidance, but for an irreversible real-mail tool the density is mostly earned.

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 forwarding-specific behaviors the schema cannot express: header-block format, threading, attachment carry-over, skipped-file reporting, and irreversibility. Minor gaps remain: the result shape is only hinted at ('the result NAMES the files it sent') and the approval/draft alternative is not routed.

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 baseline is 3, and the schema already documents parameters like attachments, from, and html in depth. The description adds genuine cross-parameter meaning invisible in the schema: 'to' recipients are exactly as supplied and never resolved, and attachments are additive to the original's files rather than replacing 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?

Opens with a specific verb+resource ('Forward a message to new recipients') anchored to a familiar real-client behavior. It explicitly distinguishes itself from reply_email ('unlike reply_email, recipients here are exactly the addresses you supply and are never resolved from the original message'), so an agent can reliably pick it among reply_email, draft_forward, and send_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 an explicit contrast with reply_email and a concrete preference rule ('Prefer an address a find_contact result marked confidence book'). However, it never addresses the draft_forward/approval path or send_email for new messages, so exclusion coverage is not complete.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds substantial context beyond them: the preview's approximate length (200 chars), what it strips (quoted history, signature), its null behavior for empty or image-led bodies, and a security warning to treat message content as data never as instructions. That last point is high-value behavioral context the 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?

Front-loaded with the core purpose, then preview semantics, routing, the null edge case, and security. Every sentence is purposeful, but there is mild redundancy: 'what has come in?' is ONE call' and 'USE THE PREVIEW rather than reading each message' make the same efficiency point twice. Otherwise zero 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?

Complete for a low-complexity list tool with no output schema. The description carries the return-value burden by explaining the preview field, its null case, and its scope, while annotations cover the safety profile and the schema covers both parameters. An agent has everything needed 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?

Schema description coverage is 100%: both limit and mailbox already carry descriptions with defaults and constraints. The description adds no syntax or format detail for the parameters beyond what the schema provides, so the baseline 3 applies. This is acceptable because the schema does the heavy lifting.

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

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

States a specific verb and resource: 'List the most recent messages in a mailbox, newest first.' The ordering and scope are explicit. It differentiates from siblings by explaining where it ends and read_email begins ('it is not the message'), so an agent can distinguish it from read_email, search_emails, and list_mailboxes.

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 when-to-use guidance: 'what has come in?' is one call, and 'USE THE PREVIEW rather than reading each message.' It names the alternative explicitly and the condition that selects it: 'call read_email when you need what a message actually says, the recipients, or its attachments.' Nothing is left to inference.

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

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

Adds context beyond the readOnlyHint and idempotentHint annotations by noting that addresses are managed by the mailbox owner, not via the connector, and that the mail server decides whether it will carry one.

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

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

Two sentences pack relevant information without unnecessary verbosity or repetition.

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

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

Given the absence of an output schema, the description adequately explains what the tool returns and how to apply it, making it self-contained.

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?

Tool takes no parameters, so there is no ambiguity or missing information.

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

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

Clearly states the tool lists the addresses this mailbox can send as and identifies the default, distinguishing it from sibling tools like list_mailboxes and list_emails.

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?

Explains how to use the returned identities (pass as 'from' on send_email, etc.) but does not explicitly contrast with when to use alternatives like list_mailboxes.

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

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

The annotations already mark it as read-only, idempotent, and non-destructive, and the description does not contradict that. It adds behavioral context about the meaning of selectable false and how other tools interact with such folders, which goes beyond what the annotations provide.

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

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

The description is concise, consisting of two sentences that front-load the main purpose and then provide key clarifications. No redundant or extraneous information is present, and the structure is easy to parse.

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

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

Given that there are no parameters and no output schema, the description is complete. It explains what the tool returns (list of mailboxes with special-use roles and selectable status) and provides necessary context for interpreting the results, making it sufficient for an agent to use 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 tool has no parameters, and the schema reflects this with an empty properties object. The description correctly implies the absence of parameters and adds no misleading information, so it fully aligns with the schema.

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

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

The description clearly states the verb 'List' and the resource 'mailboxes' (IMAP folders), and provides specific details about special-use roles and the selectable flag. It distinguishes this tool from siblings like create_folder, move_email, and delete_email by explaining which operations are valid on non-selectable 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?

It gives explicit guidance on when to use the tool (to list all folders) and when not to use certain operations on non-selectable folders (move_email and delete_email won't work), while noting that create_folder can use them as parents. This effectively differentiates from alternative tools and clarifies the intended use case.

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

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

Annotations already cover read-only/idempotent/non-destructive, but the description adds significant context beyond them: newest-first ordering, the fields returned (who asked, when, recipients, preview), the `requestedBy: "unknown"` edge case, and a prompt-injection warning about treating the content as data, not instructions.

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-loads the purpose and scope, then adds the workflow, the edge case, and the security note in a tight sequence. Every sentence earns its place despite the length.

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

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

With no input params and no output schema, the description carries the load by describing the returned fields and ordering. Nothing an agent needs to call and use this 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?

Zero parameters, so the schema has nothing to document (baseline 4). The description does clarify output-field semantics, notably that `requestedBy` can be "unknown" and why, which adds meaning for interpreting results.

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

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

States a specific verb (list) and resource (drafts awaiting approval in the Drafts folder), and defines scope precisely: every draft someone asked the owner to approve, newest first. An agent can distinguish this from siblings like list_emails or read_email immediately.

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

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

Explicit workflow routing: read the draft with read_email on the Drafts folder before approving, and send with approve_and_send. It names the exact alternatives and the conditions selecting them, leaving nothing to inference.

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

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

With annotations already signaling destructive/read-only false, the description adds substantial behavioral detail: the junk folder is role-resolved across providers, a junk folder is created if missing, already-junk messages are refused, flags and original dates are preserved, and the server learns from the move. This exceeds what the annotations and schema provide.

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 useful operational or provider-specific information. It is front-loaded with the core meaning ('report spam') and then builds toward constraints and edge cases. Some capitalization is stylistically noisy, but content justifies the length.

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

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

For a destructive mutation with no output schema, the description covers the essential behaviors: what the operation does, how the junk folder is resolved, what happens when no junk folder exists, refusal conditions, preservation of flags and dates, and batch-calling guidance. An agent has enough context to invoke it correctly without additional assumptions.

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 meaning beyond the schema, particularly the requirement that all UIDs come from the same source folder and the emphasis on passing all UIDs in one call. It also clarifies how the mailbox parameter relates to the current folder of the messages.

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 (move messages into the junk folder), ties it to the familiar 'report spam' concept, and clarifies that it is not merely filing but also trains the spam filter. It clearly distinguishes this from the sibling not_junk by explicitly naming it as the reverse 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?

The description gives strong contextual guidance: use this to report spam, and use not_junk to reverse it. It also instructs the agent to pass all UIDs in a single call and notes that all messages must be in the same source folder. It does not explicitly compare against move_email, but the spam-training semantics make the intended use 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?

The description goes beyond the annotations by revealing that reading does not imply marking, that results are verified by reading back flags, that UIDs are folder-scoped requiring mailbox when not from INBOX, that batch operations can partially succeed, and that already-read messages are not errors. This level of behavioral detail is exceptional and fully sets expectations for the side effects and edge cases.

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 informative but somewhat verbose and repetitive. For example, the UID folder-scoping warning is stated twice with slightly different wording, and the emphasis on batch calling is repeated in the uids parameter description. While the content is valuable, the text could be tightened without losing meaning. It is still well-structured with clear, separated points.

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 covers all necessary context: purpose, usage, batching, folder semantics, verification behavior, idempotency, and relationship to undo. It even mentions partial success, which is rare in tool descriptions. Given the absence of an output schema, the note that flags are read back provides sufficient expectation of what to observe. Nothing essential for 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?

The schema covers 100% of parameters with precise descriptions. The uids parameter explains its source (list_emails or search_emails), its batch nature (all in one call), limits (up to 500), and single-message usage (one-element array). The mailbox parameter clarifies its purpose (folder name) and default (INBOX). This leaves no room for misinterpretation.

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

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

The description clearly states the tool's purpose: 'Mark messages as read.' It explicitly distinguishes this action from merely reading a message (which does not mark it read) and from the sibling tool mark_unread, making its function unambiguous even among many related email 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 provides explicit guidance on when to use it (when the user asks to mark as read, not during reading) and how to use it correctly: pass all messages in one call, handle UID folder-specificity by providing mailbox, and expect verification of results. It also notes idempotency and names the undo operation (mark_unread), leaving no ambiguity about invocation context.

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

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

Beyond the annotations, the description reveals that results are verified by reading flags back off the server and that unchangeable messages are named rather than silently assumed done. It also discloses idempotency (already-unread is a no-op) and non-interference with other flags, answered state, and folder position. These are material 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 longer than the minimal two-sentence style, but each sentence carries distinct operational information. There is slight redundancy between 'restoring the state they were in' and 'undo for mark_read,' and 'Pass the whole set in ONE call' is echoed in the schema, so it is not maximally lean.

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 covers purpose, when to use it, batching, verification/failure reporting, UID-to-mailbox scoping, idempotency, and side-effect scope. Though there is no output schema, the verification description provides enough return-behavior guidance for an agent to understand what a successful call will report.

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?

Although the schema already documents both parameters (100% coverage), the description adds the crucial folder-scoping caveat: a UID is only meaningful in the folder it came from, so mailbox must be passed for non-INBOX UIDs. It also reinforces batch semantics by instructing the agent to pass every target message in one call, up to 500.

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 clear verb and resource ('Mark messages as unread') and immediately defines it as the inverse/undo of mark_read, making the purpose unambiguous and distinguishable from the sibling tool mark_read. The opening also clarifies the semantic meaning: restoring the previous state before a read marker was applied.

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 names mark_read as the counterpart and says to reach for mark_unread when a triage pass marked more than intended. It also gives concrete invocation guidance: pass the whole set in one call, include mailbox when UIDs did not come from INBOX, and treat already-unread messages as a no-op rather than an error.

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

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

Annotations already mark the operation as destructive and not read-only. The description adds valuable behavioral details beyond annotations: flags and original dates are preserved, and the operation requires all UIDs to come from the same source folder. 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?

Three sentences carry the essential information: the action, the preservation guarantees, the batching/destination constraints. No wasted words, and the key usage instruction is placed where it is most likely to be read.

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 three-parameter tool with no output schema and annotations covering destructive/read-only behavior, the description is sufficient. An agent knows what to call, how to batch UIDs, what constraints apply, and what behavior to expect regarding flags and dates.

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 uids, to, and from, including batching guidance and the INBOX default. The description still adds value by making explicit the same-source/same-destination invariant, which the schema does not directly state.

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.' The additional constraints about same source folder and same destination further clarify exactly what the tool does, distinguishing it from archive/delete/folder operations.

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

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

It gives clear usage context: 'Filing a backlog is what this tool is for' and instructs to pass every UID in one call and make one call per destination for multiple folders. It does not explicitly contrast with alternatives like archive_email or delete_email, but the usage guidance is strong and concrete.

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/readOnly annotations, the description discloses several non-obvious behaviors: there is no source folder parameter, the junk folder itself is rejected as a destination, mailboxes without a junk folder cause a refusal rather than auto-creation, and metadata such as flags and original dates are preserved. No statement contradicts the annotations.

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

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

The description is longer than average but every sentence carries a distinct operational constraint or clarification. It is front-loaded with the core action and then layers caveats in a logical order, so an agent gets the essential behavior before edge cases.

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 everything needed to invoke it correctly: source folder, destination default and restriction, prerequisite UID acquisition, batching behavior, and refusal cases. There is no obvious missing information for selection or invocation.

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

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

Even though the schema already covers the parameters well, the description adds meaning beyond the schema: UIDs are meaningful only in the folder they came from, retrieved via list_emails or search_emails against junk, and must be batched in one call. It also clarifies that `to` overrides the INBOX default but must not be the junk folder.

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 ('Take messages back out of the junk folder and return them to the inbox'), and connects it to the familiar 'not spam' action. It also names the direct sibling relationship ('the reverse of mark_junk'), so an agent can disambiguate it from mark_junk without inspecting schemas.

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

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

It gives explicit when-to-use guidance: fetch UIDs first from list_emails or search_emails against the junk folder, pass all UIDs in one call, and use `to` only for a non-junk destination. It also states exclusions up front — no source folder parameter, refuses `to` of the junk folder, and refuses mailboxes without a junk folder.

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

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

Goes well beyond the readOnly/idempotent/non-destructive annotations: reading never marks the message read, nothing is stored, the file never leaves the mailbox, the `maxChars` budget defaults to 50,000 with a 200,000 ceiling, truncation is flagged via `totalChars`/`truncated`, and `signals` are computed over the whole file rather than the returned window. It also carries an explicit prompt-injection warning about untrusted file content.

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

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

Front-loaded with purpose and format coverage, and every clause carries information; however it is one very long paragraph that re-states some schema details (maxChars default/ceiling, the 4-page image cap), so it is dense rather than tight.

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 4-parameter, no-output-schema tool this is essentially complete: it enumerates every supported format and its rendering (PDF page markers, xlsx CSV blocks, images, unsupported-file fallback), covers truncation/pagination, result identifiers (partId), and security caveats.

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%, so the baseline is 3, but the description adds real value on top: it explains the 4-per-call pagination logic for `page`, the ordering guarantee of `refs`, and the offset/maxChars interplay for continuing a partial read. It largely mirrors the schema wording on maxChars defaults, so it is reinforcing rather than purely additive.

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

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

States a specific verb and resource ('Read the contents of one or more attached files') and anchors the input to `ref` values produced by read_email, which cleanly separates it from the sibling read_email/list_emails tools. An agent can tell what this returns (extracted text/images) without opening the schema.

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

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

Explicit routing rules: batch all refs into ONE call, skip the small inline signature images listed with a `cid`, use `page` for scanned PDFs (4 pictured pages per call, 3 calls for a 12-page scan), and continue truncated files by re-calling with a single ref plus `offset`. When-to-use and when-not-to-use are both stated.

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

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

Far exceeds the annotations (which only cover readOnly/idempotent/non-destructive): it discloses that reading does NOT mark as read, ref and downloadUrl expiry windows, that downloadUrl is a bearer link openable by anyone holding it, the meaning of authentication.verdict values, and that html is sanitised and differs from what the sender wrote. These are exactly the behavioral traits annotations cannot express.

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

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

Front-loaded and organised with capitalised section headers, and most sentences carry real safety or routing value. However it is a very long single block with repeated emphasis on the download link and expiry, which tests an agent's attention budget more than a tool of this parameter complexity warrants.

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 describing the return shape (attachments with ref/downloadUrl, replyTo, authentication, signals, html) and it does so in detail, including which fields require action from the agent. Nothing needed to call or interpret it 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% with two simple params (uid, mailbox), so the schema already carries the parameter meaning and baseline 3 would apply. The description adds a small amount of linking context by tying the result's refs to other tools, but says nothing new about uid or mailbox semantics beyond the schema.

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

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

Opens with a specific verb and resource plus scope: 'Read one message in full, including its body and recipients.' It immediately distinguishes itself from read_attachment ('This tool only lists the files; it never opens them') and from read_thread, so an agent can route without opening a schema.

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

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

Gives explicit when-to-use routing: pass refs to read_attachment to see inside a file, call send_email/reply_email/forward_email/draft_email to attach an existing file, and re-call this tool for a fresh ref once one expires. It also names the anti-pattern ('Never use this tool to check what your own outgoing formatting will look like'). Nothing is left to inference.

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

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

Annotations already declare a safe read profile, yet the description adds substantial non-obvious behavior: reading does NOT mark anything read, quoted copies are stripped by default with `quotedTrimmed`/`includeQuoted` control, threads are followed via the References header and can come back short, and per-message `authentication` verdicts should be read individually because a `fail` mid-thread signals forgery.

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 purpose and the sibling comparison are front-loaded, and nearly every sentence carries operational value. It is on the long side with dense parentheticals, but there is little filler to cut.

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

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

With no output schema, the description carries the return-value burden and does so: it names `quotedTrimmed`, `authentication` and `signals`, describes default folder scope, and warns about the References-header completeness limit. Nothing an agent needs to call and interpret this 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 baseline is 3, but the description adds real meaning: it explains why `includeQuoted` is off by default (result size multiplication), that naming `mailboxes` REPLACES the folder+Sent default, and that `quotedTrimmed` reports trimming. It slightly exceeds the schema's own wording rather than merely repeating it.

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 a specific verb, resource and scope ('Read an entire email conversation in ONE call, oldest message first, given any one message'), and the description explicitly contrasts itself with read_email. An agent can distinguish this from read_email and list_emails without opening either schema.

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

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

It names the alternative (calling read_email repeatedly) and the condition that selects this tool, plus the reverse condition: use read_email when one message's HTML or full untrimmed body is needed. It even gives a concrete trigger phrase ('catch me up on this thread').

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

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

Goes well beyond annotations: clarifies it moves nothing, marks nothing read, reports unheld messages without error, and precisely defines force's effect. This is rich operational context not in the structured data.

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 front-loaded and dense with necessary information. No wasted words despite the complexity.

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

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

For a mutation tool with no output schema, the description covers all critical aspects: what it does, when to use it, side effects (none), and edge cases (unheld messages, force). Complete for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful semantics for force (clears claims with no recorded holder) and the result naming behavior, elevating it.

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 the specific action (releasing claimed messages) and ties it directly to the sibling claim_email. The scope constraint 'only your own claims' further distinguishes this from other claim-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?

Explains when to use it (to let a colleague take claimed messages) and the force behavior, but doesn't explicitly name alternatives like assign_email which might also transfer ownership.

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, but the description adds crucial context: it states that all messages inside the folder move with it and subfolders move recursively. It also details refusal behaviors and the rationale (e.g., renaming INBOX would empty it). This goes beyond what the boolean hints alone provide.

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 typical, every sentence carries essential information: the operation, side effects, exceptions, and user-facing instructions. The ALL-CAPS emphasis draws attention to critical details without adding fluff. No redundant or tangential content exists.

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 an agent: it defines the operation, explains parameter usage, warns about destructive consequences, enumerates refusal cases, and tells the agent how to handle refusals (read and relay to the user). No output schema is present, but the behavior is fully specified, so an agent knows exactly what to expect.

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 descriptive texts for all three parameters. The description amplifies this by showing how 'newName' can contain slashes to create hierarchy and how 'parent' is used specifically for reparenting. It also gives concrete examples, making the parameter interactions clear.

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

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

The description clearly states the tool's purpose: renaming or moving a folder, and explicitly notes the IMAP equivalence. It distinguishes itself from sibling tools like create_folder and delete_folder by describing the rename/reparent action. The examples (e.g., 'Projects' to 'Archive/Projects') make the scope unambiguous.

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

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

The description provides explicit usage guidance: it explains when to use the 'parent' parameter (to reparent without changing the leaf name), warns against manually building paths, and instructs the agent to read and communicate refusal messages. It also lists specific refusal cases (INBOX, Sent, Drafts, Trash, Junk, Archive) and the reason for each.

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?

Even though annotations already flag destructive=true and readOnly=false, the description adds substantial behavioral detail: quoting style, sent-folder filing, answered flag, recipient derivation, refusal on unexpected Reply-To, attachment byte path costs, size limits, HTML escaping risks, and read-receipt limitations. It even explains that messages over the server ceiling are refused with the server's figure. This goes far beyond what annotations provide.

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 dense with high-value information; there is no fluff. It is not a short two-sentence summary, but each clause earns its place by addressing real endpoints the agent will hit (refusals, size limits, HTML escaping, receipt behavior). The main weakness is that it is a single uninterrupted block rather than logically grouped sentences, which slightly reduces scannability; still, it is well-organized.

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

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

For a complex side-effecting tool with 11 parameters and no output schema, the description covers most critical behavior: what happens on success (threading, Sent, answered flag), refusal paths, size constraints, authentication/identity nuances, and attachment handling. It does not explicitly describe the success response structure, but that is typically obvious for a send tool and is less crucial than the side-effect caveats it does cover.

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 meaning by explaining how recipients are resolved (Reply-To/From), how cc fits into that, why confirmReplyTo is required, and which attachment source to prefer (fileRef > url > uploadId > content). It also clarifies the 'all' flag's effect, though that is already partly in the schema. This enriches the agent's understanding beyond raw parameter definitions.

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 'Reply to a message' and immediately distinguishes this from siblings by explaining threading, quoting, filing to Sent, and marking as answered. It also clarifies recipient derivation (Reply-To or From) and explicitly excludes the mailbox itself, which differentiates it from forward_email and send_email. The verb-resource pair is specific and the scope 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 gives strong context on when to use the tool (when replying to an existing message) and includes warnings about real mail and refusal cases, but it never explicitly names alternatives or says when not to use it. It mentions find_contact for recipient selection, but not draft_reply or forward_email as possible alternatives, leaving the agent to infer when those would be more 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?

Annotations declare a non-read-only, idempotent, non-destructive mutation, and the description enriches that with the full lifecycle: the draft remains in Drafts unsent and editable, the assistant sees it via list_pending_approvals, approve_and_send files the Sent copy and removes the draft, and invalid uids are refused. This adds state-transition and side-effect detail well beyond the annotation flags.

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

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

Purpose is front-loaded in the first sentence, followed by usage condition, lifecycle, and failure behavior in a compact block. It is somewhat long, and the closing note about there being no 'send back for changes' tool is tangential, but each sentence carries actionable content.

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

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

For a single-parameter mutation with no output schema, the description supplies everything needed: when to call it, what state results, who acts next, how the state resolves, and what input is rejected. No annotation or schema gap is left uncovered.

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

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

Schema coverage is 100% with a single uid parameter, so the baseline is 3. The description adds a genuine constraint the schema does not encode: the uid must identify a draft in the Drafts folder or the call is refused, which sharpens valid-value selection beyond 'UID of the draft'.

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

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

States a specific verb and resource ('Mark a draft ... as waiting for approval') and immediately scopes it relative to siblings, naming the drafting tools it follows and the downstream tools (list_pending_approvals, approve_and_send) that consume the state. An agent can distinguish this from draft_* and send_email without opening any schema.

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

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

Gives explicit when-to-use conditions: after draft_reply/draft_forward/draft_email, when the user cannot send from this mailbox or wants owner review. It also names the alternative path (owner replies manually) and the failure boundary (refuses non-Draft uids), so routing is unambiguous.

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, idempotent, non-destructive behavior, and the description adds important details about result capping and true total counts. It does not contradict annotations and honestly states it does not return message bodies.

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 and contains some repetition and all-caps emphasis, but the extra length is largely justified by the need to disambiguate date matching, substring matching, and multi-folder search behavior. It could be better organized with bullets.

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

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

No output schema is provided, so the description compensates by explaining the return shape: summaries like list_emails plus the folder. Combined with the schema and annotations, it gives the agent enough context to call 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?

All 14 parameters are described in the schema, and the description adds important semantics: substring matching, delivered-date behavior, whole-day precision, defaults, and the one-call benefit of passing multiple mailboxes.

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

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

Clearly states the tool searches one or more IMAP folders and returns email summaries in the same shape as list_emails plus the folder. It explicitly contrasts with read_email and list_emails, so the purpose is unambiguous.

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

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

Provides explicit guidance on when to use search instead of read_email, how to search multiple folders in one call, and precise matching semantics for substring and date filters. It also clarifies that result caps are disclosed.

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 massively expands on the annotations (destructiveHint=true, readOnlyHint=false). It discloses the dual plain-text/HTML send behavior, the double-signature hazard, the Sent-folder filing that can fail independently of send success, partial success with rejected recipients, the 20 MB aggregate attachment cap, the token cost of inline content, and the URL-fetch behavior. Nothing contradicts the annotations — 'cannot be undone' aligns with destructiveHint=true.

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 real operational value — this is not padding — but the description is a dense, unstructured wall of text with heavy ALL-CAPS emphasis and no paragraph breaks or scannable sections. The most critical safety warning (signature duplication) appears reasonably early, but the formatting makes it harder to absorb than the content quality deserves.

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

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

For a 9-parameter, no-output-schema, high-stakes tool, the description is remarkably complete: it covers return semantics (Sent-folder filing success/failure, rejected recipient names), failure modes, limits, prerequisites, and cross-tool dependencies. Minor gaps remain, such as not explicitly describing the success-path response shape beyond the filing note, but the operational contract an agent needs is substantially present.

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

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

Schema coverage is 78% and the schema itself carries rich per-parameter descriptions, especially for attachments (url/content/fileRef/uploadId routing) and requestReadReceipt. The tool description adds value beyond the schema by explaining the dual-format behavior that governs how text and html interact, the signature-duplication consequence, and the partial-success return semantics. It does not fully compensate for the undocumented params (cc, subject), but those are self-evident.

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

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

The opening sentence states a specific verb, resource, and scope: 'Send a new email from the connected mailbox, with files attached if you pass them.' The phrase 'new email' distinguishes this from sibling tools like reply_email, forward_email, and draft_email without needing to open their schemas. The 'real mail... cannot be undone' framing also sets expectations that this is the live-send tool among the email 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 unusually rich routing guidance: use list_identities for non-default from-addresses, prefer find_contact results marked 'confidence book', use read_email to obtain fileRef values, use create_upload_link for large or user-owned files, and use check_receipts after requesting a read receipt. What it lacks is an explicit exclusion statement — it never says 'use draft_email when the user wants to review before sending' or 'use reply_email to respond to a thread' — though 'new email' implies these 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 adds transparency beyond annotations by explaining idempotency ('Clearing a flag that is not set changes nothing and is not an error'), batch behavior, and the non-destructive nature of the operation. It does not contradict the annotations (readOnlyHint false, idempotentHint true, destructiveHint false).

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 verbose and repetitive (e.g., 'one call' mentioned multiple times, long warnings about care and verification). While informative, it could be trimmed significantly without losing meaning.

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

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

The description covers all necessary context: batch operation, idempotency, mailbox handling, and edge cases like unset flags. It fully equips the agent to use the tool correctly without ambiguity.

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 descriptions for both parameters are thorough: uids includes usage, limits, and examples, while mailbox explains its default. This covers all parameters with 100% schema coverage.

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

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

The description clearly states the tool's purpose: 'Clear the flag/star marker on messages, restoring their unflagged state.' It specifies the verb (clear), the resource (emails), and distinguishes it from sibling tools like flag_email and mark_unread.

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 usage guidance: 'Pass the whole set in ONE call' with rationale, instructs to 'Clear the ones you were asked about and no others,' and explains the mailbox parameter. It also clarifies verification and default 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?

Even though destructiveHint is already true, the description goes further with critical behavioral details: the whole message is replaced, omitted fields are gone, the UID changes and the old UID stops working, and nothing is sent. This materially changes how an agent should invoke and chain the tool, and it does not contradict the annotations.

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

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

The description is dense but every sentence carries operational weight—replacement semantics, UID mutation, carryover behavior, and the no-send guarantee. It front-loads the core purpose and places the most dangerous caveat (whole-message replacement) early rather than burying 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 no output schema, the description tells the agent what to expect from the result (a new UID) and how to use it for further edits. Combined with the exhaustive input schema, it covers replacement semantics, attachment preservation, and the fact that nothing is transmitted.

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

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

Schema coverage is 100%, but the description adds semantics the schema alone does not convey: pass the FULL new version of every field, threading headers and attachments are carried over, and UID invalidation affects subsequent edits. This directly affects correct values for uid, to, subject, text, and keepAttachments.

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 and resource: 'Rewrite a draft that is already in the Drafts folder, in place of deleting it and saving a new one.' It clearly distinguishes this update tool from sibling draft-creation tools like draft_email and draft_reply by focusing on an existing draft.

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

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

It gives explicit usage criteria: 'Use this whenever the user wants a draft changed - a different wording, another recipient, a corrected subject.' It also sets boundaries by stating the draft must already be in the Drafts folder and explains what is preserved, which guides the agent away from new-draft tools.

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