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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds genuinely non-obvious behavior: the destination is resolved via SPECIAL-USE (with concrete per-provider examples) and the message is not permanently expunged, so it remains recoverable from a mail client. This is meaningful context beyond the annotations, though it says nothing about failure modes (missing UID, folder not found) or behavior when the message is already 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?

Front-loaded with the core action and its mechanism in the first sentence, with supporting detail after. The SPECIAL-USE parenthetical earns its place by explaining how the Trash folder is located, though the provider examples are slightly longer than strictly necessary.

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

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

For a destructive 3-parameter mutation with an output schema present, the definition covers what the action does, where the data goes, and the meaning of every parameter. Missing only edge-case behavior for invalid UID or already-trashed messages, which is a modest gap rather than a blocking one.

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 carry the parameters, and its Args block does: account is tied to list_accounts, folder is defined as the message's current folder, and uid is the message UID within that folder. The docstring-dump args are spelled out even though the formal schema gives only titles, which is real compensation; a minor gap is that it doesn't state the expected UID format despite typing it as a string.

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

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

States a specific verb and resource ("Delete a message") and immediately defines the mechanism: it moves the message to the account's Trash folder rather than expunging it. That mechanism statement is what separates it from move_email in the sibling list, so an agent understands the distinction without opening a schema.

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

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

Usage is implied by the mechanism (soft delete, recoverable), but there is no explicit when-to-use vs. when-not, and no named alternative — notably it never says to prefer move_email for relocating a message somewhere other than Trash. An agent must infer that from the folder semantics.

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

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

Annotations already declare non-read-only, idempotent and non-destructive behavior, so the safety profile is covered. The description adds useful mechanism detail (the \Flagged IMAP flag and the default-on behavior of the flagged arg) but says nothing about permissions, error cases, or what the response 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?

A single front-loaded sentence states the action, followed by a compact per-argument block. Every line is informative, though the Args section is a docstring rather than agent-oriented guidance.

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 rich annotations, the definition needs mainly to cover parameters and mechanism, which it does. Minor gaps are lack of explicit sibling routing and any error/permission notes.

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 every property is title-only, so the description carries the full burden and does so reasonably: it identifies account as coming from list_accounts, explains folder and uid roles, and clarifies that flagged defaults to true and false clears the flag.

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

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

States a specific verb pair (flag/unflag) and resource (message) plus the underlying mechanism of setting or clearing the \Flagged flag. It implicitly distinguishes itself from siblings like mark_read or move_email, though it never names them.

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

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

Usage is only implied by the verb; there is no explicit statement of when to choose flag_message over mark_read or other message-mutating siblings, and 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?

Annotations already declare readOnlyHint=false, openWorldHint=true, and idempotentHint=false, so the safety profile is partially covered. The description still adds real value beyond them: content transformation ("Fwd:" prefix, original headers and body below the note, attachments re-attached) and the confirm-first requirement. It does not state that repeated calls each produce a new outgoing email, so duplicate-send risk is only implied.

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

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

The purpose and the confirm-first rule are front-loaded, and the Args block is scannable with no filler. The two paragraphs are dense but every clause (prefix, headers, body placement, attachment default) conveys behavior an agent would otherwise have to guess.

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

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

An output schema exists, so return values need not be explained, and the description covers purpose, side effects, the confirm-first safety step, and every parameter for a 9-parameter mutation tool. Only edge behavior (invalid uid, missing attachments, failure modes on an open-world send) is left unstated.

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 carry the full burden, and its Args block does document all nine parameters, including the non-obvious ones (account from list_accounts, body as a note placed above forwarded content, include_attachments defaulting to true). It adds no format guidance for addresses or uid syntax, so not a full 5.

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

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

The first sentence names a specific verb and resource ("Forward a message") plus the immediate consequence ("send it immediately"), which distinguishes it from send_email, reply_email, and save_draft_email in the sibling list without opening a schema.

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

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

It gives a clear usage directive — "confirm with the user first" before an external, irreversible send — and the account/folder/uid framing shows it applies to existing messages. It stops short of explicitly directing the agent away from send_email/reply_email when those are the better fit.

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

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

Goes well beyond the annotations by disclosing implementation behavior: Gmail uses X-GM-THRID across All Mail, other providers traverse the Message-ID/In-Reply-To/References graph across inbox, sent, archive, all-mail and drafts. It also states the return shape (envelopes, no bodies), which the readOnly/idempotent hints do not convey.

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

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

Front-loaded with the core action and ordering, then provider behavior, then an Args block. Slightly redundant in restating parameter purposes after the prose, but every line carries information and there is no filler.

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

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

For a four-parameter, provider-varying lookup tool this covers the scope of the traversal, the seed identification paths, and the envelope-only return, so an agent can call it correctly without opening the schema. Output schema exists, so no further return-value explanation is required.

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 carries the full burden and does: it documents all four parameters, including the format detail that message_id includes angle brackets, and the pairing semantics of folder + uid. It also states the seed may be identified by either message_id OR folder+uid, a mutual-exclusivity rule the schema does not encode.

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 (return every message in the same conversation as a given message) plus an ordering guarantee (oldest first). It is clearly distinguishable from siblings like read_email and search_messages, which is reinforced by naming read_email for body content.

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

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

Gives a clear use context (thread/conversation expansion) and an explicit alternative for a different need: 'use read_email for content.' It does not explicitly contrast with search_messages or state when-not to use it, so it falls short of full when/when-not/alternatives coverage.

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

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

Goes beyond the annotations by disclosing the data source (a local accounts.toml), that no mail server is contacted, and — security-relevant and not in annotations — that passwords and password sources are never included. The no-network fact partly overlaps openWorldHint=false, so it is strong rather than exceptional.

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 verb and resource, then a tight enumeration of return fields, then two clarifying limitations. No filler sentences; every clause 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?

An output schema exists, yet the description still summarises the entry shape and explicitly names the field that unlocks all other tools. For a zero-argument, read-only discovery tool, nothing further is required.

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, which sets the baseline at 4. The description confirms 'Takes no arguments', consistent with the empty 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 ('List the mail accounts configured in owlpost's accounts.toml') and enumerates exactly what each entry contains (name, email, provider, IMAP/SMTP hosts, sent-mail auto-save). It is unmistakably distinct from every sibling tool, which all operate on folders or messages rather than the account config.

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

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

Explicitly routes the agent: the returned `name` is 'the value to pass as `account` to every other tool', which tells an agent to call this first before search_messages, read_email, etc. No when-not guidance is given, but for a zero-argument config readout there is no realistic alternative to exclude.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value by explaining how the folder `role` is derived (RFC 6154 SPECIAL-USE flags) and that it is null for ordinary folders, which is behavior an agent could not infer from annotations or 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?

The first sentence front-loads the purpose, and the entry-format paragraph is dense with useful detail. The 'Args:' block for a single parameter is slightly formal overhead but earns its place by naming the sibling source of the value.

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 one required parameter, a full annotation set and an output schema, the description covers what is needed: the source of the account argument and the shape/meaning of the returned folder metadata. It stops short of mentioning failure modes (bad account name, auth errors) that would make it fully self-sufficient.

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

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

Schema description coverage is 0%, so the description must carry the full burden for the single `account` parameter. It does clarify the expected value as an 'Account name from list_accounts', which identifies both the source and the format, but no further constraints (casing, aliasing) 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: list every IMAP folder (mailbox) in an account, with 'mailbox' disambiguating the term. It does not distinguish itself from the sibling resolve_folder, which plausibly overlaps in purpose, 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?

Implies intended usage by noting the returned folder `name` is what you pass to other tools, establishing this as an entry-point/discovery call, and it points at list_accounts for the required argument. It gives no explicit when-to-use versus when-not-to-use guidance, and never contrasts with resolve_folder.

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 real value by disclosing that the operation is a \Seen flag toggle rather than a content change, but says nothing about permission requirements, server sync, or what happens on an invalid uid.

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 sentence is front-loaded and the Args block is a compact, scannable list. Some redundancy with the schema exists, but given 0% schema coverage that repetition earns its place.

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

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

An output schema exists, so return values need not be explained, and the tool is simple. Still missing are the call-chain guidance (resolve_folder for the folder path, search_messages for the uid) and the behavior when the UID does not exist, which matter for a four-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 description coverage is 0%, so the description carries the full burden, and it does enumerate all four parameters including the default for read. However, the semantics are thin: "uid: Message UID" is essentially a restatement of the name and does not explain where a uid comes from (search_messages) or whether it is folder-scoped.

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 (mark a message as read or unread) and even names the underlying mechanism, the \Seen flag. It is distinguishable from the closest sibling, flag_message, only by inference from the flag name; nothing explicitly contrasts the two.

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 Args block hints at provenance for account ("from list_accounts") and folder, which implies a discovery workflow, but there is no explicit when-to-use guidance, no exclusion versus flag_message, and no statement of prerequisites for obtaining a valid uid.

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

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

The description goes well beyond the annotations by disclosing the implementation: IMAP MOVE when supported, otherwise COPY plus \Deleted flag and EXPUNGE on the original. It also warns that the message receives a new UID in the destination and the old uid becomes invalid, which is critical behavioral context an agent cannot get from destructiveHint=false/true flags alone.

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

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

The opening sentence front-loads the action, followed by the most decision-relevant behavioral caveat (UID invalidation). The Args block is slightly redundant with the schema titles but each line adds real meaning, so almost 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?

For a destructive, non-idempotent mutation the description covers mechanism, side effects on UIDs, and parameter sourcing, and an output schema exists so return values need no explanation. Remaining gaps are failure modes such as a nonexistent dest_folder or a message that cannot be expunged, which would round it out to a 5.

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 carry parameter meaning, and it largely does: account is tied to list_accounts, folder is defined as the message's current folder, uid is scoped to that folder, and dest_folder points at list_folders. It does not specify the UID string format or whether dest_folder must already exist, so it falls just short of fully compensating.

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

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

The description opens with a specific verb and resource: 'Move a message from one folder to another.' That is unambiguous and clearly distinct from sibling mutations such as delete_email or flag_message. It stops short of explicitly contrasting itself with any named sibling, so it lands at 4 rather than 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: an agent infers it should call this when a message needs relocating. There is no explicit when-to-use/when-not-to-use guidance and no mention of alternatives (e.g., copy semantics or delete_email for removal). The references to list_accounts and list_folders help with prerequisites but are not usage 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?

Annotations already declare readOnlyHint and idempotentHint, and the description goes well beyond them: default body selection, 50,000-character truncation rationale (MCP result limits), the text_full_length/html_full_length size reporting, 1-based attachment part indices for save_attachment, and inclusion of threading headers. These are exactly the behaviors an agent needs to plan around and cannot get from 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 core behavior is front-loaded in the first sentence and the truncation caveat follows immediately; nothing is padded. The docstring-style 'Args:' block is slightly mechanical with wrapped lines, but given zero schema coverage that enumeration is necessary rather than wasteful.

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

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

For a six-parameter read tool with an output schema, the definition covers the side-effect question, size/truncation limits, and the cross-tool linkage for attachments. Return-value detail is correctly delegated to the existing output schema, so nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: every one of the six parameters is explained, including defaults (include_html=false, include_text=true, body_max_chars=50000), provenance of required identifiers, and the warning that HTML mail can be very large. This is meaning the schema alone 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 ('Read one message') and enumerates exactly what comes back: decoded headers, body, attachment list. The phrase 'without marking it read' immediately separates it from mark_read, and the mention of save_attachment/list_accounts/search_messages anchors it against siblings.

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

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

Usage context is clear: it points to list_accounts, search_messages and save_attachment as the sources for its arguments, and the 'without marking it read' clause implies mark_read is the tool for that side effect. There is no explicit statement about when to prefer get_conversation over this tool for whole-thread reads, which keeps it from a 5.

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

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

Annotations only declare the generic profile (readOnly=false, destructive=false, openWorld=true, idempotent=false); the description adds the substantive behavior an agent needs — the reply is sent immediately and is not reversible, user confirmation is required first, and the exact addressing/threading/quoting transformations applied are spelled out.

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 imperative sentence carrying the critical safety constraint, followed by a compact behavior paragraph and a clean Args list; no filler and every clause conveys either a constraint or an observable effect.

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 7-parameter mutation tool with an output schema present, the definition covers invocation prerequisites, side effects, addressing rules, and per-parameter meaning; nothing an agent needs to call it correctly is missing.

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

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

With 0% schema description coverage, the description carries the full burden and does document all seven parameters, adding real meaning for body (quoted original appended), reply_all (includes original To/Cc), html (alternative part), attachments (local file paths), and account (sourced from list_accounts). The folder and uid entries are largely restatements of the field names, so it falls just short of complete.

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

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

Opens with a specific verb+resource ("Reply to a message and send the reply immediately") and immediately distinguishes itself from send_email/forward_email by describing reply-specific mechanics: Re: prefixing, In-Reply-To/References headers, and quoting the original 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?

Gives a concrete procedural constraint ("confirm with the user first") that governs when/how to invoke it, and the reply_to-an-existing-message framing implicitly excludes composing new mail. It stops short of explicitly naming send_email/forward_email as the alternatives for those cases.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavior: the resolution strategy (SPECIAL-USE flags first, fallback to common folder names) and the failure mode (returns null if no matching folder exists). What is missing is any note on provider variance in failure or caching, but the disclosure goes well beyond 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 core behavior and example lead, followed by the fallback rule and null-return, then the arg notes — a sensible front-loaded order. The Args block is a small amount of overhead but earns its place given the 0% schema coverage.

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

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

An output schema exists so return-shape explanation is unnecessary, and the description still covers the null case and both parameters. For a two-parameter resolver with full annotation coverage this is essentially complete; only explicit routing versus list_folders is absent.

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 neither parameter carries an enum in the schema, so the description does the heavy lifting: it enumerates the eight valid role values with a case-insensitivity note, and identifies account as 'Account name from list_accounts'. That is a large compensation for the schema gap, though it does not state the exact expected casing/format of the returned account string.

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

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

States a precise verb+resource ('resolve a special-use role to the provider-specific folder name') and immediately grounds it with concrete examples ('sent' becomes 'Sent Messages' on iCloud, '[Gmail]/Sent Mail' on Gmail). This is unmistakably distinct from sibling tools like list_folders, which enumerate folders rather than map a role to a provider 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 implied rather than stated: naming 'list_accounts' as the source of the account argument tells the agent the prerequisite chain, and the role vocabulary implies this precedes move_email/delete_email calls. However there is no explicit when-to-use statement and no exclusion versus list_folders, so the agent must infer the 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?

Beyond the annotations, it discloses that the mailbox is untouched, that an existing file at the target path is silently overwritten, that '~' is expanded, and that missing directories are created — all material side effects an agent could not infer from readOnlyHint/idempotentHint. The overwrite behavior is the one point of mild tension with destructiveHint=false, but because it is disclosed explicitly the agent can act on it rather than being misled.

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

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

The definition is front-loaded with the core action and side effects, then moves into a scannable per-parameter block. Every sentence carries information — no restatement of the tool name 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?

For a five-required-parameter write tool, the definition covers side effects, path resolution rules, directory creation, and briefly notes the return payload (path, size, MIME type, filename) even though a full output schema exists. An agent has everything needed to call it 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 description coverage is 0%, yet the Args block fully documents all five parameters: 'part' is annotated as a 1-based index sourced from read_email's attachments list, and 'save_to' gets detailed disambiguation between directory mode (trailing slash, existing directory, or no extension preserves the original filename) and full-path mode. This adds meaning well beyond the bare typed properties and compensates entirely 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?

The first sentence names a specific verb and resource ('Download one attachment from a message and write it to the local filesystem') with scope limited to a single attachment. It is clearly distinguishable from siblings like read_email (which lists attachments) and from the mail-mutation tools such as move_email or delete_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?

The description establishes the calling context by tying each input to its source: 'account from list_accounts' and 'part from read_email's attachments list', which tells an agent the prerequisite read step. It also states 'The mailbox is not modified', implying this is not a substitute for move/delete operations. It stops short of explicit when-not-to-use or naming an alternative save mechanism, so it falls short of a 5.

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

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

Beyond the annotations (which already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses the actual mechanism: appended to the special-use Drafts folder with the \Draft flag, and 'Each call creates a new draft', which reinforces non-idempotency concretely. It does not mention failure modes such as invalid account or missing attachment paths.

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

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

Front-loaded with the core action and the send_email contrast before the Args block, and no filler sentences. The Args block is somewhat verbose at 10 lines but each maps to a distinct parameter.

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 10-parameter mutation whose return values are already covered by an output schema, the description supplies folder/flag semantics, threading guidance for in_reply_to and references, and per-parameter meaning. Nothing an agent needs to construct a correct call 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 carries the full param burden; its Args block documents all 10 parameters and adds real meaning where the schema has only titles — 'Message-ID this draft replies to, for threading', 'Message-IDs of earlier messages in the thread', 'Local file paths to attach', and the cross-reference 'Account name from list_accounts'. A few entries (subject, body) are near-restatements, keeping it short of 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 the specific verb+resource ('Compose an email and save it to the account's Drafts folder without sending it') and immediately contrasts with send_email, so an agent can separate it from the closest sibling without opening a schema.

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

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

Explicitly says 'Use this instead of send_email whenever the user wants to check a message first', which is a clear when-to-use rule with a named alternative. It does not address when to prefer reply_email/forward_email versus using in_reply_to/references here, leaving one sibling relationship to inference.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), it discloses the key operational behavior: the folder is opened read-only so searching never marks mail read — a real risk with IMAP SEARCH. It also explains filter composition (all AND), string matching semantics (case-insensitive substring, auto-quoting of multi-word values), ordering (newest first), and that has_attachment is best-effort rather than exact.

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 summary sentence is front-loaded and the Args block is scannable, which is appropriate for 16 parameters. A few lines are near-redundant with the parameter names (cc, to, subject), but the overall size is justified by the parameter count.

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

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

An output schema exists, so the result-field enumeration is belt-and-braces but useful for deciding whether a follow-up read_email is needed. The definition covers all filters, matching semantics, and read-only safety for a 16-parameter tool; the only remaining gap is pagination/truncation semantics for limit and any error behavior for invalid folders or malformed raw queries.

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 carry all 16 parameters, and it does document each one with defaults and meaning, plus value-format details the schema omits (YYYY-MM-DD for since/before, raw IMAP syntax example, quoting behavior). It does not clarify whether seen/unseen are mutually exclusive or how they interact, and limit has no note about 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 opening sentence gives a specific verb (search), a scoped resource (one folder), the mechanism (structured filters), and the return shape (message envelopes, newest first). The single-folder scope plus the redirect to read_email for bodies clearly separates it from siblings like read_email and get_conversation.

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 routes explicitly: use list_accounts for the account name, list_folders or resolve_folder for other folders, and pass folder + uid to read_email when the body is needed. It also states that setting raw disables every other filter, which prevents misuse. It lacks explicit guidance on when to prefer this over get_conversation for thread-shaped questions.

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

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

Beyond the annotations it discloses the irreversible nature of the action, the conditional Sent-folder side effect tied to auto_save_sent (with the iCloud rationale), and the contents of the return value including the null case. That is meaningful context the annotations do not convey. It does not cover failure modes such as SMTP errors or attachment limits, so it stops short of the top mark.

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 irreversible-action warning and the sibling routing are front-loaded before the mechanical Args list, which is the right ordering for a high-stakes tool. The Args block is long but each line is short and scannable; only the subject/body entries are 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 10-parameter, non-idempotent, open-world mutation tool, the description covers prerequisites, the confirmation requirement, the side effect on the Sent folder, and the alternative tool for replies. Return values are summarized even though an output schema exists, and 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 description coverage is 0%, so the description must carry parameter meaning, and the Args block largely does: it explains where account values come from, that bcc addresses are never written to headers, that attachments are local file paths, and that in_reply_to/references drive threading. A few entries are near-tautological restatements ("subject: Subject line", "body: Plain-text body"), which keeps it from 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?

The opening clause names a specific verb and resource ("Send a new email over SMTP") plus an immediacy constraint, and the closing sentence explicitly separates it from reply_email, which covers the respond-to-existing-message case. An agent can distinguish this from save_draft_email, reply_email, and forward_email without inspecting any schema.

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

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

It gives both a positive usage rule and an explicit alternative: "To answer an existing message prefer reply_email, which fills in recipients and threading for you." It also states a prerequisite (account name comes from list_accounts) and a required pre-action step (confirm with the user first).

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