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

With no annotations provided, the description correctly takes on the burden of behavioral disclosure. It explicitly states that nothing is sent and that no confirmation is needed, which are the key safety-relevant behaviors. It does not describe all side effects (e.g., overwriting an existing draft or return value), but it covers the most important non-sending 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 two sentences with no wasted words. The primary purpose is front-loaded, and the critical non-sending caveat is included concisely.

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

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

The tool has 8 optional parameters, no parameter descriptions, no annotations, and no output schema. The description provides only the core purpose and safety caveat, leaving substantial gaps around parameter usage, expected return, and account requirements. This is insufficient for a tool with this complexity.

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

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

Schema description coverage is 0%, so the description must compensate for the 8 undocumented parameters. It does not mention to, cc, bcc, subject, body, html_body, attachments, or account, nor does it clarify that all fields are optional. The parameter names are somewhat self-explanatory, but the description adds no semantic value beyond the schema.

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

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

The description states a specific verb and resource ('Save a draft in the Drafts folder') and explicitly differentiates this tool from sending by saying 'Nothing is sent'. This clearly distinguishes create_draft from siblings like send_message and reply_to_message.

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 clear usage context: use this tool when the user needs to review and send later from their own mail client, not when an immediate send is intended. It lacks explicit naming of alternatives or a direct 'when not to use', but the implied routing is strong.

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 provided, the description carries the full burden and does well: it discloses that deletion is recoverable by default, that permanent deletion erases messages, and that the permanent path requires a two-step confirmation using confirmation_token and commit=True. This is exactly the kind of behavioral context an agent needs for a destructive tool.

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

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

Three compact sentences front-load the main operation and then expand on the two deletion modes without wasted wording. The two-step confirmation flow is explained tersely but completely.

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 description is behaviorally strong but not fully complete for a 7-parameter tool with no output schema. It leaves several invocation details to inference, especially how to specify which messages to delete and whether account/folder values need to be considered.

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 explains permanent, commit, and confirmation_token, which are the least obvious parameters. However, it does not clarify the relationship or selection between uid and uids, nor the role of folder and account beyond their schema 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?

The description states a clear verb and resource ('Delete messages') and adds important scope by explaining the default Trash behavior and the permanent-delete path. It distinguishes deletion from sibling operations like move_messages, though it does not explicitly name a sibling for comparison.

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

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

The description implies that this tool is used when messages need to be removed, and it explains the soft-delete versus permanent-delete workflows. However, it does not explicitly state when to prefer this tool over alternatives such as move_messages, nor does it describe any preconditions or exclusions.

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

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

With no annotations, the description must disclose behavioral traits. It states the primary action (saving to disk) and the default download directory, but omits important details such as whether the operation is destructive (overwrites existing files), requires authentication, or involves network calls. It also does not mention error conditions or reversibility. This is a significant gap 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?

The description is concise, consisting of two sentences that efficiently state the action, identification method, and default directory. It is well-structured and front-loaded with the core functionality, with no wasted words.

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

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

The tool has 6 parameters with no schema descriptions and no output schema. The description covers only a few aspects (identification and default download dir) but leaves other parameters unexplained, does not describe the return format beyond 'path', and lacks error handling or prerequisite details. This is incomplete for a tool with this complexity.

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

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

Schema description coverage is 0%, so the description must explain the parameters. It explains that index or filename can identify the attachment, and that download_dir defaults to the project's downloads folder. However, it does not explain the uid, folder, or account parameters, which are likely needed to specify the message. This incomplete coverage fails to compensate for the missing schema descriptions.

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

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

The description clearly states the tool saves one attachment to disk and returns the path, with identification via index or filename from get_message. It is specific and distinguishes itself from sibling tools that handle message operations rather than attachment saving.

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

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

The description gives clear context on how to identify the attachment (via index or filename from get_message), implying a prerequisite that get_message must be called first. It does not explicitly state when not to use it or alternatives, but the context is sufficient for an agent to understand its purpose.

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 provided, the description carries the full behavioral burden and does it well: it discloses the side effect ('stays unread unless mark_seen=True'), truncation at max_chars with a flag, and the exclusion of attachment content. It could add error behavior or response-shape details, but this is already substantial.

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 with no filler: the core output is front-loaded, and each following sentence adds a distinct behavioral fact. It is compact yet complete enough for an agent to understand 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?

For a 6-parameter tool with no output schema and no annotations, the description does a strong job covering return composition and side effects. Remaining gaps are folder/account selection semantics, include_html behavior, and how the truncation flag is represented in the 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?

The description adds meaning to uid, max_chars, and mark_seen, which is helpful given 0% schema description coverage. However, folder, account, and include_html receive no explanation beyond their parameter names and defaults, leaving a meaningful gap.

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

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

The description names the exact operation ('Fetch one message by uid') and enumerates the return payload: headers, body as text, and attachment names/sizes. It also disambiguates from attachment retrieval by explicitly stating the content is not included.

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 intended use case is implied: use this when you have a message uid and need a single message's contents. It does not explicitly route away from sibling tools like search_messages when no uid is available or get_attachment when attachment bytes are needed.

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 of behavioral disclosure. 'List' clearly implies a read-only operation with no side effects, and the description explicitly states the output scope (configured mailboxes and password-set booleans). This is sufficient for a simple, non-mutating 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 sentence that front-loads the verb and resource, includes the key output detail, and contains no filler. Every word 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 parameterless, read-only list tool with no output schema, the description is complete. It tells the agent exactly what will be returned (mailboxes and password-set status), and there are no additional inputs or behaviors an agent would need to know.

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. The description does not need to explain parameters, and there are none in the schema to document.

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 clearly states a specific verb ('List') and resource ('configured mailboxes'), plus a concrete attribute (password-set status). It distinguishes this tool from all siblings, which focus on messages, drafts, and folders rather than account configuration.

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 provides clear context for when to use the tool: when you need to see configured mailboxes and their password status. It does not explicitly exclude alternatives, but given that no sibling tool deals with mailbox/account configuration, the intended usage is unambiguous.

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

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

With no annotations, the description carries the full burden. It discloses meaningful behaviors: special-folder detection, case sensitivity of folder names, and possible nesting. The read-only nature is clear from 'List', and no side effects are implied. It stops short of describing response format or account-selection behavior, but core transparency is solid.

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 purposeful sentences with no filler. The primary action is front-loaded, and the critical guidance about case sensitivity and taking names from here is delivered as a concise, actionable directive.

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 core purpose and a key constraint are present, making the tool usable in simple cases. However, the description does not explain how the optional account parameter behaves, what a response contains, or how this interacts with account selection, especially given the sibling list_accounts 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?

The only parameter, 'account', is optional with a default but is never mentioned in the description. Since schema description coverage is 0%, the description should compensate by explaining which mailbox account the tool acts on or what an empty account means, but it does not.

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 action ('List') and a specific resource ('every folder in a mailbox'), and adds the useful detail that Sent, Trash, and Drafts folders are detected. This clearly distinguishes it from siblings like list_accounts, search_messages, or get_message.

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 'always take names from here rather than guessing' gives the agent a clear directive to use this tool as the authoritative source for folder names. It implies the tool should be used before operations that require exact folder names, though it does not explicitly name alternatives or exclusions.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the core mutation (setting read_state true or false), but it does not mention permissions, whether the operation is reversible, what happens when both uid and uids are supplied, or any error/side-effect behavior.

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

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

A single sentence with no filler. The core behavior is front-loaded, and the parenthetical '(read_state=True)' efficiently ties the human description to the schema 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?

With five parameters, zero required, no annotations, and no output schema, this one-line description is under-specified. An agent would need to infer how account and folder affect the operation, whether uid or uids is preferred, and what calling the tool returns or confirms.

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 maps 'one or more' to uid/uids and mentions read_state=True, but it does not explain the distinction between uid and uids, nor what folder and account mean or how they behave with 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?

The description clearly states the action ('Mark') and the resource ('one or more messages') plus the direction ('read... or unread'). It is specific enough to be understood on its own, but it does not explicitly differentiate itself from siblings like set_flag, which could also touch message state.

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

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

There is no guidance about when to use this tool versus alternatives such as set_flag, delete_messages, or move_messages. The description only states what it does, not under what circumstances it should be chosen.

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 behavioral disclosure burden. It does disclose a meaningful side effect: 'UIDs change on move', which is exactly the kind of warning an agent needs. However, it does not mention permissions, error behavior, reversibility, or what the operation returns.

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 two short sentences with no filler. The primary action is front-loaded, followed by essential usage guidance and a critical behavioral warning. Every sentence earns its place.

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

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

Given five optional-looking parameters, no annotations, 0% schema coverage, and no output schema, the description leaves too much ambiguous. It does not clarify which parameter is the target folder, whether to pass uid or uids, or how account is resolved. The UID warning and list_folders hint help, but the invocation contract is still underspecified.

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, but it only partially clarifies folder naming. It does not explain the relationship between uid and uids, the role of the source folder parameter versus destination, or how account should be populated. The phrase 'another folder' is not explicitly mapped to the destination property.

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 action: 'Move messages to another folder', clearly identifying the resource (messages) and the operation (moving to a folder). It also gives a concrete example ('to archive them') and is clearly distinct from sibling tools like delete_messages, send_message, or mark_read.

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

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

The description gives explicit operational guidance: use an exact folder name from list_folders, which is a useful precondition and directs the agent to a sibling tool. It provides context for when this tool fits, such as archiving, but does not explicitly state when not to use it versus alternatives like delete_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?

With no annotations, the description carries the full burden and discloses the important two-phase commit behavior ('Previews first and sends on the second call'). It also explains reply_all recipient behavior and thread preservation. It does not detail side effects of preview or whether the first call mutates anything, but the core behavioral contract is clear.

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 no filler. The core purpose is front-loaded, and the second sentence packs the critical workflow detail into a compact reference to send_message.

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 tool with no annotations and no output schema, the description is too thin. It does not explain what the preview response contains, how to obtain or interpret confirmation_token, which message uid refers to, or what the final send returns. The reliance on 'exactly like send_message' is helpful but not self-contained.

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, but it only explains reply_all, commit, and confirmation_token. The other seven parameters (uid, body, folder, account, html_body, attachments, quote_original) receive no explanation and are not obviously inferred from the description alone.

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

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

States a specific verb ('Reply'), a specific resource ('a message'), and a key scoping detail ('keeping the thread intact'). It also distinguishes itself from send_message by specifying recipient behavior ('Goes to the sender only unless reply_all=True').

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?

Provides clear operational guidance: preview first, then send with commit=True and confirmation_token. The 'exactly like send_message' reference strongly implies a shared workflow, but does not explicitly state when to choose this over alternatives like send_message or create_draft for new emails.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively explains that reading never marks messages as seen, describes server-dependent behavior for 'text', warns about performance implications of include_snippet, and clarifies date comparison semantics. It does not cover auth or rate limits, but the key behavioral traits are well disclosed.

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 compact and front-loads the core purpose, then provides targeted details on tricky parameters. Each sentence contributes new information without redundancy. It could be slightly more structured but is efficient overall.

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 14 parameters and no output schema or annotations, the description is reasonably complete for a search tool. It explains key behaviors like read safety, date handling, and performance costs. However, it omits details like how multiple filters combine (AND/OR), pagination semantics of limit/offset, and the meaning of an empty text search. These gaps prevent a higher score.

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 description coverage, so the description must compensate. It adds meaning for several parameters: date format and day-only comparison, server-side substring behavior of 'text', the download cost of include_snippet, and raw_criteria overriding other filters. However, many parameters (limit, offset, folder, unseen, flagged, subject, to_address, from_address, account) are left unexplained, though their names are self-descriptive. Partial coverage earns a 3.

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

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

The description clearly states the tool searches a folder and returns message headers, with a specific ordering (newest first). This distinguishes it from siblings like get_message (single message retrieval) and list_folders (folder listing). The verb 'search' and resource 'folder' are explicit.

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 provides practical usage tips, such as keeping the limit small when include_snippet is true, and notes that raw_criteria overrides other filters. However, it does not explicitly compare against alternatives or state when not to use it, though the context is clear enough for an agent to infer appropriate usage.

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 available, the description carries the full burden and does a strong job: it discloses the non-sending preview, the required commit token flow, the Sent-folder copy, and the local-path requirement for attachments. It omits some details like error behavior and token expiration, but the critical behavioral traits are 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?

Three tight sentences with no filler. The most important behavioral caveat, the preview-then-commit sequence, is front-loaded, and each sentence contributes unique 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 tool with no output schema and no annotations, the description covers the full calling protocol, side effects, and the token requirement. Minor gaps remain around exact preview return structure, error cases, and account selection, but an 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 coverage is 0%, so the description must compensate. It adds meaningful semantics for attachments, commit, confirmation_token, and 'identical arguments'. However, most parameters like to, cc, bcc, body, html_body, and account are left to inference from their names.

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 clearly states the action as 'Send a new mail' and adds the two-call preview/commit behavior. The word 'new' distinguishes it from reply_to_message, though it does not explicitly name alternatives like create_draft.

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

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

The description gives concrete procedural instructions: first call previews and returns a token, second call with commit=True actually sends. However, it does not explicitly say when to prefer this tool over siblings such as create_draft or reply_to_message, or when not to use it.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only says 'add or remove' but does not explain the effect of the 'value' parameter (whether true adds and false removes), nor any side effects like persistence, authentication requirements, or error conditions. This is a significant gap 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?

The description is a single, concise sentence that is easy to parse and front-loads the core purpose. However, it lacks any structural breakdown of parameters or usage, but that's a completeness issue, not a conciseness one. It earns a 4 for being appropriately sized.

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

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

The tool has 6 parameters, no output schema, and no annotations, yet the description provides only the function's purpose and flag list. It does not cover parameter semantics, return values, or any edge cases, making it inadequate for an agent to call it correctly without additional schema documentation.

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 0% description coverage, and the description does not compensate. It fails to explain the meaning of 'uid', 'uids', 'value', 'folder', or 'account'. Even the list of flags is not explicitly tied to the 'flag' parameter. An agent would have to guess the semantics from parameter names and defaults, which is insufficient.

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 clearly states the tool's function: adding or removing an IMAP flag, and enumerates the valid flag values. This distinguishes it from generic message operations, though it doesn't explicitly differentiate from mark_read, which could be seen as a subset. Still, it's specific enough for an agent to understand the core purpose.

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

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

The description provides no guidance on when to use this tool versus alternatives like mark_read or delete_messages. There is no mention of exclusions or conditions, so an agent would have to infer usage from the function name and description, which is insufficient.

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