Multi Mail

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds one useful behavioral fact — the draft is retained, not dispatched — but says nothing about permissions, provider constraints, or limits.

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?

A single front-loaded sentence with zero filler; the verb and the retain-as-draft constraint both land immediately. It is arguably undersized for an 8-parameter tool, which keeps it short of a 5.

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

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

An output schema exists, so return values need not be described, and the schema fully documents inputs. However, for a tool with 8 parameters and several near-identical draft siblings, the description does not fully equip the agent with routing or prerequisite context.

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

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

Schema description coverage is 100%, so every one of the 8 parameters (including the two attachment shapes) is already documented in the schema. The description adds no additional meaning about mailbox, recipients, html/body interaction, or attachments, 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 (compose) and resource (a message) with an explicit behavioral constraint: it is kept in the mailbox as a draft rather than sent. This implicitly distinguishes it from drafts_send, but the sibling is not named, so the 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?

The phrase 'keep it there as a draft' implies the use case (create without sending), but there is no explicit when-to-use guidance, no prerequisites (e.g., a connected mailbox of a specific provider), and no named alternatives among drafts_send/drafts_forward/drafts_reply.

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 readOnlyHint=false, so the bar is lower. The description nonetheless adds real value beyond them: it reassures that already-sent mail is untouched and explains the Gmail/Outlook mailbox restriction and its failure mode (deleting sent mail), which the annotations do not convey.

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

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

Three short sentences, front-loaded with the action, then the safety note, then the constraint. Every sentence earns its place with no padding.

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

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

An output schema exists, so return values need not be explained, and the destructive nature plus the mailbox restriction are covered. What remains implicit is error behavior on a non-existent or already-sent draft id, though this is a minor gap for a simple two-parameter 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 description coverage is 100%, so both parameters (id, mailbox) are already well documented in the schema, including the id pattern and its provenance. The description adds no additional parameter-level meaning, 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 (throw away/discard) and resource (draft), and clearly distinguishes itself from siblings like drafts_create, drafts_send, and drafts_update. An agent can tell immediately this is the deletion operation on drafts.

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

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

Gives an explicit environmental constraint ('Gmail mailboxes only') with the reason, which is actionable context for selecting the tool. It does not, however, name an alternative tool or describe the conditions under which discarding is preferable to drafts_update or letting a draft send.

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 declaring readOnlyHint=false/destructiveHint=false, the description adds real behavioral context: no send occurs until the draft is sent, and the forward preserves carried files and stays in the existing thread. These are traits not encoded in the annotations.

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

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

Two tightly written sentences, with the core action front-loaded and the safety reassurance second. No filler or repetition.

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

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

An output schema exists, so return values need no explanation, and the description plus annotations cover the essential behavior for a draft-creation tool. Only the routing against sibling draft/forward tools is left implicit.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description's 'files it carries' and 'thread it already sits in' describe forward behavior rather than clarifying parameter inputs, so it adds little per-parameter meaning beyond the schema baseline.

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

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

States a specific verb and resource: 'Compose a forward of a message as a draft.' The 'as a draft' qualifier cleanly separates it from the send-oriented siblings like messages_forward, though it never names an alternative directly.

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 line 'Nothing leaves the mailbox until the draft is sent' implies the use case (stage a forward for later review rather than send now), but the when-to-use vs messages_forward or drafts_create is left to inference 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?

Annotations only state readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description adds real behavioral context beyond that: the draft is created inside the source thread, the original is quoted beneath the reply, and no mail is dispatched by this call. It doesn't cover provider/permission constraints, 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?

A single sentence, front-loaded with the purpose before the addressing modes and the no-send safety note. No filler, though the middle clause about quoting is slightly dense.

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 need no explanation, and the 9 parameters are fully described in the schema. The description covers the essential draft semantics; only provider/permission prerequisites for the underlying message are left implicit.

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

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

Schema description coverage is 100%, so every parameter (including replyAll, to, cc, bcc, html, attachments) is already documented in the schema. The description reinforces replyAll's meaning ("to whoever wrote it, or with replyAll to everyone on it") but adds no new syntax or format detail, so baseline 3 applies.

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

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

Specific verb+resource: compose a reply as a draft, and it states the key structural facts (inside the thread it answers, quoting the original below). It does not explicitly differentiate itself from siblings like messages_reply or drafts_create, so it falls short of a 5.

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

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

"Nothing leaves the mailbox until the draft is sent" implies the when-to-use case (draft-first vs. immediate send) but never names or rules out an alternative such as messages_reply or drafts_send. Usage is inferable but not explicit.

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

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

Annotations already flag destructive=true and idempotent=true, and the description substantiates both: it says the draft is consumed and that a spent requestId sends nothing again, with the response indicating whether the send went or may have gone. That is real added context about state destruction and at-least-once ambiguity, not a restatement of the 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?

Front-loaded with the core action and effect, and every sentence carries information. The final sentence is somewhat convoluted ('whether that send went or may have gone'), a minor readability cost in an otherwise tight 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?

With an output schema present, return values need not be documented, and the description still tells the agent the response disambiguates send outcome. Preconditions, destructive effect, and idempotency semantics are all covered for a three-parameter mutation tool.

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

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

Schema description coverage is 100% and the schema already explains id, mailbox, and the requestId idempotency contract nearly verbatim ('One whose send went or may have gone sends nothing again'). The description largely echoes that, adding little syntax or format detail beyond the schema, 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+resource ('Send a draft') and immediately defines the effect ('It leaves the mailbox and consumes the draft'). It also draws the boundary against siblings by declaring that only drafts qualify and that preparation belongs to a draft tool, so an agent can separate it from drafts_create 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?

Explicit when-to-use and when-not: 'Call this only when the person asked for this message to go; when they asked to prepare one, draft it instead.' It also states the precondition (a message already sent or received is refused, and nothing leaves) and the requestId reuse 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 readOnlyHint=false and destructiveHint=true, so the safety profile is known. The description adds genuinely new behavior: omitted fields are preserved, and on IMAP the edit yields a NEW id, the old id stops resolving, and any surviving old version appears as previousVersionId. That is exactly the kind of non-obvious side effect the agent cannot infer from annotations.

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

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

Three sentences, front-loaded with the core action, then patch semantics, then the provider-specific id caveat. Every sentence carries information, though the phrasing ('the answer names', 'reads nothing') is slightly oblique and costs a beat of parsing.

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

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

With an output schema present, return values need not be explained, and the description still adds the id/previousVersionId outcome the agent must anticipate. For a 9-parameter destructive edit tool this is close to complete; only explicit alternative-tool routing is missing.

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

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

Schema coverage is 100%, so per-parameter meaning is already handled and baseline would be 3. The description adds cross-parameter semantics the schema does not express — that any omitted field is left at its current value — which materially changes how an agent should call this with 9 optional-ish 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?

States a specific verb and resource ('Change a draft in a connected mailbox') plus the mutation model, which is enough to identify the operation. It never names or contrasts with siblings like drafts_create or drafts_send, so differentiation is left to the name rather than the prose.

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 patch semantics ('A field the call leaves out stays as the draft has it') implicitly tell the agent this is for partial edits rather than full rewrites, which is useful. There is no explicit when-to-use/when-not guidance and no routing to alternatives such as drafts_create or drafts_send.

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

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

Annotations only declare it is a non-destructive write; the description adds substantial context beyond that — '/' nests under the preceding label in Gmail, acts as a folder path on imap, is a literal character in Outlook, and missing parent labels are created first. The implicit side effect of auto-creating parents is genuinely useful disclosure.

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?

A single front-loaded sentence that carries a lot of information with no filler. It is slightly dense and awkwardly phrased ("answer the id it is applied by", "made first where missing"), which costs a point.

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, return values need not be explained, and the description covers creation semantics, id return, and provider-specific naming. It omits edge cases such as duplicate-label behavior or required permissions, so it is strong but not exhaustive.

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 goes further by explaining that the `name` value's '/' has provider-dependent semantics (hierarchy vs. literal character), which the schema does not convey.

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

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

States a specific verb and resource ("Create a label in a connected mailbox") and adds that it returns the applied id. It does not explicitly name siblings, but "create" is self-differentiating against labels_update/labels_delete/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?

There is no when-to-use or when-not-to-use guidance, nor any pointer to alternatives such as labels_update for renaming or labels_list for lookup. The provider-specific '/' behavior is behavioral detail, not selection guidance.

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

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

Annotations already declare destructiveHint=true, and the description adds substantial value beyond them: it explains exactly what is destroyed per provider – Gmail label removed from every message, Outlook category removed from the list, IMAP folder deleted only if empty. This is exactly the kind of consequence detail an agent needs before invoking a destructive 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 core action and id source are front-loaded, and the long second sentence earns its length by covering three distinct provider behaviors. Phrasing around the IMAP case ('deletes only a folder holding no mail and no folder') is slightly convoluted but not wasteful.

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

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

For a destructive tool with an output schema and safe/destructive annotations, the description covers the essential behavioral consequences that annotations cannot express. It stops short of noting error conditions or whether deleting an in-use label is recoverable, but it is otherwise complete enough to call correctly.

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

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

Schema description coverage is 100%, so both parameters (id, mailbox) are already documented in the schema, and the description largely restates the id source. It adds a little provider-dependent meaning to mailbox but no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (delete one label) and ties the id to its source (labels_list), which distinguishes it cleanly from labels_update, labels_create, and labels_list. An agent can tell what this does and where the argument comes from 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?

Names the prerequisite clearly (id from labels_list) and describes the operational context (no message is deleted), but gives no explicit when-not-to-use guidance or comparison against labels_update as the non-destructive alternative. Usage is clear but not fully routed.

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=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: that IMAP folders surface as labels nested by '/', and that system labels UNREAD, STARRED and SPAM are always present.

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

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

Two compact sentences with the core purpose front-loaded and the IMAP caveat second. The phrase 'by the id each is applied by' is slightly awkward and costs a little readability, but there is no filler.

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

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

An output schema exists, so return-value explanation is not needed, and the description covers the non-obvious IMAP label semantics. For a one-parameter read tool with full schema coverage and annotations, this is sufficient.

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

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

Schema coverage is 100% and the single 'mailbox' parameter is fully documented as a name or email address, so the schema carries the parameter burden. The description adds no format or syntax detail about the identifier beyond what the schema already states.

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

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

The description states a specific verb and resource ('List the labels a connected mailbox holds') and adds a scoping detail about IMAP providers that separates it from the mailboxes_list sibling. It stops short of explicitly naming the sibling it is not, so it is clear but not fully differentiated.

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 the mention of a connected mailbox and the IMAP folder-as-label note. There is no explicit statement of when to call labels_list versus mailboxes_list, nor any prerequisite or exclusion.

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 destructiveHint=true and readOnlyHint=false already declared, the description adds real value beyond annotations: it discloses that an imap rename changes the label's id (breaking existing references) and that colour updates are unavailable on imap, while Outlook cannot be renamed. It does not discuss reversibility or permissions.

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

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

Three front-loaded sentences with no filler; the action comes first, then the id source, then provider caveats. Slightly dense on provider details, but each sentence earns its place.

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

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

An output schema exists, so return values need not be documented, yet the description still flags the imap behaviour of returning a new label id. For a 4-parameter mutation with full schema coverage and annotations, nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema cannot: the id originates from labels_list, and the color parameter is effectively restricted by mailbox provider (Outlook colour-only, imap no colour). The name parameter's imap rename semantics are also clarified.

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 pair and resource ('Rename a label, recolour it, or both') and points to labels_list as the source of the id, which separates it from labels_create and labels_delete. An agent can tell what it does without opening the schema.

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

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

Gives strong provider-conditional guidance: Outlook categories accept only a new colour, imap renames the folder and takes no colour. It does not explicitly contrast with labels_create/labels_delete or state when not to use it, so it falls short of full alternatives coverage.

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, openWorldHint=false, destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: results disclose per-provider tool gaps and confirm that every listed mailbox's mail is read/written via Multi Mail's tools. It does not discuss ordering, caching, or capability edge cases.

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

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

Two sentences of reasonable length, but the first is awkwardly constructed ('mailboxes that answer, each by the name a tool's mailbox input takes') and the second sentence partially restates the same idea about Multi Mail's tooling. Front-loading the core 'list connected mailboxes' action would help.

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 need not be spelled out, and annotations cover the safety profile. The description is nearly complete for a zero-param listing tool, with the only notable gap being explicit routing guidance versus sibling list tools.

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

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

Zero parameters, so the baseline is 4. The description still earns its place by explaining that the returned mailbox names are exactly the identifiers other tools' mailbox inputs expect, which clarifies how this tool's output maps onto sibling tools' 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?

States a specific verb and resource: list the connected mailboxes, and it goes further by noting the result includes each mailbox's canonical name and the tools its provider lacks. It is distinguishable from siblings like messages_list_all_mailboxes, though the phrase 'mailboxes that answer' is vague jargon that slightly muddies 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?

The description implies usage by saying mailbox names are 'the name a tool's mailbox input takes,' which tells the agent these values feed other tools' mailbox parameters. However, it never states when to call this versus alternatives, nor any prerequisites or 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 cover the read-only safety profile, and the description adds real context beyond them: the answer shape differs by the `as` parameter (plain text vs base64 file), and it discloses that a GET 'carrying this same credential' is required. It could say more about unsupported attachment types or failure modes, but the added auth and format context is valuable.

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

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

Three sentences, mostly front-loaded, but the final sentence ('Either answer names the address the original is served at whole, to a GET carrying this same credential') is syntactically tangled and harder to parse than its content warrants.

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

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

With an output schema, full param coverage, and annotations, the description only needs to add what the structured data cannot: the format contract and the credential requirement, which it does. For a 5-param read tool it is nearly complete, missing only edge-case guidance.

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 restates the `as` distinction ('what it says' vs 'the file itself, base64') and adds the continuation nuance ('The original always comes whole'), which the schema already conveys, so it adds little beyond the structured 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?

States a specific verb ('Read') and resource ('one attachment of a message'), and explicitly routes enumeration to the siblings by noting 'messages_get and threads_get name a message's attachments and their sizes.' An agent can distinguish this from messages_get/threads_get 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?

It clarifies the relationship to alternatives by explaining that messages_get/threads_get only name attachments and sizes, implying this tool retrieves the content itself. It gives no explicit exclusions or prerequisite conditions, but the routing intent 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=true, idempotentHint=true and openWorldHint=true, so the safety profile is carried structurally. The description earns credit for adding replay semantics ('a request id already spent sends nothing again') and the provider-limit note on payload, though it does not spell out why the operation is destructive (e.g. irreversible send, no recall).

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 and every sentence carries decision-relevant information (recipients, thread, size limit, send-vs-draft, idempotency). 'Only the provider's own limit applies to what it carries' is slightly opaque phrasing, which keeps it short of a 5.

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

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

With an output schema present, return shape need not be explained, yet the description still tells the agent the answer distinguishes a send that went from one that may have gone. Combined with the draft-vs-send routing and idempotency note, an agent has what it needs; only the destructive/irreversibility angle is left implicit.

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

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

Schema description coverage is 100%, so the schema documents every parameter (to, html, note, mailbox, messageId, requestId) on its own; baseline 3 applies. The description reinforces the requestId replay rule and the attachment behavior but adds no format or syntax 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?

States a specific verb and resource (forward one message), and three concrete scoping facts: recipients are the named addresses, existing attachments ride along, and it stays in its current thread. It also distinguishes itself from the draft path, so an agent can separate it from drafts_forward without opening either schema.

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

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

Gives an explicit routing rule: 'Call this only when the person asked for this message to go; when they asked to prepare one, draft it instead.' That is a clear when-to-use plus a when-not-to-use with the alternative behavior named, which is exactly what the sibling list (drafts_forward) requires.

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 profile, so safety is covered. The description adds one behavioral detail about recipient truncation and the omittedRecipients count, but the phrasing is so muddled that the added value is partial.

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 tight and front-loaded. The second sentence is awkwardly constructed ('A message whose recipients one answer cannot carry names the first that fit') and consumes space without delivering a clear point.

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 covering return values and annotations covering the safety profile, the definition needs only to state what is read and how. That is largely done; the odd recipient/omittedRecipients sentence is a minor blemish rather than a missing element.

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

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

Schema description coverage is 100%, so all three parameters (id, view, mailbox) are already documented, including the view enum semantics. The description adds no syntax or format 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 ('Read one message in a connected mailbox') plus scope ('with its headers and its body'). This clearly distinguishes it from messages_list and messages_list_all_mailboxes, though it does not explicitly name the nearest siblings (threads_get, messages_attachments_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?

No when-to-use or when-not guidance, and no routing to alternatives such as messages_list to obtain ids. The only usage-adjacent content is the garbled recipient sentence, which does not help an agent decide when this tool applies.

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

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

Annotations already declare readOnly=true, destructive=false and openWorld=false, so the safety profile is covered. The description adds genuine behavioral context about per-provider query dialects and the omittedRecipients output behavior, but it is marred by awkward prose and omits pagination/result-shape framing beyond what the schema says.

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 poorly front-loaded and hard to parse: 'A message whose recipients one answer cannot carry names the first that fit, omittedRecipients counting the rest' uses a confusing backward reference, and the final sentence about mailboxes_list is tangential. Only the first clause is clean; the rest buries and bloats the 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?

An output schema exists and the safety profile is fully covered by annotations, so return values needn't be explained. Still, the one sentence that does discuss output (omittedRecipients) is redundant and cryptic, and the description gives no guidance on pagination behavior even though pageToken semantics are non-trivial (threads recurring across pages).

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 high (83%), and the schema already documents q, by, view, mailbox, pageToken and maxResults in depth, so the description does not need to carry parameter meaning. The description's provider-language remarks overlap with the q schema text rather than adding syntax the schema lacks, making 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 clause gives a specific verb and resource ('Search one connected mailbox') with a clear scope (one mailbox, provider's own query language), which an agent can distinguish from messages_list_all_mailboxes. However, it never names that sibling, so the differentiation is left implicit. The remaining sentences drift into output details (omittedRecipients) and cross-references rather than reinforcing 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: the phrase 'one connected mailbox' hints that the all-mailbox variant is a separate tool, and the query-language detail signals search semantics. There is no explicit when-to-use, when-not-to-use, or named alternative, so an agent must infer routing from the sibling list.

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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond them: results name their source mailbox, unsearchable mailboxes are reported, results are merged newest-first with threads keyed by their newest message, and recipient lists are truncated with omittedRecipients counting the remainder.

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 and merge semantics are front-loaded, but the sentences are long, clause-heavy and occasionally awkward ('The answer names the mailbox each result came from, names any mailbox it could not search...'), which slows an agent parsing the routing information. Some of the merging detail could be trimmed given an output schema exists.

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

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

With an output schema present, return structure need not be explained, yet the description still covers cross-mailbox merge order, partial-failure reporting and recipient truncation. Combined with 100% parameter coverage, an agent has nearly everything needed to call it correctly; only explicit sibling routing is missing.

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

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

Schema description coverage is 100%, so the schema already carries the heavy lifting on q, by, view and maxResults. The description only mildly extends this ('a thread by its newest' restates by=thread semantics) and adds no new syntax or format detail, 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?

The description opens with a specific verb and scope: 'Search every mailbox you have connected in one call,' which clearly separates it from the single-mailbox sibling. It never names messages_list explicitly as the narrower alternative, so the differentiation is inferential rather than stated.

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 'in one call' and 'every mailbox' implies when this is preferable to a per-mailbox search, and the closing sentence scopes which mailboxes are covered via mailboxes_list. However, there is no explicit when-not guidance (e.g., use messages_list for a single mailbox) and no stated prerequisites or limits.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses concrete behavior: the reply is threaded and quotes the original, and a replayed requestId 'sends nothing again' with an answer that says whether the send went or may have gone. It does not cover other side effects (e.g. whether the reply is stored in Sent) or any permission requirements, so it stops 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?

Three sentences, each carrying distinct load: capability/threading, send-vs-draft routing, and idempotency. The core purpose is front-loaded in the first clause and there is no filler or restatement of the title.

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 an output schema, the description covers the decision-critical items: what it does, when to use it versus drafting, recipient defaults, and retry safety. Return values need not be explained since an output schema exists, and nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description still adds routing semantics the schema does not spell out - default recipients are whoever wrote the message, and replyAll extends that to everyone on it, while cc substitutes for the replyAll copies. It does not elaborate on html/body interplay beyond what the schema already documents.

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

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

States a specific verb and resource ('Reply to a message') plus two differentiating traits: it goes 'inside its own thread and quoting it below the reply' and supports both sender-only and replyAll routing. This distinguishes it cleanly from siblings like messages_send, messages_forward and drafts_reply without needing the schema.

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

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

Gives an explicit use/do-not-use rule: 'Call this only when the person asked for this message to go; when they asked to prepare one, draft it instead.' That names the alternative path (drafting) and the condition that selects it, so the agent never has to infer whether to send or prepare.

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 and openWorld=true. The description goes beyond them by explaining the practical meaning of the idempotency key — a spent request id resends nothing and the response reports whether the send went or may have gone — which is genuinely useful retry guidance not encoded in the 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?

Three sentences, each doing distinct work: what it does, when to use it, and the idempotency contract. Front-loaded and free of filler.

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

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

With an output schema present, return shape need not be described, and the description covers the actionable decision plus retry semantics. Minor gap: it doesn't mention authentication/send-as identity or attachment-provider constraints, though those are largely captured in schema descriptions.

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

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

Schema description coverage is 100%, so every parameter including requestId, html, and attachments is already documented in the schema. The description reinforces the requestId contract but adds no format or syntax detail beyond it; baseline 3 is appropriate.

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

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

States a specific verb and resource (compose and send a message in a connected mailbox) and explicitly separates itself from the drafting path. An agent can tell it apart from drafts_create / drafts_send 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?

Explicitly gives the selection rule: call only when the person asked the message to go, otherwise draft. It does not name the sibling tools (drafts_create, drafts_send) or address reply/forward variants, but the when/when-not condition is unambiguous.

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

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

Goes well beyond the annotations by disclosing server-side validation behavior that the schema only hints at: forwarding rules are refused regardless of what the provider would accept, and destination labels TRASH/SPAM are blocked. It also documents the Outlook-only constraint that a rule may only add labels or remove INBOX, which an agent could not infer from readOnly/destructive hints.

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

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

Three sentences, front-loaded with the action and followed by constraints; nothing is padding. The second sentence is dense and the Outlook sentence is syntactically awkward, but each sentence carries distinct information.

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

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

For a mutating tool with an output schema and annotations covering the safety profile, this covers the remaining gaps an agent needs: accepted vs refused rule shapes and the Outlook restriction. Return-format details are correctly omitted because an output schema 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 already 100%, so the baseline is 3, but the description adds real meaning: it explains why 'forward' is present-but-refused and clarifies that for Outlook mailboxes removeLabelIds effectively only accepts INBOX. These provider-specific semantics are not captured in the property 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?

States a specific verb and resource ('Create a rule that files incoming mail in a connected mailbox') and immediately narrows the scope to filing-only rules. It is easily distinguished from settings_filters_list and settings_filters_delete, which share the filter resource but not the creation/filing semantics.

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

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

Gives clear when-not guidance: rules that carry mail out of the mailbox, or bin/junk matches, are refused. It also spells out the Outlook-specific condition. It stops short of naming an alternative tool (e.g., labels_create for tagging without matching), so the routing story is implicit rather than explicit.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond them: 'Mail it already filed stays where it is', clarifying that deletion is not retroactive and does not re-file existing messages. It stops short of stating irreversibility or permission requirements, so not 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?

Two short sentences, zero filler, with the core action first and the side-effect caveat immediately after. Nothing is repeated or padded.

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

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

For a two-parameter delete with an output schema that already covers the response, the description supplies the action, the identifier source, and the non-retroactive effect. It is nearly complete; only irreversibility/permission context is absent, which is minor given the destructiveHint annotation.

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 both parameters (id, mailbox) are documented in the schema, including the pointer to settings_filters_list for the id. The description adds no format, constraint, or sourcing detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb+resource: delete one filter rule identified by its id. The scope ('one rule', 'by its id') lets an agent distinguish it from settings_filters_create and settings_filters_list. It does not name siblings explicitly, so it earns a 4 rather than a 5.

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

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

There is no when-to-use statement, no prerequisite description, and no mention of alternatives such as settings_filters_list (where the id comes from) or settings_filters_create. The usage is only implied by the verb and by the schema's parameter 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful domain context — that the returned rules govern incoming-mail filing for a connected mailbox — but says nothing about authorization needs, whether an unconnected mailbox errors, or result size/pagination.

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?

A single short sentence with no filler, front-loaded on the verb and resource. The phrasing ('the rules a connected mailbox files incoming mail by') is slightly awkward with its trailing preposition, costing a little clarity.

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 need not be explained, and the one parameter is fully documented in-schema. For a simple read-only list tool this is nearly complete, with only connection/prerequisite context missing.

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

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

Schema description coverage is 100% and the single 'mailbox' parameter is documented in-schema as a name or email address, so the schema carries the burden. The description adds only the notion that the mailbox is 'connected' and that its rules concern incoming mail, which is marginal extra meaning.

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

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

States a specific verb ('List') and resource ('the rules a connected mailbox files incoming mail by'), which names the filter/rule concept rather than restating the tool name. It is distinguishable from settings_filters_create/delete by the read verb, though it never explicitly says it is the read counterpart of those siblings and uses 'rules' instead of the 'filters' terminology found in the tool name.

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

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

The description gives no when-to-use conditions, prerequisites (e.g. mailbox must be connected), or pointers to alternatives such as settings_filters_create or settings_filters_delete. Usage is only inferable from the verb.

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 openWorldHint=false, so the safety profile is covered. The description adds useful field-level context (auto-answer state, message text, schedule/restrictions), but does not disclose anything about permissions needed or the shape of the response beyond those field names.

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 no filler; the object of the read is stated immediately and the enumerated fields are the only elaboration.

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 return shape need not be restated, and annotations cover the safety profile, so this simple one-parameter read tool is adequately described. The only real gap is the absence of routing guidance relative to settings_update_vacation.

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 single 'mailbox' parameter is fully documented in the schema, so the baseline is 3. The description only implies the mailbox scope via 'a connected mailbox' and adds no format or naming 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?

States a specific verb (Read) and the resource (the vacation responder / automatic-answer configuration) along with the fields it exposes. It does not name its sibling settings_update_vacation, so differentiation from the write counterpart is only implied by the verb 'Read'.

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 explicit guidance on when to call this versus settings_update_vacation, nor any stated prerequisites (e.g. mailbox must exist, must be connected). The read intent is inferable from the verb but nothing is 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?

Annotations already establish the safe read-only profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds meaningful beyond-annotation behavior: the response is HTML, an absent signature yields no signature rather than an error, and the operation is unsupported for Outlook mailboxes.

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 tightly written sentences with zero filler. The core purpose is front-loaded, followed immediately by the edge case and the provider limitation.

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-value structure need not be explained. Given the simple one-parameter read operation, the description covers the essential context: provider support, output format, and empty-signature behavior.

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

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

Schema description coverage is 100%, so the single mailbox parameter is already fully documented as a name or email address. The description adds no syntax, format, or constraint details beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb (Read) and resource (signature on the mailbox's own send-as identity), and the 'Gmail mailboxes only' caveat distinguishes it from the broader settings family. The sibling settings_send_as_patch is implicitly the write counterpart, so the read-only purpose is clear without ambiguity.

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 a clear usage condition and exclusion: it works only for Gmail mailboxes, since Outlook exposes no signature. However, it does not explicitly name the natural alternative for changing a signature (settings_send_as_patch) or otherwise route the agent to the correct sibling tool.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds the crucial detail that nothing of the old value is retained, that an empty string clears the signature, and that Outlook mailboxes are unsupported. These are behavioral facts the annotations cannot express.

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

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

Three short sentences, front-loaded with the destructive replace action, then the prerequisite, then the provider restriction. No filler.

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

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

An output schema exists so return values need no explanation, and the description covers destruction semantics, prerequisites, and provider limitations. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented (baseline 3). The description adds real semantic value by explaining the empty-string case for 'signature' and clarifying that the target is the mailbox's own send-as identity, though it does not elaborate on the HTML sanitisation noted 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?

States a precise verb+resource ('Replace the signature on the mailbox's own send-as identity'), which is clearly distinct from the read-side sibling settings_send_as_get. An agent can tell what this writes and to what object without opening the schema.

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

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

Gives an explicit prerequisite/alternative ('read it first with settings_send_as_get') and an explicit exclusion ('Gmail mailboxes only: an Outlook mailbox exposes no signature to write'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real behavioral value beyond them: it explains WHAT is destroyed (a Gmail mailbox replaces the whole responder, dropping any existing schedule or restriction) and how Outlook differs (keeps unnamed fields, holds no subject). This is exactly the kind of provider-specific destructive nuance annotations cannot convey.

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

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

Two sentences, front-loaded with the core on/off action before the provider-specific caveats. Dense but essentially every clause (Gmail replace semantics, Outlook preservation, no subject) earns its place.

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

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

An output schema exists so return values need not be explained, and annotations plus the provider-specific destructive details give an agent enough to call this correctly. The main omission is any explicit routing to settings_get_vacation.

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 four parameters are documented in the schema, so the baseline is 3. The description adds only incidental hints ('holds no subject' touches responseSubject) and otherwise does not clarify parameter behavior beyond the schema.

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

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

The description states a specific verb+resource (turn the vacation responder on/off) and clearly identifies the operation. It distinguishes itself semantically from settings_get_vacation without naming it, so an agent gets the intent but must infer the distinction from the verb.

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: the tradeoff of on vs off is described, but there is no explicit when-to-use guidance and no naming of the sibling settings_get_vacation as the read alternative or of any prerequisites. Adequate but with a clear gap.

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

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

Annotations only supply the safety flags (readOnlyHint=false, destructiveHint=true, openWorldHint=false); the description adds genuinely useful behavior beyond them — the thread survives in the mailbox and search, Gmail removes a label while Outlook/IMAP move messages, an Archive folder is created if absent, and new ids are returned. It does not explain why destructiveHint is set despite the data being preserved, leaving a small tension unaddressed.

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, which is good, but the whole description is one sprawling sentence with awkward constructions ('made as Archive where it has none', 'each under a new id the answer names') that force re-reading. Provider detail is useful but could be structured as shorter clauses.

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 need not be explained, yet the description still covers the mutation's observable effects and provider-specific variance well. An agent has enough to call it correctly; only the rationale for the destructive annotation is missing.

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

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

Schema coverage is 100% and both parameters (mailbox, id) are fully documented in the schema, including the id pattern. The description adds no parameter-level syntax or constraint detail beyond that, 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?

The description gives a concrete verb+resource ('Take one thread out of the inbox') and spells out the exact resulting state per provider (Gmail drops the inbox label, Outlook/IMAP move to Archive). It implicitly distinguishes itself from threads_trash by noting the thread 'stays in the mailbox and in search', but it never names a sibling 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?

Usage is only implied: an agent can infer this is the non-destructive inbox-clearing option as opposed to threads_trash or threads_modify, but the description never states when to choose it over those siblings. No prerequisites, no exclusions, no alternative named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and closed-world scope, so safety is covered. The description adds two useful behaviors beyond that: results are returned 'oldest first' and long recipient lists are truncated with an omittedRecipients count. The truncation sentence is garbled ('A message whose recipients one answer cannot carry names the first that fit'), which blunts its 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 first sentence is tight and front-loaded. The second sentence is nearly unparseable and reads like a mangled sentence about recipient truncation, so it costs more in confusion than it returns in 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?

An output schema exists, so the description need not explain return values, and the core behavior (read all messages in a thread, ordered oldest first) is present. However, it omits the view-mode choice entirely and the one piece of behavioral prose it does include is confusing rather than clarifying.

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

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

Schema description coverage is 100%, and the schema fully documents id, mailbox, and the full/summary/headers view enum including what each mode omits. The description adds nothing about any of the three 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?

States a specific verb and resource: 'Read every message of one thread in a connected mailbox.' The scope ('every message of one thread') distinguishes it from messages_get and messages_list well enough for selection, though it never names those siblings 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?

Usage is only implied by the tool's narrow scope – read this when you want a whole thread rather than a single message. There is no explicit when-to-use, no mention of the alternative messages_get, and no note on prerequisites such as needing a threadId from a prior search.

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 destructiveHint=true already declared, the description goes well beyond the annotation by disclosing concrete effects: SPAM junks the thread, removing SPAM restores it to the inbox, Gmail TRASH bins it, folder-label moves reissue new message ids, and imap mailboxes have varying id constraints. It omits permission/auth requirements and rate limits, but the side-effect disclosure is strong.

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 opening sentence is well front-loaded, but the final provider-taxonomy sentence is a single dense run-on that crams Gmail, Outlook, imap-generic and folder-move rules together. The information is valuable but its structure makes it hard to parse quickly.

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 5-param tool with an output schema and destructive annotations, the description covers the essential behavioral surface, including that moved messages get new ids that the response names. It is largely complete, though the per-provider matrix would benefit from being broken out.

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 only 60%, but the description compensates: it explains that id is a threadId from a search/read (or a message id under message scope) and constrains which label ids are valid per mailbox/provider. The addLabelIds/removeLabelIds semantics (junk/unbin, move-to-folder) are only implied rather than spelled out per parameter.

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

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

The description gives a specific verb+resource with scope: 'Apply and remove labels on one thread, or one message of it.' It also flags the label-id source (labels_list). It does not, however, distinguish itself from close siblings like threads_archive, threads_trash, or threads_untrash, which overlap in effect (adding TRASH/SPAM).

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 where ids come from (labels_list) and lays out provider-specific rules for which label ids are legal, which is useful context. But it never explicitly says when to use this tool versus the sibling threads_archive/threads_trash/threads_untrash, leaving the agent to infer routing from the side-effect notes.

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 and readOnlyHint=false, and the description adds non-obvious consequences: where the item lands per provider (Gmail bin, Outlook Deleted Items, imap trash), retention behavior, label retention on Gmail/imap, and a new message id on non-Gmail imap. The id-mutation side effect is exactly the kind of trait annotations cannot convey.

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

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

The primary action is front-loaded and the sentences carry dense, useful information with little filler. The second sentence is a convoluted run-on with nested clauses, which slightly hurts readability, 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?

With an output schema present, return values needn't be explained, and the description correctly defers to it ('which the answer names'). It covers destination, retention, undo, and id behavior, though it leaves the relationship to threads_archive implicit.

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

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

Schema description coverage is 100%, so the schema already documents id, scope, and mailbox semantics (including the scope enum). The description reinforces the thread-vs-message distinction but adds no format or syntax detail beyond the schema, so the baseline 3 is correct.

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

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

States a specific verb+resource ('Move one thread, or one message of it, to the trash') and names the exact sibling/reverse operation (threads_untrash). An agent can distinguish it from threads_archive, threads_modify, and the messages_* tools 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?

Names threads_untrash as the operation that reverses this one, giving clear recovery context, and the 'one thread, or one message of it' phrasing signals the message-scope case. There is no explicit statement of when to prefer this over threads_archive, so it stops short of full when/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?

Beyond the annotations, it discloses substantial behavioral detail: provider-specific landing locations (Outlook/imap drafts→Drafts, sent→Sent, otherwise Inbox), Gmail label preservation, and that some imap messages come back under a new id. It does not address permissions or rate limits, but the provider-dependent outcome is exactly the kind of context an agent cannot get elsewhere.

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 clause and the second sentence is dense with genuinely useful provider behavior. It is one long, slightly overstuffed sentence, but every phrase carries information rather than padding.

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

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

With an output schema present, return values need not be explained, yet the description still notes that the answer names new ids. Combined with annotations covering the safety profile and a 100%-covered schema, the definition is complete enough to invoke correctly, with only permission/prerequisite context missing.

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

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

Schema coverage is 100%, so mailbox, id and scope are fully documented in the schema itself. The description adds no syntax or format detail for the parameters beyond echoing the thread-vs-message distinction already in the scope enum description.

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

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

States a specific verb and resource ('bring ... back out of the trash') and explicitly bounds scope to 'one thread, or one message of it', which maps directly onto the scope parameter. Together with the sibling threads_trash, an agent can immediately tell this is the inverse operation.

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

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

The inverse relationship to threads_trash is implied by 'back out of the trash', so usage is inferrable, but the description never states when to pick this over alternatives or that the thread/message must currently be in trash. No explicit when-not guidance.

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