Mail Agent MCP

by SinoEdwards

Overview Schema Related Servers Score Discussions

TypeScript

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.1
Disambiguation4/5
Most tools target a distinct resource and action, with descriptions that cross-reference lookalikes (search vs latest, flag vs keyword, single vs bulk delete). A few clusters such as delete_spam/delete_by_domain/bulk_delete_by_searcch and the preview_send/reply/forward variants could still cause misselection.
Naming Consistency3/5
The imap_ prefix and generally verb_noun structure help, but conventions are mixed: delete vs remove (delete_email vs remove_keyword), get/find/search for lookup tools, folder_status and doman_stats are noun phrases, and connect/disconnect lack an explicit object.
Tool Count2/5
41 tools is well above the 25+ threshold for a heavy toolset. The broad email domain justifies some sprawl, but the many delete, spam, folder, and flag variants make the surface feel overly large and harder for an agent to navigate efficiently.
Completeness3/5
Core mail workflows such as search, read, send via preview/confim, delete, move, and flagging are well covered. However, whitelist management has no remove counterpart, folders cannot be renamed or deleted, and there is no copy-email tool, leaving some obvious dead ends.
Average 3.9/5 across 41 of 41 tools scored. Lowest: 2.3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- No commit activity data available
- Last stable release on August 31, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior1/5
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.
Conciseness3/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose3/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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 only says 'Add a new IMAP account configuration' and reveals nothing about side effects: whether account creation attempts server connectivity, what happens on duplicate names, whether existing credentials are overwritten, or what the operation returns. For a mutating tool storing credentials, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence with zero wasted words. It's appropriately sized given the schema carries the parameter detail. It loses one point because it could have used the spare space to at least name the sibling for updates or note the connectivity-testing behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a 12-parameter mutating tool with no annotations and no output schema, yet the description supplies only five words of context. The account-creation workflow, duplicate-name handling, return payload, and whether the server is contacted during creation are all left unspecified. The schema documents parameters, but the operational context an agent needs to correctly invoke and verify this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with every one of the 12 parameters documented including defaults (tls=true, port=993, smtpPort=587) and the smtpHost rewrite rule. The description adds nothing beyond the schema, but since the schema does the heavy lifting, the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Add') and resource ('a new IMAP account configuration'), and the word 'new' implicitly distinguishes it from updating existing accounts. However, it doesn't name the sibling imap_update_account as the alternative for existing accounts, so differentiation relies on inference rather than explicit contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no when-to-use guidance whatsoever. It doesn't state that this tool creates new accounts while imap_update_account modifies existing ones, nor does it mention any prerequisites (e.g., needing imap_connect or imap_test_account first). An agent must infer usage purely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing behavior. It only says 'update' and offers the SMTP-fix use case; it does not explain partial-update semantics, credential requirements, whether unmentioned fields are preserved, or any side effects of updating an account.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The core action is front-loaded, and the second sentence adds a concrete motivating 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema richly documents parameters such as smtpSecure behavior and sentFolder override semantics, so parameter context is strong. However, for a complex mutation tool with 16 parameters and no annotations or output schema, the description is thin on update behavior, idempotency, and what happens to fields not supplied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all 16 parameters in detail. The description adds no parameter-level meaning beyond pointing at SMTP settings, which is a subset of what the schema covers. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb-resource pair, 'Update an existing IMAP account,' which precisely identifies the action and target. Describing it as useful for fixing SMTP settings helps distinguish it from imap_add_account and imap_remove_account without any ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames this as the tool for changing settings on an existing account, especially SMTP configuration, and contrasts it with removing and re-adding the account. It does not explicitly name sibling tools or state when not to use it, so it falls just short of full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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 does disclose one key behavioral trait, that the email is not sent, and notes that account defaultBcc is applied when configured. However, it does not explain connection/account prerequisites, whether repeated calls create duplicate drafts, what happens with the folder override, or what a successful call returns. The description is not misleading, but it leaves several operational behaviors to the agent's inference.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences and front-loads the primary action and no-send distinction. There is no filler. The second sentence is compact, but it references imap_send_email, which is not present in the sibling list, slightly reducing its standalone clarity. Overall it is efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a 14-parameter tool with no annotations and no output schema, the description is adequately scoped for selecting the tool but thin on invocation details. The schema covers parameter meanings, and the description covers the core purpose, but return values, connection/account prerequisites, and draft-folder fallback behavior are not addressed. This is a minimum-viable definition with clear gaps around operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all 14 parameters in detail, so the baseline is 3. The description only adds a cross-reference to imap_send_email and account defaultBcc behavior, but the defaultBcc behavior is already stated in the bcc parameter description. The description adds little semantic value beyond what the schema provides, though it does not conflict with it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Save an email as a draft in the Drafts folder'. It also explicitly says '(no send)', which distinguishes it from send-related siblings like imap_confirm_send or imap_preview_send_email. An agent can immediately tell what this tool does and what it does not do.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: use this tool when you want to persist an email as a draft without sending it. The '(no send)' contrast with send tools is a clear contextual signal, though it does not explicitly name alternative tools or exclusion conditions. It is slightly less explicit than the best examples but still unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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 the most critical behaviors: the tool does not send, it freezes a draft, and it returns a draftId requiring confirmation. However, the 'freeze' semantics are left vague — there is no disclosure of whether the frozen draft persists server-side, whether it can expire, whether repeated calls create orphaned drafts, or whether the operation is reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences totaling roughly 20 words, with the core purpose front-loaded in the first sentence and the follow-up action in the second. There is zero filler and every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter tool with no annotations and no output schema, the description covers the purpose and the required next step but leaves gaps: the response shape beyond 'draftId', what happens to the frozen draft if never confirmed, and any caveats about confirmation being idempotent or time-limited. It is minimally viable but not fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 schema already documents all 11 parameters. The description adds no parameter-level meaning beyond the schema (e.g., the BCC-defaults-merge behavior or the accountId/accountName interplay are only in the schema).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-plus-resource construction ('Preview and freeze a new email without sending it') and immediately clarifies the non-sending scope, distinguishing it from any direct-send tool. It also names the companion tool (imap_confirm_send) and the 'new email' wording separates it from the reply/forward preview siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this is the preview stage of a two-step send flow, and it explicitly instructs the agent to confirm the returned draftId with imap_confirm_send. 'Without sending it' and 'new email' provide partial exclusion guidance against send and reply/forward tools, though it does not explicitly enumerate when NOT to use it versus imap_save_draft.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses a meaningful behavioral guarantee ('exactly once') and a precondition ('previously frozen'), which is more than a bare send description. It does not describe failure behavior or maintenance state, but the core side effect and idempotency are clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with no filler. The key action, object, and guarantee are all 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with full schema documentation and no output schema, the description is mostly sufficient. Missing usage alternatives and explicit failure behavior are minor gaps given the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already fully documented. The description adds no new parameter-level meaning beyond the schema; 'previously frozen' loosely clarifies draftId, but the schema already attributes draftId to a safe-send preview tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Send'), a specific resource ('previously frozen safe-send draft'), and a key constraint ('exactly once'). This clearly distinguishes the tool from sibling draft/preview tools 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'previously frozen safe-send draft' implies the tool should be used after a safe-send preview step, but it does not explicitly name when to use this tool versus alternatives or state when not to use it. The guidance is present only by implication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of explaining behavior. It does disclose that the tool does not send the email and that it returns a draftId. However, 'freeze' is not fully elaborated — the description does not say whether a server-side draft is created, whether attachments are actually stored, or what the side effects of freezing are beyond the returned draftId.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core purpose and followed immediately by the required next step. Every word earns its place and there is no redundant restating of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a preview workflow, the description covers what the agent needs to know: it creates a frozen forward, does not send it, and returns a draftId to use with imap_confirm_send. The rich parameter schema fills in the remaining details, and the absence of an output schema is partly compensated by the explicit draftId mention. It could be more explicit about the 'freeze' semantics, but it is sufficiently complete for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the parameters are already individually documented. The tool description adds no additional parameter-level meaning beyond referencing the returned draftId. Baseline 3 is appropriate because the schema is doing the heavy lifting and the description does not conflict with it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific action: 'Preview and freeze a forward without sending it,' with a clear verb and object. The phrase 'without sending it' and the callout to 'Confirm the returned draftId with imap_confirm_send' further disambiguate this from send-and-forget operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this to prepare and freeze a forward before actually sending, and then follow up with imap_confirm_send. It does not explicitly contrast with the sibling preview tools for send or reply, but the 'forward' scope and the confirm flow provide enough directional guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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 explains that images are returned inline, while PDFs and other files are saved only inside the configured download directory, and that savePath outside the directory is rejected. This is meaningful behavioral context beyond the raw schema, though it does not cover every edge case such as failure modes or MIME-type handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no filler. The primary behavior and identifier requirements appear first, followed by relevant file-handling details and a concise usage cue. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with seven parameters, no output schema, and no annotations, the description covers the essential context: what is downloaded, how it is identified, what happens to different file types, and when to use it. It could be slightly more explicit about return values for PDFs given the extractText parameter, but it is largely complete 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.
Parameters3/5
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 seven parameters. The description adds minimal new meaning beyond referencing folder + uid + attachment filename/contentId as the lookup key and implying the save destination behavior. This is adequate but does not substantially expand on the schema's parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific action (Download), a specific resource (a single attachment from an email), and the identifying fields (folder + uid + attachment filename/contentId). It also references imap_get_email as the source of those identifiers and explicitly distinguishes itself from retrieving just the message body, which separates it clearly from sibling tools like 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a direct condition: 'Use when the user wants the actual file contents, not just the message body.' This tells an agent when to select this tool, though it does not name alternative tools explicitly or state when not to use it beyond the message-body contrast. It still provides clear practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It explicitly discloses that the tool does not send and that a draftId is returned for a follow-up confirmation step. It does not fully define what 'freeze' entails, such as editability or draft persistence, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no filler. The core behavior is stated first, and the actionable follow-up step is included concisely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description covers the essential workflow: preview/freeze, no send, and confirmation via the returned draftId. It leaves some ambiguity around 'freeze' and the exact response shape, but an agent has enough context to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and every parameter already has meaningful descriptions. The tool description itself adds no param-specific guidance, so the baseline of 3 is appropriate; the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb and resource: 'Preview and freeze a threaded reply without sending it.' It clearly differentiates the tool from send/forward preview siblings by emphasizing threading and the no-send behavior, and it names the companion tool imap_confirm_send.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context: use this for a threaded reply, do not send, then confirm with imap_confirm_send. It does not explicitly exclude alternatives like imap_preview_send_email or imap_preview_forward_email, but the 'threaded reply' and confirmation flow make the intended usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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 does so well. It discloses both the max upload size (26214400 bytes) and the auto-deletion behavior (after 86400000 ms), including configurable environment variables. It also states the side effect of returning a path for later use, making the tool's behavior and lifecycle transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the main action and purpose appear in the first sentence, workflow in the second, and limits/lifecycle in the third. Every sentence conveys a needed fact without fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, this description is complete enough for an agent to call it correctly and integrate it into the email-sending workflow. It explains purpose, when to use it, the next step, size constraints, and auto-cleanup behavior; nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters: filename, base64-encoded content, and MIME type, so schema coverage is 100%. The description adds no parameter-specific detail beyond the general purpose, so the baseline score of 3 is appropriate: the schema handles parameter semantics, and the description adds minimal unique param guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Upload a file to the attachment root' and the resource/use case: 'return a path for imap_preview_send_email attachments.' It explains what the tool does and why it exists, distinguishing it from siblings by positioning it as an attachment-staging step rather than a send or preview operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit workflow: upload, preview, then 'use imap_confirm_send only after explicit user confirmation.' It also provides the rationale for using this path ('avoids putting large attachment bytes in the context window'), which clearly signals when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![mail-agent-mcp MCP server](https://glama.ai/mcp/servers/SinoEdwards/mail-agent-mcp/badges/card.svg)](https://glama.ai/mcp/servers/SinoEdwards/mail-agent-mcp)

Score Badge

Copy to your README.md:

[![mail-agent-mcp MCP server](https://glama.ai/mcp/servers/SinoEdwards/mail-agent-mcp/badges/score.svg)](https://glama.ai/mcp/servers/SinoEdwards/mail-agent-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/SinoEdwards/mail-agent-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server