Apple Mail
Server Quality Checklist
Latest release: v0.1.0
- Disambiguation5/5
Each tool targets a distinct resource and action, with detailed 'use when' and 'do not use when' guidance that clearly differentiates similar-sounding tools like send-email vs send-serial-email vs send-draft, or search-messages vs list-messages. No two tools overlap in purpose.
Naming Consistency5/5All 61 tools follow a consistent verb_noun snake_case pattern (e.g., delete-template, list-messages, batch-flag-messages). The naming is uniform and predictable, making it easy to infer tool behavior from its name.
Tool Count2/5With 61 tools, the count is far above the typical well-scoped range of 3-15. While each tool has a clear purpose, the high number—especially the proliferation of batch variants and diagnostic tools—makes the surface feel bloated and potentially overwhelming for an agent.
Completeness5/5The tool set covers virtually every aspect of email management: sending, receiving, drafting, replying, forwarding, mailbox CRUD, rule management, template management, smart mailboxes, contacts, attachments, scheduling, and diagnostics. There are no obvious gaps for a consumer email client.
Average 4.7/5 across 61 of 61 tools scored. Lowest: 4.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 5 commits in the last 12 weeks
- Last stable release on
- 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.jsonto 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?
No annotations exist, so description carries full burden. It discloses return counts but omits details like idempotency, error handling, or side effects. Basic but 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences front-loading usage and boundaries. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema (indicated) and good usage guidance, description is mostly complete. Missing a note on handling already-read messages or failure scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description only says 'marking multiple messages (1–100 ids)' without detailing the ID format or parameter syntax. Leaves agent to infer from schema pattern.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool marks multiple messages as read in one call, specifying the range of 1-100 IDs. It distinguishes itself from siblings like mark-as-read and batch-mark-as-unread.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (multiple messages), when not to (single or unread), provides alternative tools, and advises to get IDs from search-messages or list-messages first.
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 provided, so description must carry the burden. It mentions 'moves a real message' and returns a confirmation, but lacks details on authentication or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured with clear sections (Use when, Returns, Do not use when, Safety), and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the main use case and return value. The output schema exists and description addresses it. Minor gap: 'account' parameter not explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, and the description does not explain the 'account' parameter or provide additional meaning beyond naming 'id' and 'mailbox'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (moving a single message by id into another mailbox/folder) and distinguishes from siblings like batch-move-messages and delete-message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when' and 'Do not use when' conditions, names alternative tools, and advises using list-mailboxes to confirm destination.
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 provided, so description carries full burden. It discloses that it marks messages as unread and returns success/failure counts, but lacks details on side effects, reversibility, permissions, or rate limits. Adequate but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Efficiently structured with labeled sections: Use when, Returns, Do not use when, and prerequisite. Every sentence is valuable with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple batch mutation tool with one parameter and existing output schema, description covers usage, return, exclusions, and prerequisite. Lacks mentions of threading or access implications, but largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 0% (description does not describe parameter format), but the schema provides a pattern for ids. Description adds context that ids come from search/list results. Baseline 3 due to low coverage, with partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool marks multiple messages (1-100) as unread in one call. It distinguishes from siblings like mark-as-unread (single) and batch-mark-as-read (read instead of unread).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' with specific alternatives. Also provides prerequisite: get ids from search-messages or list-messages 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 provided, so description carries full burden. It discloses destructive nature, moves to Trash, requires user confirmation, and suggests prior message verification. Returns counts of deleted and failed. Lacks mention of authorization requirements but overall thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is structured with clear sections (use, do not use, safety, returns). Front-loaded with purpose. Slightly verbose in safety section but overall well-organized and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, guidelines, safety, and return values. With output schema present, explanation of return values is adequate. Could mention partial failure handling or idempotency, but sufficient for a batch delete tool among many siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'ids'. Schema already specifies array of strings with pattern and min/max. Description adds that it's multiple messages and they are moved to Trash, but doesn't elaborate on the nature of IDs (e.g., message IDs). With 0% schema description coverage, some extra context is provided, but not fully compensating.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it deletes multiple messages in one call, distinguishing from delete-message (single) and batch-move-messages (filing). The verb 'deleting' and resource 'multiple messages' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: deleting multiple messages in one call' and 'Do not use when: deleting just one (use delete-message) or filing messages away (use batch-move-messages)'. Provides clear context and alternatives.
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. It discloses that the tool creates a real folder, returns a confirmation, and includes a safety warning to confirm name and account. It does not detail side effects or auth requirements, but provides sufficient context for a simple create 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear sections (Use when, Returns, Do not use, Safety). Every sentence is meaningful and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple creation tool with an output schema, the description covers purpose, usage, result, and safety. It could mention prerequisites (e.g., account must exist), but overall it is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (name lacks description; account is described). The description mentions 'name and target account' in safety but adds no new details beyond the schema, such as name format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource ('creating a new mailbox/folder in an account') and explicitly distinguishes from sibling tools like rename-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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (creating a new mailbox), when not to use (renaming or deleting), and names alternative tools (rename-mailbox, delete-mailbox). Also advises checking existing mailboxes with list-mailboxes.
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 full burden. It declares the tool as destructive, requires explicit user confirmation, and explains the internal locating logic (account, mailbox, native message id). Lacks details on error cases (e.g., draft not found) but sufficiently covers main behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: use-case, return values, exclusions, safety. Front-loaded with 'Use when'. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, safety warning, and mentioned return values (draft_id, subject), the description is nearly complete. It could mention prerequisites (from list-drafts/read-draft) more explicitly, but the implied workflow is clear. Output schema existence reduces burden on description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter draft_id is described only by the schema's pattern. The description does not explain its purpose, origin, or format beyond the schema. With 0% schema coverage, the description should compensate but fails to add any meaningful context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes an Apple Mail draft by draft_id, distinguishing it from deleting ordinary mail via the sibling tool delete-message. It specifies the verb 'delete' and resource 'draft', and the 'Use when' phrase sets clear scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use ('moving one inspected Apple Mail draft to Trash'), when not to use ('deleting ordinary mail'), and recommends an alternative tool (delete-message). Also implies appropriate preceding step (read-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?
No annotations provided, so description carries full burden. It discloses the action (move to Trash, not permanent delete), returns confirmation, and warns of destructiveness. However, it doesn't mention rate limits or auth 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise, front-loaded with use guidance. Every sentence is necessary and no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it has an output schema (mentioned in context), the description doesn't need to detail return values. It covers the essential purpose, usage, and safety. Could add more about output, but sufficient for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds minimal parameter info: just 'by id'. The schema has a pattern, but the description doesn't explain what the pattern means or provide usage context for the id parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes a single message by id and moves it to Trash. Distinguishes from batch-delete-messages and move-message, so the agent can differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when' and 'Do not use when' with specific sibling tools (batch-delete-messages, move-message). Also includes safety steps like requiring confirmation and searching 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 provided, so description carries full burden. It discloses return counts (how many unflagged and failed), batch size limit (1-100), and prerequisite ids. Does not mention idempotency or invalid id handling, but overall informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with 'Use when'. Every sentence adds value: purpose, limits, return, alternatives, prerequisites. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple batch tool with one parameter and output schema, description covers core usage, return value, prerequisites, and differentiation from siblings. Lacks error handling details but adequate for effective agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description mentions 'removing flags from multiple messages (1–100 ids)' which explains the ids parameter implicitly. Also advises getting ids from other tools, adding context beyond schema pattern. However, does not elaborate on parameter format or validation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'removing flags from multiple messages (1–100 ids) in one call.' Verb is specific (removing flags), resource is messages, scope is batch. Distinguishes from unflag-message and batch-flag-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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when' and 'Do not use when' conditions, including alternatives (unflag-message, batch-flag-messages) and prerequisite to get ids from search-messages or list-messages.
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?
The description discloses that the tool returns a confirmation and does not have annotations, so it carries the full burden. However, it does not describe what happens if the rule is already enabled, whether the operation is idempotent, or any potential side effects. Basic behavior is covered, but edge cases are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of three brief sentences. It front-loads the purpose and returns, then immediately provides usage boundaries. Every sentence serves a clear purpose, with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with an output schema, the description covers the key aspects: purpose, return value, and usage boundaries. It could mention idempotency or what happens if the rule does not exist, but overall it is adequately complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning for the 'name' parameter. The description indicates that the parameter is the rule name and advises using list-rules to confirm the exact name, providing valuable guidance. However, it does not specify format, case sensitivity, or validation beyond the schema's minLength.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: 'turning on an existing Mail rule by name.' It clearly identifies the action (enable), the resource (Mail rule), and the required input (name). This differentiates it effectively from sibling tools like disable-rule, 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/5Does 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 ('Use when: turning on an existing Mail rule by name'), when not to use it ('Do not use when: turning a rule off, creating one, or deleting one'), and suggests an alternative tool (list-rules) to confirm the exact rule name. This leaves no ambiguity for the agent.
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 must bear full transparency burden. It discloses the return ('a confirmation that the message was marked unread'), which is adequate for a simple state toggle. However, it does not mention idempotency or permissions, though these are implied by the tool's simplicity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with three sentences—no superfluous words. It fronts the usage guidance and return value, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema, the description covers purpose, usage context, prerequisites (getting the id), and return value. It lacks only minor details like whether marking an already unread message is a no-op, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains that the id parameter identifies the message and where to obtain it ('Get the id from search-messages or list-messages first'), but does not clarify the pattern or accepted formats, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'marking a single message (by id) as unread,' clearly defining the verb and resource. It distinguishes from sibling tools like 'batch-mark-as-unread' and 'mark-as-read' by specifying single vs. batch and unread vs. read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use ('marking a single message as unread') and when-not-to-use ('Do not use when: marking several at once... or marking read'), with direct references to alternative tools (batch-mark-as-unread, mark-as-read). Also instructs to obtain id from search-messages or list-messages.
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 provided, so the description carries the burden. While it implies a read-only operation, it does not explicitly state behavioral traits like non-destructiveness, idempotency, or authorization needs. The description is adequate but lacks full 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each essential: usage indication, return description, and exclusion of alternative. Front-loaded with the primary use case. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description does not need to detail return structure. It lists key returned fields and distinguishes from list-drafts. Missing minor details like error conditions or prerequisites, but sufficient for a read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds context by stating the tool reads a draft selected from list-drafts, implying the draft_id parameter comes from that source. The parameter name and pattern are self-explanatory, and the description adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the full current contents of a draft, lists the returned fields (draft_id, From, recipients, subject, full body), and distinguishes itself from list-drafts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use ('reading the full current contents of one draft selected from list-drafts') and when not to use ('only need draft summaries – use list-drafts').
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. It states the operation renames a real folder, warns about case-sensitive exact match for oldName, and mentions return value. However, it does not disclose permissions, rate limits, or side effects on messages inside the folder, but the safety warning adds value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, using bullet-like phrases ('Use when:', 'Returns:', 'Do not use when:', 'Safety:'). It front-loads the key purpose and contains no unnecessary words, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple operation (rename mailbox) with 3 parameters and no nested objects, the description covers when to use, how to use (case-sensitive match), return value, and alternatives. It could mention error handling or prerequisites, but is largely complete for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (33% - only account described). The description clarifies the roles of oldName and newName by framing the rename action, but does not explain the account parameter. It adds partial meaning but does not fully compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: renaming an existing mailbox/folder. It specifies the verb 'rename' and the resource 'mailbox/folder', and distinguishes from siblings by explicitly mentioning create-mailbox and delete-mailbox as alternative tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' guidance, including alternative tools (create-mailbox, delete-mailbox) and a recommendation to use list-mailboxes to confirm the current name. This helps the agent choose correctly.
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 fully carries the transparency burden. It labels the operation as 'destructive', explains 'removes the folder and any messages it contains', and states that explicit user confirmation is required. It could additionally mention irreversibility but 'destructive' implies permanence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is highly concise and well-structured with clear sections: 'Use when:', 'Returns:', 'Do not use when:', 'Safety:'. Every sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deletion tool, the description covers purpose, usage boundaries, safety implications, prerequisite actions, and return value. With an output schema present (not shown but noted), the description is sufficiently complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 2 parameters with 50% description coverage (account has description, name does not). The description adds indirect guidance for name ('use list-mailboxes first to confirm the exact name') but does not directly describe the name parameter's format or meaning. Account's description is already in the schema. Overall, marginal added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'deleting a mailbox/folder from an account.' It also distinguishes from siblings like rename-mailbox and delete-message, making the function unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when:' and 'Do not use when:' conditions with alternative tools named (rename-mailbox, delete-message, batch-delete-messages). Also advises prerequisite actions: 'use list-mailboxes first to confirm the exact name' and 'Require explicit user confirmation.'
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 discloses that it reads actual Drafts mailbox (not just open windows) and describes the return content (draft_id, identity, recipients, etc.). It lacks mention of permissions or idempotency but covers essential traits 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with usage context, and contains no redundant information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no required ones) and the presence of an output schema, the description covers all necessary aspects. It explains when to use, what it does, what it returns, and when not to use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter (limit) described in the schema. The description does not add extra meaning beyond the schema. 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists saved Apple Mail drafts from every account's Drafts mailbox, not just open compose windows. It uses a specific verb ('list') and resource ('drafts') and explicitly distinguishes from list-messages for ordinary mailbox 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when:' and 'Do not use when:' sections provide clear context for when to use this tool versus alternatives. The sibling tool list-messages is named as the appropriate alternative for ordinary 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?
No annotations provided, but description details return values (names, counts). It implies a read-only operation; however, it doesn't explicitly state safety or permissions, which would enhance 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, front-loaded sentences covering purpose, returns, and exclusions. No redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single optional parameter and existing output schema, the description fully covers what the agent needs to know: when to use, what it returns, and what not to use it for.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and schema description is clear. Description adds usage context but does not significantly extend parameter meaning beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool lists mailbox/folder names and unread/message counts, and distinguishes it from siblings like list-messages and list-accounts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear 'Use when' and 'Do not use when' sections with specific alternative tools, giving explicit guidance.
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 exist, so description must carry full burden. It describes return fields (id, date, subject, sender) and mentions diagnostics for skipped mailboxes. However, it does not explicitly state read-only nature, auth requirements, or side effects. With zero annotation coverage, more behavioral context would be prudent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Succinct and front-loaded: starts with 'Use when', each sentence adds value. No redundant or vague statements. Efficient use of words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description still explains return format (fields and diagnostics). It covers usage scenarios, parameter roles, and how it integrates with sibling tools. Complete for a listing tool with six parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions. The description adds meaningful context: explains pagination (limit/offset), filtering by sender and unreadOnly, and optional mailbox vs. all mailboxes. It does not mention the 'account' parameter but covers the primary functional parameters well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists recent messages from a mailbox with optional filters (sender, unreadOnly) and pagination. It differentiates from siblings: search-messages (for specific criteria) and get-message (for body by ID). The verb 'browse' and resource 'recent messages' are precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections with concrete alternatives. It specifies pagination via limit/offset, obtaining IDs for other tools, and when to use search-messages or get-message instead. No ambiguity.
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 provided, but description states the action is marking as read (non-destructive) and return is a confirmation. Lacks details on permissions or idempotency, but sufficient for this simple action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise, front-loaded purpose, returns, exclusions, and prerequisites in a clear structure with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with output schema, description covers purpose, usage guidelines, parameter source, and return value. Complete and sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. Description mentions 'by id' and source of id, but does not explain id format or pattern. Adequate but minimal additional meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's action: marking a single message as read. It explicitly distinguishes from siblings like batch-mark-as-read and mark-as-unread.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when to use (single message) and when not to (batch, unread), and directs to retrieve id from search-messages or list-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?
No annotations are present, so the description carries the full burden. It discloses the return format (id, date, subject, sender, read state) and a notable behavioral detail: partial-coverage diagnostics when some mailboxes are skipped. This is sufficient for a non-destructive search tool, though additional info on rate limits or performance could enhance it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: it starts with 'Use when', then 'Returns', then 'Do not use when', and finally 'Prefer this first'. Every sentence is functional and adds value, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (not shown but indicated), the description appropriately covers return fields and an edge case (partial coverage). For a search tool with 10 parameters, it provides sufficient context for an agent to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions for all 10 parameters. The description only mentions filters generically and does not add meaning beyond the schema. Baseline 3 is appropriate since the schema already provides full parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: searching messages with various filters (query, sender, subject, date, read, flag) to obtain IDs for follow-up operations. It distinguishes from siblings like list-messages (plain listing), get-message (if ID known), and get-thread (conversation), so the agent can select correctly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' instructions, naming specific alternatives (list-messages, get-message, get-thread). It also advises to prefer this tool first to get IDs needed by other tools, giving clear context for selection.
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 fully bears the transparency burden. It clearly states the tool is destructive ('the rule is removed permanently'), requires explicit user confirmation, and suggests a prerequisite step (list-rules). It also describes the return value (confirmation). This fully discloses behavioral impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: four short, front-loaded sections covering use, return, alternatives, and safety. Every sentence adds value with zero redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter delete tool with no annotations, the description covers purpose, usage, return, and safety. However, it lacks information about error cases (e.g., behavior if rule does not exist) or idempotency. The output schema exists but is not described; the description says 'returns a confirmation' which is sufficient. Overall, very good but not fully exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should add parameter meaning. It mentions 'by name' and advises using list-rules to confirm the exact name, implying case-sensitive exact match. However, it does not directly describe the 'name' parameter's format or constraints beyond the schema (minLength 1). The extra guidance helps but is indirect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool permanently removes a Mail rule by name, and explicitly distinguishes it from disable-rule (pause) and create-rule. The verb 'deleting' and the resource 'Mail rule' are 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use ('permanently removing a Mail rule') and when-not-to-use ('only want to pause it' or 'create one') with named alternatives (disable-rule, create-rule). Also advises to use list-rules first for confirmation.
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. It discloses that the tool disables without deleting and returns a confirmation. It does not mention any destructive behavior, which is appropriate as it is non-destructive. There is no contradiction. However, it could add context on whether the rule remains visible or its state after disabling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two sentences to convey purpose, usage guidelines, and a helpful tip. Every sentence is value-adding, and it is front-loaded with the primary use case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no annotations, output schema exists), the description covers the main aspects: action, return type, and precondition. It does not mention error handling or what happens if the rule doesn't exist, which might be covered in the output schema. Slight room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'name' has no description in the schema (0% coverage). The description adds value by specifying it is the exact rule name and advising to use list-rules to confirm. This helps the agent understand the required input beyond the schema's minimal definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: disabling an existing Mail rule by name without deleting it. It uses a specific verb (disable) and a resource (Mail rule). It also distinguishes itself from sibling tools like enable-rule, 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use (turning off an existing rule) and when not to use (for enabling, creating, or deleting). It mentions specific alternative tools (enable-rule, create-rule, delete-rule) and advises using list-rules to confirm the exact rule name.
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 exist, so description carries full burden. It describes return data (totals, unread, recent activity, per-account breakdown) and mentions IMAP STATUS optimization for the account parameter. Lacks explicit mention of read-only nature or potential performance impact, but overall 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise multi-sentence structure, front-loaded with usage context, then lists returns and exclusions. 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description adequately covers the tool's purpose and parameters. Additional details about per-account breakdown structure could be inferred from schema, but the description is sufficiently complete for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one optional parameter with schema coverage 100%. The description adds extra semantic context beyond the schema by noting the IMAP STATUS optimization for configured accounts, which aids agent understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides 'aggregate mailbox statistics' including total, unread, and recent counts, and distinguishes itself from sibling tools like get-unread-count and list-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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections, with specific alternative tool names (get-unread-count, list-messages, search-messages), providing clear 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?
No annotations provided, so description carries full burden. It explains scope and default behavior, but could mention if there are any side effects or rate limits. However, for a simple read operation, it is transparent enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with usage condition. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and presence of output schema, the description is sufficient for an agent to decide when to use it. Lacks mention of error handling but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The description adds context by explaining scoping and default INBOX, going beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the number of unread messages without listing them. It specifies default scope (INBOX) and distinguishes from siblings like list-messages and get-mail-stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (need count only) and when not to use (need actual messages or broader totals) with specific sibling tool names. Also explains default and scoping behavior.
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, but description discloses it returns metadata only, not bytes. It is read-only in nature, though not explicitly stated as such.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences structured with usage context, return value, and exclusions. Slightly verbose but well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, description covers all needed context: purpose, parameter prerequisite, and return summary (names, MIME types, sizes, count). No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'id' is explained as the message id, with guidance on how to obtain it. Despite 0% schema coverage, the description fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'enumerating', the resource 'attachments' by message id, and outputs (names, MIME types, sizes, count). It distinguishes from siblings like fetch-attachment and save-attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use when' and 'Do not use when', directing to alternative tools for bytes and advising to obtain message id from search-messages or list-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?
No annotations provided, so the description carries the full burden. It discloses the mutating effect ('changes when a real email will be sent') and the need for confirmation. It could be improved by covering edge cases (e.g., if send_at is in the past) but is generally 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, purposeful sentences: usage guidelines, return value, and safety warning. No fluff, front-loaded with the key use case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with an output schema, the description covers behavior, conditions, and return value. Minor gaps exist (e.g., error cases, validation of send_at), but overall it is sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds value beyond the schema: it contextually explains 'schedule_id' and 'send_at' as a 'timezone-aware time', and clarifies 'confirmed' as requiring explicit user confirmation. Schema coverage is 33% (only send_at described), and the description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('changing the future time') and resource ('pending Apple Mail scheduled send'). It differentiates from siblings like 'cancel-scheduled-send' by focusing on rescheduling rather than cancellation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' conditions are given, including specific statuses (e.g., 'already sending, sent, failed, cancelled, needs_review') and the requirement for explicit confirmation before setting 'confirmed=true'.
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 full burden. It discloses writes to disk, persistence across restarts, and overwrite behavior. Could mention permissions or reversibility, but is transparent for a typical write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using structured sections (Use when, Do not use when, Safety). No redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 params and an output schema. The description covers usage, exclusions, safety, and return values. It is sufficiently complete for the complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (3 of 6 params documented). The description adds context: 'optional default to/cc', 'passing existing id' for update, and mention of placeholders. This compensates for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool saves or updates a reusable email template, specifying the resource (template) and action (save/update). It differentiates from siblings like use-template and create-draft, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (creating/updating a template), when not to use (one-off messages, filling in a template), and names alternative tools (create-draft, send-email, use-template). This gives clear decision criteria.
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?
Although no annotations are provided, the description discloses key behavioral traits: it creates a draft in Mail.app for user review and sends a confirmation. It does not mention side effects beyond creating a draft, which is adequate for a non-destructive action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (3 sentences) and well-structured with clear 'Use when', 'Returns', and 'Do not use when' sections. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 presence of an output schema, the description sufficiently covers the core functionality and return value (confirmation). However, it could mention that the draft remains editable by the user, though this is implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds context to parameters beyond the schema by noting that recipients, subject, and body are optional overrides. With 80% schema coverage, the description reinforces the purpose of each override, especially clarifying that id is a template identifier.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: composing a new draft from a saved template by id, with optional overrides. It distinguishes itself from sibling tools like get-template and send-email, providing a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (composing a draft from a template) and when not to use (inspecting template via get-template, or sending directly via send-email). This provides clear guidance for selection.
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 provided, so the description carries full burden. It discloses that colors are applied via Mail.app (AppleScript) and that IMAP-routed ids are flagged but not colored. It also states the return value: counts of flagged and failed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences in a single paragraph. Clear and front-loaded with the main action. Could be slightly more structured (e.g., bullet points) but is efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers prerequisites, return value, and color behavior nuance. An output schema exists but is not shown; the description fills in the return format. Still, could mention how to interpret the counts or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Two parameters with 50% schema description coverage. The description adds context: explains the color enum values and notes that IMAP ids get colorless flags. For ids, it mentions the range (1-100) already in schema but adds guidance on sourcing ids.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool batches flagging of multiple messages (1-100 ids), optionally with a color. It explicitly distinguishes from single-flag and unflag tools, leaving no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use (flagging multiple messages) and when-not-to-use (single flag -> use flag-message, removing flags -> use batch-unflag-messages). Also gives a prerequisite: get ids from search-messages or list-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?
No annotations provided, so description carries full burden. It discloses the safety implication (prevents future action), return value (cancelled schedule, leaves draft), and need for confirmation. Does not cover all potential errors but adequate for main behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise with 4 sentences, each serving a distinct purpose (use case, return, exclusions, safety). Well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple nature and existence of output schema (not shown but signaled), the description covers all needed aspects: when to use, when not, safety, return, and parameter semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% but description explains that 'confirmed' requires explicit confirmation before setting to true, and 'schedule_id' must be the exact one from user. Adds meaning beyond schema pattern and required fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'preventing one pending Apple Mail scheduled send'. It uses a specific verb (cancel) and resource (scheduled send), and distinguishes from sibling tools like reschedule-scheduled-send.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when:' and 'Do not use when:' conditions, including when the job is already sending or terminal. Also includes safety warning requiring explicit confirmation.
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?
Despite no annotations, the description thoroughly covers behavioral traits: it edits SyncedSmartMailboxes.plist directly with backup and atomic write, never rewrites existing smart mailboxes, and warns that Mail should be quit first for reliability. This exceeds typical transparency expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear headings ('Use when:', 'Returns:', 'Do not use when:', 'Safety:') and front-loads the purpose. Every sentence adds value, though it could be slightly more concise. Overall, it is effective and not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (plist editing, multiple criteria, output confirmation) and the presence of an output schema, the description covers essential aspects: usage context, return values, safety precautions, and prerequisites (quit Mail). It does not detail the return schema structure, but that is handled by the output schema. The explanation is sufficient for an AI agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the optional parameters (bodyContains, fromContains, subjectContains) as substring matches. The description reinforces this by mentioning 'matches a sender, subject, or body substring'. It does not add syntax or format details beyond the schema, but the 75% schema coverage means the description is not burdened heavily. There is slight room to explain how multiple criteria combine (AND/OR), but it is not necessary for basic usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates an Apple Mail smart mailbox, a criteria-based virtual view matching sender, subject, or body substring. It distinguishes from creating a real folder by explicitly mentioning the sibling tool 'create-mailbox' in the usage guidance, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' instructions, including the alternative 'create-mailbox' for real folders. It also notes the specific German-localized macOS use case where AppleScript fails, offering clear context for when 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses destructiveness ('removes permanently from on-disk store') and safety advice. It lacks detail on the return value beyond 'confirmation', but an output schema exists, so that is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences), front-loaded with 'Use when', and every sentence adds unique value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-param deletion tool, the description covers purpose, usage guidelines, safety, and confirmation advice. With an output schema existing, it is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage for the id parameter. The description adds context by explaining it's a template id and instructs to confirm it with list-templates, aiding the agent beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for 'permanently removing a saved email template by id'. It distinguishes from siblings like get-template (view) and save-template (update).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('permanently removing'), when not to use (view/update), and provides alternatives. Also advises using list-templates first to confirm id, and notes the need for explicit user confirmation.
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 provided, but description explains return format ('detailed diagnostic report with structured checks') and mentions actionable remediation messages. Could explicitly state read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with usage context, no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters and an output schema present, description covers purpose, usage boundaries, and return format completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; baseline 4 applies as per rules. Description adds no param info, which is acceptable given zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'diagnoses' and specific resources 'Mail.app automation permissions, account state, and IMAP/SMTP backends', differentiating from sibling tools like health-check and get-mail-stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('troubleshooting setup problems'), when not to use, and provides alternative tool names (health-check, get-mail-stats).
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 exist, so description must cover behavior. It explains the color limitation for IMAP IDs, which is a significant nuance. However, it does not explicitly state that flagging modifies the message (though implied).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with clear sections: 'Use when', 'Returns', 'Do not use when', 'Note'. Front-loaded with purpose and no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, output schema exists), the description covers usage boundaries, parameter specifics, and a notable behavioral quirk. It is complete and self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds context beyond the schema: id must be obtained beforehand, color options are repeated, and the IMAP color limitation is explained. Schema coverage is 50%, but the description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool flags a single message by ID, optionally with a color, and distinguishes it from related tools like batch-flag-messages and unflag-message. The verb 'flag' and resource 'message' are 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear guidance, including getting the ID from search-messages or list-messages. Alternatives are named directly.
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 provided. Description implies read-only behavior by stating 'reading full contents' and listing return values, but does not explicitly mention safety, permissions, or side effects. However, the description is clear enough for a simple retrieval 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: first states usage, second states returns, third states when not to use with alternatives. Front-loaded and concise with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema present), the description covers all necessary aspects: what the tool does, when to use it, what it returns, and how it differs from related tools. The output schema handles remaining details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (id) with no description in schema. The description adds meaning by stating 'by id' and clarifying that 'id' refers to the template's identifier. The usage guidelines further advise using list-templates to obtain the ID if unavailable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the full contents of one saved template by its ID, listing specific fields (name, subject, default to/cc, body). It distinguishes from siblings like list-templates and use-template by providing when-not-to-use guidance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (reading full contents of a template by ID) and when not to use (no ID or want to apply template). Provides clear alternatives: list-templates to get IDs and use-template to apply the template into a 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?
With no annotations provided, the description carries full burden. It discloses that results are returned oldest-first, explains the threading algorithm (imap: id vs normalized subject), and lists the exact return fields (normalized subject, id, date, subject, sender, read state). No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with the use condition. Every sentence serves a purpose: usage, threading logic, return format, and when-not-to-use. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the description adds extra value by detailing the return fields and behavior. It covers all necessary aspects: input requirements, threading behavior, output format, and exclusion cases. Complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 new information about the parameters beyond what the schema already provides; the only extra detail is the pattern hint for id, which is already captured in the schema's pattern. No elaboration on limit, account, or mailbox beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource ('get-thread') and clearly states the tool's purpose: take one message id and return the whole conversation. It distinguishes itself from siblings like get-message and search-messages by explaining the threading logic based on References/Message-ID vs normalized subject.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use ('have one message id and want the whole conversation') and when not to use ('only need the single message' or 'searching by arbitrary criteria'), naming alternative tools (get-message, search-messages). This provides clear guidance for agent decision-making.
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 full burden. It discloses the tool's read-only nature (health check, returns status), what it does not do, and the result format. It does not mention permissions or side effects, but for a simple health check, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loading usage context and return format. Every word contributes value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers all essential aspects: purpose, usage conditions, and return format. An output schema exists (context signal), so detailed return structure is not needed in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. No parameter details needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks Mail.app reachability and basic server health, returning overall status with per-check pass/fail. It distinguishes itself from the sibling 'doctor' tool by specifying what it does not do (detailed diagnostics).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when' and 'Do not use when' sections, naming the alternative 'doctor' for cases needing detailed diagnostics. This offers clear guidance on 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states it returns account names and a count, implying no side effects. However, it does not mention authentication requirements or potential limitations, though the operation appears simple and read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, focused sentences. Front-loaded with use case, 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with an output schema, the description is sufficient. It states what is returned (account names and count). Given the context of sibling tools, this is complete for an agent to understand usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, and schema coverage is 100% (empty). Description adds value by explaining the return value (account names and count), which is not in the schema. Baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it discovers configured Mail accounts (e.g., iCloud, Gmail) to provide account names for other tools. It distinguishes from sibling tools by specifying when not to use it (folders or 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (discovering accounts for passing name) and when not to use (use list-mailboxes instead for folders, list-messages/search-messages for messages). Provides clear alternatives.
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 must cover behavioral traits. It states the output (each rule's name and enabled/disabled state), implying a read-only, non-destructive operation. It does not mention authentication, rate limits, or return volume, but for a simple list tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences, front-loads the purpose, and contains no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and presence of an output schema, the description covers all necessary context: purpose, usage guidance, and basic output. No gaps remain for a minimal list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is 100% (trivially). With 0 parameters, the baseline is 4. The description adds no parameter info because none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: discovering Mail rules and their enabled/disabled states. It uses a specific verb ('discovering') and resource ('Mail rules'), and distinguishes from sibling tools for changing rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly outlines when to use (discovering rules before enabling/disabling/deleting) and when not to use (changing rules), and names alternative tools (enable-rule, disable-rule, create-rule, delete-rule).
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?
Despite no annotations, the description fully discloses behavior: it is read-only, lists scheduled sends, and provides details on returned fields. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three highly informative sentences front-loaded with intent, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description covers return fields and use cases sufficiently. Simple tool with one optional param, no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'status' (optional enum) is not explicitly explained in the description, but the enum values are clear and the use cases imply filtering by status. Given 0% schema coverage, the description could add more, but it's adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists scheduled sends, with specific use cases (reviewing future sends, checking status, diagnosing failed/needs_review jobs) and explicitly distinguishes from list-drafts for ordinary drafts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear context and name the alternative tool (list-drafts), meeting the highest standard for usage 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?
No annotations are provided, so the description carries full burden. It explains it returns identity_id, account, email, formatted sender, enabled state, and default state. Since it's a read-only list operation, the behavior is transparent enough. Could mention that it does not modify data, but the context implies that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear structure: usage guidance, return fields, and exclusion. Every sentence is necessary and no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, a list operation, and the existence of an output schema, the description is complete. It covers purpose, when to use, and return data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so baseline is 4. The description adds value by explaining what fields are returned, which is more than the empty schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'list' and resource 'sending identities', clearly stating it discovers 'From addresses/aliases' in Apple Mail. It distinguishes from sibling 'list-accounts' by noting the difference between accounts and aliases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear context and an alternative ('list-accounts'). This helps the agent select the correct tool.
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?
Without annotations, description explains output fields (id, name, subject) and side-effect-free listing. It does not mention pagination or limits, but given no parameters, it's sufficiently 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: when to use, what returns, when not to use. No redundancy, highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and output schema existence, description fully covers purpose, usage context, and return content. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters present, so baseline 4 applies. Schema coverage is 100% (trivial), and description adds value by explaining what the output contains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists saved email templates with their ids, names, and subjects, using specific verb (discovering) and resource (templates). It implicitly distinguishes from siblings by listing use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (before using/editing a template) and when not to use (when wanting full body or applying a template), with direct alternatives (get-template, use-template).
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 exist, so description bears full burden. It discloses that the tool 'SENDS real email immediately and cannot be unsent', requires explicit confirmation, and explains how drafts with attachments are handled differently. This is thorough and safety-conscious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: starts with purpose, then returns, then exclusions, then safety. Every sentence adds value without redundancy. Ideal length for an AI agent to quickly parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (sending email with MIME considerations) and presence of an output schema, the description covers all essential aspects: when to use, what it returns, safety warnings, and special cases (attachments). No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (draft_id) is defined, and the input schema has 0% description coverage. The description does not explain the parameter's origin or format beyond its pattern; the return values mention draft_id but not how to obtain it. While the parameter is simple, adding context (e.g., 'obtain from list-drafts') would improve clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sends an existing Apple Mail draft and specifies when to use it (after user review or explicit request). It distinguishes from siblings like create-draft, read-draft, and update-draft by emphasizing sending, not editing or creating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear context: send only after review or explicit request, and avoid if user still needs to edit or if attachments are present (use send-email instead). This contrasts effectively with sibling tools.
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?
Despite no annotations, the description discloses that the action is local, reversible, and sends nothing. It mentions return value but could add detail on authorization or side effects; still strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with clear sections (use when, do not use when, returns, safety). Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and presence of an output schema, the description covers all necessary aspects: purpose, usage context, behavioral effects, and return type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes the parameter well. The description adds the return value indication, providing additional context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for setting the plugin's default From identity for future create-draft calls. It distinguishes from siblings by specifying its local scope and effect, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections with concrete alternatives (e.g., passing 'from' to create-draft) provide clear guidance on when to invoke this tool versus others.
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 provided, so description carries full burden. It states it returns a confirmation. It does not detail error cases or permission requirements, but for a simple, non-destructive mutation, 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four well-organized sentences: use when, returns, do not use, and a hint to get the parameter. No fluff, information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple mutation tool. Addresses purpose, parameter source, and exclusions. Has an output schema (not shown) so return details are covered. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but description explains that the 'id' parameter is a message identifier and suggests how to get it. This adds valuable context beyond the schema's pattern constraint.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action: removing a flag from a single message. Differentiates from sibling tools flag-message and batch-unflag-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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (removing flag from single message) and when not to (batch unflagging or adding flag). Also advises how to obtain the required id parameter from search-messages or list-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?
No annotations are provided, so the description carries full burden. It discloses key behavioral traits: the rule automatically acts on real mail on an ongoing basis, includes delete/move actions, and that actions are irreversible. It also advises user confirmation for safety. This fully compensates for missing 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is 3-4 sentences, front-loaded with the 'Use when' directive. Every sentence serves a purpose: usage conditions, behavioral caution, and alternative guidance. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, complex nested schema, and presence of an output schema, the description covers safety, usage guidelines, and key parameter behaviors. It lacks detailed parameter syntax but provides sufficient context for an agent to understand the tool's purpose and risks. Could be slightly more thorough on condition/action structures but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It mentions condition components (field/operator/value) and actions (markRead, markFlagged, delete, moveTo) and explains the matchAll flag's purpose. While not detailing every parameter format (e.g., operator enum values), it adds essential context beyond the schema such as the matchAll behavior and mandatory actions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('creating') and resource ('a new Mail rule'), and details the components (conditions and actions). It distinguishes from sibling tools like enable-rule, disable-rule, and delete-rule, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when' and 'Do not use when' conditions, naming specific alternative tools (enable-rule, disable-rule, delete-rule) and advising to use list-rules to avoid duplicates. This gives clear guidance on when and when not to use the tool.
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 must carry the full burden. It discloses that the tool returns whether Mail.app is running and sync activity detected. It does not mention side effects, rate limits, or whether it triggers any action, but for a read-only check the transparency 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences that front-load the purpose and return value. No wasted words; every sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an available output schema, the description covers all necessary context: when to use, what it returns, and how it differs from siblings. It is fully complete for a simple check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and schema description coverage is trivially 100%. The description does not need to add parameter information, and it appropriately omits any. The baseline for 0 params is 4, but the tool's simplicity and clarity merit a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks if Mail.app is running and actively syncing, with a concrete use case (explaining missing new mail). It distinguishes itself by specifying what not to use it for and naming alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' statements with specific alternatives (get-mail-stats for message counts, doctor for full diagnosis). This fully guides the agent on when to invoke this tool vs siblings.
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 fully discloses that it moves many real messages, warns to confirm destination and ids, and explains return values (counts of moved and failed). Clearly a mutation 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each with a distinct role: use case, returns, exclusions, safety. Front-loaded with main purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Includes references to sibling tools and prerequisites, return value description, and safety note. Adequate for a batch move operation with output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description clarifies that ids are message identifiers (1-100) and mailbox is destination folder, adding value to the schema. However, it does not mention the optional account parameter, which has a description in schema but could be reinforced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it moves multiple messages (1-100 ids) into the same destination mailbox, with an example of bulk archiving. It distinguishes from sibling tools like move-message (single) and batch-delete-messages (deleting).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections, referencing specific alternatives (move-message, batch-delete-messages) and prerequisite (list-mailboxes).
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 explicitly states that the tool only creates and saves a draft and sends nothing, and lists the return values, providing full behavioral clarity. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured, concise, and front-loaded with the primary usage condition. Every section serves a distinct purpose: usage, parameter guidance, return details, exclusion conditions, and safety note. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage conditions, parameter guidance for non-obvious ones, return summary, and safety assurance. Given that the output schema is available (and the description lists key return fields), and the input schema provides details, the description is sufficiently complete for an agent to decide and use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds value by explaining the intended use of `from` (alias selection after list-sending-identities) and marking `account` as deprecated, which goes beyond the schema. For other parameters, the schema descriptions (63% coverage) already provide basic info, and the return description hints at their role. This combination effectively compensates for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: composing an email for user review before sending, positioning it as the safe default for new messages. It distinguishes it from related actions (editing drafts, sending immediately) and provides usage guidance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage conditions (when to use and when not to use with specific alternative tool names), and advises on how to select a From alias, making it easy for an agent to decide.
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?
Without annotations, the description carries full burden. It discloses default dry run behavior, edits to Apple Mail plist (with backup/atomic preservation), potential creation of many smart mailboxes, scanning of ~400 messages, and performance impact on large mailboxes. Safety advice to review dry run first is included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear sections (Use when, Returns, Do not use when, Safety). Every sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given tool complexity and no annotations, the description covers usage, safety, performance, return values (with output schema present), and behavioral traits. It provides all necessary context for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds value by explaining how parameters work together (e.g., dryRun controls creation vs. proposal) and providing context beyond schema descriptions (e.g., scanning range). While not per-parameter, it enhances overall understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: auto-discovering newsletter/bulk senders in INBOXes and optionally creating smart mailboxes per sender. It distinguishes from sibling tools 'create-smart-mailbox' and 'create-mailbox' by specifying when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides 'Use when' and 'Do not use when' conditions, including alternative tools (create-smart-mailbox for known senders, create-mailbox for real folders). This gives clear guidance on tool selection.
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?
Without annotations, the description fully discloses destructive nature, backup mechanism, atomic write, and irreversibility, plus the need to quit Mail for reliability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise, well-organized into sections, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description covers purpose, usage, safety, and prerequisites completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description's usage context (e.g., 'by name', 'confirm exact name') compensates. However, it doesn't restate parameter details, which is acceptable given the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes an Apple Mail smart mailbox (virtual view) by name, and distinguishes it from siblings like delete-mailbox (real folder) and delete-message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when' and 'Do not use when' conditions, including references to alternatives and prerequisites like confirming the name with list-smart-mailboxes and quitting Mail.
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?
Discloses that the operation is read-only (retrieving inline), returns base64-encoded bytes with size and MIME type, and does not save to disk. No annotations exist, so the description fully covers behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact with front-loaded usage conditions and return value summary. Every sentence serves a purpose with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the tool has only two required parameters, the description provides complete guidance on when to use and the return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description maps the two parameters to 'message id' and 'attachmentName', adding meaning over raw schema names. However, it does not explain the format of 'id' (e.g., regex pattern), which is a minor gap for 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves attachment raw bytes inline as base64 by message id and attachment name, and distinguishes it from list-attachments and save-attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when' and 'Do not use when' with alternatives (list-attachments, save-attachment), guiding the agent on appropriate contexts.
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?
Since no annotations are provided, the description fully bears the burden of transparency. It warns that with send=true the message is sent immediately and cannot be unsent, requiring explicit user confirmation. It also describes the draft-saving behavior. No contradicting annotations exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (3 sentences) and well-structured: it starts with a usage directive, then lists parameters, then exclusions, then safety notes. Every sentence is essential and additive. No redundant or missing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, output schema exists) and the rich context from sibling tools, the description covers all necessary aspects: purpose, parameter meanings, usage boundaries, behavioral implications, and safety. The output schema handles return value documentation, so no further detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds context beyond the schema: it clarifies that 'id' is the message being forwarded, 'to' is an array of new recipients, 'body' is optional prepended text, and 'send' controls immediate send vs. draft. However, it does not detail the format constraints for 'id' (regex) or 'to' (email validation), which the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (forward) and resource (existing message), and distinguishes it from siblings like reply-to-message and send-email/compose. It uses specific verbs and lists key parameters (id, to, body, send).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (forwarding an existing message) and when not to use (replying or composing new), with references to alternative tools (reply-to-message, send-email, create-draft). Also provides guidance on using send=false to save as 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?
No annotations are provided, so the description fully carries the burden. It discloses that the tool lists smart mailboxes and returns their names and criteria summaries, implying a read-only operation without side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: when to use, what it returns, when not to use. Every sentence is necessary and front-loaded with the most important usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters and an output schema (which would explain return values), the description provides complete context: the purpose, usage cues, and a brief description of return data. Nothing is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the baseline is 4. The description adds no parameter-specific information, which is fine as none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists 'Apple Mail smart mailboxes (criteria-based virtual views)', using a specific verb and resource, and distinguishes from its sibling tool list-mailboxes which lists real folders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when:' and 'Do not use when:' sections provide clear usage guidance, including a localization issue on German macOS, and directly names the alternative tool list-mailboxes.
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 fully discloses critical behavior: sending sends real email immediately and cannot be unsent, requiring explicit user confirmation. It also mentions the draft-saving option and threading preservation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (6 sentences) and well-structured with clear sections: action, usage, parameters, returns, exclusions, safety. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of email actions and many sibling tools, the description is complete: it covers purpose, when to use, when not to use, parameter roles, safety, and return value. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 50% of parameters (send, replyAll have descriptions). The description adds meaning for id and body by context (replying to an existing message) and clarifies the effect of send and replyAll beyond their boolean labels.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'replying to an existing message by id, preserving its threading headers.' It specifies key options (replyAll, send) and distinguishes from sibling tools like send-email, create-draft, and forward-message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear usage boundaries, including naming alternative tools for other scenarios (send-email, create-draft, forward-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?
No annotations provided, so description carries full burden. It discloses key behaviors: drafts with attachments refused, Mac must stay logged in, overdue jobs run after wake/login, and the real future send. It also explains the return value structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with sections (Use when, Returns, Requirements, Do not use, Safety) and is approximately 7 sentences. Every sentence adds essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and 3 required parameters with partial schema coverage, the description covers use case, prerequisites, safety, return info, and constraints. It is sufficiently complete for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, and description adds meaning beyond schema by explaining the confirmation requirement and attachment restriction. It reinforces send_at format and confirmed semantics, adding value over the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Use when: the user explicitly asks to send one or more fully reviewed Apple Mail drafts at a future date/time', which clearly identifies the specific verb and resource. It distinguishes from sibling tools like send-draft (immediate send) and other scheduling 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides both when to use ('Use when') and when not to use ('Do not use when'), including alternatives like Mail's native Send Later mailbox. It gives clear context and exclusions.
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?
Discloses that email is sent immediately and cannot be unsent, requiring explicit user confirmation. Explains transport implications (SMTP vs AppleScript, MIME wrapping). Despite no annotations, description fully covers 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with core usage conditionals, no wasted words. Every sentence provides essential guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a sending tool: covers target, safety, alternatives, transport details, return value (confirmation). Remaining schema descriptions plus output schema (exists) provide full picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: clarifies arrays for recipients, optional attachments, transport enum descriptions. Schema covers 63% of parameters with descriptions; description fills gaps and adds usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it sends a single email now with recipients, attachments, and transport. Distinguished from siblings like create-draft, reply-to-message, forward-message, send-serial-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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when' and 'Do not use when' conditions, listing specific alternatives for review, reply/forward, per-recipient copies.
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 were provided, but the description fully covers behavioral traits: it SENDS many real emails immediately, cannot be unsent, requires explicit user confirmation, and returns a per-recipient report. This compensates for the lack of 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three short paragraphs that are front-loaded with the core use case. Every sentence adds value, no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (mail merge with placeholders, safety concerns) and the presence of an output schema (referenced but not shown), the description is complete: it covers when to use, safety, return format, and distinguishes from alternatives. Little else is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 context by explaining placeholder syntax {{Key}}, default and max delayMs, and the structure of recipient variables. It integrates parameter usage into the overall workflow, providing value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it is for mail-merge with personalized copies to many recipients, using {{Key}} placeholders. It clearly distinguishes from send-email (shared list) and create-draft (saving for review).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' conditions, naming specific alternative tools (send-email, create-draft). It also gives safety prerequisites, requiring explicit user confirmation.
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 full burden. It covers omitted fields preservation, empty array clearing, refusal of attached drafts, and safety (updates only, sends nothing). This is comprehensive behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections 'Use when', 'Returns', 'Do not use when', and 'Safety'. Every sentence adds value, and it is front-loaded with critical usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 7 parameters, large sibling set, and presence of an output schema, the description covers all essential aspects: usage scope, parameter behavior, return value, and safety. Error handling is omitted but acceptable for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (14%), so description must compensate. It explains that omitted fields are preserved, empty arrays clear recipients, and from can be identity id/email/sender. However, it does not detail subject or body beyond their existence, leaving some gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it edits an existing Apple Mail draft, selected by draft_id. It distinguishes from sibling create-draft and from editing drafts with attachments, providing a specific verb+resource+scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when' and 'Do not use when' scenarios, with alternatives like create-draft and editing drafts with attachments in Mail.app. The description gives clear context for when to invoke this tool vs siblings.
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?
Describes return fields (subject, body, rfcMessageId), the effect of preferHtml, and reliability requirements for large folders, despite no 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with 'Use when', then returns, tip, and 'Do not use'. Every sentence is necessary and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, parameter nuances, return format, and exclusions. With output schema present, it is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds important meaning beyond schema: id format, mailbox+account requirement for large folders, and preferHtml behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool reads the full body of one message given an ID, distinguishing it from search-messages and get-thread.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (reading a message by ID) and when not to use (without an ID or wanting a conversation), with a tip for large folders.
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 provided, but description fully discloses the behavioral context: why numeric IDs are needed for color flags, resolution via RFC822 Message-ID, and return format including null for unresolvable IDs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise 4-sentence description with front-loaded key use case, no unnecessary words, and clear separation between usage guidance and output specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, description covers input format, output structure, motivation, and alternative tools—complete for a single-parameter resolution tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds meaning by explaining the imap: prefix, the resolution process, and the pass-through for numeric IDs, compensating fully for lack of param documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it resolves imap: message IDs to numeric Mail.app IDs, specifically for applying flag colors. It distinguishes from sibling tools like flag-message by explaining the color limitation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when' and 'Do not use when' conditions, including when to use alternative tools (flag/move/mark for non-color operations).
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 full burden. It thoroughly discloses safety constraints (allowed roots, path separator rules, rejection behavior) and the return value (confirmation of saved file path). This is comprehensive 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with clear sections: when to use, return value, when not to use, and safety. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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), the description covers all necessary aspects: purpose, usage guidance, behavioral traits, and parameter semantics. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so description must compensate. It explains that savePath is a directory and that the file is saved as savePath/attachmentName. It also adds constraints like path separators and '..' prohibition, which are not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'writing one of a message's attachments to disk', which is a specific verb+resource. It distinguishes from sibling tools like list-attachments and fetch-attachment by specifying when each alternative should be used.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use when:' and 'Do not use when:' with clear conditions and references to alternatives (list-attachments, fetch-attachment). This provides excellent guidance for tool selection.
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 full burden. It discloses that the tool reads the macOS Contacts database directly, requires Full Disk Access, and does not need Contacts.app running or an Automation grant. This gives agents critical 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences, logically ordered: use-case, permissions, return values, exclusion. No fluff; every sentence is essential and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema, the description covers purpose, usage, permissions, parameter meaning, and return values. It is self-contained and answers likely agent questions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (only a bare 'query' string with minLength). The description compensates by specifying that the query can include name, organization, nickname, or email, adding semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool looks up a person in Contacts by name, organization, nickname, or email to find email addresses and phone numbers for composing mail. It distinguishes from the sibling tool search-messages, which searches email messages instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear guidance. It names the alternative tool search-messages for searching email, leaving no ambiguity.
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:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/yu2001-s/apple-mail'
If you have feedback or need assistance with the MCP directory API, please join our Discord server