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 a mutating, non-idempotent, open-world operation, and the description adds substantial context beyond them: a folder may be created and subscribed if none exists, the caller must tell the user a new folder will appear, messages must share one source folder, flags and original dates are preserved, and the reply reports the folder used plus each message's new UID. Nothing contradicts the destructiveHint/readOnlyHint profile.

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 action and its key caveat, and nearly every sentence carries decision-relevant information. It runs long for a two-parameter tool, with some client-specific color (Gmail/Outlook/Roundcube) that could be tightened, but it is not padded.

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

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

With no output schema, the description still explains the return payload (folder actually used and each message's new UID), the side effect of folder creation, the refusal case, and preservation guarantees. An agent has everything needed to call it correctly and to report the outcome to the user.

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 operational meaning: all UIDs must come from the SAME source folder, batching in one call is preferred over per-message calls, and the returned new UIDs are what you need to reverse the move. That goes beyond the schema's field-level text.

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

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

The description names a specific verb and resource and pins down the exact semantics: 'Archive messages - file them where this mailbox's own Archive button files them, out of the inbox but not deleted.' It explicitly distinguishes the operation from move_email({to:"Archive"}), so an agent can tell the two apart 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 gives explicit when-not guidance ('REFUSES messages that are already in the archive... use move_email if they want them somewhere else') and names the alternative tool with the condition that selects it. It also warns against the naive path of moving to a folder literally named 'Archive'.

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?

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses several non-obvious traits: reading marks nothing as read, the 2,000-message per-folder truncation and that the result reports it, UTC timestamps, and that classification is header-based, never content-based, with a `reason` per automatic entry. These are exactly the behaviors an agent needs and cannot get from the structured fields.

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

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

The description is dense but front-loaded: the core result shape comes first, then classification rules, then window/cap constraints. Nearly every clause carries information, though the sentence about reply detection ('each by a message addressed to them in Sent, or by the answered flag') is harder to parse than it needs to be.

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 full burden of describing return shape and it does so thoroughly: conversation fields, preview, counts, unread counts, reply status, separately listed automatic mail with sender/subject/reason, and the `totals` object. An agent knows what it will get back.

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 hours, limit, since (with offset and the 'give this or hours, not both' rule) and mailboxes. The description adds only the UTC note and confirms that limit doesn't affect totals, so baseline 3 is appropriate.

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

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

The description states a specific resource and scope ('what arrived in a recent window, grouped into conversations, in one call') and describes behaviors (conversation grouping, separating newsletters/automatic mail, reply status) that no sibling like list_emails or search_emails offers. An agent can tell it apart from read_thread and owed_replies 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?

Usage is implied by 'in one call' and the grouped-summary framing, but the description never explicitly says when to prefer this over list_emails, search_emails, owed_replies, or waiting_on. No exclusions or alternative-routing guidance is given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds rich behavioral context: the async nature of bounces, default folder inclusion of Junk, the PERMANENT vs TEMPORARY distinction and its resend implications, and the warning that no bounce is weak evidence of delivery. This goes well 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 front-loaded with the core purpose, then adds necessary behavioral details in a logical flow. It is somewhat long but every sentence carries critical information for correct invocation or interpretation. Minor redundancy exists (e.g., 'which is what this does'), but overall it is efficient.

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 check tool with no output schema, the description covers all an agent needs: what it finds, where it scans by default, how to interpret results (permanent vs temporary), and when to combine with sibling tools. Nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters with descriptions and constraints. The description adds context about the default folder scanning ('INBOX and the Junk folder by default') and the recipient-based filtering, which complements but doesn't significantly exceed the schema's own parameter descriptions. Baseline 3 is correct when schema does the heavy lifting, but the extra behavioral context about scanning raises it to 4.

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+resource ('Find messages that came back undelivered') and clearly distinguishes the tool from check_receipts by contrasting failure detection with arrival detection. An agent can tell it apart from siblings like check_deliverability and check_receipts without opening their 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?

The description explicitly names the alternative check_receipts and states exactly when to call it ('if the user is asking whether a message ARRIVED rather than whether it failed'). It also specifies default folder scanning behavior and conditions for resending. No inference is required.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real context beyond them: the empty result is not an error, files live in a draft in the user's Drafts folder, and that draft is auto-removed on attach or swept later. This lifecycle and side-effect disclosure is valuable and consistent with 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?

Four sentences, all front-loaded and functional: purpose, ordering, empty-result behavior, then draft lifecycle. Nothing is redundant or 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?

No output schema exists, yet the description explains what comes back (a fileRef per file, or a plain empty notice) and how to interpret it. For a single-parameter read tool, nothing an agent needs to call 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 uploadId parameter is already documented as coming from create_upload_link, so the schema carries the load. The description only reinforces the ordering relationship with create_upload_link, adding no new syntax or format detail. 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?

States a specific verb and resource ('Look for the files an upload link put into this mailbox') and the return value ('give back a fileRef for each so you can attach them'). It clearly positions itself relative to the sibling create_upload_link, so an agent can distinguish it 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?

Gives explicit timing ('straight after you upload the file yourself, or once the person says they have') and an explicit anti-pattern ('tell them what you are waiting for rather than calling this repeatedly'). This is exactly the when/when-not guidance the dimension asks for.

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

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

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?

Goes well beyond the annotations: it discloses that the folder is SUBSCRIBED and therefore visible in subscribed-only clients, that '/' builds hierarchy and auto-creates missing parents, that matching against existing folders is case-insensitive and returns the existing folder, and that it REFUSES names with blank segments. These are exactly the mutation/side-effect details 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-loads the core purpose and each clause carries distinct information (subscription, hierarchy, idempotency, refusal). It is long and leans on shouty all-caps emphasis ('SUBSCRIBED', 'IN THE NAME BUILDS A HIERARCHY', 'REFUSES'), which costs some readability, but little is genuinely 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?

With no output schema, the description still covers the return signal ('the reply says whether it actually created anything'), the mutation/idempotency behavior, and the error condition (blank segments). Everything an agent needs to call this correctly is 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 description coverage is already 100%, so baseline is 3, but the description adds real semantics: '/' nests rather than appearing literally, a literal '/' is therefore illegal in a name, and `parent` may legitimately be a non-selectable folder because nesting under it makes it selectable. That is meaningful behavior beyond the schema strings.

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+resource ('Create an IMAP folder') and immediately differentiates from siblings like rename_folder/delete_folder by describing hierarchy-building and subscription outcomes rather than just restating the title. An agent can identify the operation without opening the schema.

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

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

Gives clear context on when this is the right call (asserting the folder lands where expected, is subscribed, and nests via '/'), and notes the idempotent existing-folder case so the agent knows re-calling is safe. It never explicitly routes to an alternative (e.g. rename_folder) or states when NOT to use it, so it falls short of the 5 bar.

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 cover the safety profile (non-destructive, idempotent false, openWorld false), and the description adds substantial extra behavior: files land in Drafts as a holding draft that is auto-removed on attach, no sign-in/password needed for the link, several files at once, and explicit no-retry guidance on proxy/timeout/DNS failures. It also discloses a security constraint (only person-named files) that no annotation conveys.

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

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

Front-loaded with purpose followed by the two usage branches, and every paragraph carries actionable content (security caution, network caveat, follow-up call). It is long, and the heavy capitalization and some restatement (e.g., the 'no sign-in' point and the closing 'neither' clause) add bulk, but little is truly wasted.

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 zero-parameter tool with no output schema, the description covers the full workflow: what it produces, where files land, the follow-up check_upload call that yields fileRef, and cleanup behavior. An agent has everything needed to invoke it and act on the result.

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 there is nothing to document and the baseline of 4 applies. The description adds usage syntax for the resulting URL (`?filename=...`) but no input parameters exist to disambiguate.

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+resource: produce a one-off link that puts files into the mailbox. It explicitly distinguishes this from the sibling attachment paths (files already in the mailbox via read_email's ref, or files reachable by URL), so an agent knows exactly which tool applies.

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?

Names the conditions for use (file NOT already in the mailbox and NOT reachable by URL) and the two alternative execution modes: direct curl when shell+network exist, versus handing the link to the person otherwise. It explicitly warns that running commands and having network access are separate questions, removing the main inference trap.

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 supply destructiveHint=true and idempotentHint=false; the description adds the crucial nuance that this is a soft, recoverable delete (Trash), that already-trashed messages are rejected, and that batching is required. These are non-obvious behavioral traits an agent could not infer from the annotations alone.

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, front-loaded with the core action and scope, each carrying distinct information (recoverability, same-folder rule, Trash refusal, batching). The permanence sentence is a bit long but justifies itself by preventing a dangerous assumption.

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 covers the essential behavior, refusal case, and batch expectation. It omits what happens on partial failure (e.g., UIDs spanning folders) and whether per-message results are returned, which would matter for a 500-item batch call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a real constraint beyond the schema: every UID must be in the same folder, and all UIDs should be passed in one call rather than one per message. It does not, however, relate the mailbox parameter to that same-folder constraint.

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+resource ("Move messages to the Trash folder") and immediately distinguishes it from permanent deletion, which it explicitly says it does not perform. An agent can separate this from siblings like archive_email, move_email, or delete_folder 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?

It gives clear usage context (clicking Delete in Outlook/webmail) and explicit exclusions: all UIDs must share one folder, and messages already in Trash are refused. It references a "separate, explicitly named operation" for permanent deletion without naming the sibling tool, so routing is implied rather than spelled out.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds real value beyond them: the mailbox owner's signature is auto-inserted below the agent's words, with the concrete consequence that writing a sign-off yields a double-signed message, which is a behavioral trait no annotation conveys.

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

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

Front-loaded with the core action and reasonably tight. The closing find_contact/confidence-book sentence is useful for populating `to` but reads as an aside rather than being integrated into the main flow, keeping it just short of 5.

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 write tool with no output schema, the description covers the distinguishing behavior (draft saved, not sent), the signature caveat, and the lifecycle (editable/sendable/deletable in any client). It leaves the return value (e.g. a draft id) and the update_draft relationship implicit.

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%, just under the high threshold, and the schema already documents from, html, text, plainTextOnly, requestReadReceipt and all four attachment paths in detail. The description only adds that `to` is required and the signature behavior, so it neither compensates for nor meaningfully extends the schema.

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

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

States a specific verb and resource ("Save a message to the Drafts folder without sending it") and explicitly distinguishes itself from send_email, so an agent can route correctly without opening either schema. The scope (no SMTP submission) 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?

Names send_email and states the condition that separates them ("the only difference between the two tools is that this one does not submit the message to SMTP"), which is clear contextual guidance. However it never states a positive when-to-use trigger or addresses the update_draft sibling, leaving some 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 cover the safety profile (readOnly=false, destructive=false, openWorld=true, non-idempotent). The description adds real behavioral context beyond them: oversized attachments are listed as skipped and the agent MUST tell the user, recipients are never resolved from the original, the original's inline images and body block are carried, and the draft opens in a real mail client. No permissions or rate-limit behavior is disclosed, so it falls short of a 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?

Front-loads the core action in the first clause, then spends its length on genuinely load-bearing details (attachment carry/skip, signature duplication, recipient resolution). The final sentence about find_contact's "confidence book" mark is an orphan that belongs to a sibling tool and lands without context, which is the one clear structural blemish.

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 partly by stating the result names carried attachments and flags skipped ones. For a 10-parameter, nested-attachment tool it covers the high-risk behaviors (double signature, skipped files, unresolved recipients). It does not mention how the draft relates to the approval siblings (request_approval, list_pending_approvals) or subsequent update_draft edits.

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 already 90%, so the baseline is 3. The description adds genuine meaning on top: it clarifies that `to`/`cc` are exactly the supplied addresses and never resolved from the original, and that attachments are the original's carried files with skipped ones surfaced in the result. Per-parameter syntax is left entirely to the schema, which is fine at this 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?

States a specific verb and resource ("Compose a forward and save it in the Drafts folder, unsent") and explicitly contrasts with draft_email, which "composes a standalone message carrying none of the original." It also implicitly separates itself from forward_email by saying it holds exactly what that tool would have sent, so an agent can route between the three 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 clear context: the draft is for the user to check, edit, send or delete later, and it names draft_email as the alternative for a message with no original. It also warns not to write a sign-off because the mailbox owner's signature is appended. It stops short of an explicit "use this instead of forward_email when you want review before sending" rule, so it is clear but not fully directive.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds rich behavioral context: the original is not marked answered until a reply is actually sent, the mailbox owner's signature is added automatically, the draft opens in Outlook or webmail, and threading behavior differs from a standalone draft. No annotation contradiction is present.

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

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

The description is front-loaded with purpose and sibling differentiation, and most sentences provide useful behavioral context. However, it is somewhat long for a tool whose parameter details are fully covered by the schema, and the final sentence about find_contact confidence feels appended rather than tightly integrated.

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

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

Given 11 parameters, no output schema, and fully described parameter schemas, the description supplies the missing behavioral and routing context an agent needs: unsent nature, auto-signature, threading, unanswered status, and the distinction from reply_email and draft_email.

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 some recipient and body-related context, such as recipients being taken from the original, but it does not meaningfully add syntax or semantics beyond what the schema provides.

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

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

The first sentence names a specific verb plus resource: 'Compose a reply to a message and save it in the Drafts folder, unsent.' It then distinguishes the tool from close siblings reply_email and draft_email, so an agent can tell exactly what it does 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?

The description explicitly routes the agent away from reply_email by saying the result is unsent and holds exactly what reply_email would have sent. It also names draft_email and explains the standalone-message alternative, so the when-to-use distinction is explicit.

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

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by stating flagging does not move or mark messages read, that flags are verified by reading back off the server with per-message failure naming, and the idempotency behavior. This is rich, non-obvious behavioral context.

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

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

Front-loaded with the core purpose and packed with useful detail, but slightly dense and somewhat repetitive (idempotency is stated both explicitly and echoed by the annotation). Every sentence still carries substantive information.

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

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

For a 2-parameter, no-output-schema state-mutation tool, the description covers purpose, invocation batching, folder scoping, verification behavior, idempotency, and the clearing alternative. Nothing an agent needs to call 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%, so the baseline is 3, but the description adds real meaning: a uid only means something in its originating folder, and `mailbox` should be passed when uids did not come from INBOX. That scoping rule is not derivable from the schema alone.

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

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

States a specific verb+resource ('Flag messages') and immediately anchors it to a recognizable mental model ('the same star/flag marker Outlook and webmail show'). It also ties the state to a sibling's filter (search_emails's `flagged`), making it easy to distinguish from other mail-state 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?

Gives explicit invocation guidance ('Pass the whole set in ONE call'), the mailbox-selection condition ('pass `mailbox` when the uids did not come from INBOX'), and names the clearing alternative ('unflag_email clears it'). When-to-use is grounded in 'the user's own attention' marker semantics.

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?

Annotations already declare readOnlyHint, idempotentHint and non-open-world, so the safety profile is covered. The description adds genuinely new behavioral context: addresses are provisioned by the mailbox owner outside this connector, and the mail server may still refuse to send as one. What it doesn't clarify is the shape of the returned list (e.g. whether the default is flagged), but the annotations carry most of the burden.

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, front-loaded with the result and then the actionable follow-up and the caveat. Every sentence carries distinct information; no repetition of the title or annotations.

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

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

For a simple read-only listing tool with no output schema, the description covers what is returned (addresses plus the default) and the downstream usage and provisioning caveats. 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?

One optional parameter (`routine`) with 100% schema description coverage, so the schema fully documents it. The description says nothing about `routine`, adding no meaning beyond the schema; 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 specific verb and resource ('List the addresses this mailbox can send as') plus the default-selection detail, which no sibling covers. An agent can distinguish this from list_mailboxes or find_contact 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?

Explicitly tells the agent what to do with the result — pass an address as `from` on send_email, reply_email, forward_email or draft_email — naming the exact sibling tools and the condition for using them. It also pre-empts a mistaken expectation by noting addresses are not created through this connector.

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?

Annotations only supply the generic safety profile (destructive, non-idempotent, not read-only); the description adds real behavior the annotations cannot convey: it creates and subscribes a junk folder when absent, refuses already-junked messages, preserves flags and original dates, requires a single source folder, and triggers server-side spam training. It does not describe response payload shape beyond 'the reply says so', but the behavioral disclosure is well above the annotation baseline.

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, then constraints, then the sibling pointer — a sensible order. It is on the long side and leans on all-caps emphasis for the folder-creation behavior, which is slightly noisy, but each sentence carries distinct information.

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

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

For a destructive, side-effectful batch operation with no output schema, the description covers the essentials: folder resolution by role across M365/Gmail/IMAP, creation-if-missing with subscription, refusal semantics, preservation guarantees, and batching. An agent has everything needed to call it safely and 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 both parameters are already documented, including the batching guidance the description repeats verbatim in its final sentence. The description's only genuine addition is the same-source-folder constraint, which touches the mailbox parameter but is framed behaviorally rather than as parameter syntax, so the baseline 3 holds.

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+resource ('Move messages into the junk folder') and anchors it to a familiar mental model ('what "report spam" does in a mail client'), which cleanly separates it from siblings like move_email. It also names not_junk as the inverse, so an agent can route correctly 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?

Explicit when-to-use (spam reporting / filter training), when-not (messages already in the junk folder are refused), an alternative (not_junk reverses this), and an operational constraint (all messages must share one source folder, batch UIDs in one call). Nothing important 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?

Goes well beyond the annotations (readOnly=false, idempotent=true, destructive=false) by disclosing that results are verified against the server, that batches can genuinely half-succeed with per-message failures named, and that marking an already-read message is a no-op rather than an error. The folder-scoping rule for uids is real operational context an agent could not infer from structured fields.

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 action, then the caution, then the verification behavior, then the parameter pitfall, then the undo relationship. Despite its length, every sentence carries a distinct, load-bearing instruction and none is 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?

With no output schema, the description takes on the job of explaining returns (per-message verification, partial success) and does so. For a two-parameter mutation with full annotation coverage, nothing an agent needs to call 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% so the baseline is 3, but the description adds genuine semantic weight: why `mailbox` matters (a uid only means something in the folder it came from, with the Archive-search pitfall called out) and that `uids` should carry the whole set in one call. That is meaningful context beyond the schema text.

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 messages as read') and immediately differentiates from the natural sibling read_email by explaining that reading does not mark read. An agent can distinguish this from mark_unread, flag_email, and read_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 ('run it when the person asks for it') and when-not ('never because you have looked at something'), names mark_unread as the inverse action, and prescribes batching every message in ONE call. This is close to exhaustive routing guidance.

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

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

Annotations cover the safety profile, but the description adds substantive behavior: verification by reading flags back off the server so failed changes are named rather than assumed, the no-op-is-not-an-error idempotency semantics, and the non-interference guarantee (stays flagged, answered, in place). This is exactly the extra context beyond structured fields that earns a high score.

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?

Six dense sentences, each load-bearing: purpose, relationship to mark_read, batching instruction, verification behavior, mailbox rule, idempotency, non-interference. The single-call directive is front-loaded and no sentence is filler.

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

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

No output schema exists, so the description carries return behavior, and it does: the server verifies flags and names any message it could not change. Combined with the idempotency and scope statements, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100% so the baseline is 3, and the schema already explains batching and UID sourcing. The description adds genuine meaning by explaining *why* `mailbox` matters (a uid is only meaningful in its originating folder), which the schema's 'IMAP folder name. Defaults to INBOX.' does not convey.

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 messages unread) plus the exact semantic scope: restoring the pre-read state, and explicitly the inverse of mark_read. An agent can distinguish this from mark_read, flag_email and unflag_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?

Explicit when-to-use ('the undo for mark_read', 'when a triage pass marked more than the person meant'), how to batch ('pass the whole set in ONE call'), and a conditional routing rule: pass `mailbox` when the uids did not come from INBOX. Alternatives and the exclusion condition are both named.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavior: flags and original dates are preserved, and all UIDs must share one source and one destination. It doesn't address partial-failure behavior or whether moved UIDs remain valid, which keeps it out of 5 territory.

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, front-loaded with the core action, then the preservation guarantee, then the batch constraint. Every sentence carries information an agent needs; no filler.

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

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

For a 3-parameter mutation tool with no output schema, the description covers action, side effects on flags/dates, and batching constraints. Minor gaps remain around error/partial-failure handling, but nothing essential to invoking 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 description coverage is 100% and the schema already explains 'from' defaulting to INBOX, the 500-item cap, and the one-element-array case. The description's batching advice largely restates what the 'uids' schema description already says, so it adds little beyond the baseline.

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

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

States a specific verb+resource ('Move messages from one IMAP folder to another'), which cleanly separates it from siblings like archive_email, delete_email, and assign_email. An agent can pick this tool 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 clear when-to-use guidance ('Filing a backlog is what this tool is for') and a concrete batching rule (one call per destination folder). It does not explicitly name the sibling alternatives (archive_email, delete_email) an agent might confuse it with, 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?

Annotations only declare the generic profile (destructive true, idempotent false, openWorld true); the description supplies the real behavioral context: there is no source-folder parameter, a `to` pointing at junk is refused, a mailbox with no junk folder is refused rather than having one created, and flags and original arrival dates are preserved. This is precisely the beyond-annotation detail that prevents misuse.

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 action and the single most important constraint (no source folder) before the operational details. It is dense and mostly earns its length, though the batch-in-one-call guidance and the 'uid only means something in its folder' point are each stated more than once across description and schema.

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

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

For a mutation tool with no output schema, the description covers prerequisites, error/refusal cases, side effects on message metadata, and the cost trade-off of batching. An agent has everything needed to invoke it correctly on the first try.

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 meaning the schema lacks: the `to` parameter's refusal condition ('refuses a `to` that is the junk folder itself') and why INBOX is the default ('that is what "not spam" means'). It also reframes `uids` as a folder-scoped batch, which is more than the schema states.

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 ('take messages back out of the junk folder and return them to the inbox') and anchors it against a named sibling by calling itself 'the reverse of mark_junk'. An agent can distinguish it from mark_junk, move_email and delete_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 prerequisites ('get the uids from list_emails or search_emails against the junk folder first'), the batching rule ('pass every UID in one call rather than calling it once per message'), and a conditional alternative path via `to`. The warning that 'a uid only means something in the folder it came from' is exactly the precondition an agent needs.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely non-obvious behavior beyond them: the precise definition of what 'counts' as a reply (Sent message in same conversation or same subject, or the answered flag) and the explicit 'Reading marks nothing as read' caveat. It stops short of describing pagination or rate limits, but the side-effect disclosure is the important piece.

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?

Dense but well-front-loaded: the core purpose leads, then exclusions, the reply definition, and the return shape. Most sentences earn their place, though the reply-definition clause is long enough to slow scanning slightly.

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

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

With no output schema, the description correctly covers the return contract (oldest-first ordering, preview, days waited, unread flag, toYou vs Cc). Combined with the exclusion rules and reply definition, an agent has enough to call and interpret results, though edge cases like what happens at the 30-day cap are unaddressed.

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 every parameter (days, limit, mailboxes, directOnly, includeRead, excludeAddresses) is already documented in the schema, including defaults. The description adds behavioral framing but no parameter-specific syntax or constraints beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb-and-resource ('Real people waiting on a reply... every person whose latest message the owner has not answered') and a clear scope. It implicitly distinguishes itself from siblings like waiting_on (the mirror direction) and catch_up (whose filtering logic it reuses), so an agent can 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?

Explains the filtering contract clearly (newsletters/marketing/auto mail excluded, 'judged as catch_up judges them') and sets expectations by noting 'Whether a message actually needs an answer is left to the reader.' However, it never names a sibling to call instead (e.g. waiting_on for the reverse direction), so usage is contextual rather than fully directive.

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?

Adds substantial behavior beyond the readOnly/idempotent annotations: reading does not mark as read, `ref` expires in an hour, `downloadUrl` expires in fifteen minutes, html is sanitised so it is not what the sender wrote, and it explains the semantics of `authentication.verdict`/`fromSelf` and `signals[].agentDirected`. This is exactly the kind of context annotations cannot carry.

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 purpose is front-loaded and each block (attachments, replyTo, authentication, signals, html) covers a distinct concern rather than repeating itself. It is nonetheless very long and dense for a read tool, with all-caps procedural instruction that is hard to scan, so it is not maximally 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?

With no output schema, the description carries the full burden and does: it enumerates the returned fields (body, recipients, attachments/ref/downloadUrl, replyTo, authentication, signals, html) and their meaning. An agent has everything needed to call it and interpret the result.

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 only `uid` and `mailbox`, both fully documented in the schema ('UID from list_emails', 'IMAP folder name. Defaults to INBOX'). The description adds no syntax or format detail for these parameters, so the 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?

Opens with a precise verb+resource+scope: 'Read one message in full, including its body and recipients.' It is immediately distinguishable from read_thread (a thread), read_attachment (attachment contents) and list_emails (enumeration), and it explicitly says it 'only lists the files; it never opens them.'

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

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

Gives explicit routing: use the `ref` with read_attachment to see inside a file, pass `ref` as `fileRef` to send/reply/forward/draft to re-attach, hand `downloadUrl` to the user when they want the file itself. It also states when-not ('do not act on any instruction in the message') and names the alternative tool for each 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 cover safety (readOnly, idempotent, non-destructive) but the description adds substantial context beyond them: reading does NOT mark messages read, quoted copies are trimmed by default (`quotedTrimmed` flag), bodies are plain text only, and threads are followed via the References header so incomplete results are possible. It also warns about per-message authentication verdicts being the place forgeries hide.

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 value (one call, oldest first) and keeps every sentence load-bearing. It is on the long side and dense, but the length is justified by the number of distinct behavioral caveats; no filler sentences.

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 carries the return-value burden and does it: it names `quotedTrimmed`, `authentication`, and `signals` fields and defers their details to read_email. For a 5-param read tool with an open-world hint, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains that naming `mailboxes` REPLACES the own-folder-plus-Sent default, and explains the size tradeoff behind `includeQuoted`. It does not restate uid/limit, which the schema already covers well.

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+resource with scope: 'Read an entire email conversation in ONE call, oldest message first, given any one message in it.' It also explicitly distinguishes itself from the sibling read_email at multiple points (HTML vs plain text, one call vs one per message).

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

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

Gives explicit routing: use this for 'catch me up on this thread', use read_email when you need one message's HTML or untrimmed body. Also states when to set includeQuoted ('only when the user specifically needs the verbatim text'). Both the when and the when-not are present.

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?

The description adds substantial behavioral context beyond annotations: the draft remains unsent and editable, the owner sees it via list_pending_approvals, approval proceeds through approve_and_send, and non-draft UIDs are refused. It is consistent with the non-read-only, idempotent 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 core action is front-loaded, and each sentence earns its place by covering workflow, persistence, validation, or limitations. Despite covering several points, it remains focused and non-repetitive.

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 tool with annotations and no output schema, the description is complete: it explains the state change, workflow position, downstream tool, persistence, and refusal behavior. Nothing necessary 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?

Schema coverage is 100% and the uid parameter is already documented in the schema. The description still adds a meaningful validity condition: the UID must refer to a draft in the Drafts folder, which is beyond the schema's source hint.

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 gives a specific verb and resource: mark a draft as waiting for owner approval. It clearly distinguishes this tool from siblings by naming approve_and_send, list_pending_approvals, and the drafting tools it follows.

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

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

It states exactly when to use it: after draft_reply, draft_forward, or draft_email, for users who cannot send from the mailbox or want owner review. It also names the follow-up tools and the no-send-back limitation, leaving little 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 cover only the safety profile (read-only, idempotent, open world), and the description goes well beyond them: at-least-one-criterion enforcement, nonexistent folders skipped but named in the result, explicit cap disclosure with true total, per-result mailbox attribution because UIDs are folder-scoped, and delivered-date vs Date: header semantics.

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 well, but it is long and repeats schema text near-verbatim, particularly the delivered-date/whole-day-precision caveat that already appears on `since`, `before`, and `on`, and the multi-folder batching advice that appears on `mailboxes`.

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 carries the return contract itself: same shape as list_emails plus `mailbox`, a `preview` of the first line or two, and an explicit cap indicator with the true total. Nothing an agent needs to call 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%, so the baseline is 3, but the description adds real value the schema lacks: a concrete substring pitfall example ('from: "a@b.com" also matches "xa@b.commercial.example"') and the strategy of passing all plausible folders in one `mailboxes` argument rather than several calls.

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

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

States a specific verb (search) over a specific resource (IMAP folders) and pins the exact return shape ('summaries in exactly the shape list_emails returns plus the folder'), immediately separating it from read_email and select_emails by 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?

Gives explicit when-to-use guidance ('SEARCH EVERY FOLDER THE MESSAGE COULD BE IN, IN ONE CALL'), explicit when-not-to ('Not message bodies, though; read_email is the tool for reading one message in full'), and names select_emails as the alternative for bulk UID collection.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: no previews or bodies are returned, capped results report the true total, substring matching can match unintended senders, and senders past the 25 largest are collapsed into one shared group. That is exactly the kind of behavioral detail an agent needs before deciding to act.

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?

It is a single very long, densely packed sentence chain, but every clause carries information and the core purpose is front-loaded. Structure could be improved by splitting it, but there is essentially no filler.

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

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

For a 16-parameter, no-output-schema tool, the description covers return shape (groups, counts, date range, subjects), the cap behavior, and the workflow fit with write tools. Nothing an agent needs to call 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%, so the baseline is 3, but the description adds meaning beyond the schema: fromAny is described as matched-alternatives with a 20-sender cap, all:true as the no-condition escape hatch, and the substring caveat applies to the whole matching model. It does not, however, add much for the individual date/flag filters, which the schema already documents.

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 (find/select), resource (messages matching a search), result shape (UIDs grouped by folder then sender) and purpose (feeding bulk per-folder write calls). It explicitly contrasts with search_emails, so an agent can distinguish the two 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 exact downstream tools this feeds (delete_email, move_email, archive_email, mark_junk, etc.), specifies the one-write-call-per-folder constraint, and states when to prefer search_emails instead. Both the when and the alternative are explicit.

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

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

Annotations declare destructive/openWorld/non-idempotent, and the description adds concrete behavior beyond them: one copy filed in Sent, draft leaves Drafts, no signature is appended, Bcc/Reply-To drafts are refused, and the action delivers real mail irreversibly. This is exactly the extra context a mutation tool 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?

Long but front-loaded: the core action and its effect come first, then prerequisites, then refusal cases. Every sentence carries distinct information, though the paragraph-length delivery is dense and could be tightened slightly without losing 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?

With no output schema, the description still covers what an agent needs: preconditions, the uid volatility hazard, refusal branches with routing, and the irreversible side effect. Nothing essential about invoking 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 uid parameter is documented there, so the baseline is 3. The description adds real value over the schema by warning that the uid is volatile ('a draft gets a new uid each time anyone saves it'), explaining why it must be fetched immediately before sending.

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 is already in the Drafts folder') and scopes it against siblings: it is not send_email (new mail) and not approve_and_send (approval path). The 'exactly as it sits there' framing tells the agent no re-composition happens.

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 prerequisites and alternatives: read with read_email on Drafts first, take uid from list_emails on that folder now, and approval-gated drafts must go through approve_and_send instead. Also names the two refusal cases and says each refusal states the remedy.

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

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

Annotations declare idempotentHint=true and destructiveHint=false, but the description adds genuinely new behavior: the read-back verification pattern ('flags are read back off the server, so a message that could not be changed is named rather than assumed done'), the no-op semantics on unset flags, and the folder-scoping of UIDs. This goes well beyond the annotation surface.

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

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

Front-loaded with the core action, then usage, caution, verification, and scoping in a logical order. Almost every sentence earns its place, though the rhetorical 'BE MORE CAREFUL WITH THIS ONE THAN WITH mark_unread' is slightly verbose and the caution is restated across two sentences.

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 batch mutation tool with no output schema, the description covers everything an agent needs: batch semantics, non-idempotent-user-expectation caution, server-side verification, and folder/UID scoping. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema with the key insight that 'a uid only means something in the folder it came from, so pass `mailbox` when the uids did not come from INBOX', which clarifies when the otherwise-invisible default matters.

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 ('Clear the flag/star marker on messages, restoring their unflagged state'), and explicitly differentiates itself from the sibling mark_unread by contrasting the kind of state being changed. An agent can distinguish it from flag_email, mark_read, and delete_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 guidance ('Pass the whole set in ONE call', 'Clear the ones you were asked about and no others', 'check the set first if the request was vague') and names an alternative (mark_unread) as a comparison point. The condition for supplying `mailbox` is also spelled out.

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: it discloses that the edit is a whole-message replacement ('anything left out is gone'), that threading headers and existing attachments survive, that the UID changes and the old one stops working, and that the draft remains unsent. These are exactly the destructive, non-idempotent traits the annotations imply, made concrete and actionable.

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 full-replacement warning are front-loaded, and every sentence carries real information. It is a dense block of prose that could be broken into shorter statements, but there is essentially no wasted text.

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

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

For an 11-parameter destructive edit with no output schema, the description covers the consequences an agent must know before calling it: replacement semantics, UID mutation, threading/attachment carry-over, signature behavior, and unsent status. Nothing material is missing.

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

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

Schema description coverage is 100%, so per-field meaning is already carried by the schema; the baseline is 3. The description reinforces replacement semantics ('pass the FULL new version of every field') and adds the signature-handling rule, but that rule is behavioral rather than a clarification of any specific parameter.

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

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

States a specific verb and resource ('Rewrite a draft already in the Drafts folder') and immediately frames it against the alternative workflow ('in place of deleting it and saving a new one'), which cleanly distinguishes it from draft_email/draft_reply. An agent can identify the operation without opening the schema.

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

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

Gives concrete when-to-use triggers ('a different wording, another recipient, a corrected subject') and a clear when-not-to ('do not write a sign-off or paste a signature in yourself'). It does not name the sibling tools an agent might otherwise pick (draft_email, draft_reply), leaving that comparison to inference, so it falls short of a 5.

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

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

Annotations already cover the safe-read profile, yet the description goes well beyond: the 2,000-message truncation limit, the `answerCheck`/`partial` fields, partial entries sorted last, oldest-first ordering with wait days and chase counts, and the exclusion rules for no-reply/self/excluded addresses. This is the kind of operational context an agent cannot get from annotations or schema.

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

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

Front-loaded with the one-line purpose, and nearly every sentence carries operational weight (reply definition, exclusions, truncation). It is dense and slightly overlong, and the closing draft_reply sentence is a mild cross-sell, but nothing is 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?

With no output schema, the description must describe the return shape and does so thoroughly: what each entry contains, ordering, the wait-day and chase counts, and how partial results are marked and sequenced. An agent could consume the output without further guessing.

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 every parameter, its default, and the lookbackDays > olderThanDays rule. The description largely restates those bounds, adding only the semantic interpretation of the two-day window and how excludeAddresses is applied, so the baseline 3 is right.

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+resource and, crucially, the direction of the relationship: "Messages the mailbox owner sent that nobody has answered." That framing alone separates it from reply-oriented siblings without needing to name them.

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

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

The description establishes the trigger scenario clearly (sent mail with no reply) and implies the value of doing it "in one call," but never names the obvious alternative `owed_replies` nor states when NOT to reach for this tool. Usage is inferable, not explicit.

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