Multi Mail

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

With annotations already declaring a non-destructive write, the description adds useful behavioral detail: the draft remains in the mailbox, unconfirmed addresses should not be written to, and signatures are inserted by default unless sign=false. It still does not cover error or permission behavior, but the added context is substantive.

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 the content is information-rich, but the description is a dense single paragraph with long nested clauses. It is not wasteful, yet it is harder to parse than necessary for an agent deciding how to call the tool.

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

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

The tool has an output schema, rich annotations, and full schema description coverage, so the description need not explain return values or every parameter. It adds important draft and signature context, though it could more explicitly distinguish this tool from sibling draft operations.

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 parameters thoroughly. The description adds some meaning around sign/from signature behavior, but it does not need to compensate for missing parameter documentation and does not explain most of the 13 parameters.

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

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

The description states a specific action and resource: 'Compose an email in a connected mailbox and keep it there as a draft.' This makes clear it creates a draft rather than sending, but it does not explicitly differentiate from siblings such as drafts_update or drafts_send.

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

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

It provides workflow guidance for finding an address in past mail and for handling signatures, including 'sign false leaves it off a terse note.' However, it does not explicitly say when to use this instead of drafts_update or drafts_send, leaving the sibling selection mostly implied.

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

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

Annotations already flag destructiveHint=true, so the bar is lower — yet the description adds real behavioral context: the draft goes to the provider bin, remains under provider retention, is restorable to a draft via threads_untrash with the returned messageId, and is refused for already-sent messages. That is precisely the mutation detail an agent cannot get from the annotation.

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 action is correctly front-loaded in the first clause, but the remainder is a dense colon-and-dash chain that fuses the restore path, the retention caveat, and the refusal rules into one long sentence. Every fact is relevant, yet the packing makes the restore instructions easy to misread.

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

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

For a two-parameter destructive tool with an output schema, the description covers what an agent needs: what happens to the object, when the call is refused, and how to undo it. The one soft spot is the unexplained `messageId` reference, which is never tied back to this tool's returned id.

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 both `id` and `mailbox` are already documented, and the baseline of 3 applies. The description does not add syntax or format guidance for either parameter; its only reference is `messageId`, which is not a parameter of this tool and could momentarily confuse an agent about what to pass.

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

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

Opens with a specific verb+resource: "Move a draft to the bin." It also names the fallback/sibling mechanism (threads_untrash) and the scope value needed, so an agent can separate this from threads_trash or drafts_update 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 eligibility rules are given: only a draft not yet sent moves; sent or received messages are refused, and a message already named by a send through Lumman is refused too. It also tells the agent how to reverse the action. What's missing is a direct routing statement against nearby siblings such as drafts_update or threads_trash.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), it discloses the key traits an agent cannot infer: nothing is transmitted until sent, an unverified address must be confirmed before being written, signatures land below the agent's words and above the quote, sign=false suppresses them, flag works only on Outlook, and from-address latitude differs by provider (Gmail verified aliases vs. Outlook's own address only).

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

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

Purpose is front-loaded in the first sentence, which is good. But the remainder is a single dense paragraph of heavily nested em-dash clauses ('the newest found with to: and their address whose sender is an address mailboxes_list names') that are hard to parse on first read; the oblique phrasing costs more comprehension than the word count saves.

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 13 parameters, nested attachment variants, and an output schema already declaring return values, the description covers the non-obvious decision points: address confirmation, signature placement, provider-dependent from behavior, and thread placement. Return shape is correctly left to the output schema; only a brief note on draft state after creation is arguably thin.

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 per-parameter descriptions are themselves unusually rich (chatFiles vs attachments, contentId inline images, the upload-address handshake), so the schema carries the load. The description adds little param-level detail beyond the sign/signature rule and the from-address provider constraints, which are partly restated. 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?

Opens with a specific verb+resource ('Compose a forward of a message as a draft') and adds two scoping qualifiers — the files it carries and the thread it already sits in. Combined with 'Nothing leaves the mailbox until the draft is sent,' an agent can distinguish this from messages_forward (sends now) and drafts_create (new message) 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 concrete operating procedure: unresolved addresses must be looked up via messages_list_all_mailboxes with from:/to: at headers view and confirmed by the person before being written. It does not explicitly name drafts_create or messages_forward as alternatives, so the routing is implied by 'as a draft' rather than stated.

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

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

Beyond the annotations, it discloses that the operation creates a draft rather than sending, how unknown addresses are resolved and confirmed, how signatures are placed, and how sender address selection differs by provider. These are substantive behavioral details 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?

The description is a long, dense paragraph with nested dashes and parenthetical clauses that make it hard to parse. The purpose is front-loaded, but the remaining prose is far from concise and includes complex procedural guidance that could be structured more clearly.

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 14-parameter schema, rich parameter descriptions, and an output schema, the description covers the critical non-obvious behavior: draft-only semantics, recipient selection, signature handling, and sender address constraints. It does not explain every parameter, but the schema already does so in detail.

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 14 parameters in detail. The description adds some recipient and signature context, but much of that overlaps with the schema's own parameter descriptions, making the baseline 3 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 opening clause states a specific verb and resource: compose a reply to a message as a draft, threaded and quoting the original. It distinguishes draft creation from sending, but it does not explicitly compare itself with sibling tools such as messages_reply or drafts_create.

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

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

The description implies when to use it by saying 'Nothing leaves the mailbox until the draft is sent,' and it explains replyAll, cc, and signature choices. However, it does not explicitly name alternatives or state when another draft or reply tool should be chosen instead.

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 destructive/open-world annotations it discloses that the draft is consumed, that the send is an external irreversible act ("leaves the mailbox"), the requestId idempotency contract (a spent id sends nothing again and the answer reports whether the send went or may have gone), and that afterwards runs under another tool's permission yet the mail still goes if that step fails.

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 effect and the draft-only constraint are front-loaded, and every sentence carries substance. The framing line about mail "asked to go" vs. "asked to prepare" is slightly discursive for the value it adds.

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 annotations covering the safety profile and an output schema covering return values, the description still supplies what an agent actually needs: the draft-only precondition, the consumption of the draft, the idempotency rule, and the failure semantics of the afterwards option.

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 descriptions already explain id, mailbox, requestId dedup, and the afterwards side effect, so the schema does the heavy lifting. The description's requestId sentence largely restates what the schema already says, adding only that the response reports whether the send went or may have gone.

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?

"Send a draft. It leaves the mailbox and consumes the draft." gives a specific verb and resource plus its effect, and "Only a draft is sent: a message already sent or received is refused" separates it from messages_send without requiring the schemas to be opened.

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 draws the intended boundary ("mail the person asked to go" vs. "mail they asked to prepare") and states the hard precondition that the target must still be a draft. It never names messages_send explicitly as the route for composing new mail, so the routing is clear but not 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?

The description adds substantial behavior beyond the annotations: omitted fields are preserved, Gmail and Outlook handle subject/conversation changes differently, imap drafts move to a new id, the old id stops resolving, and a previous version may remain as previousVersionId. It also discloses attachment replacement semantics and Outlook-specific caveats, which is rich transparency for a destructive mutation.

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 in the first sentence, but the description is a dense, meandering paragraph with archaic phrasing and many semicolon-linked caveats. Most content is relevant to a complex mutation, but the structure makes it harder to parse than necessary.

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

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

Given 10 parameters, full schema coverage, annotations covering destructive behavior, and an output schema, the description is largely complete about side effects and provider-specific outcomes. It could be stronger with explicit routing to sibling draft tools and clearer permission expectations, but the behavioral picture is sufficiently detailed.

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 the baseline is 3. The description still adds useful parameter meaning, especially that a new subject can move a Gmail draft to its own conversation and that omitted fields retain their existing values, going beyond the schema's short field descriptions.

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

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

The description clearly states the specific action: changing an existing draft in a connected mailbox. It distinguishes the operation from creating or sending a draft through the word 'Change' and the resource 'draft', but it does not explicitly differentiate from sibling tools such as drafts_create or drafts_send.

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 'Change a draft' and by details such as omitted fields staying unchanged, but the description never explicitly says when to use this tool instead of drafts_create, drafts_send, drafts_reply, or drafts_delete. It gives some procedural guidance around confirming an unlisted address, but no clear exclusions or alternatives.

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

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

The annotations already establish that this is a non-read-only, non-destructive mutation. The description adds important behavioral context beyond the annotations, especially that a slash nests labels and that missing parent labels are created first, and it distinguishes Outlook folders from categories. It does not cover duplicate-name behavior or failure modes, 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?

The first sentence is front-loaded and clear, but the second sentence is grammatically tangled and difficult to parse: 'In a Gmail mailbox, and as a folder in one whose provider is imap or in an Outlook mailbox, a / nests it...' The content is useful, but the structure could be cleaner.

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 an output schema and annotations present, the description does not need to explain return values or safety hints. It covers the key mailbox-provider semantics and the parent-label creation side effect, though it omits duplicate handling and error behavior, leaving a small completeness gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema by explaining that slash characters create nested labels and that in Outlook a name containing a slash or folder=true creates a folder rather than a category.

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

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

The description uses a specific verb and resource: 'Create a label in a connected mailbox.' It also states that the tool returns the label id, and its create semantics clearly distinguish it from sibling tools such as labels_update, labels_delete, and labels_list.

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

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

The description implies that this tool is for creating labels and explains provider-specific behavior, but it does not explicitly say when to use it instead of labels_update or labels_list, nor does it state when not to use it. Usage is inferable but not directly guided.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description goes well beyond them by disclosing that no messages are deleted and that effects differ by provider (Gmail label removed from every message, Outlook category removed from the list, messages keep the name). The final sentence about imap is worded so ambiguously ('deletes only a folder holding no mail and no folder') that the critical edge case is hard to parse, which keeps this from 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?

The action is front-loaded and the 'No message is deleted' clause earns its place, but the provider sentence is dense and the trailing imap sentence is convoluted enough that a reader must re-parse it. That sentence arguably fails to earn its place in its current form.

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 annotations covering the destructive/idempotent profile and an output schema present, the description supplies the remaining piece an agent needs: what actually happens to messages under each provider. The only gap is the muddled imap behavior, which leaves one provider's outcome uncertain.

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 both parameters are already documented; the description only reinforces that id comes from labels_list. It adds no format, constraint, or failure-mode detail beyond the schema, 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 ('Delete one label') plus the identifier source ('by its id from labels_list'), which separates it cleanly from labels_create and labels_update. An agent knows exactly what the tool 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?

It gives clear operational context: the id must come from labels_list, and it explains the message-level consequences of deleting. It does not explicitly say when to prefer labels_update over delete, nor does it warn to confirm before invoking a destructive call, so no true exclusions 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?

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description is free to add the genuinely useful part: how labels differ per provider (IMAP folders, Outlook categories/folders with counts, Gmail system labels and CATEGORY_* tabs) and which Outlook folders are excluded. It stops short of describing pagination or ordering, but the provider semantics are real added value.

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 information is front-loaded correctly (what it lists, then per-provider semantics), but it is one dense paragraph with run-on sentences such as the Outlook sentence stacking path, counts and unread counts. Phrases like "Gmail's mark of what matters" are filler that dilute an otherwise technical description.

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?

An output schema exists, so return shape need not be explained, and the description instead supplies the interpretive context an agent needs to read label ids and types. Pagination and result limits are the only notable omissions for a list operation.

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

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

Schema coverage is 100% with a single well-described 'mailbox' parameter (name or email), so baseline is 3. The description reinforces the notion of a 'connected mailbox' with provider-dependent behavior but adds no syntax or format detail beyond the schema.

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

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

The first sentence gives a specific verb and resource: listing the labels a mailbox holds, keyed by label id. It is unambiguous against the mutation siblings (labels_create/update/delete), but it never explicitly contrasts itself with those siblings or with threads_get which also surfaces label ids.

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 only implied: an agent can infer from 'List' and readOnlyHint that this is the discovery step, and the closing reference to threads_modify hints at how labels are consumed. There is no explicit 'use this before labels_update or threads_modify to obtain ids' statement, and no exclusions.

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

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

Annotations already flag destructive and idempotent behavior, but the description adds meaningful non-obvious effects: a new name carries nested labels, Outlook category/folder constraints apply, and an IMAP rename answers the label's new id. These details go well 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 purpose is front-loaded and the provider-specific cases are packed efficiently into four sentences with little waste. The phrasing 'by / with it' is slightly awkward, and the provider detail density keeps it from being maximally crisp.

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 provider-sensitive update tool, the description covers the key cases and relies appropriately on the schema for parameter details and the output schema for return values. No major behavioral or usage omission remains.

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

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

Schema coverage is 100%, so the schema already documents all four parameters and the colour enum. The description still adds provider-dependent meaning for name and colour, though it does not add syntax or enum details beyond the schema.

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

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

The opening sentence gives a specific verb and resource ('Rename a label, recolour it, or both') and clearly identifies an edit operation. It references labels_list as the id source but does not explicitly distinguish this tool from labels_create or labels_delete.

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 the prerequisite that the id comes from labels_list and gives provider-specific applicability rules, such as Outlook categories taking only a new colour and Outlook folders only a new name. It does not explicitly say when not to use the tool or name create/delete as alternatives.

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

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

Annotations already cover the safety profile (readOnlyHint true, destructiveHint false, openWorldHint false), so the description only needs to add context, and it does: it discloses the exact per-mailbox attributes returned, including reconnect-needed state and provider/toggle limitations. "It counts no action" adds a behavioral trait not present in any structured field, though the phrasing is opaque enough to be only partly useful.

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 long run-on sentence built from dashes and comma-separated clauses, which makes the field inventory hard to parse at a glance. The verb and resource are front-loaded, which is good, but the trailing enumeration of returned attributes is dense and could have been a compact list or omitted given the output schema.

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

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

For a zero-parameter read tool with full annotation coverage and an output schema, the essential information is present and no critical gap exists. The main omissions are the relationship to messages_list_all_mailboxes and clarification of the cryptic "counts no action" claim, and much of the text duplicates what the output schema already declares.

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 takes zero parameters, so there is no parameter meaning to add and the baseline of 4 would normally apply. The description instead spends its words on return-value attributes, which are already covered by the output schema, so it neither compensates nor harms — a middling 3 reflects the absence of any parameter-relevant contribution.

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

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

"List the connected mailboxes" gives a specific verb and resource, then enumerates the providers covered (Gmail, Outlook.com/Hotmail, Microsoft 365, generic IMAP), so the scope is unambiguous. It stops short of distinguishing itself from the sibling messages_list_all_mailboxes, which an agent could plausibly confuse with this tool.

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

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

The phrase "each by the name a tool's mailbox input takes" implicitly tells the agent to call this first to discover valid mailbox identifiers for other tools, which is useful usage context. However, there is no explicit when-to-use statement, no exclusion, and no mention of the messages_list_all_mailboxes alternative, so the guidance is only implied.

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

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

Goes well beyond the readOnly/non-destructive annotations: discloses that text mode returns plain text, original returns base64 bytes or a downscaled picture, and that the answer carries a link valid for 15 minutes served to a credential-free GET. Even supplies a concrete curl invocation with its failure 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 action and mode selection before the link/curl detail, and every sentence carries information. The prose is somewhat run-on and the curl paragraph is dense, but nothing is 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?

Covers mode selection, size/continuation behavior, how the id is obtained, and how to retrieve the original via the expiring link — enough that an agent can call it correctly even though an output schema also exists.

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; the description still adds value by clarifying what `as` yields in each mode (base64, shrunk picture) and that `continuation` only affects text mode while the original always comes whole.

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 one attachment of a message") and implicitly distinguishes itself from messages_get/threads_get, which only name attachments and sizes. An agent can tell exactly which tool fetches attachment bytes versus which lists 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?

Names the prerequisite path explicitly ("messages_get and threads_get name a message's attachments and their sizes"), so the agent knows how to obtain the id. It also explains the text-vs-original choice and the fallback for oversized pictures, though it gives no explicit exclusions for when not to call 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?

Beyond the annotations it discloses the idempotency contract (a spent requestId sends nothing again, and the answer distinguishes 'went' from 'may have gone'), the signature placement relative to quoted text when sign=false, and provider-specific limits on carried files. It also implies side effects (write to the thread, optional signature injection) in a way annotations alone would not convey.

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

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

The core action is front-loaded in a clean first sentence, but the remainder is a single dense paragraph of long, heavily subordinated clauses that are hard to parse ('the words close as the person's own would'). Information is valuable but structure and phrasing cost readability.

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

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

Given a 15-parameter nested schema, an output schema, and full annotation coverage, the description covers the send-vs-draft decision, idempotency, signature behavior, and file carry limits. It leaves the flag, importance, afterwards, and multi-shape attachment mechanics entirely to the schema, which is acceptable but not exhaustive for a destructive send operation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning around signature and quote handling for note/html and echoes the requestId semantics already in the schema, but says nothing about cc, bcc, flag, importance, afterwards, chatFiles, or the four attachment shapes, so it does not meaningfully exceed 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 opening sentence gives a specific verb and resource with scope: forward one message, with its files, inside the thread it already sits in. It implicitly separates itself from drafts_forward ('mail they asked to prepare is a draft') but never names the sibling, so differentiation requires inference.

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 the selecting condition between sending and drafting ('It sends mail the person asked to go; mail they asked to prepare is a draft') and gives a prerequisite workflow for unverified addresses (look up in past mail via messages_list_all_mailboxes and have the person confirm). No explicit 'do not use when' clause, and the alternative tool is not 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?

With annotations already declaring a safe read-only, non-destructive, closed-world operation, the description adds useful behavioral context beyond those fields. It explains recipient truncation via omittedRecipients and timezone-offset formatting in the response, though it does not cover permission requirements or error cases.

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

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

The definition is front-loaded with a clear first sentence, but the later sentences about omittedRecipients and timezone formatting are convoluted and harder to parse than necessary. The content earns its place, but the phrasing is not concise.

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

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

The tool has a complete input schema, an output schema, and annotations covering safety, so the description need not explain every return field. It still adds context about recipient truncation and timezone representation, and is largely complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the id, view, and mailbox semantics are already documented in the schema. The description does not add parameter-specific syntax or selection guidance beyond what the schema provides, making the baseline 3 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 first sentence clearly states a specific verb and resource: reading one message in a connected mailbox, including headers and body. It distinguishes a single-message operation from list-style siblings through the phrase 'one message,' but it does not explicitly name alternatives such as messages_list or threads_get.

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

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

The description implies usage by saying it reads one message, but it gives no explicit guidance about when to choose this over messages_list, threads_get, or messages_attachments_get. There are no exclusions, prerequisites, or alternative-selection cues.

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, destructiveHint false, openWorldHint false), and the description goes well beyond them with pagination quirks ('a short page can have more after it'), the Outlook 1,000-result ceiling, imap notSearched reporting for folders not reached, and omittedRecipients truncation. None of this repeats the annotations and none of it contradicts them.

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 every clause carries information, but the prose is baroque and heavily post-modified ('the times it answers with carry their offset...'), making it slow to parse. Size is defensible for a 13-parameter multi-provider tool, yet the phrasing costs readability without adding precision.

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

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

Despite an output schema existing, the description names the notable response fields (notSearched, omittedRecipients, ceiling, now) that an agent must interpret to page correctly or explain truncated results. Provider-specific behavioral divergences for Gmail, Outlook and imap are all covered.

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 on top: that an Outlook mailbox without q reads one folder (inbox unless folder names another) while with q it searches every folder, which is a semantic interaction between q, folder and the provider that the schema does not state. The rest of the parameter detail remains in the schema, so it is not a 5.

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

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

Opens with a specific verb and resource: 'Search one connected mailbox in its own provider's query language... or list its mail by those inputs alone.' The phrase 'one connected mailbox' implicitly separates it from the sibling messages_list_all_mailboxes, and the q/keyword split makes the two modes of use 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 explains how the two modes work (query language vs. filter inputs alone) and gives per-provider scoping rules, but it never explicitly says when to pick this tool over messages_list_all_mailboxes, threads_get, or messages_get. Usage is implied by scope rather than stated as a decision rule.

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 read-only, non-destructive, non-open-world behavior, and the description adds substantial context: merged newest-first results, thread grouping by newest message, mailbox provenance, omittedRecipients counting, time-zone offsets, pagination behavior, and run-mark advancement rules. It also discloses provider-specific limitations for 'waiting' and query support.

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

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

The description is a single dense run-on paragraph with awkward phrasing and repeated provider-specific search-operator details. The purpose is front-loaded, but the rest is poorly structured and much of it duplicates the schema rather than earning its place.

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

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

For a complex multi-mailbox search with pagination, incremental runs, and waiting modes, it covers provider differences, result merging, partial pages, and failure reporting. The output schema handles return values, and the main missing piece is explicit routing guidance versus messages_list.

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

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

Schema description coverage is 100%, so all eight parameters are already documented in the schema, including the extensive provider-specific 'q' syntax and 'run' mark semantics. The description largely repeats that schema content and adds only limited additional meaning, such as 'Left out, every message is answered' for 'q'.

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: 'Search every mailbox you have connected - every email account at once - in one call, or only those mailboxes names.' The scope is clear enough to distinguish it from a single-mailbox search, though it does not name the sibling messages_list explicitly.

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 two main modes, all connected mailboxes or only named ones, and suggests incremental polling: 'the time of the last look is the cheapest way to watch for new mail.' The 'run' parameter description also covers scheduled repeated searches, but there is no explicit when-not guidance or named alternative.

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

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

Beyond the annotations, the description discloses idempotency behavior for requestId, replyAll recipient exclusions, signature placement and sign=false behavior, provider-specific from-address rules, Outlook-only flag behavior, and what afterwards does if archiving or marking read fails. These details materially inform safe invocation of a destructive send operation.

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

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

The purpose is front-loaded, but the description is a dense, run-on paragraph with nested clauses that are difficult to scan. Much of the content is valuable for this complex tool, but the phrasing is unnecessarily ornate and would benefit from tighter structure.

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

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

Given a 16-parameter send tool with full schema coverage and an output schema, the description covers the major behavioral concerns an agent needs: recipient resolution, replyAll semantics, requestId idempotency, signatures, from-address rules, and post-send side effects. Return details are left appropriately to the output schema.

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 parameters. The description adds useful cross-parameter semantics: recipient defaults when to/cc are omitted, signature placement relative to quoted text, requestId replay behavior, and provider-specific from-address constraints.

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

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

The description states a specific verb and resource: replying to a message inside its own thread and quoting it below the reply. It distinguishes this send action from draft preparation and clarifies recipient behavior with replyAll, making it identifiable against siblings such as drafts_reply and messages_send.

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 explains when this tool sends versus when the person asked only to prepare a draft, and it describes recipient defaults and how to find an address the person did not provide. It does not explicitly compare against messages_forward or state a general exclusion for new-message composition, but the send-versus-draft guidance is clear.

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

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

Annotations already declare destructiveHint, idempotentHint and openWorldHint, and the description corroborates and enriches them: a spent requestId 'sends nothing again' and the answer distinguishes 'went' from 'may have gone'. It adds provider-specific behavior (from-address restrictions on Outlook vs Gmail, flags only on Outlook), signature insertion order relative to quotes, and the partial-failure semantics of 'afterwards' where the thread action fails but mail still went.

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, which is good, but the body is one dense em-dash-chained paragraph where sentences such as 'the words close as the person's own would' or 'the manner they write to them in' are oblique enough to need re-reading. The content mostly earns its place; the packaging makes it harder to scan than it should 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?

For a 15-parameter, nested, destructive, provider-varying send, the description covers the hard judgment calls: send vs draft, address confirmation before use, idempotency, signature, and post-send thread actions. The multi-shape attachments flow (including the deferred HTTP PUT round-trip) is left entirely to the schema, and an output schema exists to carry return detail, so coverage is strong but not complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely extends several parameters: requestId gains retry semantics, `sign` gains signature placement and sign-off duplication rules, `from` gains per-provider address eligibility, and `afterwards` gains the permission-inheritance and failure caveat. It says nothing about attachments or chatFiles, but those are fully documented in the schema.

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

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

Opens with a specific verb and resource ('Compose a new message in a connected mailbox and send it in one call') and immediately draws the boundary against drafting ('mail they asked to prepare is a draft'), which separates it from drafts_create without opening either schema. The distinction is stated as a rule about intent, not just a label.

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 to siblings for sub-tasks: messages_list_all_mailboxes with from:/to: at the headers view to find an unknown address, mailboxes_list to identify the person's own addresses, settings_send_as_get for the signature. It does not, however, route the obvious alternatives for messages_reply, messages_forward or drafts_send, so those exclusions are 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?

The description goes far beyond standard behaviors by disclosing crucial behavioral traits, such as the rule refusing to carry mail out of the mailbox, the 'every condition must match' logic, and specific provider limitations (e.g., Gmail label vs. Outlook folder).

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 overly dense, repetitive, and excessively long. While exhaustive, it prioritizes technical detail over concise guidance, making it difficult for an agent to quickly grasp the core functionality without reading multiple sentences of caveats.

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 complexity of the tool (19 parameters and multiple provider variants), the description is maximally complete. It covers cross-platform nuances, limitations, and functional logic for every major component.

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

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

Although the schema coverage is 100%, the description adds vital semantic meaning, explaining the functional difference between parameters (e.g., what `folder` means on Gmail vs. Outlook) and the implications of complex field usage like `removeLabelIds`.

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 tool's purpose is clearly stated as creating a rule or filter for an email mailbox. It uses specific language to define what the rule does (categorizes, moves, marks as read) and how it interacts with the mailbox.

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

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

It provides excellent usage guidance by explicitly contrasting this tool with `sweeps_preview` (sweep/delete) and `focus` (Outlook category setting), helping the agent choose between a permanent rule and a one-off cleanup/specific category setting.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavioral context — 'Mail it already filed stays where it is' — clarifying the scope of destruction, which the annotations cannot convey. It stops short of noting auth/permission requirements or that the rule stops applying to future mail.

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

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

Two tight sentences with no filler; the action and its scope come first and the reassurance about existing mail follows. Every clause carries 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?

With an output schema and rich annotations present, the description needn't explain return values or safety flags. It covers the main ambiguity for a destructive tool (what survives the deletion), though it omits the auth/prerequisite path and any warning about irreversibility.

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 (id, mailbox) are already fully documented, including that the id comes from settings_filters_list. The description only restates 'by its id' and adds nothing about the mailbox parameter, 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?

States a specific verb and two precise resource variants (a rule, or a sender's Focused/Other placement) plus the lookup key (id). This clearly distinguishes it from settings_filters_create/update/list and from the drafts/labels delete siblings.

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

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

Usage is only implied: 'by its id' hints that an id must first be obtained, but the description never names settings_filters_list or says when to delete versus disable via settings_filters_update. No explicit when-not or alternatives are 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 establish readOnly=true, destructive=false, openWorld=false, so the safety bar is low and the description adds real context: it discloses that results include per-rule action markers (forward, redirect, bin, junk, delete, hide), creator, target folders, AI-client timestamps, plus provider-specific additions (Outlook Focused/Other placements, Gmail's forward-all setting). What it omits is anything about volume, pagination, or failure modes for an unknown mailbox.

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

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

The entire description is one ~70-word run-on sentence chained with semicolons and relative clauses. The purpose is front-loaded, but the provider-specific caveats are buried and would read far better as separate sentences or a short bulleted list.

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 an output schema present and full annotation coverage, the description only needs to frame what the list contains and any provider divergence — both are covered. The gap is small: no note on behavior when the mailbox name is ambiguous or unknown.

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

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

Schema coverage is 100% with a single required 'mailbox' parameter already documented as name or email address. The description's phrase 'a connected mailbox' adds the constraint that the mailbox must be connected, which is mildly useful, but it provides no format or resolution detail beyond the schema.

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

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

The opening clause gives a specific verb+resource: list the rules a connected mailbox files incoming mail by, i.e. filter rules, which is distinct from the create/delete/update filter siblings. The trailing enumerations of what each rule reports stay on-topic but dilute the single clear statement of purpose.

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 only implied — an agent infers it reads filter configuration for a given mailbox, versus settings_filters_create/update/delete which mutate. No explicit when-to-use, prerequisites, or named alternative is given, and the Gmail/Outlook differences are framed as return-content notes rather than selection guidance.

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

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

Beyond the destructiveHint annotation, it discloses the key destructive behavior: a change replaces every condition, exception and action, so anything not named is dropped, and the person must agree first. It also covers refusal conditions, read-only Outlook rules, platform-specific id behavior (Outlook keeps the id; Gmail recreates under a new id), and that the response is the rule as it now stands.

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, but the description is a single long, convoluted paragraph with nested clauses and archaic phrasing. Most content is relevant to this 20-parameter destructive tool, yet the structure makes it harder to scan than a shorter, segmented description would.

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

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

For a complex, destructive filter-update tool with a rich schema and an output schema, the description covers the essential behavioral contract: replacement semantics, consent before loss, refusal cases, platform differences, and sibling routing. Return-value detail is unnecessary because an output schema exists, though it still notes that the rule is returned as it now stands.

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 the many parameters; the description still adds important semantics by saying conditions and actions must be named whole as settings_filters_create takes them, sender lists included. It also clarifies that enabled is Outlook-only pause/resume and that replacing a rule means unnamed conditions are lost.

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

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

The description opens with a specific verb and resource: 'Change one rule by its id from settings_filters_list,' and immediately ties the id source to the list tool, distinguishing the update case from create/list. It also notes the Outlook pause/resume variant, so an agent knows this is the mutation tool for an existing filter.

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 when to use this tool (changing an existing rule by id) and routes nearby cases to siblings: Focused/Other sender placement is moved by settings_filters_create with focus and removed by settings_filters_delete. It also explains that forwarding/redirecting/binning/junking/deleting rules can only be paused or removed here, which is clear when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds genuine value beyond them by disclosing the breadth of what is returned: the on/off state, message text, and any schedule or restriction, which tells the agent this is a richer read than a bare boolean.

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?

One front-loaded sentence with the verb leading, and the dash-delimited clauses enumerate the returned facets efficiently. Slightly dense phrasing, but every clause carries 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 single-parameter read with a full output schema and complete annotations, the description covers purpose and returned scope without redundant return-value detail. 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?

There is a single parameter, mailbox, fully documented in the schema as a name or email address (100% coverage). The description adds nothing about the parameter itself, so the baseline of 3 applies - the schema does the work.

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 (read) and resource (the automatic vacation/out-of-office reply) and enumerates what is inspected: whether it fires, its text, and its schedule or restrictions. The read framing implicitly contrasts with settings_update_vacation, though no sibling is named outright.

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

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

Use is implied - inspect a given mailbox's vacation responder - but there is no explicit when-to-use, when-not, or named alternative such as settings_send_as_find or settings_filters_list for other settings inquiries. The agent must infer that this is the read-only counterpart to settings_update_vacation.

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?

Richly discloses behavior beyond the annotations: it creates a self-addressed draft (a write, consistent with readOnlyHint=false and destructiveHint=false), explains the draft is the person's to see, that sending turns it into a test message to themselves, the inference heuristic used (marked block, else shared closing lines, never a 'Sent from my iPhone' line), and IMAP-specific sourcing. Prerequisites and refusal conditions are surfaced, all beyond what annotations declare.

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 content is valuable but delivered as one long, densely embedded run-on sentence with awkward phrasing ('the person's to see', 'takes the name its newest sent mail goes out under'), making it hard to parse. The lead action is front-loaded, but the structure sacrifices readability for compression.

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?

An output schema exists, so return values needn't be explained, and the description covers the remaining essentials: the required tool permissions, the server-side-signature refusal, the draft side effect, the downstream patch hand-off, and the IMAP caveat. 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?

Single parameter 'mailbox' with 100% schema coverage already documenting it as name or email address, so baseline is 3. The description adds no new parameter-level detail, only behavioral notes about IMAP sending-name resolution.

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 (find the signature) and clarifies it does more than a read: it also writes the result into a new self-addressed draft. It implicitly distinguishes itself from settings_send_as_get (which reads the configured signature) and settings_send_as_patch (which applies it), though those sibling names are not stated explicitly as alternatives.

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 real prerequisites (messages_get and drafts_create must be enabled per mailbox) and an explicit refusal condition (company adds a signature server-side). It also defines the downstream hand-off: only on the person's word does settings_send_as_patch with fromDraft keep the signature. It stops short of stating a clear 'use this vs settings_send_as_get' selection rule.

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

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

Annotations already establish readOnlyHint, destructiveHint false and openWorldHint false, so the description's added value is in the edge-case behavior: an empty signature returns without one, the company may append its own server-side, and inline images are named without their bytes. That is genuine context beyond the structured fields, though the final sentence is hard enough to parse that some of the value is lost.

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 fact is buried in a long run-on sentence, and the trailing sentence about Outlook/imap providers is a tangled pile of relative clauses that takes several reads to decode. It is not front-loaded: the actionable read semantics are interleaved with caveats and provider minutiae.

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 an output schema present and annotations covering the safety profile, the description only needed to convey scoping and edge cases, which it largely does. The dangling 'sign false' reference and the impenetrable provider sentence are the only real gaps for an agent deciding whether to call 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?

There is a single parameter at 100% schema description coverage ('The mailbox's name or its email address'), so the schema already does the work. The description refers to 'the mailbox' but adds no accepted forms, defaults, or resolution behavior 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?

The opening clause states a specific verb and resource: read the default send-as address's signature, returned as HTML. It also names the counterpart setter, settings_send_as_patch, so the agent can place it in the read/write pair. However, the second sentence drifts into provider-specific trivia that muddies rather than sharpens the distinction from settings_send_as_find.

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 the read/write pairing with settings_send_as_patch, and the description notes when a signature will be absent (no signature configured, or the company appends one server-side). There is no explicit 'use this when you need X, use the sibling when Y' statement, and the reference to a 'sign false' flag on 'the call' is ambiguous and does not correspond to any parameter in this tool's schema.

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 behavior beyond the annotations: old signature contents are not retained, empty input clears the signature, Gmail's refusal condition is stated, provider-specific storage rules are explained, and size/picture/markup constraints are disclosed. This is consistent with destructiveHint=true and idempotentHint=true.

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

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

The main purpose and destructive behavior are front-loaded, and most sentences carry necessary provider-specific details. However, the provider rules are packed into long, dense sentences that make the description harder to scan than it could 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?

Given the destructive mutation, provider-specific behavior, four parameters, full schema coverage, annotations, and an output schema, the description is complete enough for correct invocation. It covers refusal conditions, empty-value semantics, and the main provider-dependent alternatives.

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 four parameters, including fromDraft, signature, and displayName. The description adds provider-level context, but most parameter-specific meaning is already present in the schema, so it only meets the baseline rather than adding significant new semantics.

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

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

The description starts with a specific verb and resource: replacing the signature of the address the mailbox sends from by default. It also distinguishes the read counterpart explicitly via settings_send_as_get and describes the empty-signature clearing behavior.

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

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

It gives explicit alternatives and conditions: settings_send_as_get reads the old signature beforehand, an empty signature clears it, fromDraft is used for Outlook/imap mailboxes, displayName is used for imap mailboxes, and Gmail refuses changes where the address is not the sign-in address.

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 provides deep operational context regarding scheduling persistence. It explicitly states that schedules are kept even when the responder is off and notes the specific behavior of losing the subject line when the mailbox is turned on from an off state.

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 slightly long, but its density of information justifies the length. It avoids filler and focuses exclusively on high-value operational constraints and behaviors.

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 complexity of how scheduling and state persistence work in this system, the description is exceptionally complete. It covers edge cases like previously ended schedules, which is critical for agent accuracy.

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?

Since the input schema provides 100% coverage for all parameters, the baseline score of 3 is maintained. The description only elaborates on the semantic purpose of changing the body or subject, rather than compensating for missing schema detail.

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 tool clearly defines its purpose as managing the 'vacation responder,' covering both enabling/disabling and modifying the content. It is distinct from general draft tools or list operations in the provided sibling list.

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

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

The description clearly explains the boundaries of the operation—what can be changed (content, status). While it doesn't explicitly name the contrasting tool, the focus on modification vs. retrieval guides usage effectively.

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

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

Beyond the annotations, the description discloses extensive behavior: refused filing targets, heldApart protections, alreadyRead behavior, notReached and failure limits, the three-minute call window, resumption semantics under the same sweep, daily allowance treatment, and timezone reporting. These details are consistent with destructiveHint=true and idempotentHint=true.

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

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

The description is a single sprawling, telegraphic block with semicolon-separated clauses that is difficult to scan. Most content is relevant, but the run-on structure and lack of grouping undermine front-loading and readability.

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

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

For a complex destructive batch tool, the description covers preconditions, safety exclusions, failure limits, idempotent resumption, and response-time semantics. The output schema can carry the exact return shape, so the description is complete enough for an agent to call it safely.

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

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

Schema coverage is already 75%, but the description adds meaning: group numbers and message counts must match the preview, label ids come from labels_list, action outcomes are explained through bin/archive/read/file prose, and mailbox password handling is described. onlyIfNewest is left to the schema, which keeps this below a full 5.

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

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

The description states a specific verb and resource: it moves the groups counted by sweeps_preview into trash, archive, labels, or read state. It also distinguishes the tool from sweeps_preview and sweeps_put_back, so an agent can tell this applies a preview and mutates mail.

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

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

The description makes clear that groups must come from sweeps_preview, that message counts must match the preview, and that binning requires a suitably narrowed preview. It also names sweeps_put_back for reversal. It stops short of explicit routing guidance versus direct siblings such as threads_trash or threads_archive, but the preconditions and refusal cases cover most usage decisions.

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

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

Annotations already mark this as read-only and non-destructive, but the description adds substantial behavioral context: read caps of 10,000 messages and 150 for Gmail, prompt-attack withholding, leftOut categories, actionsLeft, a one-hour sweep handle, and time-zone offsets. It does not contradict the annotations.

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

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

The description is a dense, run-on block with many clauses and little structure, making it hard to scan. It contains useful caveats, but it is overlong and poorly front-loaded for its purpose.

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 13-parameter preview tool with an output schema, it covers the important read limits, output fields, withholding behavior, and time-zone handling comprehensively. Nothing essential appears missing, though the density hurts usability.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some meaning beyond the schema by relating senders to nextSenders and subject narrowing, and by noting the default folder and excluded folders, but most parameter semantics are already supplied by the schema.

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

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

The description opens by stating it counts senders in one mailbox folder before a clear-out and explicitly contrasts with sweeps_apply, which performs the move. The verb, resource, and scope are specific, though the phrase 'Count who fills one folder' is less direct than it could be.

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 tells the agent this is the preview step before sweeps_apply and that nothing is moved, and it names sweeps_apply as the tool that executes approved groups. It does not spell out when-not scenarios beyond the read-only preview/apply split.

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 specifies that only read-marking is reverted (and only that), that filed mail leaves the label/folder while a pre-existing label stays, that moved and deleted messages are handled distinctly (changed / gone), that a call runs for about three minutes and a repeat call picks up the remainder, and that it consumes no daily quota. None of that is derivable from readOnly/destructive/idempotent hints.

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

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

Purpose is front-loaded, but the body is a single sprawling sentence chaining restore targets, edge cases, timeouts and quota in one breath. Every clause carries information, yet the nested 'or the folder of a mailbox held by its password, it came from' phrasing forces re-reading; splitting into short statements would preserve content and improve scanability.

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

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

For a mutating, retryable undo tool with an output schema already defining returns, the description supplies the operationally important facts: scope, partial-completion retry, timeout window, quota exemption, and per-message edge outcomes. The main remaining gap is an explicit precondition tying the call to a still-open apply window.

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

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

Schema coverage is 67%, and the undocumented parameter (groups) is exactly the one the description explains: 'every group, or those named', making clear it is an optional subset selector defaulting to all groups. The sweep handle's origin is reinforced, though the mailbox parameter's password/sign-in framing adds only mild clarity beyond the schema's own 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 opening clause states a specific verb and resource: return what sweeps_apply moved under a sweep handle, per group, restoring folder/label placement. It clearly names its inverse sibling (sweeps_apply) so an agent can distinguish the pair. The long run-on structure around 'each message to the Outlook folder... or in Gmail...' muddies the read but does not obscure the core purpose.

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 rather than stated: it references a prior sweeps_apply and a sweep handle from sweeps_preview, and 'every group, or those named' hints at the default-vs-subset choice. It also gives a partial exclusion ('a message moved since the apply is left where it is'), but there is no explicit when-to-use/when-not framing or statement of prerequisites (e.g., whether an apply must still be in effect).

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 (destructiveHint, idempotentHint): it discloses that the item stays in the mailbox and in search, that an Archive folder may be created with new ids returned in the answer, and that batch calls can end partially with done / notDone / possiblyDone / notReached outcomes, including timeout and connection-loss causes. That is substantive operational context an agent could not get from the annotations alone. Note the mild tension with destructiveHint=true since the description stresses the mail remains searchable, but this is a nuance rather than a contradiction.

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

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

The purpose is front-loaded in the opening clause, which is good, but the rest is one sprawling run-on sentence with dense clauses and informal phrasing ('under one call's time', 'asked with no answer back') that makes the batch and outcome semantics harder to parse than necessary. No filler sentences, but readability suffers.

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 batch semantics and partial-failure modes, the description covers the essentials: what changes per provider, what persists, what the outcome buckets mean, and the retry path. An output schema exists, so the extra detail on result buckets is bonus rather than obligation; only the relationship to threads_modify and the exact id format are left 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 coverage is 100%, so the baseline is 3, and the description adds real meaning on top: ids is a mutually exclusive alternative to id, is capped at 2-100, and is processed as one action within a single call's time; scope=message targets one message rather than the whole thread. It stops short of documenting the id pattern/format constraints, which the schema already covers.

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

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

States a concrete verb and resource (take a thread or message out of the inbox, i.e. archive) and then spells out the provider-specific effect: Gmail loses its inbox label, Outlook moves to archive folder, IMAP moves inbox messages to an Archive folder created if absent. It also implicitly separates itself from threads_get/messages_get by naming them as the read tools used to verify possiblyDone results.

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 conditions for the two input shapes: a single id for one thread or message, or ids for 2-100 at once counted as one action. It also explains what to do on partial failure (re-run the notReached entries). It never explicitly contrasts with threads_modify (which can also remove the inbox label) or threads_trash, so the sibling choice is left partly 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 cover the safety profile (readOnly, non-destructive, closed-world), yet the description still discloses real response-shaping behavior: oldest-first ordering, quote stripping that depends on whether the message carries the quoted answer, recipient truncation with an omittedRecipients count, and per-message timestamps carrying the reader's time-zone offset with a fallback to UTC. That is meaningful context beyond the annotations, though the phrasing is opaque enough to slow an agent down.

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 first sentence is well front-loaded, and each later sentence does carry distinct information, so nothing is filler. However, the sentences are convoluted to the point of near-unparseability ("A message's quote of another the answer carries is left out of its words"), which undermines structure and scanability.

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 an output schema present the description need not restate return values, and it still covers ordering, quoting behavior, recipient truncation and timestamp semantics — the non-obvious parts. What is missing is usage context (when this beats reading individual messages) rather than behavioral detail.

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 all three parameters (id, view, mailbox) are documented in the schema, including the view enum's full/summary/headers semantics. The description adds no additional meaning about 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?

"Read every message of one thread in a connected mailbox, oldest first" gives a specific verb (read), resource (thread), scope (all messages) and ordering, so an agent knows what it gets. It does not explicitly distinguish itself from the thread-mutating siblings (threads_archive/modify/trash) or from messages_get, so sibling differentiation is left to inference.

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

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

There is no when-to-use guidance: nothing says to pick threads_get over messages_get or messages_list, and no exclusions or prerequisites are stated. The only routing hint appears in the schema ("The threadId a search or a read answered"), not in the description.

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 destructive=true, idempotent=true, readOnly=false, but the description goes well beyond that by explaining provider-specific label semantics for STARRED, SPAM, INBOX, TRASH, folder moves, skipped messages, partial outcomes, and untouched sent/drafts. This is rich behavioral context for a mutation 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?

The content is a single very long run-on paragraph with repeated clauses and no structural separation, so critical rules are buried mid-sentence. It is comprehensive but poorly organized and difficult to scan.

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 8-parameter mutation tool with nested flag fields and an output schema, the description covers provider differences, batching, result states, and skip/partial cases thoroughly. Nothing material appears missing 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 75%, with descriptions for id, ids, scope, mailbox, importance, flag, and the label arrays. The description adds meaningful semantics for batch behavior (2-100 as one action), scope=message, label-source, and provider restrictions, though it does not add much beyond the schema for importance or flag.

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

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

Opens with a specific verb and resource: 'Apply and remove labels on one thread, or one message of it,' and names concrete outcomes (folder, star, read/unread). It distinguishes label ids from labels_list and points to threads_archive, threads_trash, threads_untrash, threads_get, and messages_get for adjacent operations, so the agent can identify the tool.

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

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

It names alternatives and exclusions: labels_list for ids, threads_archive for removing from the inbox, threads_trash and SPAM for binning, threads_untrash for restoring, plus rules for INBOX and folder moves. However, the guidance is buried in a dense paragraph rather than stated as a clear upfront when-to-use rule, and there is no concise 'use this versus X' summary.

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 destructive and idempotent annotations, it discloses reversibility, provider-controlled retention, provider-specific label and message-ID effects, partial completion, timeouts, connection failures, and which items remain untouched. These details substantially clarify the side effects and failure behavior of the mutation.

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 the content is relevant, but the final sentence is an excessive run-on covering batching, statuses, verification, failure causes, and retries. Dense phrasing and repeated dashes make otherwise valuable instructions difficult to parse; shorter sentences or bullets would be much clearer.

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 provider-dependent, batch-capable destructive operation, the description supplies unusually complete context about scope, persistence, ID changes, partial failures, verification, and safe retries. The input and output schemas cover the remaining structural details.

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%, and the description repeats some of it, including the 2-to-100 batch range and message scope. It nevertheless adds useful meaning about batch action counting, per-item outcomes, newly assigned IDs, and how scope affects the appropriate verification tool.

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

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

The opening clearly states the verb, resource, and scope: moving either a whole thread or one message to the trash. It also maps trash to provider-specific folders and distinguishes the operation from threads_untrash.

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 concrete operational guidance for single versus batch calls using id or ids, names threads_untrash for reversal, and directs the agent to threads_get or messages_get after an ambiguous possiblyDone result. It also explains that notReached items can be retried with the same call.

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 by disclosing provider-specific restore semantics: Google-sign-in Gmail restores with every label, imap Gmail routes drafts/sent/other into different folders while preserving ids, and Outlook/imap returns messages to the folder they were moved from (latest move, within 30 days, folder still existing). It also discloses partial-failure behavior (done/notDone/possiblyDone/notReached) that the annotations do not cover. Nothing contradicts idempotentHint=true or 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 is front-loaded, but the remainder is one dense run-on paragraph with tangled clauses ('which threads_get - or messages_get for a message - reads to check') that must be re-read to parse. The content is relevant, yet it is not structured into scannable segments, hurting readability for an agent skimming the definition.

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 an output schema, the description covers everything an agent needs: per-provider restore destinations, the 30-day/folder-existence constraint, batch limits of 2-100, idempotency context, and the meaning of each partial-success status. No decision-relevant behavior is left unexplained.

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

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

Schema coverage is already 100%, but the description adds meaning the schema lacks: it explains that 'ids' replaces 'id' and is batched under one call's time as 'one action', and that 'scope: message' narrows the operation to a single message whose id is accepted. It also explains that restored messages are reported with the folder as restoredTo, linking inputs to output fields.

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

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

The first sentence names a specific verb and resource: 'Bring one thread, or one message of it, back out of the trash.' It also states the scope alternatives (whole thread vs single message) up front, so an agent can distinguish it from threads_trash, threads_archive, and threads_modify 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 concrete operational guidance: 'possiblyDone ... which threads_get - or messages_get for a message - reads to check' and 'notReached ... for the same call again' tells the agent exactly how to follow up after a partial result. It does not explicitly compare itself to alternative restore paths (e.g. threads_modify removing the TRASH label), so the alternative-selection guidance is implicit rather than stated.

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