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

No annotations are provided, so the description carries the full behavioral burden. It discloses the outcome location (Archive folder) but says nothing about permissions, idempotency when the message is already archived, reversibility, or failure behavior for invalid 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?

One short sentence, front-loaded with the action and destination, with zero 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?

For a one-parameter mutation tool with no output schema the definition is minimally workable, but the missing id-format detail and lack of any behavioral notes leave an agent with gaps it would have to discover by trial.

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 0%, so the description must compensate. It does add value by noting message_id accepts either a ref or a raw id, but it never defines what a 'ref' looks like or whether both forms are accepted everywhere, leaving the single parameter partly specified.

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/archive) and resource (message) plus a concrete destination (Archive folder), which implicitly separates it from generic move_message. It never explicitly names a sibling, so it falls short of a 5.

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

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

Single-message scope is implied by the name and the destination implies a lighter-touch alternative to delete_message, but there is no explicit when/when-not guidance or mention of bulk_archive_messages / move_message as alternatives.

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

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

No annotations are provided, so the description carries the full behavioral burden. It says messages are moved to Archive but omits whether the operation is reversible, permission requirements, partial-failure behavior for invalid ids, and any batch size limits — significant gaps for a bulk mutation tool.

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

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

A single front-loaded sentence that puts the action and scope first, with zero filler. Nothing in it repeats structured fields verbatim.

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 bulk mutation tool with no annotations and no output schema, the description is too thin — an agent cannot tell how failures are reported or what happens to a batch with partially invalid ids. The absence of any annotation safety signal leaves the behavioral profile largely undescribed.

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

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

There is one parameter with 0% schema description coverage, so the schema says nothing about the argument. The description partially compensates by stating the array accepts 'refs or raw ids', which is genuinely useful identifier-format guidance beyond the schema, but it says nothing about array size limits or empty-list 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 (move) and resource (many messages) plus the destination (Archive folder) and the batching intent ('in one call'). It differentiates from the singular sibling archive_message through 'many', though it never names the sibling explicitly.

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

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

'in one call' implies this is the batch alternative to archive_message, but the description never states when to prefer the bulk form or whether individual calls are ever appropriate. No exclusions or preconditions 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?

With no annotations, the description carries the full burden and does most of it: it discloses that dry_run is TRUE by default and what it returns, that on_protected skips protected senders by default, that date/sender filters are applied client-side, and that only_newsletters costs an extra header pass. It stops short of stating whether delete is permanent or recoverable and what the final report looks like.

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

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

Long but front-loaded and organized as one labeled block per parameter, so an agent can skim to the field it needs. A few parenthetical asides (the 'old <topic>' sweep example, the newsletter-vs-junk lecture) run longer than strictly necessary, but nothing is wasted filler.

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

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

For a 12-parameter, no-annotation, no-output-schema mutation tool this is close to complete: safety defaults, filtering composition rules, and protected-sender behavior are all covered. The remaining gaps are max_results truncation behavior and the shape of the non-dry-run result.

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

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

Schema description coverage is 0%, so the description must compensate for all 12 parameters, and it explains roughly ten of them including the undocumented-in-schema action enum values and the destination_folder requirement for move. max_results is only mentioned in passing as an upper bound with no default or truncation semantics, and folder's default of inbox is left implicit.

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 — find every message matching a query and apply one action to all of them in a single call — plus the distinguishing benefit (ids never enter the conversation). It is clearly the general filter-driven counterpart to the action-specific siblings (bulk_archive_messages, bulk_move_messages, etc.).

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

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

Explicitly prescribes the dry_run-then-rerun workflow, spells out the on_protected policy choices, and tells the agent when to prefer received_before/after over a Graph date $filter and when to use senders_only instead of a sender $filter. It even routes the agent to sender_summary for picking addresses.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the default side effect (marks read first), the all-or-nothing refusal semantics ('deletes nothing if any message is from a protected sender'), the override flag, and a real limitation (senders unknown for unlisted refs). That is non-obvious, decision-critical behavior an agent cannot infer from the schema.

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

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

Roughly three short sentences, front-loaded with the action and destination, then the refusal rule and the data-availability caveat. No filler; every clause adds information.

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

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

Covers action, defaults, failure mode, and override for a mutation tool with no annotations and no output schema. It omits what the call returns (counts, per-id results) and how unknown or malformed ids are handled, but the agent has enough to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate and does: message_ids accepts 'refs or raw ids', mark_as_read defaults true with the False case explained, and allow_protected is tied to the protected-sender refusal. All three parameters get meaning beyond their bare type and default.

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 with scope: 'Move many messages (refs or raw ids) to Deleted Items in one call.' The bulk framing plus the destination folder distinguishes it implicitly from the singular delete_message and from bulk_move_messages, which targets arbitrary folders.

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

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

Gives an explicit conditional path: if the call refuses due to a protected sender, 're-call with allow_protected=True to override.' It does not explicitly route the agent to delete_message for single messages or bulk_move_messages for other folders, so it falls short of full when/when-not coverage.

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

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

No annotations are provided, so the description carries the burden. It usefully discloses the underlying Graph $batch mechanism and that the operation toggles rather than only sets read state, but says nothing about per-message failure handling, batch limits, or required permissions.

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

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

A single front-loaded sentence with no filler. The only cost is terse jargon ('refs', '$batch') that may need unpacking.

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

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

For a 2-parameter bulk mutation with no annotations and no output schema, the description covers the core action but leaves out failure semantics and batching constraints an agent would need to call it safely.

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

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

Schema coverage is 0%, so the description must compensate. It does add real meaning for message_ids by noting 'refs or raw ids', and 'read/unread' hints at the is_read boolean, but is_read is never named and no format details or default (true) are given in prose.

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

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

States a specific verb and resource ('Mark many messages ... read/unread in one call') and the parenthetical '(refs or raw ids)' plus 'many ... in one call' implicitly separates it from the singular mark_read sibling. It does not explicitly name the alternative, 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?

Usage is only implied: 'many ... in one call' signals this is the bulk/efficient path versus mark_read, but the description never says when to prefer it, whether there is a batch size limit, or when to fall back to the single-message tool.

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

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

No annotations are provided, so the description carries the full disclosure burden. It signals batching ('in one call') but says nothing about permissions needed, behavior on unknown message ids or missing folders, whether the batch is atomic or partially applied, or batch size limits — significant gaps for a mutation tool.

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

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

One sentence, front-loaded with the verb and resource, with zero filler. It is efficient, though the terseness leaves little room for the behavioral and parameter detail a bulk mutation tool arguably 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?

With no annotations, no output schema, and 0% schema description coverage, the description should cover more: mutation semantics, failure modes, and return/confirmation behavior are all absent. An agent can form a call but cannot anticipate how errors or partial failures are handled.

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 0%, so the description must compensate, and it does partially: message_ids accepts 'refs or raw ids' and destination_folder accepts an 'id or well-known name.' This adds real meaning beyond the bare string/array types, but leaves 'ref' undefined and gives no examples for either parameter.

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

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

States a specific verb and resource ('Move many messages') plus the bulk scope 'in one call,' which implicitly separates it from the sibling move_message. It does not explicitly name that sibling, but an agent can distinguish bulk from single-message moves without reading the schema.

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

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

Usage is implied by 'many messages ... in one call,' suggesting it is for batch relocation rather than single moves. However, there is no explicit when-to-use/when-not guidance, no mention of when to prefer bulk_by_query or move_message, and no note on prerequisites such as folder existence.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that the message is saved to Drafts and never sent, but it does not mention permissions/auth needs, return behavior, or what happens on invalid recipients.

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

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

Front-loads the key purpose and non-sending behavior, then uses a compact Args list for parameters. There is no wasted text.

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

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

Given no annotations and no output schema, the description is mostly complete for calling the tool: it explains the action, non-send guarantee, storage location, and all parameters. It could be stronger with auth/error or return details, but the core invocation needs are covered.

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

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

Schema description coverage is 0%, so the description must compensate, and it does document all five parameters: to, subject, body, optional cc, and html. It adds useful semantics such as body being plain text by default and html=True making it HTML, though array/string details are 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 (compose a brand-new draft email) and explicitly excludes replies, which distinguishes it from the sibling create_reply_draft. It also clarifies that the draft is saved, not sent.

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

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

Gives clear usage context: brand-new email, not a reply, saved to Drafts and not sent. The alternative create_reply_draft is strongly implied by 'NOT a reply,' though not explicitly named as the tool to use 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?

No annotations are provided, so the description carries the full behavioral burden. It does not say what happens on a duplicate display_name, whether creation is idempotent, what permissions are required, or what the call returns (a folder id would plausibly be needed for later moves). For a mutation tool with zero annotation coverage this is a substantial gap.

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 with the core action and the key parameter behavior front-loaded, followed by a short usage hint. Nothing is padded, though the trailing usage sentence is thinner than it could be.

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

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

With no annotations, no output schema, and 0% schema description coverage, the definition should explain return value and duplicate-name behavior. It covers the parameters' meaning adequately but leaves the agent guessing about failure modes and what it gets back.

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

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

Schema coverage is 0%, so the description must compensate, and it does half the job: parent_folder is explained as accepting an id or display name and being omittable for a top-level folder, which the schema does not convey. display_name is only implicitly characterized as the folder's name; no constraints (uniqueness, length, allowed characters) are given.

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

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

States a specific verb and resource ('Create a mail folder'), which no sibling shares — list_folders reads, create_folder writes. It also distinguishes the nested vs top-level case. It stops short of noting what the call returns or how it differs from other creation tools like create_draft, but the resource is unambiguous.

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

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

The phrase 'Useful before moving mail into a new folder' implies the workflow (create_folder then move_message) but never names move_message or states when not to use it. Usage context is implied rather than spelled out, so an agent must infer the sequencing.

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

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

With no annotations, the description carries the burden and does disclose the crucial non-sending, human-review behavior. It omits whether it produces a reply vs reply-all, and whether existing draft conflicts overwrite anything.

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

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

Two compact sentences, front-loaded with the action and immediately followed by the non-send caveat. No filler.

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

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

For a simple 2-param tool with no output schema this is nearly adequate, but the undefined 'comment' parameter and no guidance on return value or draft location leave a real 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 0%, so both parameters are undocumented in structured data. The description explains message_id accepts 'ref or raw id', but the 'comment' parameter is never mentioned, leaving its role (reply body?) entirely unclear.

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

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

States a specific verb and resource ('Create a draft reply to a message') with an explicit parenthetical on id format. It is distinguishable from create_draft, though it doesn't explicitly contrast with that sibling.

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 clause 'Does NOT send it; a human reviews/sends from Outlook' implies this is the right choice when you want a human-gated reply rather than a send. However, it never explicitly says when to use this versus create_draft or which message types are eligible.

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

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

With no annotations, the description carries the full burden and does real work: it discloses the soft-delete/recoverability model ('recoverable from there until you empty it') and an otherwise invisible side effect (message is marked read before deletion, configurable via mark_as_read). It stops short of error behavior for already-deleted or missing messages.

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: destination and recoverability first, then the side effect and its override. Every clause earns its place.

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

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

For a two-parameter mutation with no annotations and no output schema, the description covers destination, reversibility, and side effects. What remains unstated (error/idempotency behavior on an already-deleted message, return value) is minor but not zero.

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 0%, so the description must compensate, and it does for mark_as_read — naming the default's purpose (keep deleted mail out of the unread count) and the opt-out (mark_as_read=False). It also clarifies that message_id accepts either a reference or a raw id, which the bare 'string' schema does not convey.

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

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

States a specific verb and resource ('Move a message ... to Deleted Items') plus the accepted identifier forms ('by ref or raw id'), which distinguishes it from move_message (arbitrary destination) and bulk_delete_messages (plural). An agent can pick it without opening the schema.

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

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

The recoverable-vs-permanent distinction implies this is a soft delete, but it never states when to prefer delete_message over archive_message, move_message, or bulk_delete_messages, nor any precondition (e.g. message must not already be deleted). Usage is implied rather than stated.

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

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

No annotations exist, so the description carries the full burden and does: it discloses that failing header sub-requests are silently dropped, explains the resulting discrepancy against bulk_by_query(only_newsletters=True), and warns that the List-Unsubscribe header marks bulk senders rather than junk. This is exactly the kind of failure-mode and misinterpretation context an agent needs.

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

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

Front-loaded with the action and the detection rule, then the IMPORTANT caveat, then the return shape, then args — a sound ordering. It runs a little long, and the sentence about the model deduping 200 rows by hand is motivational rather than operational, but nothing is padding.

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

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

With no annotations and no output schema, the description supplies the return shape ({checked, headers_ok, header_fetch_failed, newsletter_messages, senders}), the rationale for those fields, and the semantic trap to avoid. Nothing an agent needs in order to call it or interpret it is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it documents all three parameters: folder accepts an id or well-known name, max_check bounds how many recent messages are scanned, and group_by_sender=False yields raw per-message rows. It does not give an example of a well-known folder name, which would have closed the gap fully.

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 ('Scan a folder for bulk mail... and report how each sender can be unsubscribed') and pins down the detection criterion (List-Unsubscribe header). It is clearly distinct from unsubscribe/unsubscribe_many (discovery, not action) and from bulk_by_query, which it names 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?

Gives a strong exclusion ('Treat this as a list of candidates to show the user, never as a list to sweep') and explains why grouping is the default and when to set group_by_sender=False. It stops short of explicitly naming the sibling that performs the unsubscribe, leaving that hop implicit.

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

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

With no annotations the description carries the full load, and it discloses non-obvious traits: body is converted to plaintext, truncated, and the truncation exists for token economy. It does not cover invalid/expired ref behavior or whether attachments/HTML structure are dropped, which are the remaining gaps for a read tool.

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

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

Front-loaded sentence states purpose and the two most important behaviors (plaintext, truncation) before the Args breakdown. The Args block is tight, though it slightly duplicates the schema's field names.

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

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

No output schema exists, and the description covers what comes back: subject/from/date in metadata-only mode and a plaintext body otherwise, plus the size cap. Error handling and ref lifetime are the only notable omissions for a single-item read 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%, so the description must compensate, and it does: it explains the accepted id formats, the effect of include_body, and the semantics of max_chars including the 0 sentinel. It omits the actual default values (4000 and true) that the schema declares, so an agent must open the schema for those.

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 ('Get one message by ref') and pins the identifier form ('a short ref from list_messages, or a raw Graph id'). It is clearly differentiable from list_messages, which is named as the source of refs.

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 actionable per-parameter usage: include_body=False for metadata-only, max_chars=0 for no limit. The ref-from-list_messages hint establishes the workflow. It stops short of explicit when-not-to-use guidance (e.g., use list_messages for searching, or bulk tools for many messages).

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?

No annotations are supplied, so the description must carry behavioral disclosure. It does say what the tool returns (two counts), implying a lightweight read, but it does not state whether the operation is read-only, whether counts are scoped to a folder, or how counts are affected by unread state — modest but not rich transparency.

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 tool and its output with zero 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?

For a no-parameter summary tool with no output schema, the description conveys the essentials of what is returned. It could clarify scope (which inbox/folder) and read-only nature, but it is close to complete for this complexity level.

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

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

The schema has zero parameters and 100% coverage, so there is nothing for the description to disambiguate. The baseline for a no-parameter tool 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 ('quick counts') and resource ('the inbox') plus the two values returned: total messages and unread messages. An agent can tell this is a summary/count tool distinct from siblings like list_messages or sender_summary, though it does not explicitly name those alternatives.

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

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

The word 'quick' implies this is a lightweight overview rather than a message-listing tool, but there is no explicit statement of when to use it versus list_messages or sender_summary, and no exclusions 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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It communicates scope by saying "all mail folders" and lists returned fields, but it does not explicitly state that the operation is read-only, whether folders are ordered or nested, 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 a single, front-loaded sentence that immediately states the action and return fields. The examples are useful and no sentence 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?

For a zero-parameter listing tool with an output schema, the description is nearly complete: it names the resource, scope, and returned fields. Minor gaps remain around folder hierarchy, ordering, or whether all folder types are always included.

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

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

The tool has zero parameters, so the baseline score is 4 under the rubric. The description does not need to explain parameter semantics, and the empty schema is consistent with that.

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

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

The description states a specific verb and resource: "List all mail folders," and adds concrete examples such as Inbox, Archive, and custom folders. It clearly distinguishes folder listing from message listing, though it does not explicitly contrast with sibling tools like create_folder or list_messages.

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: an agent would call this to discover folder ids and display names before operations like move_message or list_messages. However, the description does not explicitly state when to use this tool versus alternatives, nor does it include exclusions or 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?

No annotations exist, so the description carries the full burden and does well: it discloses default ordering, the `ref` handle indirection, automatic pagination under fetch_all, a default safety cap of 500, and an explicit cost warning that per-message previews across a big folder are expensive. It stops short of stating read-only semantics, auth/permission needs, or rate limits.

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

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

Front-loaded with the one-line purpose, ordering, and the critical `ref` handoff before the Args block, and each Args line adds real information rather than restating a name. It runs long, but the length is driven by nine undocumented parameters, so little 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, so return values need no elaboration beyond the `ref` handoff, which is supplied anyway. For a zero-required-parameter, nine-argument listing tool with no annotations, an agent has everything needed to page, filter, search, or bulk-fetch correctly.

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

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

Schema description coverage is 0%, so the description must compensate entirely and it does — all nine parameters are explained with behavior the schema cannot express: well-known folder names enumerated, top/skip nullified by fetch_all, an OData $filter example, search precedence over filter, and max_results described as a safety limit with its default.

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 messages in a folder') plus the default ordering and the one condition that changes it ('newest first (unless searching)'). It also explains the returned shape ('compact rows keyed by a short `ref` handle (not the raw Graph id)'), which instantly distinguishes it from get_message and the bulk_* 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?

Gives explicit conditions for the tricky flags: fetch_all for whole-folder bulk work, include_keywords for triage vs get_message for a full read, and notes that search causes filter_query/order to be ignored. It does not, however, route the agent between this tool and siblings like inbox_summary, sender_summary, or bulk_by_query, so the alternatives coverage is partial.

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?

No annotations exist, so the description carries the full burden. It helpfully discloses that the operation is a toggle (read OR unread), but says nothing about idempotency, permission requirements, behavior for an unknown message_id, or what is returned — significant gaps for a mutation tool.

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

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

A single front-loaded sentence with zero waste. The action and the toggle semantics are both delivered 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?

For a simple two-parameter mutation with no annotations and no output schema, the description covers the core semantics but leaves the agent guessing about idempotency, error behavior, and return value. Adequate minimum, with clear gaps.

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%, so the description must compensate. It adds real meaning to message_id by revealing it accepts 'a ref or raw id', and to is_read via 'as read or unread', but it does not explain the ref format, why two input forms exist, or the default of is_read=true — so the compensation is only partial.

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

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

States a specific verb and resource ('mark a message ... as read or unread'), and the singular 'a message' implicitly distinguishes it from the bulk_mark_read sibling. However, it never names or contrasts that sibling explicitly, so the differentiation is left to inference.

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

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

Usage is only implied: the singular 'a message' suggests single-message operation, and the sibling list contains bulk_mark_read, but the description never states when to use this versus the bulk variant. No prerequisites or exclusions 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not say whether the destination folder must already exist, whether moving requires permissions, what happens on invalid IDs, or what the response looks like.

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 tightly-worded sentence that front-loads the action and resource with zero waste. The parenthetical parameter hints are efficient rather than verbose.

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 annotations, no output schema, and 0% schema description coverage, the description needs to do more. It covers the basic action and parameter formats but omits error behavior, folder prerequisites, and return semantics for a simple two-parameter mutation.

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 0%, so the description must compensate and does so partially: it clarifies message_id accepts a ref or raw id and destination_folder accepts an id or well-known name. That adds real meaning beyond the bare schema, but the accepted formats/values are not fully specified.

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 (move) and resource (message) plus the destination concept (folder). It is clear what the tool does, though it does not explicitly name a sibling like bulk_move_messages to distinguish the single-message case.

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 singular 'a message', which suggests it is for one message rather than bulk operations. It never states when to use this instead of bulk_move_messages or archive_message, leaving the agent to infer the single-vs-bulk distinction.

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

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

With no annotations, the description carries the full burden and does so well: it discloses case-insensitive matching, glob vs substring semantics, default exclusion behavior in bulk_by_query, outright refusal in bulk_delete_messages, and per-call override 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 description is front-loaded with the core purpose, then adds only relevant pattern and bulk-operation details. Every sentence contributes useful information.

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

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

For a low-complexity tool with optional parameters and no output schema, the description is nearly complete. Minor gaps remain around return shape for reads and edge cases such as duplicates or invalid patterns.

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 0%, so the description needs to compensate. It explains the pattern syntax well and clarifies no-argument reads, but does not explicitly describe the add and remove array parameters beyond what their names imply.

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 pair: reading or editing a keep-list of protected senders. It also distinguishes the tool from bulk siblings by explaining that bulk operations will not touch these senders.

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

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

It explicitly says when to use the tool, gives examples of valuable mail to protect, explains that no arguments means read-only access, and describes how bulk_by_query and bulk_delete_messages behave with this list.

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

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

With no annotations, the description carries the burden well: it discloses return fields, sorting order, the max_results scan cap, and important caveats about heuristic brand labels and shared brands. It does not cover error behavior or permissions, but for a read-only summary tool this is substantially transparent.

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

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

The purpose is front-loaded, then usage rationale, return shape, and caveats follow in a logical order. The length is justified by the grouping semantics and the brand-label warning.

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

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

No output schema or annotations exist, yet the description explains the returned row fields, ordering, and the key grouping caveat around brand and brand_shared. That is enough for an agent to invoke and interpret the summary correctly.

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

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

Schema description coverage is 0%, but the Args block explains all five parameters, including folder identification, min_count filtering, top row limits, max_results message scanning, and unread_only. This adds clear meaning beyond the bare schema titles and defaults.

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: group a folder by sending address and report per-sender message/read counts. The scope is precise enough to distinguish it from generic message-listing or folder-summary 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?

Explicitly says to use it before proposing deletion and explains why read-rate evidence matters. It does not name sibling alternatives such as find_newsletters or protective-sender tools, so it stops short of full when/when-not routing.

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

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

With no annotations, the description carries the full burden and does so: it discloses the three method branches, that one-click returns HTTP status, that mailto only creates a DRAFT (scope cannot send), that weblinks are deliberately not auto-fetched for safety, and the caveat that unsubscribing confirms the address is live. These are exactly the side effects and risks an agent needs before mutating 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?

Front-loaded with the core action, then a scannable bullet list per method, ending with the important caveat. Dense and mostly waste-free, though the repeated 'with execute=True' phrasing in each bullet is slightly redundant against the standalone default sentence.

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

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

No output schema and no annotations, yet the description explains what each branch returns (HTTP status, draft, URL, or a method/target report). It doesn't say what happens when a message has no List-Unsubscribe header, the one gap an agent might hit in practice.

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 0%, so the description must compensate, and it does: 'message_id' is described as a ref or raw id, and 'execute' is fully explained as the gate between report-only and performing the action, far beyond the bare boolean/default 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 and resource ('Unsubscribe from the bulk sender of a message') and clarifies the identifier accepts a ref or raw id. It is easily separable from siblings like delete_message, unsubscribe_many, and find_newsletters because it names the exact mechanism (List-Unsubscribe headers).

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

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

Explicitly documents that execute=False is a dry-run report and execute=True performs the action, with behavior varying by method. It also gives a real exclusion rule: 'for actual spam, prefer delete/block instead,' routing the agent to sibling tools for the wrong case.

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

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

With no annotations, the description carries the burden and does well: it discloses dedup keying on target rather than sender, the deliberate tradeoff of duplicate requests over missed unsubscribes, batching of the header fetch, and the needs_browser bucket so 'nothing fails silently'. It omits any mention of the execute flag's default-false/dry-run behavior and required permissions, which are the most consequential behaviors for a mutation tool.

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

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

Purpose and the sibling comparison are front-loaded, and the dedup rationale, while long, explains behavior an agent may need to reason about. Some of the savedSearchId narrative is more justification than instruction and could be tightened.

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 return shape is spelled out well, which is valuable with no output schema, and the batching/dedup model is covered. But for a two-param mutation tool with no annotations, leaving the execute dry-run flag completely unexplained is a material completeness gap.

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

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

Schema coverage is 0% and neither parameter is described. message_ids is only indirectly implied by talk of per-message tokens and savedSearchId, and the execute boolean (default false) is never mentioned at all — the agent cannot tell from the definition whether the call actually unsubscribes or only previews.

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 and scale ('Unsubscribe from many bulk senders in one call'), and explicitly contrasts itself with the sibling unsubscribe() as the batched variant. An agent can distinguish it from unsubscribe and from bulk_* tools immediately.

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

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

Names the alternative ('Same per-message semantics as unsubscribe(), but ... one tool call instead of one per sender'), which tells the agent to prefer this for multi-sender sweeps. It never states the inverse condition (when to use the single-message tool, or that a single ID should go to unsubscribe()), so the guidance is clear but not fully two-sided.

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