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

Annotations already mark it read-only, and the description adds valuable behavior: credentials are never included in the result and the tool reports permitted actions. This helps set expectations beyond 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?

Two short sentences with no filler. The core purpose is front-loaded, and the usage guidance and privacy note each earn their 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 diagnostic tool with an output schema, the description fully covers when to use it, what it verifies, and an important behavioral caveat. 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 schema carries no burden. The description appropriately focuses on behavior rather than parameter documentation.

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: verify IMAP/SMTP credentials and report permitted actions. This clearly differentiates it from the sibling email operations, none of which are diagnostic.

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 instructs to run this tool first when a tool fails or account setup is unknown. This gives an agent a clear decision rule for when to invoke it.

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

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

Annotations already flag destructiveHint=true, but the description adds that the operation is a move to Trash rather than an expunge, so the message remains recoverable. It also discloses the EMAIL_ALLOW_DELETE=true prerequisite. These details go beyond the annotation and clarify the actual destructive scope and conditions, providing substantial added context.

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 (two short paragraphs) and front-loads the core action and prerequisite in the first sentence. The second paragraph adds a single clarifying nuance about recoverability. No unnecessary words or repetition. It is well-structured and efficient.

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 only 2 parameters (1 required) and an output schema present, the description covers the essential behavioral aspects: the action, the recoverability, and the prerequisite. Nothing critical is missing, and the existence of an output schema means return values are already defined. The description is complete for its 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?

The input schema already describes both parameters (uid and folder) with 100% coverage. The description does not add further explanation of parameters or their usage beyond what the schema provides. It only mentions the folder implicitly through the move-to-Trash action, but that's not new information. Baseline 3 is appropriate given high schema coverage.

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 ('Move a message to Trash') with a clear resource (a message) and destination (Trash). It differentiates from the sibling move_email by specifying the Trash destination and the recoverable nature, making its purpose unambiguous. The title also aligns perfectly.

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 does not explicitly state when to use this tool versus alternatives like move_email. It implies this is for deletion (to Trash) but doesn't contrast with move_email or other siblings. The only guideline is the prerequisite EMAIL_ALLOW_DELETE=true, which is a requirement rather than a selection criterion. Guidance is minimal but present.

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 indicate this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds materially useful context: writes are confined to EMAIL_ATTACHMENT_DIR and filenames are sanitised, which clarifies side-effect scope and security behavior. This goes beyond the annotations without contradicting them.

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 deliver the action, result, and key behavioral constraints with no redundancy. The most important information is front-loaded, and 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?

For a tool with full schema coverage, an output schema, and annotations covering read/write/destructive hints, the description is sufficiently complete. It adds security and scope constraints that matter for safe invocation. Minor omissions like overwrite behavior or error handling are not critical given the available structured metadata.

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

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

Schema description coverage is 100%, so the parameters are fully documented in the schema. The description does not add parameter-level meaning, but it also does not need to because the schema already explains uid, folder, and filename. The baseline of 3 applies because the description offers no supplementary parameter insight.

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 ('Save an attachment'), the destination ('server's attachment directory'), and the result ('return its path'). It clearly distinguishes itself from the sibling tools, none of which handle attachment downloading.

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 purpose implicitly defines when to use this tool: when a downloaded attachment is needed. However, there is no explicit guidance about when not to use it or which alternatives to prefer. The description does not mention exclusions or conditions beyond the simple action, so guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the output includes IMAP special-use flags, which is useful return-value context. However, it does not disclose potential behaviors such as sorting, pagination, failure modes, or whether folder hierarchy details are included.

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 sentence that immediately states what the tool does and the key output detail. There is no filler, and the most important information is front-loaded.

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

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

For a read-only, zero-parameter list operation with an output schema present, the description is sufficient. The agent knows what will be returned (folders with IMAP special-use flags) and that no arguments are needed. Nothing essential is missing for correct invocation.

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

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

The tool has zero parameters and schema description coverage is 100%, so the schema fully defines the input contract. With no parameters to explain, the description does not need to add parameter-level detail. This warrants the baseline score of 4.

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

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

The description states a specific verb and resource: 'List the folders in the mailbox'. It also adds a distinguishing detail, 'with their IMAP special-use flags', which is not present in any sibling tool description. This makes the tool's purpose clear and unique among the listed 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?

There is no explicit guidance about when to use this tool versus alternatives, nor any mention of prerequisites such as needing an existing connection. The tool name and description make the basic intent obvious, but the description does not provide usage context 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?

Annotations already convey readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds no behavioral context beyond those annotations; it restates the seen/flagged actions without disclosing additional traits such as authorization needs or side effects, so it meets the baseline but does not exceed it.

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 communicates the complete purpose with no filler or redundancy. Every word contributes to understanding the tool's scope.

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

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

Given the annotations, full parameter schemas, and an output schema, the concise description is sufficient for an agent to select and invoke the tool correctly. The only slight tension is the title, but the description resolves it, so 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?

Schema description coverage is 100%, so every parameter (uid, seen, folder, flagged) already has a clear schema description. The tool description adds no additional parameter semantics beyond what the schema provides, matching the baseline for full schema coverage.

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 ('mark') and resource ('a message') and enumerates the exact operations: read/unread and flag/unflag. Although the title 'Flag an email' is narrower, the description clarifies the full scope and distinguishes this from sibling tools like read_email, move_email, and 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 context is clear: use this tool when a message's seen or flagged state needs to be changed. However, the description does not explicitly state alternatives or exclusion conditions, such as 'use read_email if you only need to view the message,' so usage guidance is implied rather than stated.

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

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

Annotations already flag this as destructive, so the description's added value is the permission requirement EMAIL_ALLOW_DELETE=true, which is useful operational context. This does not contradict the annotations.

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

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

The description is two short sentences with no filler. The core action is front-loaded and the permission requirement is stated immediately after.

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

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

The tool is simple, has an output schema, and benefits from annotations that indicate destructive behavior. The description adds the key precondition. A minor gap is that it does not describe failure behavior, but this is not critical given the annotations and schema coverage.

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

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

Schema description coverage is 100%, so the schema already documents uid, folder, and destination. The description does not add parameter-specific meaning beyond the action, so a baseline score of 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?

The description states a specific verb ('Move') and resource ('message to another folder'), making the operation unambiguous. It stands apart from siblings like delete_email and mark_email because the action and target are clearly named.

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 for when to use the tool: moving a message between folders. It also provides a concrete precondition, EMAIL_ALLOW_DELETE=true, which helps an agent determine whether the call is permitted. It does not explicitly exclude alternatives, but the context is sufficient given the sibling set.

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 readOnlyHint and openWorldHint annotations, the description discloses useful return-behavior details: HTML-only messages are converted to plain text, and long bodies are truncated with a marker rather than silently cut. This helps the agent set expectations about the content it will receive. It does not discuss error behavior or rate limits, but with read-only annotation coverage this is adequate.

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

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

Two short sentences front-load the core behavior and then add the only critical output caveat about body conversion and truncation. There is no filler, repetition, or unnecessary detail.

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, 100% parameter coverage, and read-only annotations, the description covers the important behavioral caveats. A minor gap is the lack of an explicit pointer to download_attachment for attachment content, but the phrase 'attachment list' already distinguishes the tool from that sibling.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description adds no parameter-specific meaning beyond confirming that body, headers, and attachment list are returned; therefore the baseline score of 3 applies.

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

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

The description uses a specific verb and resource: 'Open one message and return its body, headers, and attachment list.' This clearly identifies the operation and distinguishes it from sibling tools like search_emails (finding messages) and download_attachment (fetching attachment bytes).

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 the intended flow: after search_emails returns a UID, open that message. The uid parameter description reinforces this by saying the UID comes from search_emails. However, the description itself does not explicitly list when not to use this tool or direct the agent to download_attachment for actual attachment content, so it stops 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?

Annotations indicate this is a mutating operation (readOnlyHint=false) but not destructive. The description adds substantive context beyond annotations: it writes to the Drafts folder, nothing leaves the account, and it is safe when sending is disabled. This gives the agent important behavioral expectations.

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 with each one earning its place: the core action, the safety rationale, and the crucial condition about EMAIL_ALLOW_SEND. It is front-loaded with the primary purpose and contains 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?

Given the output schema exists and annotations are present, the description covers the essential context for correct invocation: what the tool does, why it is safe, and when it works. A bit more detail about draft placement or reply_to behavior would be helpful but is not required for basic use.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description does not add parameter-specific detail, but the baseline of 3 applies because the schema carries the full burden.

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: 'Write a message to the Drafts folder without sending it.' It clearly differentiates from send_email by emphasizing that the user will send it themselves, so an agent can distinguish this tool from its siblings.

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

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

The description explains when to use this tool: as the safe way to prepare mail when the user wants to review it first, and it explicitly notes it works when EMAIL_ALLOW_SEND is false. It does not name send_email outright but the contrast is strong enough to guide selection.

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 openWorldHint, and the description adds meaningful behavior: newest-first ordering, summary-only results, AND-combined filters, and empty-query behavior. It also clarifies the relationship to read_email via uid. This goes well beyond the structured annotations without contradicting them.

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

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

Three sentences front-load the core purpose, then compactly convey filter behavior and the necessary next step. Every sentence earns its place, and there is no redundancy with the schema.

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 search tool, the description plus rich schema and output schema cover the essentials: order, result shape, filter semantics, default behavior, and follow-up action. It is not fully exhaustive—e.g., it does not mention pagination beyond limit—but the available structured data fills most gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining how filters combine (AND) and what happens when no filters are provided, which is not stated in individual parameter descriptions. This is a meaningful supplement to the schema.

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

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

Description names a specific verb ('Find messages') and resource, and differentiates from sibling tools by explicitly stating the result is short summaries, not full bodies. It also names the companion read_email call, so the agent understands where search ends and retrieval begins.

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 usage context: filters are ANDed, omitting all filters returns recent messages, and full message bodies require a separate read_email call. It does not explicitly enumerate when not to use this tool versus siblings like wait_for_new_emails, but the context is strong enough for an agent to choose correctly.

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

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

Beyond the annotations, the description reveals that sending is irreversible, requires user confirmation, is gated by an environment flag, and enforces recipient allowlisting. It also explains reply threading/filling behavior. This is rich contextual disclosure that helps the agent anticipate real-world consequences.

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 tightly written sentences. The most important safety warning is front-loaded, followed by enabling conditions and a specific usage pattern. There is no filler or repetition of schema details.

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 9-parameter tool, the description covers the key operational constraints: side-effect irreversibility, user confirmation, environment gating, allowlist enforcement, and reply behavior. The schema covers parameters, and an output schema exists, so nothing critical 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 100%, so the baseline is 3. The description adds meaningful semantics for reply_to_uid, explaining that it threads the reply and auto-fills recipient and subject. This goes beyond the schema's simple field descriptions.

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

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

The description opens with 'Send an email', a specific verb and resource. It further differentiates itself by highlighting irreversibility and the reply behavior, which separates it from sibling tools like save_draft and read_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 gives clear context: confirm content first, sending only works when EMAIL_ALLOW_SEND=true, allowlist requirements, and how to reply via reply_to_uid. It does not explicitly contrast with save_draft, so it misses the full 'when to use vs alternatives' guidance.

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

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

The description discloses blocking behavior, early return upon arrival, empty results on timeout, and exclusion of pre-existing messages. These details go beyond the readOnlyHint and openWorldHint annotations and give the agent accurate expectations for a potentially long-running call.

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 tight paragraphs with no filler; the main verb and resource come first, followed by a use case and edge-case behavior. Every sentence contributes useful information.

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

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

For a blocking read tool, the description, annotations, full parameter schema, and output schema together fully specify when and how to invoke it. The agent knows the purpose, wait semantics, timeout behavior, and that existing messages are excluded.

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%, with all four parameters documented with defaults and bounds, so the description does not need to repeat parameter details. It adds contextual framing around blocking and new messages, but no parameter-specific semantics beyond what the schema already provides.

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?

Description opens with a clear verb ('Block') and resource ('mail arrives in the folder... return the new messages'). It distinguishes itself from reading existing mail by emphasizing only new arrivals and gives a concrete example use case (verification code).

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?

States when to use it: 'wait for something expected, such as a verification code.' It also clarifies a boundary with 'nothing already in the folder is reported,' which tells the agent not to use this for reading existing mail. It does not explicitly name sibling alternatives, but the context is clear enough.

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