mail-calendar-mcp

by mathewcsims

Overview Schema Related Servers Score Discussions

TypeScript

Local

Server Quality Checklist

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

Latest release: v0.1.0
Disambiguation5/5
Each tool has a clear domain prefix (calendar_ or mail_) and a distinct action on a specific resource. Overlaps are minimal and descriptions clarify any ambiguity.
Naming Consistency5/5
All tools follow a consistent snake_case verb_noun pattern with domain prefixes. The naming is uniform within and across both calendar and mail domains.
Tool Count4/5
51 tools is high but warranted for covering two full applications (Mail and Calendar). The granularity supports detailed operations, though some niche tools (e.g., mail_get_message_headers) could be merged.
Completeness5/5
CRUD operations, alarms, attendees, signatures, drafts, flags, attachments, and advanced features like availability and raw message source are all covered, with documented platform limitations.
Average 3.7/5 across 51 of 51 tools scored. Lowest: 2.4/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
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate destructiveHint=true, so the description adds no behavioral context beyond what is structured. It does not mention irreversibility, impact on existing drafts, or any side effects. With annotations present, the description should still add value but fails to do so.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise and front-loaded. However, it lacks structure (e.g., separate sections for purpose, parameters, behavior). While brevity is positive, some additional information could be included without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema) and the presence of destructive annotations, the description is too minimal. It does not explain the tool's effect thoroughly—deleting a signature but omitting whether it affects existing signatures in drafts or sent messages. Completeness is insufficient for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameter descriptions (0% schema coverage), and the tool description does not explain the 'name' parameter—its nature, format, or how to obtain it. The description provides zero added meaning for the parameter, leaving the agent blind to what value is expected.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a Mail signature, which is a specific verb-resource pair. It distinguishes from sibling tools like mail_create_signature and mail_update_signature, as it is the only delete operation for signatures. However, it lacks additional specificity (e.g., 'permanently deletes'), so it doesn't achieve a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., the signature must exist) or contexts where deletion might be inappropriate. This lack of usage direction leaves the AI agent without essential decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what annotations already provide. Annotations indicate mutation (readOnlyHint=false) but no destructive or idempotent hints. The description does not disclose permissions, reversibility, or behavior for events with no alarms.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 5 words, achieving high conciseness. However, it could be slightly expanded to include essential context without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should mention return values or confirmation. It does not. It also fails to specify which parameters are required or behavior for edge cases (e.g., event not found). Incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (uid lacks description). The tool description does not explain the uid parameter, nor does it add meaning for calendarName or calendarIndex beyond the schema. For a required parameter with missing schema description, the description should compensate, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'remove' and the resource 'every alarm from an event', which distinguishes it from sibling tools like 'calendar_add_alarm'. However, it could be more explicit about removing all alarms from a specific event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, prerequisites (e.g., event existence), or when not to use it. This leaves the agent without context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, idempotentHint=true) already signal low-risk behavior. The description adds no further behavioral context, such as handling of missing alarms or error conditions. With annotations present, the description provides minimal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but omits important details like parameter relationships and output format. It is not overly verbose, but lacks completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and absence of output schema, the description partially covers the purpose but fails to explain the return structure or behavior edge cases. It is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (two parameters have descriptions), but the tool description does not explain any parameter semantics, especially not for the required 'uid' parameter. It fails to add meaning beyond the schema, leaving gaps for the user.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists alarms of specific types (display/sound/mail) on an event. However, it does not differentiate from sibling tools like calendar_add_alarm or calendar_remove_all_alarms, though the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No prerequisites or context provided, leaving the agent to infer usage from the tool name and parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate mutability (readOnlyHint=false) and non-destructiveness (destructiveHint=false), which the description's 'Create' aligns with. However, the description adds no further behavioral context beyond what annotations already signal, such as whether creation overwrites existing signatures or requires special permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The single-sentence description is very concise, but it sacrifices essential details. It is front-loaded with the verb and object, but the brevity leads to information loss that is not compensated by brevity alone.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and the simple parameters, the description should at least hint at the content format (e.g., HTML or plain text) or return value (e.g., the created signature ID). It fails to provide sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain the parameters but fails to do so. 'name' and 'content' are not described at all; the description merely states the action. This leaves the agent without guidance on what values to provide for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new Mail signature.' uses a specific verb and resource, clearly indicating the action and object. It distinguishes the tool from sibling tools like 'mail_delete_signature', 'mail_update_signature', and 'mail_list_signatures'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., 'mail_update_signature' for modifications). There are no conditions, prerequisites, or exclusions mentioned, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating a safe read operation. The description adds no further behavioral context, such as failure modes, return format details, or whether attachments are included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, to the point, no redundancy. However, it could be more structured by explicitly listing what 'full metadata' includes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should clarify return values. It mentions 'full metadata and plaintext body' but does not define metadata scope or how the two identifier parameters interact. Incomplete for a retrieval tool with 4 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%. The description does not explain any parameters, leaving accountName and mailboxPath without descriptions. The schema provides some info for messageId and rfc822MessageId, but the description adds no extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full metadata and plaintext body for a single message, using specific verbs and resources. It distinguishes from sibling tools like mail_get_message_headers and mail_get_message_source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no mention of prerequisites or when not to use it. The description does not differentiate between the two identifier parameters (messageId vs. rfc822MessageId) or provide usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true, implying safe re-calls. The description adds that it can set both read and unread states. However, it does not disclose any behavioral details beyond that, such as response behavior or side effects. With annotations covering idempotency, the description adds minimal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence), which is concise but lacks necessary details. While brevity is good, the single sentence does not earn its place because it omits critical information. It is appropriately sized for a simple tool but not sufficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters (3 required) and no output schema, the description is incomplete. It does not explain how to specify the target message or the meaning of the required 'value' parameter. The agent lacks sufficient information to correctly invoke the tool without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanations for the parameters. For example, the 'value' boolean parameter is not clarified (true for read vs false for unread), and the difference between 'messageId' and 'rfc822MessageId' is not addressed. The description completely fails to add meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: marking a message as read or unread. It uses a specific verb 'mark' and resource 'message', differentiating it from sibling tools like 'mail_set_flagged' (which sets flagged status) and 'mail_set_flag_color' (which sets flag color).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites (e.g., message must exist), nor does it explain when not to use it. Siblings like 'mail_get_message' could be used for reading, but no comparison is made.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true, but the description adds no behavioral context beyond that. It does not disclose any side effects, authentication needs, or behavior when signature doesn't exist. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise (one sentence), but sacrifices essential details. While it is efficient, its brevity reduces usefulness. Could include more context without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and simple parameters, the description should explain return behavior (e.g., success acknowledgment), error states (if signature name not found), and whether the update is atomic. Currently it provides only the minimum purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must clarify parameters. It only mentions 'content' in passing, but does not explain that 'name' identifies the signature or what format 'content' should be (e.g., plain text, HTML). The description adds minimal value over the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Update') and resource ('an existing Mail signature's content'), and the tool name matches. It distinguishes itself from sibling tools like 'mail_create_signature' and 'mail_delete_signature' by specifying 'update' and 'existing'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., delete + create), no prerequisites (signature must exist), and no context on idempotency or error conditions. The agent is left to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, so the description aligns with a mutation operation. However, no additional behavioral details are disclosed (e.g., whether it copies attachments, how it handles recipients). The description adds minimal value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (7 words) and to the point, but it is too brief to be effective. It sacrifices necessary detail for brevity, making it less helpful than a slightly longer but more informative description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 0% schema description coverage, no output schema, and no usage guidance, the description is highly incomplete. An agent would lack critical information about parameters, return values, and when to use this tool, making it nearly impossible to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 6 parameters (cc, to, messageId, accountName, mailboxPath, additionalContent). The agent must infer parameter meaning from names alone, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and the resource 'forward draft of an existing message'. It distinguishes from sibling tools like 'mail_create_draft' (blank draft) and 'mail_create_reply_draft' (reply 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'mail_create_draft' or 'mail_create_reply_draft'. The description does not mention prerequisites or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint=true and non-readonly, but description adds no behavioral context beyond the stated action. No contradictions, but no additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence with no superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no output schema, and no parameter descriptions, the description is insufficient for the agent to understand how to use the tool correctly. Lacks details on identification of message and return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fails to explain any parameter (e.g., 'value' as boolean for flag state, or distinction between messageId and rfc822MessageId).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states action ('Flag or unflag') and resource ('a message'). It distinguishes from sibling tools like mail_set_flag_color (color) and mail_set_read_status (read status).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. The description does not provide context for appropriate use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false), idempotence (idempotentHint=true), and non-destructiveness (destructiveHint=false). The description adds no behavioral context beyond the bare verb 'rename', missing details like whether the name change is immediate or requires confirmation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no redundancy, though it could be slightly expanded for completeness without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and sparse description, it omits important context: prerequisite (calendar must exist), error conditions, and whether renaming affects events or sharing settings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% with descriptions for 'calendarName' and 'calendarIndex', but 'newName' lacks description. The tool description adds no parameter info, so it meets the baseline for adequate schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Rename an existing calendar' clearly states the action and the resource, distinguishing it from siblings like 'calendar_create_calendar' and 'calendar_delete_calendar'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites mentioned (e.g., calendar must exist), and no context on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotency and read-only nature. The description adds that the output is the 'raw header block', but lacks details on what this includes (e.g., all headers? only certain ones?) or performance considerations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence), but it is too minimal; a bit more detail (e.g., that it returns headers without body) could improve understanding without adding verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and lack of output schema, the description is insufficient. It does not explain what 'raw header block' means, how to choose between messageId and rfc822MessageId, or any edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (two of four parameters have descriptions). The tool description does not add any extra meaning to the parameters, so it fails to compensate for the missing descriptions on accountName and mailboxPath.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the 'raw header block' of a message, which is specific and distinct from siblings like mail_get_message (full message) or mail_get_message_source (raw MIME source).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives. For instance, when to use messageId vs rfc822MessageId, or why one might prefer headers over the full message, is not addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only but not destructive. Description just restates the action without disclosing behavioral traits like side effects, error cases, or requirements (e.g., event existence, permissions).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, efficient and front-loaded. No wasted words, but could be slightly more structured with bullet points.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 5 parameters and no output schema, the description is somewhat adequate but lacks context on return value, validation, or interaction with other alarms. Missing guidance on when to use calendarIndex vs calendarName.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description repeats schema information (kind types, timing) but adds no new semantic meaning beyond what the schema already provides. Schema descriptions cover 60% of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states action (Add), resource (alarm to an event), and specific parameters (type and timing). Distinguishes from sibling tools like calendar_list_alarms and calendar_remove_all_alarms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not state prerequisites, when not to use, or mention other tools for related tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only mutation (readOnlyHint: false) and non-destructive (destructiveHint: false). The description adds no behavioral context beyond that, such as what happens if a mailbox already exists or if the parent path is invalid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that is front-loaded with the key action and resource. No unnecessary words or details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with no output schema, the description covers the basic purpose but lacks details on error conditions (e.g., duplicate mailbox) or prerequisites (e.g., account must exist). It is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (33%), with only parentPath described. The description mentions 'optionally nested under an existing parent mailbox path' but does not add semantics for the required parameters name and accountName.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create'), the resource ('mailbox/folder'), and the scope ('under an account') with an optional nesting behavior. This distinguishes it from sibling tools like mail_delete_mailbox and mail_rename_mailbox.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., mail_create_draft) or when not to use it. It lacks any explicit context for selecting this tool over other creation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-destructive and non-read-only. Description adds 'recoverable — just relocates it' which reassures about safety, but omits other behavioral aspects like effect on flags or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise, single sentence with no wasted words. Front-loaded with main action. However, could benefit from slightly more detail without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters and no output schema, the description is sparse. Does not explain what happens if mailboxes don't exist, whether messageId is optional, or return value. Incomplete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (destAccountName) has a description in the schema; the tool description adds no parameter details. Schema coverage is very low at 17%, and the description does not compensate by explaining required or optional parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Move a message to a different mailbox' with the verb, resource, and destination. Includes clarification 'recoverable — just relocates it' to distinguish from deletion, which is relevant given siblings like mail_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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for moving messages (not copying or deleting), but no explicit guidance on when to use versus alternatives like mail_copy_message or when not to use. Lacks context clues 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutation (readOnlyHint=false), idempotent, non-destructive. Description adds that -1 clears the flag. However, it does not disclose return behavior, authentication needs, or side effects (e.g., whether existing flag is replaced). With idempotentHint=true, the description is adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no waste. Front-loaded with verb and resource. Could potentially add a brief note on parameter identification without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 5 parameters (3 required), no output schema. Description only covers one parameter's semantics. For a mutation tool, more context is needed on how the flag is identified (via messageId or rfc822MessageId) and the effect of setting an existing flag. Insufficient for effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the description must explain parameters. It partially explains colorIndex (range and -1 meaning) but says nothing about messageId, accountName, mailboxPath, or rfc822MessageId. For required parameters, the description omits critical identification details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Set' and resource 'colored-flag index', clearly distinguishing from sibling 'mail_set_flagged' which likely toggles a boolean flag. The range and clearing behavior are specified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly describes usage by explaining -1 clears and 0-6 selects colors, but does not explicitly state when to use this tool vs alternatives like mail_set_flagged or mail_set_read_status. No when-not-to-use or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false) and non-idempotent, non-destructive. Description adds context about experimental status and potential platform limitations, which is helpful but does not elaborate on side effects or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose, second adds critical caution. Front-loaded with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and simple operation, description lacks details on return values, error states, prerequisites (e.g., must have event), and idempotency. Does not fully inform agent for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only calendarName and calendarIndex have descriptions). The description clarifies that email is the attendee identifier, but does not explain uid or add details beyond schema for other parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action: 'Remove an attendee (by email) from an event.' It specifies verb and resource, and distinguishes from sibling tool calendar_add_attendee.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides caution about experimental nature and failure handling, but does not give explicit when-to-use or when-not-to-use guidance compared to alternatives like calendar_update_event.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=false, but the description clarifies the non-destructive nature by specifying the original is left in place, adding context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence) but under-specified for a tool with 6 parameters, lacking necessary detail to guide correct invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, no output schema, and 0% schema coverage, the description is insufficient to fully understand the tool's behavior, parameter roles, and return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description does not explain any of the 6 parameters (e.g., accountName, mailboxPath, messageId), failing to add meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool copies a message to a different mailbox and explicitly notes that the original remains in place, distinguishing it from the sibling tool 'mail_move_message' which moves the 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description 'leaving the original in place' directly contrasts with a move operation, implicitly guiding the agent to use this tool when the original should be preserved versus using mail_move_message when it should be removed.
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 the side effect of creating a draft and the prefilling behavior, which adds value beyond the minimal annotations. However, it does not detail error handling, permission requirements, or behavior for invalid message 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core action. Every word contributes to the purpose without extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters and the absence of an output schema, the description lacks essential context such as parameter semantics, prerequisites, and side effects beyond draft creation. The agent may struggle to use the tool correctly without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 20% schema description coverage, the description should compensate by explaining parameters like mailboxPath, replyToAll, and accountName, but it does not. Only additionalContent's purpose is implied through the description of prefilling quoted content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create a reply draft), the target (existing message), and the prefilled content (quoted original). It effectively distinguishes from sibling tools like mail_create_draft and mail_create_forward_draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for replying with quoted content but does not explicitly state when to use this tool versus alternatives such as mail_create_draft or mail_create_forward_draft. No guidance on when not to use it is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set destructiveHint=true, indicating destructive nature. Description adds 'IRREVERSIBLE', 'cannot be undone', and 'bypassing/purging Trash', providing extra behavioral context beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Highly concise, single sentence front-loads the irreversible nature and confirm requirement. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite complexity (5 params, no output schema), description only covers the confirm parameter. Crucial details like message identification (messageId vs rfc822MessageId) and mailbox specification are missing, making it incomplete for safe execution.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet description only explains the 'confirm' parameter. Other parameters (accountName, mailboxPath, messageId, rfc822MessageId) are left unexplained. Description fails to compensate for lack of schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (permanently delete) and resource (message), with specific verbs and scope. Distinguishes from siblings like mail_delete_message by noting bypassing/purging Trash and irreversibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies when to use (irreversible deletion) and mentions confirm requirement, but lacks explicit when-not to use or comparison to alternatives like mail_delete_message. Some guidance from context but not comprehensive.
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?
Description discloses verification after creation and known flaky spots, adding value beyond annotations (which only set readOnlyHint=false). 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with clear front-loading: purpose first, then crucial behavioral note. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description is functional but minimal; lacks output details and comprehensive guidance for a 9-parameter tool. Schema partially compensates, but overall completeness is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 56% (below high threshold), and the description adds no parameter explanations. Relies heavily on schema, which has gaps (summary, location, alldayEvent, description undocmented).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new event', which is a specific verb+resource. It adds verification behavior, distinguishing it from siblings like calendar_update_event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., calendar_update_event) or when not to use it. The description only implies use for creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it warns about historical unreliability and explains the verification step. Annotations indicate non-read-only and non-destructive, which aligns. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with clear purpose, followed by essential behavioral context. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing return value information (no output schema), prerequisites, error cases, and side effects like invitation sending. The verification behavior is noted but overall completeness is low for a 4-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% with descriptions only for calendarName and calendarIndex. The description does not explain required parameters 'uid' and 'email', leaving them undocumented. It adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add), the resource (attendee), and method (by email). It distinguishes itself from sibling tools like calendar_remove_attendee by specifying the addition operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about historical unreliability and verification behavior, but lacks explicit guidance on when to use this tool versus alternatives like calendar_add_alarm or prerequisites such as event existence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds the useful detail that nested subfolders and unread counts are included, which is behavioral context beyond the structured 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, front-loading the key action and resource. It is efficient, but could potentially include minimal parameter context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with clear annotations, the description covers the main purpose and key inclusions. However, it lacks parameter guidance and usage context, leaving some gaps (e.g., error handling, performance).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description does not explain the required 'accountName' parameter beyond its name. It fails to specify format, source, or constraints, leaving the agent without guidance on how to populate it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List', the resource 'mailbox/folder tree', and specifies that it includes 'nested subfolders and unread counts'. This distinctly separates it from sibling tools that list drafts, accounts, or signatures.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to view the folder structure, but it does not provide explicit guidance on when to use it versus alternative list tools, nor does it exclude any scenarios. Usage is clear but not differentiated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint. The description adds behavioral context beyond annotations: optional filters, pagination details. No contradiction, but could mention null results or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, well-structured with no wasted words. Front-loads the core purpose and key behavioral details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description lacks completeness: no info on return format, ordering, error handling, or how filters combine. For a search tool with 8 parameters, this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description mentions some parameters (read status, flagged status, subject/sender substring, limit) but not all 8, notably missing required parameters (accountName, mailboxPath) and offset. Insufficient compensation for schema lack.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (search/list), resource (messages in a mailbox), and specific filters (read status, flagged status, subject/sender substring). It differentiates from sibling tools like mail_get_message or mail_list_mailboxes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions pagination behavior (default limit 50, max 500) which is a usage guideline, but does not explicitly state when to use this tool versus alternatives or any exclusions. The guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no guidance (readOnlyHint=false, destructiveHint=false), so the description must carry the burden. It states 'update fields' indicating a mutation, but does not disclose side effects (e.g., does it replace all fields or merge?), required permissions, or what happens if the session is not open. Some behavioral context is provided but insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence of 11 words, front-loaded with the action 'Update fields'. No redundant words, very concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too brief given the tool's complexity: 8 parameters (including nuanced ones like fromAddress with multi-account fallback and attachmentPaths with unverified insertion), no output schema, and no mention of return value or error conditions. Essential context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 38% (low). The description only lists subject/content/recipients, ignoring fromAddress and attachmentPaths which have important details in the schema. It does not add meaning beyond what the schema already provides for the mentioned parameters, and fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Update), the resource (fields of an open draft compose session), and the identifier (composeSessionId). It distinguishes from sibling tools like mail_create_draft or mail_delete_draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear that this tool is for updating an existing draft session. While it doesn't explicitly state when not to use it or provide alternatives, the context of sibling tools provides differentiation. Could be improved by mentioning prerequisites like composeSessionId validity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it's read-only and idempotent. The description adds a useful behavioral note about the null email entry for the organizer, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action, no wasted words. The note is appended as a second sentence, which is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not explain the return format or fields. It covers purpose and one behavioral caveat but lacks completeness for an agent, such as what the output looks like or that it returns a list of attendee objects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not add any parameter-specific details beyond the schema. Schema coverage is 67%, but the description rehashes no parameter descriptions. The note about null email is not about a parameter but about result behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('attendees on an event'). It is concise and unambiguous, with no sibling tool that performs the same function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. However, the context is implied: when you need to see attendees of an event. No guidance on when not to use it.
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?
Discloses that the tool verifies changes by re-reading and highlights recurrence edits as a known flaky area, adding behavioral context beyond annotations. Annotations are minimal, so description carries burden well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no fluff. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a mutation tool but lacks details on success/failure behavior, parameter interactions, and return values. No output schema provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 30%, but description does not add meaning for the majority of parameters. Only recurrence gets extra context. Does not compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Update fields on an existing event by uid', specifying the action, resource, and identifier. Distinct from sibling tools like create or delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions recurrence edits as flaky and that the tool verifies changes, but does not explicitly state when to use this tool versus alternatives (e.g., delete and recreate). No exclusions given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds important context that the deletion is recoverable via Trash, which goes beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, front-loading the verb 'Delete' and key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with no output schema, the description mentions recoverability but does not clarify return values, error conditions, or prerequisites like whether the draft must exist, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage for parameters, and the description does not explain what accountName or draftMessageId represent, nor provide formatting guidance, forcing reliance on parameter names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a persisted draft from the Drafts mailbox, and explicitly compares it to mail_delete_message, distinguishing it from sibling deletion tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for draft deletion and mentions similarity to mail_delete_message, but does not explicitly state when to use this tool versus alternatives like mail_permanently_delete_message.
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?
Adds value beyond annotations by specifying recoverability (stays in Trash until emptied). No contradiction with destructiveHint=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise (two sentences) with front-loaded verb, but lacks parameter guidance which would improve structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite short description, it fails to cover parameter usage and identification of messages. Given no output schema and 4 params, more detail is needed for agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and description provides no parameter explanations. Four parameters exist (messageId, accountName, mailboxPath, rfc822MessageId) but are not described.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (move to Trash) and adds recoverable behavior, distinguishing it from permanent deletion tool (mail_permanently_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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies when to use via recoverable hint, but does not explicitly mention alternatives or when not to use it. Sibling tools exist, so more guidance would help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds limited behavioral context; the 'recursive' detail is useful but not critical for safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence achieves complete purpose statement with no superfluous words, appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple parameters, annotations, and no output schema, the description sufficiently covers the tool's role and key behavior (recursive breakdown); lacks output shape explanation but that is acceptable without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the single parameter with adequate description; the tool description does not add further semantic details beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description specifies verb 'Get', resource 'unread message counts for an account', and includes distinctive detail 'broken down by mailbox (recursive)', clearly distinguishing from sibling tools that list mailboxes or accounts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied but not explicitly contrasted with alternatives; no when-to-use or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety and side-effect aspects. The description adds that it lists 'persisted drafts' specifically, but does not provide additional behavioral details like pagination or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that directly states the tool's purpose without any unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (list drafts with one parameter, no output schema), the description is mostly complete. It could optionally mention that the return value is a list of draft messages, but the current description suffices for basic understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, leaving the single parameter 'accountName' undefined. The description's phrasing 'in an account's Drafts mailbox' implies that accountName identifies the account, providing essential context that the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'persisted drafts in an account's Drafts mailbox', which unambiguously defines the tool's function. This distinguishes it from sibling tools like mail_create_draft or mail_delete_draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as mail_search_messages or mail_list_mailboxes. There is no mention of prerequisites, typical use cases, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description discloses the verification step and known flakiness in Calendar's scripting dictionary, providing valuable behavioral context that helps the agent anticipate potential issues.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two sentences that front-load the purpose and add a meaningful detail. Every word serves a purpose, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple creation tool with one parameter, the description covers the core function and a behavioral nuance. However, it omits any mention of return value or error conditions, which would be helpful for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage for the 'name' parameter, and the description does not explain its meaning or usage. The description fails to compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create a new calendar', specifying the verb and resource. It distinguishes the tool from sibling tools like calendar_delete_calendar and calendar_rename_calendar, which handle different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating a calendar but does not explicitly provide guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds that the UID is a 'stable iCalendar identifier', providing context about identifier stability. No mention of error handling or missing event 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Front-loaded key information: action, resource, identifier type. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, and the description does not explain the return format or behavior when the event is not found. For a read-only tool, this is a gap; however, annotations indicate idempotent read, mitigating some completeness concerns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, with calendarName and calendarIndex having descriptions. The tool description adds minimal value: it notes the UID is from calendar_list_events output, but doesn't elaborate on format or required constraints. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a single event by its UID, a specific identifier. It distinguishes from sibling list/search tools by specifying the unique identifier method.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions using the UID from calendar_list_events output, implying when to use it (when you have a UID). However, it does not explicitly state when not to use it or compare to alternatives like calendar_search_events.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations readOnlyHint, idempotentHint, openWorldHint are present. The description adds context: the date range cap is to avoid hanging from multi-year recurrence expansion, and pagination is indicated. It also explains calendarIndex for disambiguation. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with key information, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the critical aspects: required bounded range, max range reason, pagination. It lacks details about return values but given readOnlyHint and no output schema, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%. The description adds the 366-day cap for startDate/endDate, but does not elaborate on limit/offset behavior or calendarIndex beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists events with a bounded date range and pagination. The verb 'List events' and resource 'calendar' are specific. It distinguishes from sibling tools like calendar_search_events and calendar_get_event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description emphasizes that the date range is required (max 366 days) and mentions pagination, but it does not explicitly state when to use this tool versus alternatives like calendar_search_events. There is no when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe, idempotent reads. The description adds value by noting the 366-day range cap and advising to narrow it for large calendars, which are behavioral traits beyond what annotations provide. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 14 words. It conveys the core purpose and constraints without redundant or extraneous information. Every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is read-only with 5 parameters (3 required) and no output schema. The description covers the key search constraints but omits details about the return format (e.g., list of matching events) and any pagination or sorting. It is mostly complete but could be slightly more explicit about what the search returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, which is high, so a baseline of 3 is appropriate. The description does not add parameter-level meaning beyond what the schema already covers (e.g., endDate cap is mentioned in schema). No new semantic enhancements for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a search of events by summary text within a bounded date range. The verb 'Search' and resource 'events' are specific, and the constraints (summary text, date range) distinguish it from sibling tools like calendar_list_events (which lists all events) and calendar_get_event (single event by ID).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the tool is for searching by text with a date range, but it does not explicitly state when not to use it or mention alternatives. The context of 'bounded date range' implies when to apply, but no guidance on exclusion or comparison with sibling tools is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent hints. Description adds that it returns name, size, and download state, adding value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 12 words, front-loaded with action and scope, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks details on return structure (only mentions fields), no pagination or error info. With no output schema, more context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only messageId and rfc822MessageId have descriptions). The main description does not compensate by explaining accountName or mailboxPath, leaving ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states 'List attachments on a message' with a specific verb and resource, and clarifies 'without downloading them', distinguishing it from sibling 'mail_get_attachment'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly indicates when to use (list without download) but lacks explicit when-not-to-use or alternatives. Sibling context helps differentiate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it returns 'name + content' but does not disclose ordering, pagination, or any potential limits. Without an output schema, more detail on response structure would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, efficient, front-loaded with action and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description could elaborate on the response format beyond 'name + content'. However, for a simple list tool with clear sibling differentiation, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are 0 parameters, and schema coverage is 100% (empty). The description correctly adds no parameter information because none exist. Baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'Mail signatures', and specifies the returned fields 'name + content'. It is distinct from sibling tools like mail_create_signature or mail_delete_signature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, but it is the only list tool for signatures among siblings, making its use implied. Lacks conditions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: it explains the computation is local from calendar_list_events-equivalent data and that Calendar.app has no native free/busy API. This complements the readOnlyHint and idempotentHint annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose. Every sentence adds value: the first defines the operation and constraints, the second provides important implementation context. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers purpose and computation method, it lacks details on the output format (expected return value for free/busy gaps) and parameter format examples. With no output schema and three required params, the description could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'bounded date range (max 366 days)' for startDate and endDate, adding meaning beyond the schema, which lacks descriptions for those parameters. However, it does not specify date format or the structure of the calendars array objects, and schema coverage is only 33%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'compute', the resource 'free/busy gaps across one or more calendars', and the constraint 'bounded date range (max 366 days)'. It distinguishes from sibling tools by noting it is locally computed and not a native free/busy API, which is unique among calendar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use (need free/busy gaps) and a caution that it is locally computed, not native. It does not explicitly list alternatives, but the limitation helps avoid misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, which are consistent with 'get details'. The description does not add extra behavioral context, but with strong annotations 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence with no wasted words. The key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and good annotations, the description covers the basic purpose and input, but omits any description of the return value or output format, which an agent would need to know for full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the only parameter 'accountName' has a clear description. The tool description merely echoes 'by name', adding no new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('get details'), the resource ('a single Mail account'), and a key parameter ('by name'). It effectively distinguishes from siblings like mail_list_accounts and mail_get_account_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates when to use (when needing details for one specific account), but does not provide explicit when-not or alternative tools. However, the context from sibling names helps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only and idempotent. The description adds value by specifying the raw format (RFC822) and that it includes headers and MIME body, but doesn't disclose potential issues like large message handling. With annotations present, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose and use case. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters and no output schema. The description covers the purpose and use case but doesn't describe the return format in detail (e.g., whether it's plain text or binary). Given the moderate complexity and presence of annotations, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only messageId and rfc822MessageId have descriptions). The description does not add any parameter-level details for the undocumented accountName and mailboxPath parameters, so it fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the full raw RFC822 source (headers + MIME body) and distinguishes from siblings like mail_get_message and mail_get_message_headers by specifying the raw source extraction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use it ('to extract HTML bodies or inspect MIME structure'). It doesn't mention when not to use it or alternatives, but the purpose is clear enough to differentiate from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds a critical behavioral caveat about platform limitations and unreliability, enhancing the agent's understanding of potential errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no extraneous content; the first states purpose, the second provides a crucial warning. Information is front-loaded and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple rename operation with three required parameters and no output schema, the description covers the essential operation and a major caveat, though it omits details like return value or idempotency (already in annotations).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 33% schema description coverage (only 'path' is described), the description fails to explain 'accountName' and 'newName,' leaving the agent with little additional meaning beyond the tool name and schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Rename an existing mailbox/folder,' specifying the verb 'rename' and the resource 'mailbox/folder,' distinguishing it from siblings like mail_create_mailbox and mail_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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes unreliability via AppleScript/JXA and advises expecting a PLATFORM_LIMITATION error and fallback to manual renaming, providing guidance on when this tool may fail, though it does not explicitly name alternative 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?
The description goes beyond annotations by adding: '[IRREVERSIBLE]' explicitly, and a known limitation about unreliability with cloud accounts. The destructiveHint annotation is true, but the description adds concrete context about failures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence that front-loads the most critical information: irreversibility, permanence, and known limitations. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature, the description covers essential behavioral context (permanence, confirm requirement, failure modes). No output schema exists, but return values are not critical here. One could argue a brief note on typical return on success/failure would improve completeness, but it's already strong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (33%), but the description compensates by specifying that confirm must be true (critical for destructive action). It does not elaborate on accountName or path, but the example '["INBOX"]' in schema provides some context. The added value of the confirm requirement is significant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Permanently delete a mailbox/folder and everything in it.' The wording is specific and leaves no ambiguity. It also distinguishes itself from related tools by emphasizing permanence and irreversibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a key usage requirement: 'Requires confirm:true.' It also alerts about potential failures with cloud-synced accounts. However, it does not explicitly mention alternatives or when to avoid using this tool, relying on the context of the warning instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool refuses large attachments, which is valuable beyond annotations. Annotations declare readOnlyHint=false and destructiveHint=false, consistent with saving a file. However, it could mention overwrite behavior or error handling for missing files.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. First sentence states purpose and method; second adds critical behavioral guidance. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers core purpose and a key constraint (size limit). However, it lacks explanation of required parameters (accountName, mailboxPath, destDirectory) and does not specify return values (no output schema). For a tool with 6 parameters and no output schema, more context would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 2 of 6 parameters have schema descriptions (messageId and rfc822MessageId). The description adds minimal meaning: it clarifies that 'index' comes from mail_list_attachments. It does not explain accountName, mailboxPath, or destDirectory. For a tool with low schema coverage (33%), the description should compensate more.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Save one attachment (by its index from mail_list_attachments) to a local directory.' It specifies the action (save), resource (attachment), and method (by index from a previous list). This distinguishes it from sibling tools like mail_list_attachments or mail_get_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Refuses attachments that would need more than a reasonable size — check size via mail_list_attachments first for anything large.' This tells the agent when to use this tool (for attachments within size limits) and when to pre-check using another 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?
Annotations already declare read-only and idempotent. The description adds value by specifying the returned fields (type, enabled state, email addresses), which aids agent understanding of the output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff, front-loaded with the core action. Highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter tool with no output schema, the description adequately covers return information (type, enabled state, email addresses). Could mention account names/identifiers, but sufficient for agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100% trivially. Baseline 4 for zero-parameter tools. Description does not need to add param details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'Mail accounts', and specifies the details returned (type, enabled state, email addresses). It distinguishes from sibling tools like mail_get_account by indicating it lists all accounts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when listing all accounts, but does not explicitly mention when not to use it or provide alternatives like mail_get_account for a single account. Guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe, read-only behavior. The description adds value by explaining what data is returned (index, writability, description) and the scope (all accounts), which is not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core purpose ('List every calendar') and immediately provides actionable context. Every part of the sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless list tool, the description is complete: it states what is listed, across what scope, and what fields are returned. Missing details like pagination or limits are minor given the tool's simplicity and the presence of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0 parameters with 100% coverage. The description compensates by explaining what the output contains (index, writability, description), which is valuable for understanding the return value even without an output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'list' and resource 'every calendar across all accounts' with details on what is returned (index, writability, description). It distinguishes this tool from siblings like calendar_list_events by focusing on calendars and providing the index for use with other calendar_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states to use this tool 'when names are ambiguous' for calendar_* tools, providing clear context. However, it does not explicitly mention when not to use it or alternatives beyond this hint, but the context is sufficient for an AI 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?
Annotations indicate readOnlyHint=false and destructiveHint=false, so the description's mention of creating a draft (mutation) aligns. The description adds valuable behavioral details: the session ID lifespan, unverified attachment insertion, and the fromAddress fallback behavior that could lead to unintended account selection. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with no extraneous information. It front-loads the primary action and then efficiently covers key details (session ID, lifespan, fromAddress requirement, attachment limitation) in just a few sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and 43% schema description coverage, the description covers the most critical aspects: what the tool returns (composeSessionId), its limited lifespan, and important parameter caveats. It could explicitly state the return format, but the provided info is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 43% schema description coverage, the description compensates by adding meaning beyond the schema. It explains that fromAddress is required and describes the fallback behavior, clarifies that content is plaintext, and notes that attachmentPaths insertion is unverified. This provides essential context for proper parameter use.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new draft email saved to the account's Drafts mailbox. It identifies the returned composeSessionId and explicitly distinguishes from siblings like mail_send_message and mail_update_draft by noting the session ID's validity until Mail.app restarts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to create a draft and obtain a composeSessionId) and provides critical context about the session ID's temporary nature. It also warns about the fromAddress fallback in multi-account setups, guiding proper usage. It does not explicitly state when not to use it, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, and the description reinforces with '[IRREVERSIBLE]'. It also states 'Requires confirm:true', which is a key safety behavior. No contradictions with annotations. However, it does not detail side effects like irreversible deletion or behavior on failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: one sentence with the core action, two usage modes, and a key requirement. No filler or redundant explanation. Front-loads the irreversible nature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the two primary usage patterns and the confirm requirement, which are the most critical aspects. It omits cc, bcc, and attachment parameters, but the schema has some descriptions for those. Given the tool's complexity (9 params, two modes), the description is adequate but could be slightly more comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the schema by explaining the two parameter groups (composeSessionId vs to/subject/content) and warning about fromAddress fallback behavior. The schema only describes 3 of 9 parameters, so the description compensates partially but does not cover cc, bcc, or attachmentPaths details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with '[IRREVERSIBLE] Send an email', clearly stating the action. It explains two modes (send existing draft or compose and send in one call), which distinguishes it from sibling tools like mail_create_draft and mail_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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use each of the two modes: use composeSessionId to send a draft, or pass to/subject/content to compose and send. It also requires confirm:true, which is a critical condition. It does not mention when not to use this tool, but the modes cover the main scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral traits: irreversibility (IRREVERSIBLE), known unreliability via scripting, expect PLATFORM_LIMITATION error, and fallback manual deletion. This goes well beyond the annotations (destructiveHint=true) by adding concrete failure scenarios and mitigation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with 'IRREVERSIBLE', and includes essential warnings and usage notes. It could be slightly more structured (e.g., separate lines for each point), but remains efficient and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description covers the core action, side effects, parameter nuances, and fallback behavior. Missing details like exact return value or alternative error handling, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the input schema: it clarifies that confirm must be set to true ('Requires confirm:true') and that calendarIndex is for disambiguating duplicate names. With schema coverage at 67%, this compensates for the missing description on the confirm parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Permanently delete a calendar and everything in it,' which clearly identifies the action and resource. It distinguishes from sibling tools like calendar_delete_event by focusing on calendar-level deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context: requires confirm:true and suggests using calendarIndex for disambiguation when names are duplicated. It also warns about potential PLATFORM_LIMITATION errors and recommends a manual fallback. However, it does not explicitly contrast when to prefer this over other deletion 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?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds context about checking app status and Automation responsiveness. However, without an output schema, it does not specify the exact return format (e.g., boolean or status text), slightly reducing transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both essential: first states purpose, second gives usage guidance. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple (no parameters, annotations cover safety/read-only). The description adds critical usage context (when to call it) and is complete for the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist in the input schema, and schema description coverage is 100%. Baseline for 0 parameters is 4, and no additional description is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Check' and clearly identifies the resource as 'Calendar.app's running status'. It is distinct from sibling tools, which are all data operations, by being a pre-operation health check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use this before other Calendar tools' and why: 'to distinguish app not running/asleep from a genuine data error'. This provides 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?
Annotations already provide readOnlyHint=true and idempotentHint=true. The description adds context about the limitations of AppleScript/JXA for rule automation, and mentions the output includes name and enabled state, which is useful beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences with no fluff. The core purpose appears first, followed by important limitations and an alternative suggestion. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description states what is returned (name and enabled state). Combined with annotations and absence of parameters, the description is fully sufficient for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, and schema description coverage is 100%. The description has no need to explain parameters. Baseline score of 4 is appropriate for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'List existing Mail rules (name, enabled state)', clearly indicating the action (list) and the resource (rules). It distinguishes this tool from sibling mail tools by specifying rules specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states it is read-only and that creating/editing rules is not achievable via AppleScript/JXA, guiding the agent to use the Mail.app UI instead. This clarifies when to use and when not to use.
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 irreversibility, platform limitation for recurring events, and that the tool returns PLATFORM_LIMITATION instead of false success. This goes beyond the destructiveHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured. Front-loaded with [IRREVERSIBLE] warning, followed by purpose, limitation, and requirement. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key behaviors: irreversible, confirmation needed, recurring event handling, and platform limitation. No output schema, but description adequately explains expected outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds value beyond schema by explaining that confirm must be true, and providing guidance on calendarName vs calendarIndex for disambiguation. 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: delete an event by uid. It distinguishes from sibling tools like calendar_delete_calendar by highlighting the recurring event limitation, which is specific to this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (to delete a single event) and when not to (for recurring events, use Calendar.app). Also specifies requirement: confirm must be true.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context about checking if the app is running and responding, which enhances understanding beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and every word adds value. It is highly concise and structured effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and a simple purpose, the description is complete. It includes usage context and error differentiation, leaving no gaps. No output schema is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and schema description coverage is 100%. The description does not need to add parameter info. Baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Check' and the resource 'Mail.app', and it distinguishes itself from sibling tools by indicating it should be used before other mail tools to verify app status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool before other Mail tools to distinguish 'app not running/asleep' from genuine data errors, providing clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

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

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

Card Badge

Copy to your README.md:

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

Score Badge

Copy to your README.md:

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

Latest Blog Posts

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

MCP directory API

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

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

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