apple-mail-mcp

Server Quality Checklist

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

Latest release: v0.10.2
Disambiguation4/5
Tools are mostly distinct but get_messages and search_messages both retrieve messages (by ID vs criteria) which could cause confusion. Otherwise, each tool targets a clear operation.
Naming Consistency5/5
All tools use consistent verb_noun snake_case naming (e.g., create_draft, delete_mailbox, update_rule). Verbs like create, delete, update, list, get, save, render are used uniformly.
Tool Count4/5
25 tools is on the higher side but justified by the comprehensive coverage of drafts, mailboxes, rules, messages, templates, accounts, and statistics. Each tool has a clear purpose.
Completeness5/5
CRUD operations are covered for drafts, mailboxes, rules, templates, and messages. Additional tools for attachments, threading, statistics, and template rendering provide a complete workflow for email management.
Average 4.3/5 across 25 of 25 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- 26 of 32 community issues answered or closed in the last 6 months
- 27 commits in the last 12 weeks
- Last stable release on June 13, 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

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey that the tool is read-only, idempotent, and non-destructive. The description adds no further behavioral context (e.g., performance, error handling, or dependencies). It meets the baseline but does not enhance transparency beyond annotations.
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 very short (6 words) and to the point. It is well-suited for a simple tool, but could be slightly more informative without losing conciseness, such as mentioning 'returns a list of mailbox objects.'
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 tool's simplicity (one required parameter, output schema present), the description is largely sufficient. However, it does not mention that the account parameter is required or that the result is a list, which could be inferred but is not explicit.
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 tool description does not add any meaning beyond what the parameter description already provides. It correctly references the account parameter implicitly but adds no detail about its format or constraints.
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 clearly states the action (list), resource (mailboxes), and scope (for an account). It is specific enough to distinguish from sibling tools like create_mailbox or list_accounts, but could be more explicit about what kind of data is returned (e.g., list of mailbox objects).
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 provides no guidance on when to use this tool versus alternatives. For example, it does not clarify that this tool should be used after listing accounts with list_accounts, or that it only returns top-level mailboxes. No when-not or alternative tool references.
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?
Annotations provide readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds no further behavioral context beyond saving attachments, such as side effects, error conditions, or permission requirements.
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 extremely concise (5 words) and gets straight to the point. No wasted words, and the schema provides parameter details.
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 minimal but sufficient given the thorough schema parameter descriptions. However, it lacks context about optional parameters and the fast path IMAP optimization, which are only in the schema.
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 baseline is 3. The description does not add additional meaning beyond the schema; however, the schema descriptions themselves are thorough.
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 (save), object (attachments from a message), and destination (to a directory). It distinguishes this tool from siblings like get_attachment_content, which retrieves content rather than saving to disk.
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?
No explicit guidance on when to use this tool vs alternatives. The purpose is clear but the description does not provide context for selection among sibling tools such as get_attachment_content.
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?
Annotations already indicate idempotentHint=true and readOnlyHint=false, so the description's mention of 'overwrite' adds contextual value by hinting that an existing template may be replaced. However, it does not detail what 'overwrite' entails (e.g., full replacement vs. partial update) or side effects like cascading to drafts using the template.
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 with no superfluous words. It is front-loaded with the core action and resource, achieving maximum conciseness.
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?
While the tool is relatively simple (3 params, 2 required), the description omits important context such as whether overwriting is an upsert (creates if not exists) or requires a prior get. The existence of an output schema reduces the need to describe return values, but behavioral specifics are missing. Score 3 reflects adequate but not comprehensive completeness.
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 fully documents parameters. The description adds no new parameter-level information beyond the schema, but the baseline of 3 is appropriate since the schema already provides adequate context for each parameter.
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 explicitly states the verb 'Create or overwrite' and the resource 'template', making the tool's purpose clear. It distinguishes itself from siblings like 'get_template', 'delete_template', 'list_templates', and 'render_template' by focusing on creation/update.
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 given on when to use this tool versus alternatives like 'create_draft' (which uses templates) or 'render_template' (which renders without saving). There is no mention of prerequisites, conditions for overwriting, or scenarios where this tool is preferred.
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?
Annotations already indicate non-read-only (readOnlyHint=false), idempotent, and non-destructive behavior. The description adds no additional behavioral traits, so it relies on annotations. No contradiction.
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?
Extremely concise: a single sentence with no wasted words. Front-loaded with the core action. Perfectly structured for quick parsing.
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?
The tool has three well-described parameters and an output schema. Annotations provide safety context. However, it lacks usage context like when to nest mailboxes. Acceptable for a simple creation 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?
The input schema has 100% coverage with parameter descriptions. The tool description does not add any extra meaning beyond what the schema already provides, resulting in a baseline 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 clearly states the action ('Create') and the resource ('a new mailbox/folder'). It effectively distinguishes the tool from siblings like delete_mailbox or list_mailboxes.
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 provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. Among 24 siblings, users lack context for tool selection.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds only that it reads by name, which is redundant with the input schema. The description does not provide additional behavioral context beyond annotations.
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, clear sentence with no unnecessary words. Efficiently communicates the tool's purpose.
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 low complexity, complete annotations, and presence of an output schema, the description adequately covers the tool's function for a simple read operation. No 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% (the only parameter 'name' has a description), so baseline is 3. The description's 'by name' adds no semantic value beyond what's 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 specific verb 'Read' plus resource 'a single template' and method 'by name', clearly distinguishing it from siblings like 'list_templates' (list all) and 'save_template' (create/update).
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?
No explicit guidance on when to use this tool versus alternatives. The usage is implied as reading a specific template, but no when-not-to-use or alternatives are mentioned.
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?
The description states 'requires user confirmation' and 'cannot be undone,' which adds context beyond annotations. However, there is a contradiction: annotations set idempotentHint=true, but a delete operation that fails on retry (index already deleted) is not truly idempotent. This inconsistency reduces transparency.
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 succinct sentences with front-loaded verb and resource. No unnecessary words. Every sentence 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?
Covers purpose, usage, and consequences. For a simple tool with one parameter and an output schema, this is sufficiently complete. Minor absence of error behavior (out-of-bounds index) is acceptable.
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%, providing baseline of 3. The description adds meaning by specifying that the index is '1-based positional index from list_rules,' which clarifies origin and usage beyond the schema description.
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?
Clearly states the action (delete) and resource (Mail.app rule) and specifies the indexing method (1-based positional index). Differentiates from siblings like delete_mailbox and delete_messages.
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 mentions requirement for user confirmation and irreversibility, providing clear usage context. Does not explicitly list when not to use or alternatives, but the nature of a delete operation makes this less critical.
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?
The description adds value beyond annotations by detailing the return structure (id, name, email addresses, account_type, enabled state) and highlighting the stability of account ids. It also provides an example. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description complements them well.
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 concise and well-structured. It starts with a clear purpose sentence, then lists key return fields, followed by a Returns section and an example. Every sentence adds value with no redundancy.
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 is complete for a simple list tool with no parameters. It fully describes the return structure and includes an example, compensating for the absence of an explicit output schema. Given the low complexity, the description covers all necessary information.
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 tool has no parameters, and the input schema has 100% coverage with no additional description needed. The description does not need to add parameter semantics, and it appropriately omits any. Baseline score of 4 is suitable.
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 tool's action: 'List all configured email accounts in Apple Mail.' It specifies the resource (email accounts) and the scope (all configured). This distinguishes it from sibling tools like list_mailboxes or list_rules.
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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or comparison with sibling tools. The only usage-related advice is about preferring account ids over names, which pertains to using the output, not tool selection.
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?
Beyond annotations (destructiveHint=true), the description adds that the operation is recoverable from Trash but effectively one-way, and mentions no rate limit. This provides useful behavioral context.
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 succinct with three sentences, each adding value: purpose, lifecycle context, and additional notes. No wasted words.
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 delete action with full annotations and schema coverage, the description covers purpose, behavior, and special constraints. It lacks only a mention of idempotency, but annotations cover that.
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 coverage is 100%, so the description does not need to add parameter details. The single parameter 'draft_id' is adequately described in the schema, and the description adds no further clarification.
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 'Delete (move to Trash) an existing draft,' using a specific verb and resource. It distinguishes itself from sibling tools like delete_messages or delete_mailbox by specifying it targets drafts.
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 provides context by calling it a 'Lifecycle endpoint for cancellation' and explaining the move to Trash. It implies when to use (to discard a draft) but does not explicitly contrast with alternatives like update_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?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds valuable context: deletion always moves to Trash (not permanent), the permanent parameter is currently a no-op, and the operation requires user confirmation. It does not detail behavior for duplicate deletions or error handling, but the added context is significant.
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 extremely concise: two sentences that front-load the core action (delete and move to Trash) and then add critical behavioral notes (destructive gating, similarity to other delete tools). Every sentence earns its place with no 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?
Given the tool's complexity (4 parameters, output schema exists), the description effectively covers the key behavioral aspects. It could be more complete by explaining behavior for invalid message IDs or partial failures, but the existence of an output schema reduces the need for such detail. Overall, it provides sufficient context for correct invocation.
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?
Input schema has 100% description coverage for all 4 parameters. The description enhances understanding by revealing that the permanent parameter is reserved and no-op, and that providing both account and source_mailbox together speeds up the operation. This adds meaningful nuance 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 explicitly states the tool deletes messages and clarifies that it always moves to the account's Trash mailbox, not permanent deletion. It distinguishes itself from sibling delete tools (delete_rule, delete_mailbox, delete_template) by mentioning they match, providing clear purpose and scope.
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 notes that the tool is destructive and gated behind user confirmation, and it matches other delete tools, implying similar usage patterns. However, it does not explicitly guide when to use this tool versus alternatives like update_message or search_messages, nor does it exclude cases where deletion might not be appropriate.
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?
Annotations already mark destructiveHint=true and idempotentHint=true. The description adds the unique context that user confirmation is needed via MCP elicitation, which is beyond annotation defaults.
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 succinct with two sentences—no wasted words. The first sentence states the primary function, and the second adds critical behavioral context. Well-structured for quick parsing.
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 simplicity (one parameter, clear purpose, existing output schema), the description fully covers necessary context: action, resource, destructive nature, and confirmation requirement.
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 covers the single parameter 'name' with full description ('Template name to delete'). The description does not add additional semantics beyond what the schema provides, so baseline score 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 clearly states 'Delete a template by name,' specifying the action and resource. It implicitly distinguishes from sibling tools like delete_draft and delete_mailbox by focusing on templates.
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 warns that the tool is destructive and requires user confirmation via MCP elicitation. While it could explicitly guide when not to use, the caution effectively sets usage boundaries.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it reads inline without writing to disk, reinforcing the non-destructive nature and providing additional I/O behavioral context. No contradiction.
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?
Two sentences plus a short paragraph. Front-loaded with the main purpose. Slightly verbose in the second part but overall efficient and well-structured.
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 presence of an output schema (not shown but indicated) and good annotations, the description covers usage context (triage workflows) and alternatives. For a 4-parameter tool with 2 required, it is fairly 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?
Schema description coverage is 100%, with each parameter described in the input schema. The tool description does not add additional meaning beyond what is already in the schema, so baseline 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?
Description states 'Read one attachment's content inline, without writing it to disk.' This is a specific verb+resource, and it distinguishes from sibling 'save_attachments' by clarifying inline reading vs. file saving.
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?
Explicitly says to use for 'triage' workflows to inspect an attachment before deciding what to do, contrasting with the alternative workflow of saving, reading, then cleaning up. This provides 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it is a read-only analytics roll-up from a single search_messages pass and explains the scan_limit truncation behavior, providing useful context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately sized but well-structured, with each sentence adding meaningful information. No unnecessary repetition or fluff.
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?
The tool has 8 parameters and an output schema. The description covers the main behavioral aspects, including the window_fully_covered indicator, which helps the agent interpret results. Given the existence of an output schema, it does not need to detail return values.
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%, but the description adds value by explaining defaults (e.g., received_within_hours=720), the meaning of scan_limit, and the window_fully_covered flag, which is not 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 clearly states it aggregates inbox statistics (message volume, read/unread/flagged counts, read ratio, top senders) over a mailbox and time window, and distinguishes itself from sibling tool 'list_mailboxes' which provides per-folder unread counts.
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 explains the default window (last ~30 days) and how to set explicit ranges via date_from/date_to. It also notes the scan_limit behavior and the window_fully_covered indicator, guiding the agent on when the results are a sample rather than a full scan. However, it does not explicitly state when not to use this tool.
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?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds return format details (dictionary with name and subject) but no further behavioral traits like auth requirements or limitations.
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 concise with no wasted words. It front-loads the main action and provides additional details in a clear, structured manner.
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 zero parameters and rich annotations, the description covers storage location, environment variable override, and return format. This is complete for a list operation.
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?
Input schema has no parameters (100% coverage), so baseline is 3. The description adds value by explaining the return structure, which is not 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 states "List all stored email templates" which uses a specific verb and resource, clearly distinguishing it from sibling tools like get_template or render_template.
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 explains where templates are stored and how to override the location, providing context for use. However, it does not explicitly state when not to use this tool or mention 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?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral details: tiered IMAP threading dispatch algorithm, AppleScript fallback, sorting by date_received ascending, and a known limitation about missed members on the fallback 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 well-structured into three clear paragraphs: purpose, algorithm/sorting, and usage suggestion plus limitation. Each sentence adds value without redundancy.
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 an output schema present, the description need not explain return values. It covers the tool's behavior, internal algorithm, and a known limitation. For a read-only threading tool, this is fully adequate.
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% with a description for message_id. The description restates that it's an internal ID but adds context about looking up the anchor message. This provides marginal added value beyond the schema, meeting the baseline of 3.
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 explicitly states it returns all messages in a thread given a message ID, with specific verb 'Return' and resource 'thread'. It distinguishes from siblings like get_messages and search_messages by explaining how the returned IDs can be piped into those tools.
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?
Provides clear context on when to use (to get a thread), how the lookup works, and what to do with the results. Does not explicitly state when not to use but offers alternatives like search_messages and get_messages.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds valuable context: rule names not unique, no stable ID, example 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?
Concise and well-structured: purpose, limitations, return format, example. No wasted words.
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 no parameters and annotations covering safety, description is complete with return format, key limitations, and example. No gaps.
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?
No parameters, so schema coverage is 100%. Description adds no parameter info needed. Baseline of 4 for zero parameters 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?
Clearly states 'List all Mail.app rules (read-only)' with specific verb and resource. Distinguishes from siblings like create_rule, delete_rule.
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 notes read-only nature and mentions mutation is a separate enhancement. Could explicitly state when to use vs alternatives, but context implies usage.
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?
Annotations already indicate read-only, idempotent, non-destructive. Description adds behavioral context: details auto-population logic with message_id (fields like recipient_name, recipient_email, etc.) and the override rule for vars. Consistent with annotations, adds value beyond them.
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?
Four sentences, front-loaded with main purpose, no fluff. Each sentence adds specific, useful information. Efficient and well-organized.
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 moderate complexity and the existence of an output schema (which covers return format), the description is complete. It covers purpose, side-effect-free nature, auto-population, override behavior, and integration with sibling tools. No gaps.
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% (all parameters have descriptions). Description adds meaning beyond schema: explains how message_id triggers auto-population of certain template variables, and that vars override auto-fills. This contextual usage info is valuable.
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?
Explicitly states 'Render a template into ready-to-send subject and body text' with a specific verb and resource. Clearly distinguishes from sibling tools like create_draft by noting that the caller must pass the output to create_draft or update_draft.
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?
Provides clear context for when to use message_id (reply context) and states no side effects. Explicitly says the caller is responsible for passing rendered text to create_draft/update_draft, differentiating from those tools. Lacks explicit 'when not to use' but covers key scenarios.
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?
Beyond annotations (destructiveHint=true, idempotentHint=true), the description fully discloses the delete-and-recreate implementation, new draft_id return, field merge semantics, and edge cases like external draft seed recovery slowness and HTML body preservation limits. No contradictions with annotations.
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 well-structured, starting with core purpose, then implementation details, then merge semantics and edge cases. It is somewhat lengthy but every sentence provides valuable information, earning 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?
Given the tool's complexity (delete-and-recreate, merge semantics, attachment handling, external draft issues), the description covers most critical aspects. It lacks explicit error handling or performance notes, but presence of output schema mitigates need for return value details.
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 description adds significant meaning beyond the input schema, especially for attachment_paths (None preserves, [] clears, list replaces) and body. It explains the general merge rule (non-None overrides). However, not all 12 parameters are individually detailed; some like cc/to/bcc rely on the general rule, leaving minor ambiguity.
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 it updates an existing draft, explains the delete-and-recreate mechanism, and distinguishes from create_draft by noting it returns a new draft_id. The verb 'update' with resource 'existing draft' is specific and unambiguous.
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 explains when to use this tool (to modify a draft) and provides context on Mail.app limitations. It gives guidance on attachment behavior and seed recovery for external drafts, but lacks explicit 'when not to use' or comparison to similar tools like delete_draft.
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?
The description adds significant behavioral context beyond the annotations, including patch semantics, atomic application, order of operations (read/flag before move), and IMAP/Gmail specifics. Annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=true) are consistent with the described behavior of updating and moving messages.
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 efficiently structured, front-loaded with the main purpose, followed by essential details on semantics, order of operations, and deprecation. Every sentence adds value, with no redundancy or fluff.
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 complexity (8 parameters, atomic operations, IMAP implications, Gmail nuances), the description covers all essential aspects: atomicity, patch semantics, order, replacement of previous tools, and deprecation info. The presence of an output schema fills any gaps about return values.
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 provides detailed explanations for each parameter (e.g., account, flagged, gmail_mode). The description's mention of 'Patch semantics' adds overarching context, but does not enhance individual parameter meanings beyond what the schema already offers.
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 tool's function: 'Update one or more messages: change read state, flag, and/or move, in one atomic call.' It also explicitly distinguishes itself from sibling tools by noting it replaces previous separate tools like mark_as_read, move_messages, and flag_message.
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 provides explicit context for when to use the tool, such as atomic updates and replacing previous tools. It also details order of operations and IMAP requirements. However, it does not explicitly state when not to use it, though usage is implied for multiple updates.
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?
Annotations provide no safety hints (readOnlyHint=false, destructiveHint=false). The description compensates fully by disclosing that certain actions trigger user confirmation, that organizational-only rules are created without a prompt, and that rules are appended to the end with the returned rule_index indicating the new total count. This adds substantial behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is five sentences long with no wasted words. It is front-loaded with the main purpose and organized logically: purpose, action-dependent confirmation, appending behavior, and return value. Every sentence 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?
Given the tool's complexity (5 parameters, nested objects, output schema, and behavioral nuances), the description covers the essential points: creation behavior, confirmation triggers, and return value meaning. It could mention error conditions or required account permissions, but overall it is fairly complete.
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 by explaining the behavioral implications of the `actions` parameter (confirmation required for move/forward/delete) and the meaning of the return value (`rule_index`), which goes beyond the schema's static 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 starts with 'Create a new Mail.app rule,' clearly stating the action and resource. It distinguishes from siblings like update_rule and delete_rule by detailing creation-specific behaviors (confirmation, appending to end), making the tool's unique purpose explicit.
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 provides explicit guidance on when to use the tool by separating rules with destructive actions (move/forward/delete) requiring confirmation from organizational-only ones that are created without a prompt. Although it does not explicitly mention alternative tools, it gives sufficient context for appropriate usage.
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?
Annotations are minimal (readOnlyHint=false, etc.), but the description thoroughly discloses behavior: mutation, user confirmation on send, IMAP requirements for HTML, error types, constraints with body_html, and fallback mechanisms. No contradiction.
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?
Well-structured with paragraphs and inline code for parameters, but slightly verbose with some details that could be streamlined. The key purpose is front-loaded.
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 15 parameters, no required ones, high schema coverage, and an output schema, the description covers creation, sending, seeding, templates, attachments, IMAP path, and error handling. It is comprehensive and leaves little ambiguity.
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?
With 80% schema description coverage, the description still adds significant value by explaining auto-quoting, id formats, mutual exclusivity, IMAP path requirements, template rendering, and more. Each parameter's behavior is richly contextualized.
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 tool creates drafts (fresh, reply, forward) and optionally sends immediately. It explains the Mail.app draft primitive and distinguishes from update/delete sibling tools.
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?
Provides clear context for when to use (creating outgoing messages) and when to use send_now. While siblings are listed, no explicit when-not-to-use or alternative selection guidance is given.
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?
Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses behaviors such as returning a list of message dicts, handling of missing IDs, empty list as no-op, and validity of SELECTED token—all adding value beyond schema.
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?
Extremely concise: two sentences plus a brief pairing note. Front-loads the core purpose, with no wasted words.
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 presence of an output schema and comprehensive input schema, the description covers purpose, usage guidance, and behavioral notes adequately. No major 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%, and the parameter descriptions in the schema are already detailed. The tool description does not add significant new information about parameters 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 clearly states that the tool retrieves full details of messages with bodies, and distinguishes itself from sibling tools like search_messages (metadata-only) and get_thread (thread member IDs).
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?
Explicitly advises pairing with search_messages and get_thread to fetch bodies for specific messages, providing clear context for when to use this tool versus 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?
Beyond annotations (destructiveHint=true), description adds specifics: IMAP requirement, user confirmation, refusal of non-empty mailboxes, Gmail restrictions, and error types. No contradiction.
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?
Well-structured with bullet points, front-loaded with main purpose. Slightly long but each sentence adds value; could be marginally shorter.
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 complexity (destructive, IMAP, error cases), description covers prerequisites, behavioral nuances, and edge cases comprehensively. Output schema exists but description completes context.
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?
Input schema covers all 3 parameters with descriptions; description adds context (slash-separated for name, display name or UUID for account, default behavior for delete_messages) beyond 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 clearly states the tool deletes a mailbox via IMAP, explains why (AppleScript limitation), and distinguishes from sibling tools like delete_messages.
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?
Explicitly describes when to use (requires IMAP credentials, user confirmation), when not to use (non-empty mailbox by default, Gmail system labels), and alternatives (delete_messages for messages).
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?
Goes well beyond annotations by describing two corpus modes, performance warnings, silent failure for missing ids, SELECTED sentinel behavior, warnings field inclusion, and opt-in attachments due to AppleScript slowness. Annotations only say readOnly/idempotent/non-destructive.
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?
Well-structured with clear breakdown of modes and thread retrieval workflow. First sentence is concise and informative. Some redundancy could be trimmed, but every section is justified by the tool's complexity.
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 15 parameters, two modes, and an output schema, the description covers all essential aspects: operations, performance trade-offs, workflow guidance, and warning mechanisms. No gaps remain for an agent to misuse the tool.
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%, but description adds crucial context about parameter interaction (e.g., source modes, account ignored when source is list, received_within_hours composes with date fields). Adds value beyond schema 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 tool's purpose: 'Search for messages matching criteria. Returns metadata-only rows.' It distinguishes from siblings like get_messages (full bodies) and get_thread (thread expansion) by explicitly mentioning thread retrieval workflow and source list mode.
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?
Provides explicit guidance on when to use default mailbox search vs. source list mode, and how to combine with get_thread and get_messages. Also warns about performance impact of body_contains/text_contains on AppleScript path, aiding decision-making.
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?
Adds significant context beyond annotations: explains two delivery methods (AppleScript vs IMAP), credential requirements, error types, and validation behavior. No contradiction with annotations.
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?
Well-structured with bullet points, front-loaded purpose, and no unnecessary words. Approximately 150 words.
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?
Covers all aspects: usage, parameters, error cases, and unsupported operations. With an output schema, return values are not needed.
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%, but description adds meaning by explaining the relationship between new_name and new_parent, special values, and validation behavior.
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 it handles both renaming and moving mailboxes, with a specific verb (update) and resource (mailbox). It distinguishes from siblings like create_mailbox and delete_mailbox.
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?
Provides explicit guidance on when to use rename-only vs move, including required IMAP credentials and the resulting error. Also warns about unsupported Gmail system labels.
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?
Annotations already provide destructiveHint=true and idempotentHint=true. The description adds valuable behavioral context: patch semantics, conditional confirmation, and refusal for unsupported actions, which are not captured by annotations.
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 well-structured, front-loading the core purpose, then parameter semantics, behavioral details, and edge cases. Every sentence serves a purpose without unnecessary verbosity.
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 existence of an output schema, the description covers all necessary behavioral and contextual aspects: patch semantics, replacement behavior, conditional confirmation, skip conditions, error handling, and replacement of a removed tool. It is fully complete.
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?
The input schema has 100% coverage, but the description adds important semantics: that only provided fields are changed, and conditions/actions are replaced wholesale. It also explains the conditions for triggering confirmation, which enriches parameter understanding.
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 'Update an existing Mail.app rule (patch semantics)', specifying the verb, resource, and semantics. It distinguishes from siblings like create_rule and delete_rule.
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 provides explicit guidance on when to use this tool, including patch semantics, conditional confirmation triggers, skip conditions, and the enable/disable path replacing set_rule_enabled. It also notes refusal conditions for unsupported actions.
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:

[![apple-mail-fast-mcp MCP server](https://glama.ai/mcp/servers/s-morgan-jeffries/apple-mail-fast-mcp/badges/card.svg)](https://glama.ai/mcp/servers/s-morgan-jeffries/apple-mail-fast-mcp)

Score Badge

Copy to your README.md:

[![apple-mail-fast-mcp MCP server](https://glama.ai/mcp/servers/s-morgan-jeffries/apple-mail-fast-mcp/badges/score.svg)](https://glama.ai/mcp/servers/s-morgan-jeffries/apple-mail-fast-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/s-morgan-jeffries/apple-mail-fast-mcp'

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