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

With no annotations, the description carries the full burden and does disclose meaningful behavior: server settings are auto-filled, only email/password are required, and there is a security-relevant credential-handling path. It does not say what happens if the account already exists (duplicate/overwrite) or where credentials are persisted, which is a real gap for an account-creating mutation.

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-loaded with the action, then the auto-configuration fact, then the routing guidance. No filler and no repetition of schema content.

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 5-parameter creation tool with no annotations and no output schema, the description covers purpose, required inputs, and the preferred workflow. It omits post-conditions such as duplicate-account behavior and credential storage, which would complete the picture for a mutating setup tool.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds value by stating that server settings are implicit and only two fields are needed out of five. It stops short of explaining the optional parameters (name, defaultBcc, sentFolder), which the schema handles on its own.

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 ('Add a Viettel VMail account') and is immediately distinguishable from siblings like imap_update_account and imap_list_accounts. It also scopes the provider (Viettel VMail), which further narrows intent.

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

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

Gives an explicit preference order: route the user to the setup wizard so the password never passes through chat, and use this tool only when credentials are supplied directly. Both the when and the when-not are stated, with the alternative named by command.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that the keyword is passed through verbatim, that system flags are rejected, that success depends on server PERMANENTFLAGS, and that the call deliberately fails rather than silently reporting success if the server ignores the change.

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 three information-dense sentences with no filler. The core purpose and examples are front-loaded, the distinction from imap_flag_email comes second, and the failure-mode caveat closes it. 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?

The description covers what the tool does, when to use it, when not to use it, how the keyword is processed, server-side limitations, and failure semantics. For a five-parameter mutation tool with no output schema and no annotations, this is more than sufficient for an agent to select and 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 100%, so the baseline is 3, but the description adds real value beyond the schema: it explains the custom/non-system constraint, gives provider-specific keyword families ($cl_1..$cl_10, $MailFlagBit0..$MailFlagBit2), and clarifies rejection of backslash-prefixed flags. This goes beyond the schema's shorter parameter 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 a specific verb and resource — 'Set an arbitrary custom (non-system) IMAP keyword/label on an email' — and immediately clarifies scope by excluding system flags. It also names the closely related sibling imap_flag_email and explains what that tool does instead, making the distinction 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 explicitly says when to use this tool versus alternatives: 'Unlike imap_flag_email (which only ever sets the system \Flagged flag)' and instructs agents to use the dedicated flag/read tools for backslash-prefixed system flags. It also adds a server-support caveat about PERMANENTFLAGS, so agents understand when the call may fail.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains the effect of flagging emails as spam, which adds useful context, but it does not mention duplicate behavior, whether existing emails are affected, or whether the addition is persistent.

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 immediately by the behavioral consequence, making it easy for an agent to parse quickly.

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 single-parameter, no-output-schema tool, the description covers the essential operation and effect. It is slightly light on edge-case behavior such as duplicates or relationship to whitelisting, but it is complete enough for a straightforward list-add mutation.

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

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

The schema covers the single parameter fully with a type and example, so baseline is 3. The description does not add additional parameter-level meaning beyond restating 'domain', but this is acceptable given the 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 clearly states the action: adding a domain to a custom spam list, and explains the practical consequence that emails from that domain will be flagged as spam. This distinguishes it from sibling tools like imap_remove_spam_domain and imap_add_whitelist_domain.

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 tool is used when a domain should be treated as spam, but it does not explicitly mention alternatives or conditions. No guidance is given about when to prefer this over imap_add_whitelist_domain or how it relates to imap_check_spam.

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?

There are no annotations, so the description carries the behavioral disclosure burden. It does disclose a meaningful behavioral consequence ('will never be flagged as spam'), but it does not mention whether the operation is idempotent, whether already-flagged emails are affected, or whether authentication/account context is required.

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 action is front-loaded, and the second sentence adds the key behavioral consequence without redundancy.

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

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

For a simple one-parameter tool with no output schema, the description provides enough context to understand what the tool does and why it would be used. A minor gap is that it does not explicitly situate itself against the spam-domain sibling tools, but this is not essential 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 input schema already fully documents the single parameter 'domain' with an example, so description-level parameter guidance is not necessary. The description adds no new format, validation, or normalization details beyond the schema. 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?

The description states a specific verb and resource: add a domain to the whitelist. It also clarifies the effect ('never be flagged as spam'), which distinguishes it from related tools like imap_add_spam_domain and imap_remove_spam_domain.

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 when to use the tool: when the agent wants to prevent emails from a domain being flagged as spam. However, it does not explicitly mention alternatives or when not to use it, even though sibling tools like imap_add_spam_domain present a clear contrast.

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 disclosing behavior. It usefully explains chunking, batch processing, and auto-reconnection to prevent timeouts. However, it does not mention that deletions are likely permanent or how IMAP delete/expunge behavior works, leaving important side effects undisclosed.

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 concise sentences, front-loaded with the core action and key behaviors. The second sentence justifies the batching mechanism in one clause; no filler or irrelevant detail is present.

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 schema plus description is sufficient to make a basic call, but the definition lacks guidance on destructive consequences and how this differs from imap_bulk_delete_by_search. For a bulk mutation tool with no annotations, that is a notable gap.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds only minor context about batching, which aligns with chunkSize, but does not add meaningful parameter semantics 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 operation: deleting multiple emails at once, with batching and auto-reconnection. It is clearly distinct from single-email deletion, though it does not explicitly contrast with imap_bulk_delete_by_search or imap_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?

There is no guidance about when to prefer this tool over imap_delete_email or imap_bulk_delete_by_search, nor any mention of when not to use it. The only implied usage is 'bulk deletes', which is not enough to route an agent confidently among sibling tools.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It explicitly states the destructive outcome (delete them all), the safety guard (no-criteria calls are refused), and the dryRun preview option. It could add more detail about irreversibility or batch behavior, but the core destructive and guarded nature is transparent.

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

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

The description is three concise sentences with no filler. The action and use case lead, followed by the mandatory-criteria safety rule and the dryRun hint. Every sentence contributes critical information for correct invocation.

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 destructive bulk nature and the absence of annotations or an output schema, the description covers the essential concerns: what it deletes, when it refuses to run, and how to preview before deleting. It does not describe return values or chunked-batch behavior, but an agent has enough information to invoke it safely and 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 100%, so the schema already documents each parameter. The description adds valuable cross-parameter semantics by grouping from, to, subject, before, and since as required criteria and noting that at least one must be supplied. It also highlights dryRun as a preview mechanism, going beyond the schema's per-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 clearly states the action: search for emails matching criteria and delete them all. It specifies the resource (emails) and the filtering behavior, and it distinguishes itself from sibling tools like imap_bulk_delete by requiring search criteria before any deletion.

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: use this for bulk cleanup of spam or unwanted emails. It also provides a strong exclusion rule—calls with no criteria are refused—so an agent knows not to invoke it without at least one of the listed fields. It does not explicitly name alternative tools for single deletions or domain-based cleanup, but the criteria-based use case is clear.

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 it performs well: it discloses the exact checks performed (bulk-mailer X-Mailer/User-Agent signatures, Precedence: bulk, DMARC/SPF/DKIM failures, List-Unsubscribe/Reply-To mismatches), the extra network cost for header checks ('Fetches message headers in one extra batch round-trip'), and the structure of what is returned. The only notable gap is that it never explicitly states that the operation is read-only and modifies nothing, though the verb 'check' and the existence of separate mutation siblings make this inferable.

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

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

The description is front-loaded with the core purpose in the first sentence, and every subsequent sentence earns its place: methodology, rationale for the header layer, and return composition. The middle methodology sentence is dense but each listed check carries decision-relevant signal for the agent. It is longer than the minimum, but none of it is filler, so the length is justified.

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 there is no output schema, the description's statement of return composition ('domain-based spam, a separate list of header-flagged mails, and domain statistics') is helpful but underspecified — the agent cannot know the exact result shape, field names, or types. Side-effect guarantees (that nothing is deleted or moved) are only implicit, and error/edge behavior for invalid accounts or folders is not addressed. For a 6-parameter analysis tool with zero annotations and no output schema, this is adequate but leaves real 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 of 3 applies. The description adds some meaning beyond the schema by explaining why the header-check layer exists and what it catches (scam mail from fresh, unlisted domains), which enriches includeHeaderChecks semantically. However, for from, since, limit, and folder, the description contributes nothing beyond what the schema already documents, so the added value is marginal.

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

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

The opening sentence 'Check emails in a folder for spam' states a specific verb, resource, and purpose, and the description elaborates with a concrete two-stage methodology (sender-domain checks plus deterministic raw-header analysis). It is clearly distinguishable from siblings like imap_delete_spam (which deletes rather than checks) and imap_domain_stats (which reports statistics rather than inspecting messages), and the return composition ('domain-based spam, a separate list of header-flagged mails, and domain statistics') further pins down its identity.

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 when to use the tool through its methodology explanation, notably that 'Header checks catch scam mail from fresh, unlisted domains that pass the domain check,' which justifies enabling the header layer. The includeHeaderChecks parameter description adds explicit when/when-not guidance ('Set false to skip header analysis'). However, no sibling is ever named and there is no explicit routing such as 'use imap_delete_spam to remove flagged mail' or 'use imap_search_emails for general search,' so usage guidance remains implied rather than explicit.

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 effects, yet it only says 'Connect to an IMAP account.' It does not say whether this establishes a persistent session, authenticates, requires the account to already exist, or what happens on repeated connection attempts. This is a significant transparency gap for a tool that likely changes connection state.

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

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

The description is very short and front-loaded, which is structurally fine. However, the single sentence essentially restates the tool name and provides no additional substance, making it under-specified rather than effectively concise.

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 no annotations and no output schema, so the description must carry most of the context. It omits prerequisites, account selection logic, connection lifecycle, return values, and failure behavior. An agent would struggle to invoke this tool correctly with only the provided text.

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 even if the description adds nothing. The description itself adds no extra meaning beyond the parameter names: both accountId and accountName are optional, and their relationship (mutual exclusivity, precedence, or requirements) is left unexplained.

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 verb ('connect') and a resource ('an IMAP account'), which conveys the basic action. However, it is vague about what connecting entails and does not differentiate this tool from related siblings like imap_test_account or imap_add_account. It reads more as a generic restatement of the tool name than a precise capability definition.

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 on when to use this tool versus alternatives, no mention of prerequisites such as an already-registered account, and no exclusions. The sibling list includes lifecycle tools like imap_add_account and imap_disconnect, but the description does not explain how imap_connect fits into that workflow.

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 disclosure burden and does meaningful work: it warns that parent folders may be auto-created and that success does not guarantee a new folder was made. It does not cover authentication, permission failures, or server-dependent path delimiter behavior, but the two disclosed traits are the most important call-time behaviors.

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 dense sentences with no filler: purpose, key behavior, and return semantics. The most decision-relevant 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 parameter-light create tool, the description covers the purpose, the main gotcha (parent auto-creation), and the tolerance for existing folders. It lacks a precise return shape and error conditions, but those are not essential for selecting and invoking the tool 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?

All three parameters already have schema descriptions, so the baseline is 3. The description adds value by giving folder path examples and explaining the auto-create behavior of the folder parameter, but it adds nothing for accountId or accountName 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 and resource: 'Create a new IMAP folder/mailbox.' It also clarifies distinctive behavior (auto-creating parents, idempotent success), which separates it from non-mutating siblings like imap_list_folders or imap_folder_status.

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 is evident: whenever an IMAP folder needs to be created. It gives useful context about auto-creation of parents and success even if the folder exists, but it does not explicitly state when not to use it or point to alternatives such as checking with imap_list_folders first.

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 of behavioral disclosure. It states the destructive action ('Delete all emails') but omits the critical fact that dryRun defaults to true, meaning the default behavior is only to report what would be deleted, not actually delete. It also doesn't address irreversibility or folder scope. This is a significant transparency 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?

Two sentences with zero waste. The action is front-loaded, and the second sentence adds a relevant use case. 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?

This is a destructive bulk operation with no annotations, no output schema, and a critical dryRun default that affects behavior. The minimal description leaves an agent without key operational context, such as the default dry-run behavior or when to prefer this tool over sibling deletion tools. It needs additional detail to be fully usable.

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 all four parameters, including domain and dryRun. The description adds no parameter-level meaning beyond what the schema provides, so the 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 uses a specific verb and resource: 'Delete all emails from a specific domain.' This clearly conveys scope and differentiates it from single-email deletion or spam-folder-specific tools. However, it does not explicitly name sibling alternatives, so it doesn't fully distinguish itself from imap_bulk_delete_by_search or imap_bulk_delete.

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

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

The phrase 'Useful for cleaning up unwanted newsletters or spam' gives an implied use case, suggesting when the tool is appropriate. But it provides no explicit guidance on when to use this tool versus related alternatives like imap_delete_spam, imap_bulk_delete, or imap_bulk_delete_by_search, and mentions no 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 provided, the description carries the full burden of behavioral disclosure. It explicitly warns that the operation is destructive, not easily undone, and server-dependent (moves to Trash or expunges). This is exactly the critical behavioral context an agent needs before invoking a delete operation.

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-loaded: the core action and destructive nature appear first, followed by a caution and explicit alternatives. Every sentence earns its place, with no redundant 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 tool's destructive nature, the description fully covers what the tool does, its irreversibility, server-dependent behavior, and clear alternatives. The schema fully documents all four parameters, and no crucial operational detail is missing for an agent to invoke it safely and 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?

The schema has 100% parameter description coverage, documenting uid, folder, accountId, and accountName sufficiently. The description adds that the operation uses 'folder + uid' to target one email, but does not need to restate parameter details already present in the schema. A baseline of 3 is appropriate since the schema does the heavy lifting.

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 identifies the action ('Delete ONE email'), the resource ('by folder + uid'), and the scope (single message), which distinguishes it immediately from the bulk-delete siblings. The verb and resource are specific and unambiguous, so an agent can select this tool without opening the schema.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: it names imap_bulk_delete and imap_bulk_delete_by_search for many-at-once deletions, and imap_move_email for filing instead of deleting. It also instructs the agent to confirm the user means this specific message, which is directly actionable.

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 behavioral disclosure burden. It reveals a destructive action ('delete') but does not disclose whether deletion is permanent or reversible, whether it consults a configured spam-domain list, or what side effects might occur. The dryRun safety parameter is only present in the schema, not reflected in the description.

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 with no filler or redundancy. The action and target are front-loaded, making it easy to scan, though this conciseness comes at the cost of behavioral 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?

For a destructive tool with five parameters, no annotations, and no output schema, the description is too sparse. It does not explain what qualifies as a 'known' spam domain, how to safely preview deletions, or what happens after processing, leaving an agent without enough context to invoke it safely.

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

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

Schema description coverage is 100%, so all five parameters are already documented with descriptions including dryRun, limit, minConfidence, folder, and accountId. The description adds no additional parameter meaning, so a baseline 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 action ('find and delete emails') and a clear resource scope ('from known spam/disposable email domains'). This distinguishes it from generic imap_delete_email and imap_bulk_delete, though it does not explicitly differentiate it from similar tools like imap_delete_by_domain.

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?

No guidance is provided on when to use this tool versus alternatives such as imap_delete_by_domain, imap_bulk_delete_by_search, or imap_check_spam. The description neither states exclusions nor offers context about prerequisites like configuring the spam domain list.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavior. It states only the action itself and does not clarify whether disconnecting preserves the stored account, whether it fails if no connection exists, or whether it is idempotent. This is a meaningful gap for a state-changing operation.

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, tightly scoped sentence with no filler or redundant phrasing. It is front-loaded with the verb and clearly names the target resource.

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 tool, the description is minimally adequate: it states the action and the required input. However, without annotations, output schema, or any note about the connection lifecycle, an agent has no information about expected outcomes or failure conditions, so the definition is not fully complete.

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 documents accountId with 100% coverage, and the description merely echoes the same meaning without adding format, source, or lifecycle details. The schema handles the heavy lifting, so the 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 uses a specific verb ('Disconnect') and a clear resource ('IMAP account'), which cleanly distinguishes it from sibling operations like imap_connect and imap_remove_account. An agent can tell exactly what action is being 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?

The description gives no guidance on when to use this tool versus alternatives such as imap_remove_account or imap_connect. There is no mention of prerequisites like requiring an active connection, nor any exclusion of cases where removal or reconnection would be more appropriate.

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 transparency burden. It implies a non-mutating aggregation operation via 'Get statistics', and adds the spam-detection intent, but it does not disclose the exact output shape, whether anything is modified, or how thresholds affect results.

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 state the function and the motivating use case with no filler. The primary action is front-loaded, followed by a pragmatic scenario.

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 adequate for selecting the tool, but because there is no output schema and no annotations, it leaves ambiguity about what statistics are returned (counts, percentages, top domains, etc.). The input parameters are well-covered, but the return contract is 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 100%, so the baseline is 3. The description does not add parameter-level meaning beyond the schema, but it does not need to since each parameter is already documented.

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 ('Get') and resource ('statistics about sender domains') with a folder scope, clearly distinguishing this aggregation tool from sibling search/retrieval tools. It is not a tautology and conveys the tool's analytic function.

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 identifies a concrete use case: 'identifying bulk senders or spam patterns.' It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select this over single-email or search tools.

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

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

With no annotations, the description carries the full burden and does well: it discloses type-dependent side effects (images returned inline, PDFs saved plus text extracted, other files written to the shared downloads directory or savePath). Gaps remain around failure conditions (missing attachment), size limits, and permissions, which an undocumented mutation-style tool would ideally state.

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

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

Three sentences, front-loaded with the action and addressing scheme, then the per-type behavior, then the usage cue. The middle sentence is dense but every clause carries information; no filler sentences.

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

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

No output schema or annotations exist, so the description must carry the behavior, and it does explain the differing return shapes by file type plus the disk-write side effect. It is nearly complete for this tool, with only error/permission behavior left unspecified.

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 maps some behavior to parameters (filename/contentId, savePath, extractText), but largely restates what the schema properties already document, adding no format or edge-case guidance beyond it.

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

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

States a specific verb+resource combination ('Download a single attachment from an email') with the addressing triple (folder + uid + attachment filename/contentId) and the reference tool for discovery (imap_get_email). An agent can distinguish this from imap_get_email, which returns the body, without opening the schema.

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

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

Gives an explicit when-to-use condition: 'Use when the user wants the actual file contents, not just the message body.' This routes the agent away from the body-reading sibling, though the alternative is not named as a fallback tool for the opposite case.

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

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

Since no annotations are provided, the description carries the full behavioral burden. It discloses that the operation searches across folders, handles moved/archived messages, explains why (UIDs are folder-relative), and describes the folder-search fallback order. While it does not mention possible return when nothing is found or potential search cost, it provides substantial behavioral context beyond a simple verb phrase.

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 useful information: what the tool returns, why it is reliable across moves, and what to do with the result. No filler or repetition.

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, the description adequately sketches the return shape ({ folder, uid } plus basic envelope) and the default behavior when folders is omitted. It could be more explicit about a not-found outcome or exact envelope contents, but the essential information an agent needs to select and call the tool correctly is present.

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 all three parameters. The description adds semantic value by explaining how the optional 'folders' parameter behaves (overrides default order) and that messageId accepts angle brackets or not, though the latter is already in the schema. This extra folder-behavior context pushes it above the baseline.

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 specific verb ('Locate') and resource ('an email by its RFC822 Message-ID'), along with the concrete return value ('current { folder, uid } plus basic envelope'). This distinguishes it from sibling tools like imap_search_emails or imap_find_thread_messages, which serve different lookup or search purposes.

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 practical usage context: it is robust to moved/archived emails and specifies the default folder search order. It also tells the agent what to do with the result, by directly pointing to imap_reply_to_email or imap_get_email. It does not explicitly contrast with alternatives, but the distinctive message-ID-based purpose is clear enough.

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 behavioral disclosure burden. It reveals the underlying search method (RFC 3501 HEADER search on In-Reply-To and References), the compatibility guarantee ('works on any IMAP server'), and the round-trip optimization when `includeBody` is true. This goes well beyond a simple purpose statement, though it omits details about return format and failure modes.

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, all dense with useful information: the core operation, a practical use case, the technical mechanism, and the key optionality with its performance rationale. No filler or redundant verbiage.

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

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

No output schema exists, so the description should clarify what the tool returns. It says 'found thread messages' and optionally 'parsed body', but does not describe the shape of the result set (e.g., array of headers, message objects, field names). The schema covers defaults and parameter richness well, but the output contract is a real gap for an agent. Thus not complete enough for a 4.

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% and the schema already explains all parameters, including `includeBody`'se N+1 benefit and `bodyFormat` behavior. The description mostly reinforces this same information rather than adding new parameter semantics. It does clarify the relationship between `sourceFolder` and `searchFolder`, but that is largely inferable from the schema too. 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?

The description states a precise operation: find messages in `searchFolder` that belong to the same conversation threads as messages in `sourceFolder`. This clearly distinguishes it from general search tools like `imap_search_emails` or single-message lookup tools like `imap_find_email_by_message_id`, and it names the mechanism (RFC 3501 HEADER search).

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 a concrete use case: 'catching replies that arrived after a thread was sorted.' It also provides guidance on when to set `includeBody=true` to avoid N+1 round-trips to `imap_get_email`. However, it does not explicitly exclude alternative tools or state when not to use it, so it falls just 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?

With no annotations, the description must carry behavioral disclosure. It clearly states this is a state-changing operation ('sets the IMAP \Flagged system flag') and explains what that means visually in common clients. It does not mention idempotency, reversibility, or response behavior, but the core side effect is 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?

Two concise sentences with no filler. The core action and system-flag detail are front-loaded, followed immediately by the exact user intents that should trigger 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 simple flag-setting operation with fully documented parameters, the description provides purpose, effect, and when-to-use guidance. It does not describe operation confirmation or error behavior, but that is not essential for an agent to select and invoke this correctly.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the input schema. The description adds no additional semantic detail about parameters, which is acceptable because the schema fully covers them.

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 ('Flag an email') and precisely defines the action as setting the IMAP \Flagged system flag. It explains the user-visible results (star in Gmail, flag in Apple Mail) and differentiates from related operations by focusing on the system flag rather than read status or keywords.

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 explicitly says 'Use this tool when a user asks to star, flag, or mark a message as important,' providing clear triggering intent. It does not explicitly contrast with sibling tools like imap_unflag_email or imap_add_keyword, so it stops short of a full exclusion list.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, but it only says 'get status information.' It does not state that the operation is read-only, what status fields (e.g., message count, unseen count, UIDNEXT) are returned, or whether a connection is required. No contradiction exists, but disclosure is minimal.

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 efficient sentence with no wasted words and the action is front-loaded: 'Get status information about a folder.' It is concise, though its brevity restricts how much guidance it can convey.

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

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

With no output schema and no annotations, the description fails to explain what the status result contains, how it differs from imap_get_unread_count, or how account selection behaves. An agent would have to guess at return semantics and sibling boundaries before invoking the tool.

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

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

Schema description coverage is 100%, so the schema already documents folder, accountId, and accountName. The description adds no parameter-level meaning beyond the schema, putting it at the baseline of 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 states a clear verb and resource: 'Get status information about a folder.' It is broadly distinguishable from siblings like imap_list_folders (listing folders) and imap_get_unread_count (counting unread messages), but it does not explicitly differentiate itself or define what 'status information' includes.

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?

No usage guidance is provided. The description does not indicate when to choose this tool over related siblings such as imap_get_unread_count or imap_list_folders, nor does it mention prerequisites like an active connection or account 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?

No annotations are provided, so the description carries the full burden, and it does disclose real behavior: the original message and headers are quoted, attachments are optional, and account defaultBcc addresses are always BCC'd. It stops short of stating whether the message is sent immediately or queued, and discloses nothing about permissions or rate limits for this mutation.

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, front-loaded with what the tool does and the source identifier, then usage routing, then a behavior caveat. No sentence is padding.

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

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

With 9 fully documented parameters and no output schema, the description covers the core mechanics an agent needs. The only meaningful omission is the result of the call (e.g., sent confirmation vs. queued/saved draft), which matters for a send-type mutation with no annotations.

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 including the to/bcc array-or-string forms and the accountId/accountName fallback is already documented. The description only restates the source identifier as 'folder + uid' and the optional-attachment and defaultBcc behavior, adding little 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?

States a specific verb (forward) and resource (existing email, identified by folder + uid) to new recipients. It also names the sibling it is not (imap_reply_to_email), so an agent can separate the two send-like tools without opening either 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?

Explicit when-to-use ('when the user wants to pass an existing message on to someone else') and an explicit alternative with its selecting condition ('use imap_reply_to_email instead to respond to the sender'). Nothing is left to inference.

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

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

With no annotations provided, the description carries the full behavioral burden and meets it: it discloses the default output behavior (clean Markdown in markdownContent), the intentional safety boundary (raw HTML is omitted 'so it never crosses the boundary'), the truncation guardrail (maxContentLength protects the context window), and what the tool deliberately does not do (attachment bytes). These are precisely the behavioral traits an agent needs to trust the tool's output.

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?

Five sentences, each earning its place: core purpose, default behavior and format variants, workflow prerequisite, truncation guidance, and sibling routing. The most decision-critical information (what it reads, default format) is front-loaded, and there is zero filler or repetition.

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 with no output schema and no annotations, the description covers a great deal: return fields, format semantics, truncation, workflow, and alternatives. The remaining gap is that IMAP UIDs are folder-scoped, and with folder defaulting to INBOX, an agent could fetch from the wrong folder after a search in another folder — a subtle correctness point the description leaves to schema inference.

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, warranting a baseline of 3. The description adds genuine value beyond the schema: it explains the rationale for maxContentLength ('protect the context window — raise it for long messages') and ties uid to the output of sibling tools. Some bodyFormat detail is restated from the schema rather than extended, which keeps this from a 5.

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

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

The description names a specific verb and resource — "Read the FULL content of a single email by its UID" — and enumerates the full scope of what is returned (body, sender/recipients, date, attachment list, optional raw headers, text-attachment previews). It naturally distinguishes itself from siblings like imap_search_emails and imap_download_attachment, and the contrast with imap_get_latest_emails ('Use after imap_get_latest_emails gives you a uid') clarifies that the sibling only produces UIDs, not content.

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

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

The prerequisite is explicit: 'Use after imap_search_emails or imap_get_latest_emails gives you a uid.' The exclusion is also explicit: 'To fetch attachment bytes, use imap_download_attachment.' This is textbook routing — the agent knows exactly when to invoke this tool and when to pick a sibling, with nothing left to inference.

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

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

There are no annotations, so the description carries the full burden. It discloses the read-style behavior, newest-first ordering, lightweight header output, body rendering options, body length cap, and the one-round-trip performance tradeoff. It doesn't mention auth or error behavior, but those are minor for this kind of fetch 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 four tight sentences: purpose, usage scenario, body/performance behavior, and alternative tool. Every sentence earns its place and there is no filler or restatement of the tool name.

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

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

With no output schema, the description supplies enough return-shape details: lightweight headers by default, optional parsed body, and body rendering cap. It also covers the main decision an agent must make (whether to include bodies and whether to search instead), making correct invocation straightforward.

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 schema already documents all 7 parameters in detail. The description adds useful context about includeBody/bodyFormat semantics and the N+1 cost avoidance, but it doesn't substantially expand per-parameter guidance beyond what the schema 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?

The description opens with a specific verb and resource: "Get the most recent emails from a folder, newest first." It clearly identifies the payload shape (lightweight headers: uid, from, subject, date) and differentiates itself from siblings by naming imap_search_emails and imap_get_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 explicit invocation scenarios: "what just came in?" / "show my latest inbox messages" when no search filter is needed. It directly routes to imap_search_emails for sender/subject/date filters and explains when includeBody=true is preferable to calling imap_get_email per message.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavior. It does explain the per-folder/total result, the default-all-folders behavior, and the performance benefit of passing a folder list. However, it does not explicitly state that the tool is non-mutating, that an active account/connection is required, or address any side-effect/authentication concerns.

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 compact sentences with no filler. The core purpose is front-loaded, the use case is quoted for clarity, and the default/scoping behavior is explained 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 simple count tool with no output schema and no annotations, the description covers the essential call semantics: what is counted, how results are grouped, the default scope, and how to limit the folder list. The only real gap is that the exact response format is not spelled out, but 'per folder, plus a total' gives enough shape for an agent to proceed.

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 all three parameters are already documented. The description adds a modest operational nuance—passing folders limits scope and speeds the call up—but it mostly restates what the schema already says ('default: all'). This is the baseline 3 for 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 is specific and action-oriented: 'Count unread (unseen) emails per folder, plus a total.' This clearly identifies the resource (unread emails), the operation (counting), and the output shape (per-folder plus a total), distinguishing it from siblings that retrieve, search, or modify emails.

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 an explicit use case: 'Use for "how many unread do I have?" overviews.' It also explains the default behavior (all folders) and how to narrow scope for speed. It does not name alternatives or state when not to use it, 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?

No annotations are provided, so the description carries the full behavioral disclosure burden. It conveys a non-mutating enumeration operation, but it does not explicitly state that there are no side effects, does not require a connection, or what the returned account representation looks like.

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

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

The description is a single short declarative sentence with no filler. The key scope ('all configured') is front-loaded, and 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 zero-parameter tool, purpose and invocation are clearly complete enough for selection and execution. Without an output schema, a brief note about the returned account identifiers or how results feed into account-scoped sibling tools would improve completeness, but the low complexity makes this a minor gap.

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

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

The input schema has zero properties and no required parameters, so there are no parameter details for the description to add. The baseline for a zero-parameter tool applies, and 'list all configured accounts' is sufficient.

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 the specific verb 'List' plus the clear resource 'configured IMAP accounts', making it obvious this is a read-only enumeration operation. It is distinctly different from siblings like imap_add_account, imap_remove_account, and imap_connect.

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 no explicit when-to-use or when-not-to-use guidance, nor does it name alternatives. The word 'configured' implies existing accounts rather than creation/connection, but an agent must infer when this is the right tool versus account-scoped operations.

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 reveals what the response contains and explains how to interpret the specialUse field, including the localized-name example ('Gesendet' is Sent when specialUse is '\Sent'). It does not explicitly claim read-only safety, but the read-only nature is strongly implied by 'List'.

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 earning its place: the first states the purpose and payload, the second gives the temporal use-case, and the third adds the specialUse mapping that prevents misinterpretation of localized folder names. The most critical 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 zero-required-parameter list tool with no output schema, the description covers the important return fields, the discovery use case, and the provider-variation rationale. It leaves minor ambiguity about whether all hierarchy levels are returned in a flat list or nested, but the hierarchy-delimiter mention partly addresses this.

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 provides 100% coverage of both optional parameters (accountId, accountName) with clear descriptions. The tool description adds no additional parameter-level meaning beyond the schema, so it stays at the baseline.

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 action ('List all folders/mailboxes') and the exact resource scope ('for an account'), then enumerates the returned data (names, hierarchy delimiter, attributes, special-use role). The emphasis on using it before search/move/create operations distinguishes it from sibling tools that operate on specific folders.

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

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

Explicitly frames the tool as a discovery step: 'Use this first to discover exact folder names before searching, moving, or creating subfolders.' It also explains why (folder naming varies by provider) but does not state when not to use it or name alternative tools like imap_folder_status.

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

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

With no annotations, the description carries the burden, and it clearly indicates a read-only enumeration ('List all known spam domains'). It also adds scope ('built-in and custom') beyond what a bare name would imply. It doesn't mention output format or auth, but for a zero-parameter list operation 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?

A single, front-loaded sentence with zero filler. 'List all known spam domains' immediately conveys action and object, and the parenthetical clarifies domain membership.

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

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

For a simple, parameterless read tool without an output schema, this is nearly complete. It would be fully complete with one explicit statement of return format (e.g., array of domain strings), but the behavior and scope are clear.

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 no parameters and schema coverage is 100%, so parameter documentation is not needed. The 0-parameter baseline is 4; the description doesn't need to compensate.

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 uses specific verb 'List' and clearly identifies resource as all known spam domains, including built-in and custom. This distinguishes it from sibling tools that manage, delete, or check spam, even without naming them.

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

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

The description implies use when the agent needs to enumerate known spam domains, but it offers no explicit when-to-use guidance or exclusions against similar siblings like imap_domain_stats or imap_check_spam. Context 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?

With no annotations, the description carries the burden of behavioral disclosure. It does reveal a notable behavioral trait: batching multiple UIDs into a single IMAP STORE round-trip. However, it does not mention side effects, reversibility, error behavior, or what happens on a successful call, which are meaningful gaps for a 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?

The description is a single sentence, front-loaded with the core action and followed by a relevant batching tip. Every word earns its place; there is no filler or redundant preamble.

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

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

For a low-complexity mutation tool with all parameters documented in the schema and no output schema, the description provides enough for an agent to invoke it correctly. It omits return/error details, but those are not forced by an output schema or complex side effects.

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's array/round-trip guidance is already present in the uid parameter's schema description, so the free text adds little new 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: 'Mark one or many emails as read.' This makes the core operation clear. However, it does not explicitly differentiate itself from the sibling imap_mark_as_unread or imap_flag_email beyond the verb phrase, so sibling differentiation is inferred rather than stated.

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 batch guidance: 'pass an array to flag N messages in one IMAP STORE round-trip (useful when triaging).' This tells an agent when the array form is valuable. It does not explicitly state when not to use this tool or name alternatives, so no exclusion or alternative routing 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?

With no annotations, the description carries the burden of explaining behavior. It does disclose the single IMAP STORE round-trip behavior for arrays, which is useful. It does not mention connection requirements, error outcomes, or reversibility, but the core effect of marking emails unread 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 purpose is front-loaded, and the batching/IMAP STORE detail is directly useful for choosing how to pass UIDs. 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 simple mutation tool with a fully documented schema, the description is largely sufficient. It lacks any statement about the return value or prerequisites like an existing connection, and there is no output schema to fill that gap, so it is adequate but not fully complete.

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 provides full descriptions for all four parameters, including UID array semantics, atomicity, folder, and account resolution. The description repeats the single-vs-array distinction but adds little beyond what the schema already communicates, 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?

The description specifies a clear verb and resource: 'mark one or many emails as unread'. It also explains that it accepts a single UID or an array, and the operation is clearly distinct from siblings like imap_mark_as_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?

It provides useful batching guidance ('pass an array to flag N messages in one IMAP STORE round-trip'), so the agent knows when to use the array form. However, it does not explicitly compare this tool to imap_mark_as_read, imap_flag_email, or other alternatives, leaving tool selection mostly 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?

With no annotations, the description carries the behavioral burden; it does disclose the side effect that the destination folder may be created if missing. However, it does not mention permissions, partial failures for array UIDs, or what happens when the destination is absent and createDestinationIfMissing is false.

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; the core operation is front-loaded and the optional behavior is stated immediately after. 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 six-parameter mutation tool with no annotations and no output schema, the description is minimal: it omits return values, error behavior when the destination is missing, and array/bulk semantics (though the schema documents uid arrays). The schema fills most parameter gaps, but operation-level and result-level context 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 the baseline is 3; the tool description itself repeats none of the parameter details but also does not need to. The examples and 'optionally creates' hint at targetFolder and createDestinationIfMissing but add no meaning 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 and resource ('Move an email') and clarifies scope by naming source/destination folders with concrete examples (INBOX to Taxes/Archive). It also surfaces the tool's unique optional destination-folder creation, which distinguishes it from sibling folder-management and deletion 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 examples imply an organizational/triage use case (moving to Taxes/Archive) but the description never explicitly says when to prefer this tool over alternatives such as imap_delete_email or imap_create_folder, and it gives no when-not-to-use 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?

With no annotations, the description carries the full burden of behavioral disclosure. It reveals the action ('Remove') but does not state whether removal is permanent, whether it deletes stored credentials, or what happens to existing connections or dependent operations.

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

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

The description is a single, front-loaded sentence with no wasted words. It is concise and easy to scan, though it sacrifices context that could have been included without bloating the text.

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

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

Given the low complexity (one required parameter) and the explicit name/action, the description is minimally viable. However, because this is a destructive operation with no annotations and no output schema, an agent would benefit from a note about permanence or side effects, which is absent.

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

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

Schema description coverage is 100%: the input schema already explains accountId as 'ID of the account to remove'. The tool description adds no parameter semantics beyond the schema, 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 ('Remove') and a clear resource ('IMAP account configuration'), making the operation unambiguous. Despite the description mirroring the tool name, it clearly identifies the destructive removal action and is distinct from sibling tools like imap_add_account or imap_update_account.

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 no guidance on when to use this tool versus alternatives such as imap_disconnect, imap_test_account, or imap_update_account. There is no mention of prerequisites, consequences, or conditions that would select this removal operation over others.

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 disclosure burden. It covers verbatim pass-through of the keyword, rejection of backslash-prefixed system flags, and the authenticity of failure rather than false success when the server disallows custom keywords. This is exactly the behavioral context an agent needs to predict outcomes.

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 packed with necessary information, with no filler. The action is up front and the distinguishing/trade-off information follows naturally. The length is justified by the complexity of custom-keyword behavior.

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 definition covers purpose, alternatives, input nuances, server-dependent behavior, and failure semantics, all in one passage. Even without an output schema, an agent knows what to expect: success or a failure rather than silent no-op. Complete for a tool of 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 coverage is 100%, so baseline is 3. The description adds value beyond the schema for the 'keyword' parameter by showing valid formats and clarifying that it is passed verbatim. It doesn't need to re-expl relatin uid/folder/account becaus they are already well described in the schema.

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

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

The description opens with a specific verb and resource: 'Remove an arbitrary custom (non-system) IMAP keyword/label from an email.' It then provides concrete examples ($cl_1, $MailFlagBit0, $promotion) and immediately differentiates itself from imap_unflag_email, which clears only the system \Flagged flag. No ambiguity remains about what this tool does.

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 explicitly contrasts with imap_unflag_email ('only ever clears the system \Flagged flag') and tells the agent to use dedicated flag/read tools for system flags like \Flagged, \Seen, \Deleted. It also warns that custom keywords depend on server PERMANTFLAGS and that the call fails if the server rejects the change. This gives clear when-to-use and when-not-to-use 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?

No annotations are provided, so the description carries full responsibility for disclosing side effects. It says the domain is removed, but does not mention whether the change is persistent, whether removing a non-existent domain errors, whether authentication/special permissions are needed, or whether this only affects local spam filtering. The description adds little beyond what the tool name already conveys.

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, front-loaded sentence. Every word contributes to the tool's purpose, with no filler or redundant 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?

The operation is very simple and the only parameter is fully documented in the schema. However, because there are no annotations and no notes on side effects or fallback behavior, the description is minimally acceptable rather than fully contextual for an agent deciding whether and how to invoke 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%, and the schema already explains that 'domain' is the domain to remove from the spam list. The tool description does not add new parameter-level meaning, so the baseline 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 uses a specific verb ('Remove') and identifies the exact resource ('custom spam list'), so an agent can immediately understand the tool's function. It also clearly differentiates from siblings like imap_add_spam_domains and imap_list_spam_domains without needing to inspect the schema.

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

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

The description implies when to use the tool: when a domain needs to be removed from the custom spam list. However, it does not explicitly state when not to use it or mention alternatives such as imap_delete_by_domain or the whitelist counterpart. The usage context is reasonably inferable but not 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?

With no annotations, the description carries the behavioral burden and does well: it discloses automatic recipient selection, subject prefixing, threading headers, replyAll expansion, and default BCC injection. It does not state permission/auth requirements or immediate-send side effects, but the key reply behavior is clearly described.

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-loaded: purpose first, then automatic behavior, then replyAll, then sibling routing, then BCC behavior. Every sentence adds distinct information without duplication.

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

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

For a 10-parameter mutation tool with no annotations and no output schema, the description covers the critical reply mechanics and alternatives well. It omits return/confirmation details and broader error handling, but remains sufficient 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining that folder + uid identify the original message, how replyAll affects recipients, and that defaultBcc is always merged. It does not cover every parameter (e.g., attachment semantics), but the added reply-specific context is valuable.

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: reply to an existing email, identified by folder + uid. It also explicitly distinguishes this from imap_send_email, so the agent can select the right sibling without opening either schema.

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

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

It gives an explicit when-to-use rule: use this instead of imap_send_email whenever the user is responding to a message already in a mailbox. It also clarifies the replyAll condition and defaultBcc behavior, leaving little ambiguity about 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the two traits an agent most needs: the message is NOT sent and the BCC list is merged with the account defaultBcc. It says nothing about what a save returns (draft id/message-id), whether an existing draft is overwritten, or error conditions, which leaves real gaps for a write operation.

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, zero filler, with the defining constraint '(no send)' front-loaded immediately after the purpose. Every clause earns its place.

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

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

For a 14-parameter write tool with no annotations and no output schema, the description covers purpose and the highest-risk behavior (no send) but is thin on everything else. Relying on 'same fields as imap_send_email' for parameter meaning and omitting any hint of the save result or overwrite semantics leaves it only minimally adequate given the schema is fully self-documenting.

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% and the param descriptions are unusually rich (attachment cid/disposition rules, accountId vs accountName fallback). The description's only added meaning is the cross-reference to imap_send_email's field set and the defaultBcc merge, so baseline 3 is correct.

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 (save an email as a draft) and pins down the destination (Drafts folder). The parenthetical '(no send)' plus the reference to imap_send_email makes it unmistakable versus the sibling that actually sends, without opening either 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 '(no send)' qualifier and the pointer to imap_send_email's field set give clear context for when this tool is the right choice. It stops short of an explicit when-not/alternative sentence (e.g. 'use imap_send_email to actually deliver'), so it is strong but not fully directive.

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 present, the description carries the full burden, and it delivers: it warns about the flagged/custom-keyword pitfall, explains that Trash/Spam/Drafts are skipped unless opted in, clarifies that lightweight headers are returned by default, and documents body rendering behavior. This goes well beyond a simple 'search emails' statement.

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 long but dense with valuable information, and it is structured around key behaviors, defaults, and alternatives. However, it opens with a caveat about flagged searches before stating the tool's core purpose, which slightly delays the main 'what does this do' message. Each sentence earns its place, but the front-loading could be tighter.

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 22 optional parameters and no output schema, the description provides a thorough operational picture: default folder, return fields, body inclusion trade-offs, folder exclusions, opt-in flags, and a critical edge case. It covers the essential behaviors an agent needs to invoke the tool correctly and interpret its results.

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, but the description adds substantial meaning beyond the schema: it explains the searchAllFolders behavior, the N+1 rationale for includeBody, how keywords relate to imap_folder_status customKeywords, and the flagged-filter caveat. This is genuinely actionable guidance, not a restatement of parameter 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 verb and resource: 'Search for emails matching criteria' and lists concrete filters like sender, recipient, subject, body, date range, and read/flagged status. It also ties the tool to a specific use case — finding messages when you know something about them but not their UID — and distinguishes it from imap_get_latest_emails.

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 explicitly says when to use this tool ('Use this to FIND messages when you know something about them but not their UID') and when to prefer a sibling ('For the newest messages without criteria, prefer imap_get_latest_emails'). It also gives practical guidance on searchAllFolders for messages filed away by rules and on includeBody to avoid the N+1 cost of calling imap_get_email per match.

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?

There are no annotations, so the description carries the full burden; it discloses the non-obvious side effects, namely that a copy is written to Sent unless disabled and the account defaultBcc is always injected. It doesn't discuss permissions, error behavior, or irreversibility of an SMTP send, which limits it to a 4.

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?

Four sentences, front-loaded with the core action, then side effects, then sibling routing, then payload capabilities; no filler or restatement of the name.

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

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

For a 12-parameter mutation tool with no annotations and no output schema, the description covers the essential behavior, side effects, and alternatives. Remaining gaps, such as dryRun validation semantics and account selection, are documented in the schema rather than 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 the schema does the heavy lifting and baseline would be 3. The description adds value by summarising the addressing/content/attachment modes and by routing large attachments to imap_upload_file, a hint not present in the schema. It doesn't explain replyTo, dryRun, or account selection, so it stays below 5.

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

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

The description gives a specific verb and resource ("compose and send a NEW email via the account's SMTP server") and explicitly separates this tool from the reply, forward, and draft siblings, so an agent can select it without opening another schema.

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

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

It states the selection condition ("fresh outbound messages") and names three alternatives (imap_reply_to_email, imap_forward_email, imap_save_draft), each with the reason to prefer it (threading, passing on, storing without sending).

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 explains that the operation is a connection test, does not require re-entering credentials, and produces folder and message counts. It does not detail failure modes or whether a network connection is established, but it gives a clear behavioral picture.

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 concise sentences lead with the purpose and then the output. Every sentence contributes necessary information, with no filler or redundant restatement.

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

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

For a simple one-parameter tool with no annotations and no output schema, the description adequately covers purpose, usage context, and return values (folder count and message count). It could mention expected behavior on failure, but this is a minor gap given the tool's simplicity.

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% and the sole parameter is described as 'Account ID to test'. The description adds the nuance 'existing account connection', which slightly reinforces that the ID must refer to an existing account, but it does not materially expand 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?

Description clearly states a specific verb ('Test') and resource ('existing account connection'), and specifies what the test validates (IMAP connectivity) and what it returns (folder count and message count). This distinguishes it from sibling account-management tools like imap_list_accounts or imap_connect.

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 'existing account connection' and 'without re-entering credentials' clearly conveys when this tool is appropriate: for testing already-configured accounts. It does not explicitly name alternatives or state exclusions, but the usage context is clear.

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 behavioral burden and does so thoroughly. It names the exact flag removed, discloses the limitation on Open-Xchange/Network Solutions and Apple Mail, explains the observable consequence (the message may still display as flagged), and prescribes a remediation 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?

The description is three sentences and every one earns its place: the main action is front-loaded, the cross-client caveat follows immediately, and the remediation is given last. The length is proportionate to the complexity of the issue it documents.

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 simple one-required-parameter schema and the absence of an output schema or annotations, the description is complete: it defines the action, explains the edge case, and names the exact sibling tools for verification and cleanup. Nothing critical is missing for an agent 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?

All four parameters are already described in the schema (100% coverage), so the baseline is 3. The description adds no parameter-specific meaning beyond the schema, such as uid/folder/account disambiguation, so there is no basis to raise the score.

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 ('Unflag an email') and precisely defines the operation as removing the IMAP \Flagged system flag, with user-facing examples like the Gmail star and Apple Mail flag. It clearly differentiates \Flagged from custom keywords, which distinguishes this tool from related keyword operations.

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

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

It explicitly warns when this tool alone may be insufficient ('some servers... Removing \Flagged alone does not clear that keyword') and gives concrete follow-up routing: check customKeywords via imap_get_email and remove the lingering label with imap_remove_keyword. This gives the agent clear conditions for using alternatives.

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

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

No annotations are provided, so the description carries the full disclosure burden. "Without removing and re-adding it" usefully signals an in-place mutation that preserves unspecified settings and existing credentials, but the description never states permission/auth requirements, whether changes take effect on live connections, or what happens when a field is omitted (partial vs full replace).

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. The core purpose and the field list come first, and the conditional guidance about connection fields is placed second where it belongs.

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 17-parameter mutation tool with no annotations and no output schema, the description plus 100%-coverage schema covers the fields an agent must supply. It is slightly thin on mutation behavior (partial-update semantics, side effects on the active connection), but the schema and the in-place-update framing carry most of the load.

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% across all 17 parameters, so the schema already documents each field, including the viettel.vn hostname constraint and empty-string-to-clear semantics. The description's connection-field note largely restates what the schema says for host and smtpHost, adding little beyond the baseline.

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 ("Update an existing VMail account") and enumerates the mutable fields, so the agent knows exactly what the tool operates on. The phrase "without removing and re-adding it" implicitly distinguishes it from the imap_remove_account / imap_add_account pair in the sibling list.

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 second sentence gives real when-to-use guidance for the connection fields: host/port/TLS/SMTP are only needed if Viettel changes the VMail server, because new accounts get them automatically. It lacks an explicit statement of the inverse case (when to prefer remove+re-add, or how this compares to imap_test_account), so it is clear context without full 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 provided, the description takes on the full burden. It discloses maximum upload size (configurable), auto-deletion after a TTL (configurable), and that the upload returns a path. This covers key behavioral aspects for a temporary upload 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 at three sentences, each providing valuable information: purpose, integration detail, and behavioral constraints. No redundant or extraneous wording.

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?

Despite no output schema, the description adequately explains the return value (a path for attachments) and important limits. For a tool with 3 simple parameters, this is complete and meets all needs for selection and 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 input schema already describes all three parameters (content, filename, contentType) with 100% coverage. The description adds no extra semantics beyond stating the tool's overall purpose, so a baseline 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 clearly states the tool's purpose: uploading a file to the server for use as an email attachment. It distinguishes it from siblings like imap_download_attachment and imap_send_email by specifying the output is a path for attachments.

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 that the tool is useful for sending large attachments to avoid context window limits and that the returned path integrates with imap_send_email. It does not explicitly state when not to use or list alternatives, but the context is clear.

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