Fluxmail Cloud

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description only needs to fill in the gaps. It adds the useful cross-provider synonym (Outlook categories) but says nothing about whether labels must already exist, whether additions are additive-only, or what happens on an already-labeled message.

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 no filler; the verb and resource lead. It is arguably under-specified rather than over-long, so nothing needs to be cut.

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

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

With a full output schema, full parameter coverage, and a complete annotation set, most of the burden is already carried elsewhere. However, for a label-mutating tool the description omits whether labels are auto-created or must pre-exist, which is the one thing an agent could easily get wrong.

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%, with labels, messageIds, and accountId all documented, so the baseline is 3. The description's only addition is clarifying that 'labels' also means Outlook categories, which is mildly useful but largely redundant with the schema's own wording.

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 (add) and resource (labels/categories) plus the target object (messages), so the operation is unambiguous. It does not explicitly contrast with the sibling remove_labels, but the add/remove pairing in the tool names makes the split obvious.

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 guidance on when to use this versus alternatives such as move_emails, archive_emails, or remove_labels, and no prerequisites noted. The agent must infer usage entirely 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 the full safety profile (not read-only, non-destructive, idempotent, closed-world), so the description only needs to add effect-level context. It does say the messages leave the inbox and land in the archive, but is silent on reversibility (restore_emails exists), permission requirements, and partial-failure behavior when some IDs are invalid.

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 no filler or repetition. It is efficient, though the brevity is achieved partly by omitting routing and behavioral context rather than by tight editing.

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 annotations plus schema cover the mechanical contract, so the description needn't explain return values. Still, for a batch mutation touching up to 100 messages, the absence of any note on reversibility or on how it differs from move_emails leaves a meaningful gap.

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

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

Schema coverage is 100% and both parameters carry their own descriptions, including the 100-ID cap and the 'optional when exactly one account is connected' rule. The description adds nothing about parameters, 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 ('move') and resource ('messages') plus the resulting state ('out of the inbox into the archive'), so an agent understands the effect. It does not differentiate from close siblings like move_emails, trash_emails, or restore_emails, which is what would push this to 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?

The description gives no when-to-use guidance, no prerequisites (e.g., connected account requirement), and never names an alternative such as move_emails for folder-to-folder moves or trash_emails for deletion. Usage has to be inferred entirely from the tool name.

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 non-read-only, non-destructive, non-idempotent, closed-world, so the safety profile is covered. The description adds value the structured fields don't: hard caps of 32,768 characters per body field and 30 attachments per draft. It stops short of stating that repeat calls create duplicate drafts or where the draft lands.

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

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

Three sentences, front-loaded with the core action, then the reply-mode conditional, then the hard limits. No restatement of the title and 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?

Eleven optional parameters, an output schema for return values, and rich schema descriptions; the description fills the remaining gaps that matter for correct invocation (reply inheritance, size and attachment caps). An agent has enough to call this correctly on the first attempt.

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 91%, so baseline is 3. The description nevertheless contributes real semantics the schema does not: replyToMessageId causes recipients and subject to be inherited from the original message, and replyAll only takes effect in combination with it — behavior an agent could not infer from the property descriptions alone.

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

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

Specific verb + resource ("Create a draft in the mailbox") with an added clarification that the draft may be a reply when replyToMessageId is supplied. It is clearly distinguishable from send_email/update_draft by the object it produces, though it never explicitly contrasts itself with those siblings.

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

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

The conditional mode is spelled out: with replyToMessageId the draft becomes a reply, recipients and subject fall back to the original, and replyAll expands to all original recipients. That is clear usage context, but there is no guidance on when to prefer update_draft over create_draft, or when to draft versus send directly.

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 readOnlyHint=false, so the core safety profile is covered by structured metadata. However, the description adds no behavioral context beyond the name—it does not state whether deletion is permanent, what happens to the draft after deletion, or any permission requirements.

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

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

The description is extremely short and front-loaded with the action and resource. There is zero filler, though the brevity contributes to the gaps noted in other dimensions rather than being a structural flaw in itself.

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

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

Although annotations cover the destructive/idempotent safety profile and an output schema exists, the description is incomplete for a mutation tool: it omits permanence, draftId semantics, and when to choose this over sibling deletion or trash operations. An agent has to rely almost entirely on the tool name and schema.

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

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

Schema description coverage is 50%: accountId is documented, but draftId has no description in the schema and the tool description adds no meaning about what a draft ID is or how to obtain it. The description 'Delete a draft' only implies the draftId parameter without explaining it.

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

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

States a clear verb ('Delete') and resource ('draft'), so an agent can immediately tell this is a removal operation for drafts. It does not explicitly differentiate itself from siblings like trash_emails, update_draft, or get_draft, but the purpose itself is unambiguous.

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

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

There is no guidance on when to use this versus alternatives such as trash_emails, update_draft, or get_draft. The description gives no prerequisites, no conditions, and no exclusions, leaving the agent to infer usage solely from the tool name.

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

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

Annotations already cover the safety profile (readOnly, non-destructive), so the description earns credit for adding real behavior: the default result is metadata plus a resource link, inline additionally returns content, PDFs get extracted text, and there is a hard 10 MB size limit. It stops short of saying what happens when the limit is exceeded or whether text extraction is lossy.

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

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

Four short sentences, each carrying new information, with the core return shape front-loaded before the optional behaviors. No repetition of the tool name or 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?

An output schema exists, so return values need no further explanation; the description still summarizes what the agent gets. For a read-only tool with all safety signals present, the only meaningful gap is the failure mode above the size limit and any account-selection 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 coverage is only 60%, and the two undocumented-ish parameters are precisely the ones explained here: inline controls content inclusion, and pages takes a range like 201-400 for PDF text. That compensates well for the schema gap, though accountId is left to 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: retrieve metadata plus a resource link for a single attachment, keyed by message and attachment. It is clearly distinct from email/thread tools, though it never explicitly contrasts with get_email_body, which is the sibling an agent might confuse it with.

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

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

The description implies when the extra behavior is wanted (use inline to get content, use pages to get a PDF text range), but there is no explicit guidance on when to choose this over get_email_body or get_email, and no prerequisites or exclusions are stated.

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

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

Adds real context beyond the annotations: idempotent replay returns the saved result rather than re-sending, attachments carry over by default, and hard limits of 32,768 comment characters and 30 attachments are disclosed. It does not elaborate on the destructive/irreversible nature of a real send or any permission requirements for the 'from' send-as address.

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

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

Four sentences, ~90 words, all load-bearing: effect first, then attachment behavior, idempotency, and limits. No filler and no 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?

With an output schema present, return values need no explanation, and the description covers the operation's side effects, defaults, and limits. It stops short of covering sender identity constraints or failure modes for an open-world, destructive send.

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 88%, so the baseline is 3; the description adds value by stating the comment length cap and the 30-attachment cap, which the schema does not. The includeAttachments default is repeated from the schema rather than extended, keeping this below a 5.

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

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

States a specific verb and resource ('Forward an email to new recipients') plus the visible effects: 'Fwd:' subject prefix and quoted original. This is clearly distinguishable from send_email or create_draft, though it never names a sibling or states the boundary 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 implied rather than stated: forwarding is for existing messages, and the idempotencyKey sentence tells you to reuse the key on retries. There is no explicit when-to-use/when-not guidance relative to send_email, create_draft, or preview_send, which are the plausible alternatives for outbound mail.

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, destructiveHint=false and openWorldHint=false, so the safety profile needs no restating. The description adds real value by naming the payload contents (workspace, plan status, permissions, mailboxes), which matters because no output schema exists. It stops short of saying whether the response is cached, fails on expired tokens, or requires elevated auth.

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 no filler; the scope qualifier ("this connection's") comes before the enumerated contents. It is appropriately sized for a no-argument tool.

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

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

With no parameters, no output schema and safety fully covered by annotations, the one thing the description must carry is what the caller gets back — and it does. Missing only guidance on how this differs from the account/label listing siblings in the same server.

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

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

Zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly does not waste words on inputs.

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

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

Specific verb ("Show") plus an enumerated resource set for the current connection: workspace, plan status, permissions, mailboxes. An agent can tell it is an introspection/status tool rather than a mailbox lister like list_accounts or list_folders, though the description never explicitly names that distinction.

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 statement of when to call this versus siblings such as list_accounts or list_send_as, and no prerequisites or exclusions. The only hint of usage is that it reports workspace/plan/permissions, which implies onboarding or capability checks, but the agent must infer that.

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 that this is a read-only, non-destructive, closed-world operation. The description adds useful behavioral context by saying the result is saved and can report success, failure, or an uncertain outcome.

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

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

The description is a single, front-loaded sentence with no wasted wording. It immediately communicates the core purpose and the possible outcome states.

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 details need not be repeated in the description, and annotations cover the safety profile. Still, the description lacks parameter guidance and explicit usage conditions, leaving gaps for an agent invoking the 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 0%, and both required parameters are undocumented in the schema. The description mentions checking a send or forward result but does not explain accountId or operationId, so it does not compensate for the parameter documentation gap.

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 pair: checking the saved result of a send or forward. It clearly distinguishes this status-checking operation from sending tools, though it does not explicitly name related siblings such as preview_send or send_email.

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

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

It implies usage after a send or forward by referring to the saved result of those operations. However, it gives no explicit when-to-use guidance, prerequisites, or alternatives for checking operation status.

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 fully covered and the description does not contradict it. The description adds essentially no behavioral detail beyond the annotations – no mention of what happens for an unknown draftId or whether a missing draft errors versus returns empty – so it neither helps nor harms.

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 wasted words. It is appropriately sized for a simple single-resource read, though it is so terse that it leaves useful context on the table.

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 cover the safety profile. For a two-parameter read tool, the remaining gaps – unknown-ID behavior and when to pass accountId – are minor, making the definition adequate for correct invocation.

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

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

Schema description coverage is 50%: accountId is documented in the schema, while draftId has no schema description. The description supplies the missing meaning for draftId ('by its draft ID'), which is the minimum needed to call the tool, but it adds nothing about format, length bounds, or the optional accountId fallback behavior.

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 an existing draft') plus the key identifier ('by its draft ID'), which cleanly separates it from create_draft, update_draft, and delete_draft. It does not, however, differentiate itself from other read tools like get_email or get_thread beyond the resource 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?

There is no explicit when-to-use guidance, no mention of prerequisites, and no named alternatives (e.g. use list_emails or get_email for non-drafts). The agent must infer usage purely from the tool name and the word 'draft'.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuinely non-obvious behavior: bodies are capped at 50,000 characters and truncation is surfaced via a bodyTruncation field so the caller knows where parts continue. It stops short of describing error behavior for an invalid messageId or the default bodyFormat.

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 truncation caveat is placed immediately after the claim it qualifies, and the payload enumeration is front-loaded.

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

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

With an output schema present the description needn't explain return values, and annotations carry the safety semantics, so what remains — payload scope plus truncation behavior — is covered. The one meaningful gap is sibling disambiguation against get_email_body and get_thread.

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 only 50%: accountId and includeHeaders are documented, but messageId and the bodyFormat enum (text/html/both/none) are bare in the schema. The description hints at body behavior and truncation but never explains what bodyFormat values do or that 'none' skips the body entirely, so it does not compensate for the coverage gap.

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 email') and enumerates the payload (recipients, body, attachment metadata), so its scope is clear. It does not, however, differentiate itself from close siblings like get_email_body or get_thread, leaving the agent to infer why reading the whole message beats reading only the body.

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 agent can infer this is the tool for fetching a single message once it has a messageId. There is no explicit when-to-use statement, no precondition about needing a messageId from list_emails/search_emails first, and no pointer to get_email_body for body-only reads or download_attachment for the attachments.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context that the body comes back truncated ('bounded portion') and that continuation is expected, but says nothing about default/maximum size behavior or what happens at end-of-body.

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, front-loaded sentences with zero filler and no repetition of the tool name or title. The second sentence carries the continuation guidance efficiently.

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

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

With annotations covering safety, an output schema carrying the return shape, and 5 parameters, the description covers the truncation/continuation model but leaves the agent without guidance on format selection or size limits. Adequate but with clear gaps for a paging 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?

No annotations beyond safety are given, but the schema is fully self-documenting: format enum, offset, maxChars, accountId, and messageId all carry descriptions or obvious constraints. The description adds one key semantic insight: the offset parameter is a pagination cursor rather than an arbitrary character index, which meaningfully extends the schema. That single insight isn't enough to reach 5, which would require explaining format choice and truncation behavior.

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

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

The description states a specific verb and resource ('Read a bounded portion of one email body'), which is concrete and distinguishes it partially from metadata readers. However, it never contrasts itself with sibling tools like get_email or get_thread, leaving the agent to infer why it would pick this over the general message getter.

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 only usage guidance is 'Use nextOffset to continue,' which covers pagination but not tool selection. There is no statement about when to call this instead of get_email, get_thread, or download_attachment.

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 safety is covered. The description adds one genuinely useful behavioral fact not present in structured fields: a 50,000 body-character cap per page, which warns of truncation. It omits how paging terminates, what the default body format is, and whether the cap applies per message or per response.

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 no filler; the size constraint is stated up front. It is efficient but so terse that the brevity starts to cost information rather than save it.

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

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

An output schema exists, so return values need not be described, but a paginated read tool with 5 parameters, 20% schema coverage, and an undocumented enum needs far more than one sentence. Missing pageSize defaults, pageToken usage, and bodyFormat effects leave an agent guessing on core invocation details.

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

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

Schema description coverage is only 20% — accountId is documented in the schema, but pageSize, pageToken, and bodyFormat (an enum with four values) carry no descriptions. The description hints at pagination and body size but does not explain pageSize bounds, pageToken round-tripping, or the text/html/both/none semantics, so the gap is not compensated.

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 ("Read a page of messages in an email thread") that clearly separates it from siblings like get_email (single message) and list_emails (folder listing). It does not explicitly name an alternative, but the thread-scoped read is unambiguous.

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

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

No guidance on when to choose this over get_email, get_email_body, or search_emails, nor on how to continue paging. The phrase "a page of" only implies that pagination exists; the agent must infer when and how to iterate.

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 fully covered without the description. The phrase 'this connection can access' adds genuine scope context (results are limited to the authenticated connection), but nothing is said about ordering, empty results, or multi-account behavior.

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

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

A single sentence with no filler, and the scope qualifier is packed into the same clause rather than deferred. Nothing could be removed without losing meaning.

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

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

With an output schema present and zero parameters, the description does not need to explain return shape or arguments, and the read-only annotations remove the behavioral burden. The only real omission is disambiguation from the folder/label/send-as listing siblings.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter detail is expected or missing.

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 ('List') and resource ('connected mailboxes') with a scoping qualifier ('this connection can access'), which is clear and actionable. It does not, however, distinguish mailboxes from near-siblings like list_folders, list_labels, or list_send_as, so an agent must infer the boundary itself.

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 natural reading is 'call this first to discover which mailbox to operate on.' There is no explicit when-to-use statement, no exclusions, and no pointer to the sibling listing tools that return adjacent resources.

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, destructiveHint=false, and openWorldHint=false, so the bar is lower. The description still adds useful behavior: results carry metadata, previews are opt-in, and paging is done via pageToken from a prior call — details not fully spelled out in the annotations. It stops short of stating ordering, result limits, or default mail-scope behavior.

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

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

Two sentences, no filler, and the core capability is front-loaded before the filtering mechanics. Slightly terse for a 16-parameter tool, 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?

An output schema exists and annotations cover safety, so the description needn't explain returns. But for a 16-parameter tool with provider-specific escape hatches (rawProviderQuery, includeSearchContext requiring a text query, accountId behavior), the description omits any mention of these interactions or the default all-mail scope, leaving the agent to read the schema closely.

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?

With 63% schema coverage across 16 parameters, the schema documents the tricky ones (folder defaults, date semantics, pageSize default, rawProviderQuery syntax). The description only summarizes filter families ('folder, sender, read state, dates and more') without adding meaning 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 and resource ('List or search emails in a mailbox') plus the scope of returned data ('metadata and optional previews'), so the operation is clear. However, it lumps 'list' and 'search' together without distinguishing this tool from the sibling search_emails / search_emails_batch, which is the main ambiguity an agent faces here.

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 filter/pagination mechanics imply the use case (browse or narrow down a mailbox), but there is no explicit when-to-use versus search_emails, search_emails_batch, or get_email. The agent must infer the choice from the tool name alone, which is the weakest part of an otherwise clear definition.

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 fully covered without the description. The description adds modest value by naming the specific folder roles that appear in results, but says nothing about ordering, completeness, or behavior when no account is connected.

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 identifies the resource first and then the payload detail. No filler or repetition; the only mild inefficiency is that the role examples are illustrative rather than actionable.

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, full param coverage, and annotations covering safety, the description need only say what is listed and it does. It falls short of complete because it omits the folders-versus-labels distinction, the one disambiguation an agent actually needs given the sibling set.

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

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

Schema description coverage is 100% and there is one optional parameter, so the schema fully documents accountId including the single-account default. The description mentions no parameters at all, leaving the baseline of 3 appropriate since the schema does all the work.

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

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

Specific verb (list) plus resource (folders in a mailbox) with concrete examples of the roles returned. An agent can tell it apart from list_emails or search_emails, but it never distinguishes folders from the sibling list_labels, which is the most likely confusion point in this toolset.

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 read-only, inventory nature of the tool. There is no statement of when to call this versus list_labels, nor any note that it is typically a prerequisite step before move_emails or archive_emails. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful provider-mapping context (Gmail labels vs Outlook categories) but says nothing about ordering, completeness of results, or scope of the listing.

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 no filler. Every word contributes to identifying the resource and its provider-specific naming.

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

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

For a simple read-only listing tool with annotations, a fully documented single optional parameter, and an output schema, the description is nearly sufficient. The only meaningful gap is the absence of any pointer to the adjacent list_folders tool for agents unsure which hierarchy they need.

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 accountId is already documented including its 'optional when exactly one account is connected' default. The description adds nothing about the parameter, which is acceptable given the schema carries the burden, but no extra value is provided.

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

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

The description names a specific verb and resource ('List the Gmail labels or Outlook categories') and clarifies the provider-dependent terminology, which is genuinely useful. It stops short of distinguishing itself from the sibling list_folders, which an agent could plausibly confuse with labels/categories.

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 statement of when to use this versus list_folders or the label-mutating siblings (add_labels, remove_labels), and no prerequisites or exclusions. The agent must infer the routing decision from names alone.

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 fully covered. The description adds only the mailbox scoping context and says nothing about ordering, pagination, or whether addresses are verified — modest value on top of 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?

A single front-loaded sentence with no filler, which is appropriately sized for a one-parameter read tool. It is efficient but borders on under-specified rather than maximally informative.

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

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

The output schema exists and annotations cover safety, so the description need not explain returns; for a simple read-only list tool the stated purpose is nearly sufficient. The only real gap is the absence of usage context linking it to the send flow.

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?

With a single parameter and 100% schema description coverage ('Account to operate on. Optional when exactly one account is connected.'), the schema already carries the semantics. The description adds no further meaning about accountId or its null/default behavior, 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 ('List') and resource ('sender addresses available for a mailbox'), which is clearly distinct from list_accounts or list_labels by resource noun. It stops short of explicitly contrasting with the closest sibling (list_accounts), so 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?

The description gives no when-to-use or when-not-to-use guidance and never names an alternative. An agent must infer that this is the pre-flight lookup before send_email or preview_send; nothing is 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 already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds nothing beyond that — no mention that the operation is a bulk state change, that unread flags are cleared irreversibly from the server's view, or what the output contains.

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

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

It is a single front-loaded sentence with no waste, but that is because it carries almost no information. Brevity here reflects under-specification rather than disciplined editing.

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 and full parameter documentation exist, so return values and params need not be explained. However, for a batch mutation tool, the description supplies no behavioral context an agent needs — no note on idempotency semantics, account defaulting, or the sibling unread counterpart.

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 accountId and messageIds (including the 100-ID cap) are fully documented in the schema. The description's word 'messages' hints at messageIds but adds no syntax, batching, or account-resolution detail beyond the schema.

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

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

The sentence 'Mark messages as read' simply restates the tool name and title with no additional specificity. It does not distinguish this from the sibling mark_emails_unread, nor clarify scope (which messages, which folders, per-account behavior).

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

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

No guidance on when to use this versus alternatives is provided. The obvious alternative, mark_emails_unread, exists as a sibling and is never mentioned, nor is there any exclusion or precondition 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 already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that – no note on partial failure, invalid/stale message IDs, or what happens to folder/label state when a message is flipped to unread.

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 short, front-loaded sentence with zero waste, but it is undersized rather than concise – the single clause leaves no room for the operational context an agent needs. Appropriate sizing would be slightly longer given this is a mutating batch operation.

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

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

An output schema exists, so return values needn't be explained, and annotations cover safety. Still, for a mutation tool that touches up to 100 messages, the description omits error behavior, account-resolution fallback, and any sibling contrast, leaving it inadequate for the tool's complexity.

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%: accountId's "optional when exactly one account is connected" and messageIds' "up to 100 IDs" are fully documented in the schema. The description contributes nothing extra, 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?

The description gives a specific verb and resource ("Mark messages as unread"), so an agent knows the action unambiguously. However, it is essentially a restatement of the name/title and adds no scoping detail such as batch limits or the read/unread counterpart, so it clears the bar without distinguishing itself from the sibling set.

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 guidance on when to use this versus alternatives. The sibling mark_emails_read is the obvious inverse, and nothing steers the agent, nor is there any note about prerequisites like a connected account or whether the messages must currently be read.

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 disclose that the operation mutates data, is destructive, and is idempotent, so the description carries less burden. It adds the useful destination constraint excluding archive/trash, but does not explain permissions, folder existence requirements, or side effects beyond what annotations already state.

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

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

The definition is a single front-loaded sentence with no wasted text. The core action and the key destination restriction are both stated immediately.

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 complete schema descriptions, rich annotations, and an output schema, the short description is nearly sufficient for correct invocation. The main remaining gap is not explicitly naming archive_emails and trash_emails as the alternatives for excluded destinations.

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 messageIds, folder, and accountId are already fully documented in the schema. The description adds no parameter-level meaning beyond the schema, which is acceptable at the baseline for complete schemas.

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: moving messages to a folder. It also distinguishes this tool from archive_emails and trash_emails by excluding the archive and trash destinations, though it does not explicitly name those sibling tools.

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

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

The phrase 'other than the archive or trash' gives an implied when-not constraint, routing archive/trash actions to other tools. However, it does not explicitly name the alternatives or explain when moving to a custom folder is preferred over other organization tools like add_labels.

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 behavioral context by stating that it performs recipient/sender/attachment checks and enforces cloud body and attachment limits, though it does not detail error behavior or return shape.

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

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

The description is three compact sentences with no wasted text. The core behavior and key validation limits are front-loaded, making it easy to scan.

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

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

The tool is complex with 12 parameters, but an output schema exists and annotations cover safety. The description covers purpose and important limits, though it omits explanation of draftId vs direct fields and reply-related parameters, leaving some gaps for a preview tool with multiple input modes.

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 at 83%, so the baseline is 3. The description earns an extra point by adding concrete constraints not present in the schema: bodyText and bodyHtml are limited to 32,768 characters each, and drafts support up to 30 attachments.

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 clear verb and resources: it shows the resolved sender, recipients, subject and attachments without sending mail. The 'without sending mail' clause distinguishes it from send_email, but it does not explicitly differentiate from draft-related siblings such as create_draft or update_draft.

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

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

Usage is implied: the tool is for previewing and validating a message before sending. However, the description does not explicitly say when to use this instead of send_email, create_draft, or update_draft, nor does it state when not to use it.

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

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

Annotations already declare idempotent=true and destructiveHint=false, so the safety profile is carried by structured data. The description adds the useful Gmail-label/Outlook-category equivalence, but says nothing about behavior when a label isn't present, batch semantics, or permission needs.

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

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

One short sentence, front-loaded with the verb and resource, with the cross-provider synonym clause attached efficiently. No wasted words.

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

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

The tool is low-complexity, an output schema exists, and annotations plus a fully-described schema cover most needs. The description fills the one gap structured data can't express — that Outlook categories are the same target — making it sufficient for correct invocation.

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

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

Schema description coverage is 100%, so all three parameters (labels, messageIds, accountId) including the 100-item cap and the single-account shortcut are already documented in the schema. The description adds nothing beyond that 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 (remove) and resource (labels/categories) on messages, and clarifies that Outlook categories are the same concept as Gmail labels. It doesn't explicitly name the inverse sibling add_labels, so differentiation is only implicit from the 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?

Usage is inferable — call it when a message should lose a label, and add_labels is the obvious counterpart — but the description never states when to use this versus alternatives, nor any prerequisites.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered upstream. The description adds nothing beyond that — notably it never says which folder messages return to (inbox vs. original location) or what happens for IDs that are not in trash.

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, front-loaded sentence with no filler. It is efficient but borders on under-specified rather than optimally concise.

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

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

An output schema exists and both parameters are documented, so the mechanical call is fully specified. However, the destination of restored messages and partial-failure behavior for non-trashed IDs remain unexplained for a 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%: accountId's optionality and messageIds' 1-100 ID limit are both documented in the schema. The description contributes no additional parameter meaning, 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 ('move ... out of') and resource ('messages'/'trash'), which is clearer than the name alone. It does not differentiate from close siblings such as move_emails or trash_emails, so an agent still has to infer that this is the inverse of trashing.

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 explicit when-to-use, when-not, or alternative is named. An agent must infer from the name alone that this is the inverse of trash_emails rather than a general folder move via move_emails.

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 the single-account scoping constraint, but says nothing about pagination behavior, result caps, or how the query and top-level filter params interact — all of which matter for a 16-param search.

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 packed sentences with zero filler, and the primary scope statement is front-loaded ahead of the syntax inventory.

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

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

The output schema and annotations relieve the description of return-value and safety explanation, and pagination params are documented in the schema. Still missing for a 16-param tool is sibling differentiation and any note on how query-syntax operators relate to the equivalent structured filter parameters.

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?

With only 63% schema description coverage, the description does real work by enumerating the portable query grammar (text, from:, to:, subject:, in:, read/starred states, attachments, date filters), which the schema leaves as an opaque 'Typed portable search syntax'. It does not, however, explain the overlap between those query operators and the separate from/to/subject/read/starred fields, leaving a meaningful ambiguity.

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

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

States a specific verb and resource ('Search one account') and scopes it to a single account with a portable typed syntax. An agent can tell it is a search operation, but nothing in the text distinguishes it from the sibling 'search_emails_batch' or from 'list_emails'.

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

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

No when-to-use, when-not-to-use, or alternative routing is provided. The closest signal, 'one account', is a scope constraint rather than guidance; an agent must infer on its own when to pick search_emails_batch, list_emails, or rawProviderQuery instead.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior — it fans out across up to 20 accounts and returns a separate result group per account — but says nothing about per-account pagination tokens, partial failures on one account, or result ordering, which are the real behavioral risks for a fan-out search.

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 with zero filler, front-loading the scope cap and the return shape. Nothing is repeated from the title or annotations.

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

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

An output schema exists, so return values needn't be described, and annotations cover safety. But for a 14-parameter, 20-account fan-out tool the description leaves material gaps: how pagination works per account, whether a failure in one account aborts the batch, and what "portable query" syntax is accepted.

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 only 43% across 14 parameters, so the description needs to compensate and largely does not. "One portable query" hints the same query is applied to every account, but the typed query syntax, the per-account pageToken semantics, pageSize defaults, and the interaction between includeSearchContext and a text query are left to the schema's terse or absent field descriptions.

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

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

States a specific verb and resource ("Search ... accounts") plus a hard scope cap ("up to 20 accounts") that matches the schema's maxItems=20, and it discloses the return shape ("one result group per account"). It does not name the single-account sibling search_emails, so differentiation relies on the word "batch"/"up to 20 accounts" rather than an explicit contrast.

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

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

Use is only implied: the multi-account fan-out and the shared query suggest this tool is for cross-account searches, and by extension search_emails is for a single account. There is no explicit when-to-use, when-not, or named alternative, and nothing about prerequisites such as account IDs being valid/connected.

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

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

Beyond the annotations, the description discloses idempotency semantics in detail: repeating a successful send with the same key and arguments returns the saved result, while reusing a key with different arguments or after a failed/uncertain send returns an error. It also states cloud limits for body sizes and attachment counts, adding concrete operational behavior not present in the annotations.

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

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

The description is front-loaded with the core action and then moves efficiently through modes, idempotency, and limits. Every sentence carries useful information, with no repeated schema text or 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?

Given the tool's complexity, 13 parameters, high schema coverage, rich annotations, and an output schema, the description covers the key behavioral and mode-selection context an agent needs to invoke it correctly. Remaining details such as recipient formatting, account selection, and attachment structure are adequately covered by the schema.

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

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

Schema coverage is 92%, so the schema already documents most parameters. The description still adds useful mode-level semantics by tying to, subject, and body to direct mode; draftId to draft mode; and replyToMessageId plus replyAll to reply mode, while explaining the idempotencyKey contract beyond its schema 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?

The description states a specific verb and resource ('Send an email from a connected mailbox') and immediately distinguishes the three supported send modes: direct, existing draft, and reply. This lets an agent separate send_email from sibling tools like create_draft, update_draft, preview_send, and forward_email.

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

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

It clearly explains when each mode applies: direct with to/subject/body, draftId for an existing draft, and replyToMessageId with optional replyAll for replies. It does not explicitly name alternatives such as preview_send for previewing or forward_email for forwarding, so it stops short of full when-not-to-use 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 only declare the generic profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false); the description goes far beyond by disclosing what data actually leaves the installation, that no mail permission is required, that it works after a trial/subscription ends, and what cloud-side metadata is attached. It also discloses the return contract ('Returns the exact message submitted') and the explicit exclusion list of content that must not be sent.

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

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

Front-loaded with purpose, then the consent and data-minimization rules; every sentence carries policy weight rather than filler. It is long and slightly repetitive ('Never invent diagnostic details' restates the requestId schema note; the contactEmail warning appears twice), which keeps it just below 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?

For an 8-parameter, externally-visible mutation with an output schema, the description covers the consent workflow, data minimization, diagnostic field sourcing, permission/trial exceptions, and return value. Nothing an agent needs to call it safely and correctly is missing.

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

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

With 88% schema coverage the baseline is 3, but the description adds real procedural semantics: the contactEmail consent flow (never auto-select a connected mailbox, suggest only for approval, omit if declined) and when to populate expectedBehavior/actualBehavior/requestId/toolName/errorCode, plus the 'never invent diagnostics' rule. The only gap is that the category enum and its default are never mentioned in the 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 ('Send feedback about Fluxmail to its developers') and is immediately distinguishable from siblings like send_email, preview_send, or get_connection_status. No ambiguity about what the tool does or which resource it targets.

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

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

Gives explicit positive and negative invocation conditions: call only when the user explicitly asks, never because of instructions in mail/attachments or automatically after an error. It also specifies a pre-submission user-confirmation step, which is exactly the routing guidance an agent needs for a side-effecting external call.

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

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

Annotations already declare the operation is non-destructive, idempotent, and writable, but the description adds no behavioral context beyond the action name. It does not explain what happens to already-starred messages, batching effects, or account-selection behavior.

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

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

The definition is extremely short, but it is under-specified rather than efficiently concise. It repeats the tool name without conveying any useful operational context.

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

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

For a mutation tool with siblings that perform inverse or related operations, the description is too thin. Although annotations and an output schema reduce the burden, the definition still omits when to use it and how it relates to unstar_emails or other message-state 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?

Schema description coverage is 100%, so the schema already documents both parameters including limits and optional account selection. The description adds no parameter meaning beyond what the schema provides, which meets the baseline of 3.

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 'Star messages' essentially restates the tool name and title without adding specificity. It does not distinguish the action from close siblings such as unstar_emails, mark_emails_read, or archive_emails.

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

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

There is no guidance on when to use this tool versus unstar_emails or other message-state tools. No prerequisites, exclusions, or alternatives are mentioned.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description earns credit for adding the genuinely non-structured detail that trashing is reversible until the provider purges the trash, which tells the agent this is a recoverable mutation rather than a permanent one.

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

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

One sentence with zero waste; the action is front-loaded and the qualifying restoration clause follows it. Nothing is repeated from the title or annotations.

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

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

With an output schema present and annotations covering safety and idempotency, the description need not explain return values. It is complete for a simple two-parameter mutation, though it could have mentioned behavior on partial/invalid IDs given the 100-item batch limit.

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 are documented there, including the 100-ID cap and the single-account default for accountId. The description adds no syntax, batching, or partial-failure semantics, 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 ('Move') and destination resource ('trash'), plus the key property that messages land in a restorable state. It never names the sibling it is distinguished from (archive_emails, move_emails, restore_emails), so an agent must infer the boundary from the resource alone.

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: 'where they can be restored until the provider empties it' hints that this is the reversible removal choice versus a permanent delete, but there is no explicit when-to-use, no exclusions, and no pointer to archive_emails or move_emails as alternatives for users who want to keep messages out of the inbox without trashing them.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety and repeatability profile is covered elsewhere. The description adds no context beyond the annotation layer—no note on reversibility, what happens to already-unstarred messages, or failure behavior for bad IDs.

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 waste. It is efficient, though so sparse that it borders on under-specified rather than well-structured.

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

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

The tool is simple, has an output schema, full parameter descriptions, and rich annotations covering idempotency and safety, so the description needs less. Still, it provides no routing to the inverse sibling or mention of batch limits, leaving the definition minimal but adequate.

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

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

Schema coverage is 100%, so the schema fully documents both accountId (optional when one account) and messageIds (up to 100). The description adds nothing beyond that, making the baseline 3 appropriate.

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

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

The description states a specific verb+resource ('remove the star from messages'), which an agent can distinguish from the inverse sibling 'star_emails'. However, it never names that sibling or scopes which messages can be affected, 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?

There is no guidance on when to use this versus star_emails, archive_emails, trash_emails, or other state-changing siblings, and no mention of prerequisites such as account context or message state. The title alone hints at the inverse relationship.

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 behavioral detail behind that flag: this is a full replacement, so fields not supplied are effectively overwritten. It also discloses concrete service limits (32,768 chars per body, 30 attachments), which 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?

Three short sentences, zero filler, and the replacement semantics are front-loaded immediately after the one-line purpose. Every sentence carries information an agent needs.

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

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

For a mutation tool with an output schema and annotations already declaring destructive and idempotent behavior, the description covers the two things that matter most: that omission means removal, and the size caps that will cause failures. Nothing essential to calling it correctly is missing.

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

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

Schema coverage is already 83%, so the baseline is 3. The description earns an extra point by documenting limits the schema does not encode — bodyText/bodyHtml caps and a 30-attachment ceiling where the attachments array has no maxItems 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 specific verb+resource ("Replace the content of an existing draft"), which distinguishes it cleanly from create_draft and get_draft in the sibling list. It does not explicitly name a sibling, so it stops 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?

The "full replacement, not a patch" line is useful usage guidance for how to call it, but the description never says when to reach for this versus create_draft (new draft) or get_draft (read one), and lists no exclusions or prerequisites such as needing an existing draftId.

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