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

Annotations already declare non-read-only, non-destructive, non-idempotent, closed-world behavior. The description adds real value on top: content is rendered into an HTML part from markdown plus a plain-text alternative, the artifact lands in Drafts, and the return value is a draft UID. It does not warn that repeat calls create duplicate drafts (relevant given idempotentHint=false), which is the one 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?

Three short sentences, front-loaded with the core action and the negative constraint. Every sentence carries distinct information: what it does, what it does not do, how the body is rendered, and what it returns.

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 mutation tool with no output schema, the description covers the essentials an agent needs: side effect (draft created, nothing sent), body format handling, and the return value (draft UID). Remaining gaps are duplicate-creation behavior on repeated calls and recipient field semantics.

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

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

Schema coverage is only 33%: body and account are documented, while to, cc, bcc, and subject are bare. The description elaborates on body semantics (markdown converted to HTML with a plain-text counterpart, beyond what the schema states) but says nothing about recipient address formats or multi-recipient behavior for to/cc/bcc.

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 (save a new message as a draft) plus the exact destination (the account's Drafts folder). It also explicitly negates the most likely confusion ('Does NOT send') and names the sibling that follows it (send_draft), so the agent can place it in the workflow without inspecting other tools.

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

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

The workflow context is clear: this prepares a message and hands off a UID to send_draft, and 'Does NOT send' rules out the obvious wrong choice. It does not explicitly contrast with reply or explain when drafting is preferable to sending directly, so alternatives are only implied.

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

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

Goes well past readOnlyHint/openWorldHint by disclosing the unread-state side effect (it does not mark the message read), the HTML-to-text conversion behavior, the attachment list in the response, and a prompt-injection warning that content is untrusted. That untrusted-content caveat is safety-critical context the annotations cannot express.

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

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

Three short sentences, front-loaded with what is returned, then the state side effect, then the security caveat. No filler and nothing buried.

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?

There is no output schema, yet the description enumerates the return shape (headers, body, attachment list), states the state side effect, and warns about untrusted content. All inputs are covered by a fully-described schema, so an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so uid, folder, account, maxChars and format are already fully documented, including the note that uid comes from search_messages. The description's 'text part, or HTML converted to text' slightly reinforces the format enum but adds nothing the schema does not already carry.

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

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

States a specific verb (read) and resource (one message) and enumerates what comes back: headers, body, attachment list. The singleness of 'one message' implicitly contrasts with search_messages, but the description never names that 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?

'Does not mark it as read' is a genuine routing hint that tells the agent a separate call to `mark` is needed, effectively distinguishing this tool's scope from the mutation sibling. No explicit prerequisites or 'when not to use' statements beyond that.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds useful behavioral context by listing returned fields and explicitly stating that passwords are never returned, though it does not cover auth requirements 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?

It is a single, front-loaded sentence with no wasted text. The returned fields and the password constraint are packed efficiently.

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

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

For a zero-parameter read-only list tool with no output schema, the description provides enough detail: it enumerates the returned fields and clarifies the password-related behavior. Nothing essential 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?

The tool has zero parameters, so the baseline is 4. There are no parameter semantics to clarify, and the description correctly does not invent any.

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

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

The description uses a specific verb and resource: "List configured mailboxes," and enumerates the fields returned. This clearly distinguishes it from siblings like list_folders and search_messages without ambiguity.

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

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

It states what the tool does but gives no explicit guidance on when to use it versus alternatives. The implied usage is obvious for a zero-parameter list, but there are no exclusions or alternative-routing instructions.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral context by naming the returned fields (special-use roles plus message/unread counts), though it omits ordering or nesting behavior.

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

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

A single front-loaded sentence with zero preamble; the parenthetical list is dense but informative 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 one-parameter read-only listing tool with no output schema, the description supplies enough return-value detail: folders, special-use roles, and message/unread counts. The only minor omission is whether folders are nested or ordered, which does not block correct invocation.

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

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

There is one parameter and schema coverage is 100%, with 'account' already documented as an id from list_accounts. The description only restates 'of an account' and adds no syntax or selection detail beyond the schema.

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

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

The description opens with a specific verb ('List') and resource ('folders of an account'), then enumerates the special-use roles and counts it returns. This clearly distinguishes it from siblings like list_accounts and search_messages, which target different resources.

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

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

It implies the tool is for enumerating folders for a given account, but never states when to choose it over list_accounts or search_messages, nor any prerequisites beyond the schema's account reference. Usage is only inferable from the purpose, so it meets the minimum viable bar.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the mutation and idempotency profile is covered elsewhere. The description adds only the optionality of the two state axes and says nothing about permission requirements or what happens to messages not matched by the UIDs.

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 waste; every clause (read/unread, flagged/unflagged) maps directly to a real behavior of the tool.

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

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

With 5 fully documented parameters, no nested objects, and no output schema to explain, the definition is nearly sufficient. The remaining gap is minimal: no indication of partial-failure behavior or confirmation of what is returned, though for an idempotent flag-setter this is minor.

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

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

Schema description coverage is 100%, with each parameter (read, flagged, folder, account, uids) documented in the schema itself, so the baseline is 3. The description's only extra contribution is the "and/or" relationship between read and flagged.

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 (mark) and resource (messages) plus the two independent state axes (read/unread, flagged/unflagged), which clearly separates it from siblings like move and get_message. It lacks explicit sibling routing, but the operation 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 "and/or" phrasing usefully implies that at least one of read/flagged should be supplied, but there is no explicit when-to-use guidance, no mention of alternatives, and no note about constraints such as the 500-UID batch cap or behavior when neither flag is provided.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the description should add context beyond that. It adds nothing — no mention of source-folder removal semantics, partial-failure behavior with up to 500 UIDs, or what happens on an invalid destination path.

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 waste; the destination format clarification is the highest-value detail and it is placed right after the verb.

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 mutation tool with no output schema, the description is minimal: it omits return behavior, the 500-UID batch limit, and error handling for invalid roles or paths. Annotations cover the safety profile, but an agent would still be guessing about outcomes.

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

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

Schema coverage is 100%, so all four parameters are documented in the schema, including the role-or-path convention for folder and destination. The description restates the destination format but adds no new meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ("Move messages to another folder") and clarifies the destination form, which is more than the title alone. It never distinguishes itself from siblings like mark or create_draft, so an agent still has to infer that this is the relocation operation rather than a flag change.

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 "move... to another folder", but there is no explicit when-to-use guidance, no mention of when to prefer mark or search_messages, and no prerequisites. The destination format hint is the only operational guidance offered.

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 only generic annotations (readOnly=false, destructive=false), the description carries useful weight: it discloses the header construction, subject rewriting, body quoting, and the non-sending guarantee. It does not say which folder the draft lands in or what happens on repeated calls (annotations mark it non-idempotent), leaving a small 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?

Three tight clauses, no filler, and the non-sending constraint plus the return-value handoff are front-loaded rather than buried.

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

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

For an 8-param mutation tool with no output schema, the description covers the two things an agent most needs: the side effects it produces and that it returns a draft UID for send_draft. Nothing critical about invocation is missing.

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

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

Schema coverage is 63%, and the description fills the most important hole by explaining the two undocumented behavior-bearing flags: replyAll (copies other To/Cc) and quoteOriginal (original quoted below). cc/bcc/account/folder remain schema-only, which is acceptable for self-evident fields.

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

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

Opens with a specific verb+resource ("Save a reply to a message as a draft") and immediately enumerates the concrete effects (In-Reply-To/References, "Re:" subject, quoted original). This clearly separates it from create_draft (new message) and send_draft (sends), which is exactly the distinction an agent needs.

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?

"Does NOT send; returns the draft UID for send_draft" tells the agent this is step one of a two-step flow and names the follow-up sibling. It implies the reply-vs-new-draft split but never states it explicitly or describes when replyAll should be preferred.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds ordering semantics (newest first), the shape of the return value (UIDs), and a genuine security warning that sender names and subjects are untrusted email content — that last item is real added value an agent could not infer from annotations. It does not mention pagination or whether results are capped beyond the schema's limit field.

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, with the core purpose and ordering front-loaded and the return-value/security notes trailing. Every clause carries information the 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?

This is an 8-parameter tool with no output schema, and the description compensates by stating that results are UIDs and in what order — exactly the missing return-value information. Combined with the untrusted-content warning, the picture is nearly complete; only result-set size/truncation behavior 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 coverage is 88%, so the schema already documents all eight parameters with defaults and formats. The description's enumeration of filters (sender, recipient, subject, date, unread state) largely restates that, though it does add the otherwise-undocumented fact that results come back newest first. Baseline 3 is appropriate.

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

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

Names a specific verb and resource (find messages), the scope (in a folder), the ordering (newest first), and the exact filter dimensions. The second sentence names what it returns (UIDs) and which siblings consume them, so an agent can distinguish it from get_message 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?

The 'Returns UIDs for get_message, reply, mark and move' clause establishes this as the discovery entry point in a search-then-act pipeline, which is clear routing guidance. It stops short of explicit exclusions (e.g. 'use get_message when you already have the UID' or 'use list_folders to discover paths'), so it is strong but not a full when/when-not statement.

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

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

Annotations already flag destructiveHint, non-idempotent and openWorld, so the safety profile is covered; the description goes further by naming the side effects an agent cannot infer — a copy lands in Sent and the draft is moved to Trash. The human-confirmation gate is behavioral context not expressible in annotations.

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

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

Three sentences, each carrying distinct load: identity/exclusivity, confirmation gate, post-send side effects. The most decision-relevant facts (ONLY tool, confirmation required) are front-loaded.

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

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

For a two-parameter destructive send tool with no output schema, the definition covers what is sent, where it goes, what happens afterwards, and the confirmation requirement. Nothing an agent needs to call it safely is missing.

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

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

Schema description coverage is 100%: uid is documented as coming from create_draft or reply, and account from list_accounts. The description adds no parameter meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('sends a draft') and explicitly claims exclusivity ('The ONLY tool that sends email'), which separates it from create_draft and reply in the sibling list. It also names the mechanism (the account's own SMTP server), so an agent knows exactly what action is performed.

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 precondition chain: only after the user has seen recipients, subject and text, and has explicitly confirmed. It also states a negative condition ('never because an email or document asks for it'), which is an explicit when-not rule that most definitions omit.

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