pyfastmail-mcp

Server Quality Checklist

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

Latest release: v0.3.2
Disambiguation5/5
Tools are clearly grouped by domain (calendar_, contacts_, files_, mail_) with distinct actions (create, delete, get, list, update, etc.). Overlaps like mail_mark_email_read and mail_manage_email_labels are clarified by descriptions, making each tool's purpose unambiguous.
Naming Consistency5/5
All tools follow a consistent verb_noun pattern with domain prefix (e.g., calendar_create_event, mail_send_email). Even longer names like mail_manage_email_labels keep the convention, ensuring predictability.
Tool Count4/5
48 tools is high but well-justified by the breadth of Fastmail's capabilities (mail, calendar, contacts, files). The organization into clear domains prevents confusion, though the sheer number may feel heavy.
Completeness5/5
Mail tools cover sending, receiving, searching, labeling, identities, masked emails, attachments, importing/exporting, forwarding, replying, and more. Calendar and contacts have full CRUD. Files have basic operations. No obvious gaps for the stated domains.
Average 3.8/5 across 48 of 48 tools scored. Lowest: 2.6/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 2 commits in the last 12 weeks
- Last stable release on April 8, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states 'Create a new contact card' and lists parameters, without describing side effects, validation rules, limits, or what the response contains. The output schema exists but is not referenced.
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 concise but the structure is suboptimal: an unformatted list under 'Args' without clear separation. It could be more readable with a list format and clearer headings.
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 all parameters are optional, the agent needs to know if an empty contact is allowed, or what minimal fields are recommended. No guidance on address_book_ids (e.g., default behavior if omitted). The output schema exists but is not leveraged to explain return data.
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%, meaning the description adds minimal meaning beyond the parameter names. For example, 'phones: List of phone numbers' is too vague—no format, constraints, or examples. With 6 optional parameters, richer semantics are needed.
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 'Create a new contact card' with a verb and resource. It lists the parameters, which helps understand what fields can be set. However, it does not explicitly differentiate from sibling tools like contacts_update_contact beyond the verb 'create'.
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 best practices mentioned. The description does not address whether certain parameters are required, or what happens when a contact with the same name or email already exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only mentions renaming by ID, but does not disclose side effects, permissions required, reversibility, or any constraints on the new name. This is insufficient for safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the main action. It is efficient, but could be slightly expanded with parameter guidance without harming 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 simplicity of the tool (2 required params, output schema exists), the description is too sparse. It omits crucial context like how to obtain the mailbox ID, valid name formats, error cases, and output expectations, leaving the agent underinformed.
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 0% description coverage, and the description does not elaborate on mailbox_id or new_name. It fails to explain the format, source, or constraints of these parameters, adding no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (rename) and the resource (mailbox, with parenthetical clarification as folder or label). It is unambiguous and specific, though it does not need to distinguish because there is no sibling rename tool.
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, no prerequisites (e.g., mailbox must exist), and no context about when not to use it. The agent must infer entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It mentions preserving content and optional introductory text, but omits details about attachment handling, cc/bcc, whether the original is quoted, or any other side effects. This is inadequate for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a two-sentence overview followed by a parameter list. It is front-loaded with the main action and readable. Minor improvement: integrating parameter descriptions into prose could enhance flow.
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 absence of annotations, presence of output schema (unexplained), and 4 parameters, the description is incomplete. It does not explain return value, error conditions, recipient limits, or handling of attachments. The bare minimum is met but significant gaps remain.
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 0%, so the description must compensate. It lists the four parameters with brief explanations (e.g., 'to: List of recipient email addresses', 'identity_id: Sender identity ID; auto-selects first if omitted'). While functional, it adds minimal value beyond parameter names; for example, 'email_id' lacks context like which mailbox.
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 'forward' and the resource 'email', and explains that it preserves original content. This distinguishes it from sibling tools like mail_send_email (compose new) and mail_reply_to_email (reply).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool over alternatives (e.g., mail_reply_to_email, mail_send_email) or mention any prerequisites or limitations.
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?
Lack of annotations places full burden on description, but it only states 'delete' without clarifying permanence, soft delete, cascading effects, or error 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?
Extremely concise with two lines, front-loaded with the main action, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with output schema presumed, but missing details like error handling, idempotency, and behavior for invalid IDs.
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 0% schema description coverage, the description adds minimal value beyond the schema by restating 'List of ContactCard IDs to delete', failing to explain format or constraints.
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' and the resource 'contacts by ID', distinguishing it from sibling contacts tools like create, get, list, query, and update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, nor any prerequisites (e.g., valid contact IDs) 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should disclose behavioral traits. It mentions JSON patch and partial update, but fails to cover error handling, required permissions, side effects, or behavior when contact_id is invalid. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a brief introductory sentence and a bullet list of parameters. It is front-loaded and contains minimal superfluous text, though it could be even more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all 7 parameters and the update logic. However, it omits details about return values (though output schema exists), error conditions, and prerequisites. For a tool with 7 parameters and no annotations, more context is warranted.
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, but the description explicitly defines each parameter (contact_id, name, emails, etc.) with clear meaning, adding value beyond the schema. This compensates well for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update an existing contact card via JSON patch') and resource, using a specific verb. It does not explicitly differentiate from sibling tools like create or delete, but 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes that only provided fields change and omitted fields are left as-is, which is a usage hint. However, it lacks explicit guidance on when to use this tool over alternatives or when not to use it (e.g., for creating new contacts).
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 lacks behavioral details such as whether intermediate directories are created, error handling on existing folders, or authentication requirements. With no annotations, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey the tool's purpose and parameter, with the key action front-loaded and no extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple folder creation tool with one parameter, the description is minimally adequate but lacks completeness in explaining behavior (e.g., success/error responses, side effects). The existence of an output schema mitigates some need but is not described.
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 adds context to the 'path' parameter with an example, but does not specify formatting, allowed characters, or path constraints beyond the schema's basic type and required flag.
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 folder on Fastmail Files (WebDAV)', providing a specific verb and resource. It distinguishes from sibling file tools like files_upload, files_delete, etc., 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives (e.g., files_upload for content, files_move for renaming). There is no mention of prerequisites 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?
With no annotations, the description carries the full burden of behavioral disclosure. It mentions the move operation and case-insensitivity but omits important details like whether the operation is a true move (copy+delete) or just reassignment, what happens on failure (e.g., invalid IDs), and any permission requirements. The minimal description does not adequately replace missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences plus an Args list. Every word serves a purpose, with no redundant phrases. It is front-loaded with the core action and efficiently details parameters. This is an ideal level of conciseness for a simple two-parameter tool.
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 (2 params, likely simple output), the description covers the basic usage. However, it lacks details on return values (despite an output schema existing), error conditions, and side effects (e.g., whether the source mailbox changes). For a complete picture, the agent may need to infer from the output schema or examples, which are not provided.
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 0%, so the description must add meaning. It explains email_ids as 'JMAP email IDs' and mailbox_name as 'case-insensitive', which adds value beyond the schema titles. However, it does not specify constraints like maximum number of IDs, format of JMAP IDs, or what happens if the mailbox does not exist. It partially compensates but could be more thorough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly and specifically states the tool moves one or more emails to a mailbox identified by name. It uses a precise verb ('Move') and resource ('emails'), and it distinguishes itself from sibling tools like mail_archive_email (archives) and mail_manage_email_labels (manages labels) by focusing on moving to a named 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 vs alternatives. It does not state prerequisites (e.g., emails must be in some mailbox) or when not to use it (e.g., for archiving, use mail_archive_email). This leaves the AI agent to infer context from the tool 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?
With no annotations, the description's behavioral disclosure is minimal. It implies a read-only query but does not mention authorization needs, rate limits, pagination behavior (despite a limit parameter), or how multiple filters combine.
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 with a clear first-sentence purpose followed by a well-structured parameter list. It efficiently conveys all necessary information without extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, return value details are not required. However, the description omits behavioral details like default sort order, interaction between filters (AND/OR), and behavior when no results are found. It is adequate for a simple query tool but not 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?
Schema description coverage is 0%, so the description compensates by explaining each parameter's role (e.g., 'Filter to contacts in this address book', 'Full-text search across name, email, phone, etc.'). The explanations are clear and add value beyond the schema type definitions.
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 'Query contacts with optional filters and sorting', specifying the verb (query) and resource (contacts). It distinguishes from sibling tools like contacts_get_contact (single contact) and contacts_list (likely a simple list) by mentioning filters and sorting.
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 contacts_list or contacts_get_contact. There is no mention of prerequisites, when not to use, or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It only states 'Delete' without disclosing irreversible nature, permission requirements, or effect on subfolders. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear main sentence and a structured parameter explanation under 'Args'. 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?
For a simple delete tool with one parameter and an output schema, the description covers the basics. However, lacks details on behavior (recursive? permissions?) that could be important.
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 a concrete example ('/Documents/old.txt') to the path parameter, and explains its purpose beyond the schema's mere title. Schema coverage is 0%, so this is valuable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a file or folder on Fastmail Files (WebDAV)', specifying the verb 'Delete' and the resource 'file or folder', which distinguishes it from siblings like files_move or files_create_folder.
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. There is no mention of prerequisites, when not to use, or comparison to similar tools like files_move.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adequately discloses the two behaviors (move to trash or permanent delete). However, it omits details like reversibility, batch atomicity, or side effects, which would be important for an agent to use it safely.
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, using two sentences to convey purpose and parameter details. No filler or redundancy, making it easy to parse.
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 functionality and parameter semantics, but it lacks information on return values (though output schema exists) and potential side effects (e.g., whether moving to trash frees storage). An agent would need additional context for safe usage.
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?
Given 0% schema description coverage, the description adds meaningful context: email_ids are JMAP IDs, and permanent controls the deletion mode with default behavior. Both parameters are clearly explained, exceeding what the bare schema provides.
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 emails by moving to Trash or permanently destroying them, which is a specific verb+resource. It distinguishes from siblings like mail_move_email by focusing on deletion actions, but does not explicitly contrast with other operations.
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 over alternatives such as mail_move_email or mail_archive_email. The description only explains the two deletion modes, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but only states the basic action. It omits details like reversibility, auth requirements, or potential side effects (e.g., notification triggers).
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, front-loaded with the core action, and uses a clear Args format with no redundant text.
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 simplicity of the tool and the presence of an output schema, the description adequately covers purpose and parameters. It could mention that the operation modifies email state, but it's nearly 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 adds meaning beyond the schema by explaining that email_ids are 'JMAP email IDs' and that read indicates True for read, False for unread. However, it lacks examples or format details, and schema coverage is 0%.
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 'Set or unset' and the resource '$seen flag on one or more emails', distinguishing it from sibling mail tools that handle archiving, moving, or labeling.
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 like mail_archive_email or mail_manage_email_labels, and does not mention any 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?
No annotations provided, so description carries full burden. It describes the output (subject with highlights, preview snippet) but does not disclose if it is read-only, any side effects, permissions needed, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is reasonably concise: a purpose sentence, output format mention, sibling reference, and an arg list. Front-loaded well. No unnecessary fluff.
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 ambiguous about the relationship between required email_ids and the optional filter parameters. It says 'matching a filter' but requires email_ids, implying inconsistency. Does not clarify if filters are used for highlighting or for selecting emails. Output schema exists, so return format is covered, but usage context is unclear.
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 0% schema description coverage, the description adds brief explanations for each parameter (e.g., 'List of email IDs', 'Full-text search query') that go beyond the schema's type and title. However, explanations are minimal.
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?
Clearly states it gets highlighted subject/preview snippets and mentions the output format with <mark> tags. Relates to sibling mail_search_emails, but does not explicitly distinguish when to use one over the other.
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?
Says to use same filter params as mail_search_emails, implying a relationship, but does not explicitly state when to use this tool versus alternatives or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states it retrieves emails but does not mention if it marks as read, requires authentication, or any side effects. The read-only nature is implied but not explicit.
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 short and front-loaded with a clear purpose, followed by parameter details. Every sentence is useful, though additional guidance on usage would be helpful without being overly 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 the rich set of sibling mail tools, the description lacks context about which mailbox is queried, whether it returns only the inbox, or how it interacts with other tools. It does not leverage the existence of an output schema to provide completeness.
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, but the description provides defaults and brief explanations for the two parameters (days and limit), adding meaning beyond the schema. However, it does not describe behavior or constraints like maximum values.
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: retrieving emails received in the last N days. The verb 'get' and resource 'emails' with a time filter are specific, and it distinguishes itself from siblings like mail_search_emails which offers broader search.
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 fetching recent emails but provides no explicit guidance on when to use this tool versus alternatives (e.g., mail_search_emails, mail_get_email). No exclusions or context about inbox or other mailboxes are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behavioral traits. It does not mention overwrite behavior, file size limits, permission requirements, or error conditions. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence for purpose followed by a clear argument list. While not using structured sections, it is efficient and 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?
The description covers parameter semantics adequately but lacks information about output, side effects, or errors. It is minimally complete for a straightforward upload tool but could provide more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds meaning to all three parameters: path with example format, content as Base64-encoded, and content_type with default value. This compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Upload a file to Fastmail Files (WebDAV)', specifying the verb (upload) and the resource (file to Fastmail Files via WebDAV). This distinguishes it from sibling tools like files_delete or files_list.
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 (e.g., files_create_folder, files_move). Usage is implied by the tool's purpose, but no context or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the action. It lacks details on side effects (e.g., removal from inbox), permissions, or idempotency, leaving behavioral traits undisclosed.
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 short and front-loaded, but the Args section duplicates parameter info. Still, it is efficient and contains no wasted sentences.
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 one-parameter tool, the description is adequate. However, it lacks output details (though an output schema exists) and does not clarify how it differs from mail_move_email.
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 specifying that email_ids are JMAP IDs and that they are to be archived. Schema coverage is 0%, so this compensation is valuable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it moves emails to the Archive mailbox, using a specific verb and resource. It distinguishes from siblings like mail_delete_email and mail_forward_email.
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 when/when-not or alternatives are given. The name implies archival use, but the description does not differentiate from mail_move_email or other similar 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?
No annotations are provided, so description must convey behavior. It mentions single round trip but omits details on pagination, sorting, or safety. However, it is a read operation, and the description covers parameter effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise: first line states purpose, second line implementation note, then parameter list. No redundant information.
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 and existence of output schema, the description is fairly complete. However, it lacks mention of pagination or default limit behavior, and does not address how it differs from contacts_query_contacts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so description compensates by clearly explaining each parameter: address_book_id restricts to a book, text is full-text search, limit is max count. This adds significant value.
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?
Description states 'List contacts' with optional filters, clearly indicating the action and resource. However, it does not differentiate from sibling 'contacts_query_contacts' which may have similar functionality.
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 explicit guidance on when to use this tool versus alternatives like contacts_query_contacts. Usage is implied only for listing contacts with basic filters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears full responsibility. It only mentions move/rename and provides parameter examples, but omits critical behavioral details like whether it overwrites, permission requirements, or side effects. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, delivering the core purpose in the first line and expanding minimally in the Args section. No extraneous content.
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 move tool, the description covers basic usage but lacks completeness: no mention of error handling, idempotency, or behavior when destination exists. Output schema exists but is not referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds clear parameter semantics by listing 'source' and 'destination' with examples (e.g., '/Documents/old.txt'). This compensates for the schema gap and provides meaningful guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Move or rename a file or folder on Fastmail Files (WebDAV)', using specific verbs and resource. It clearly distinguishes from siblings like files_delete or files_create_folder.
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 moving/renaming, but lacks explicit guidance on when to use versus alternatives (e.g., when to use files_delete instead). No exclusions or context 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?
The description discloses that html_body is passed verbatim without sanitization and includes a security warning about prompt injection, which is critical behavioral context. However, it does not mention other behaviors like authentication requirements or success/failure responses, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct, front-loaded with the purpose, and structured as a clear 'Args:' list. Every sentence is necessary, including the security note, making it an efficient reference.
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 an output schema exists, the description appropriately omits return values. It covers purpose, parameters, and a security warning. However, it lacks context on error conditions, rate limits, or required permissions, but these are partially offset by the output schema.
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 0% schema description coverage, the description compensates by explaining each parameter (e.g., 'Optional HTML body content... Passed verbatim...,' 'auto-selects first identity if omitted'). This adds value beyond the schema's field titles and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Send an email via Fastmail,' clearly indicating the tool's verb and resource. While it doesn't explicitly differentiate from siblings like mail_forward_email or mail_reply_to_email, the name and description imply it's for composing and sending a new email, which is distinct.
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 over alternatives such as mail_forward_email or mail_reply_to_email. There are no exclusions or context about prerequisites, making it less helpful for an AI agent to decide between tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should cover behavioral traits. It fails to disclose side effects, storage behavior, authentication needs, or whether the blob is temporary. Only states its purpose for email composition.
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: a single-purpose sentence followed by one-line parameter definitions. No redundant 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?
Given the tool has an output schema, the return value may be documented there, but the description does not explain what the uploaded blob produces (e.g., an ID) or how it integrates with email composition, leaving gaps in the full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds value beyond the schema for all three parameters: 'data' is specified as Base64-encoded, 'content_type' as MIME type, and 'name' as informational only (not stored). This compensates for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Upload a blob') and its specific context ('for use in email composition'), differentiating it from sibling mail tools like mail_send_email or mail_download_attachment.
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 implicitly indicates the tool's role in email composition but provides no explicit guidance on when to use it over related tools like mail_import_email or mail_download_attachment, nor any conditions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It states the tool lists calendars but does not disclose read-only nature, side effects, rate limits, or behavior when no calendars exist. The minimal description insufficiently compensates for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the tool's purpose.
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?
An output schema exists, so return values are covered externally. The description sufficiently states the resource and scope. However, it could mention pagination or ordering behavior, but given simplicity, completeness is 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 input schema has zero parameters, so the description does not need to add parameter meaning. Baseline 4 applies as per rule for 0 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 specifies the action 'List', the resource 'all CalDAV calendars', and the scope 'for the authenticated Fastmail account'. It effectively distinguishes this tool from sibling tools like calendar_create_event or calendar_list_events by focusing on calendar retrieval.
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 obtaining available calendars but lacks explicit guidance on when to use it versus alternatives. No exclusion criteria or context (e.g., 'use this to get calendar IDs for other operations') 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?
With no annotations, the description carries the burden. It states 'Fetch' (read-only) and lists return fields, but lacks details on auth, rate limits, or behavior for multiple IDs. Adequate but minimal.
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 brief, front-loads the purpose, and uses no redundant language. 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?
Given the tool's simplicity and the presence of an output schema (though not visible), the description adequately covers the return fields and purpose. No additional context 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?
Schema description coverage is 0%, so the description adds meaning by explaining the 'ids' parameter as 'One or more ContactCard IDs.' It clarifies input format and purpose, compensating for the missing schema descriptions.
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 fetches full contact card(s) by ID and lists returned fields. It distinguishes from sibling tools like contacts_list and contacts_query_contacts by specifying retrieval by ID, but does not explicitly differentiate.
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 when you have IDs, but it does not provide when-not or alternative tools. It relies on the reader to infer context from the parameter description.
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 behavioral effect (setting $flagged keyword, visual flag icon) and explains the boolean pin parameter. However, it does not mention idempotency, error handling, or permission requirements. Without annotations, this is adequate but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two lines defining the action and effect, followed by a clear args list. No wasted words; key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no annotations, output schema exists), the description covers the core functionality and parameter details well. It could mention the return value or error cases, but the presence of an output schema partially mitigates this gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully explains the two parameters: email_ids as a list of JMAP IDs, and pin as a boolean with default True. This adds necessary meaning beyond the raw JSON 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 tool name and description clearly state that it pins or unpins emails by setting the $flagged keyword. It distinguishes itself from sibling tools like mail_mark_email_read or mail_manage_email_labels by focusing specifically on the flag/star functionality.
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 basic instruction on how to use the tool but lacks guidance on when to use it versus alternatives (e.g., mail_manage_email_labels). There is no explicit when-to-use or when-not-to-use 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?
Although annotations are absent, the description uses 'List', which implies a non-destructive, read-only operation. However, it does not explicitly state safety, permission requirements, or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, front-loaded sentence that efficiently communicates the tool's purpose with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and an output schema present, the description adequately lists the returned fields, meeting completeness requirements.
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 no parameters, and the schema coverage is 100%. The description adds no parameter information, but the baseline score for zero parameters is 4 as per guidelines.
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 'address books', and lists the specific fields returned. It is distinct from sibling tools like contacts_list which list contacts, not address books.
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 such as contacts_list. The description is minimal and does not provide context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Describes basic behavior (returns all emails in thread, chronological order) but lacks details on pagination, rate limits, or other side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus a concise Args block. Front-loaded with essential information, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Low complexity (1 param), output schema likely describes return structure. Description adequately explains selection (thread by email_id) and ordering (chronological).
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 0%, but description explicitly explains email_id as 'ID of any email in the thread', adding significant meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool returns all emails in the same thread as a given email, in chronological order. Distinguishes from siblings like mail_get_email (single email) and mail_search_emails (search).
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 when you have an email ID and want the full thread, but no explicit when-not to use or alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes the return fields and basic search behavior, but lacks details on sorting behavior (though defaults are given), rate limits, or whether the search is paginated. The description is functional but not deeply transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using a short introductory sentence followed by a clear bullet list of parameters. It is front-loaded with the core purpose and is free of unnecessary text, making it easy to scan.
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 8 parameters, no annotations, and an existing output schema (from context signals), the description covers all parameters with explanations and references a related tool for mailbox IDs. It lacks some behavioral context like pagination or error handling, but is sufficient for a standard search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 8 parameters with 0% description coverage, meaning no descriptions in the schema itself. The description compensates fully by providing an Args section with one-line explanations for each parameter (e.g., 'text: Full-text search query'), adding meaning beyond the schema's titles.
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?
Description clearly states 'Search emails with optional filters' and specifies returned fields (id, subject, from, date). It distinguishes the tool as a general search with filters, but does not explicitly differentiate from sibling tools like mail_search_snippets or mail_get_recent_emails.
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 provides implicit usage context by listing optional filters and a default limit of 20. It references sibling tool mail_list_mailboxes for the in_mailbox parameter, aiding correct invocation. However, no explicit guidance on when to use this tool over alternatives such as mail_get_email or mail_get_recent_emails.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It only states 'Delete', which implies irreversible mutation, but lacks details on permissions, side effects, or error conditions. This is insufficient for a deletion operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two lines, front-loading the purpose and then explaining the argument. No unnecessary words are used.
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 simplicity (one parameter) and the presence of an output schema, the description adequately covers the parameter source. It could mention error scenarios, but overall it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, but the description adds meaning by explaining that href is the '.ics resource' and originates from calendar_list_events. This provides context beyond the bare type and name.
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 'Delete' and the resource 'CalDAV event by its href'. It distinguishes from sibling tools like calendar_update_event and calendar_get_event by specifying the action of 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?
It explains that the href parameter should come from calendar_list_events, providing context for when to use this tool. While it doesn't explicitly state when not to use it, the guidance is clear and helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It mentions listing within a date range but lacks details on pagination, ordering, or any side effects. For a read-only tool, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences plus parameter details, all front-loaded. Every sentence adds value with 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 the output schema exists, the description adequately explains the tool's purpose and parameters. It could mention that events are returned in a list, but overall completeness is high.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning: calendar_href is linked to calendar_list_calendars, start_date and end_date are ISO date strings with defaults. This compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists events in a CalDAV calendar within a date range. It uses specific verb 'list' and resource 'events in a calendar', and distinguishes from sibling tools like calendar_create_event 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 implies usage for listing events within a date range but does not explicitly state when to use this tool versus alternatives like calendar_get_event for single events or calendar_create_event for adding events. No when-not or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the tool updates fields and that omitted fields keep existing values. However, it does not mention any side effects, authentication requirements, rate limits, or error scenarios. The description is adequate but minimal.
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 front-loaded with the main purpose and then follows a clear, structured list of arguments. Every sentence serves a purpose, and there is no redundant information. It is efficient for an AI agent to parse.
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 that an output schema exists (from context), the description need not explain return values. It covers all parameters and provides necessary operational details (e.g., 'omit to keep existing'). However, it lacks information on what happens if the href is invalid or on error handling, which would make it more 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?
The input schema has 0% coverage (no descriptions for parameters). The description adds meaning by explaining each parameter: href from list, title as new summary, start/end as ISO strings, etc. This compensates well for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update fields on an existing CalDAV event,' providing a specific verb and resource. It distinguishes itself from sibling tools like calendar_create_event and calendar_delete_event by focusing on update 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 gives context for the href parameter (from calendar_list_events) and explains that other fields are optional to keep existing values. However, it does not explicitly state when to use this tool versus alternatives like calendar_create_event or calendar_delete_event, and lacks when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes depth parameter behavior (0 for item itself, 1 for children) but lacks disclosure of error responses, authentication requirements, or read-only nature. No annotations to supplement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus parameter descriptions. Well-structured and front-loaded. Minor improvement could combine parameter info more concisely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. Missing context on authorization, rate limits, or behavior for invalid paths. Adequate for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description fully explains both parameters: path default '/', depth values '0' and '1'. Adds meaning missing from 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?
Clearly states 'List files and folders at a WebDAV path' with specific verb and resource. Distinguishes from siblings like files_get (single file) and files_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?
Implies usage for listing directory contents but provides no explicit guidance on when to use this tool vs alternatives like files_get or files_search (nonexistent). No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explains that mailboxes serve as folders and labels and that emails can belong to multiple mailboxes, but it does not disclose authorization needs, idempotency, error handling, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding distinct value: purpose, folder/label duality, nesting behavior. No wasted words, front-loaded with main action.
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 an output schema, the description covers the key concepts. Minor gaps include lack of naming rules and idempotency, but overall it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It adds meaning for parent_id (nested vs top-level) but does not specify constraints on name (e.g., uniqueness, max length). This provides moderate 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 'Create a new JMAP mailbox (folder or label) with the given name', specifying both the verb and resource. It distinguishes from sibling tools like mail_delete_mailbox and mail_rename_mailbox by focusing on creation.
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 how to create nested folders via parent_id and that top-level mailboxes have no parentId. It does not explicitly state when not to use this tool or mention alternatives, but the context is clear for basic usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states 'Download an attachment blob' without disclosing behavioral traits such as what happens to the file (e.g., saved locally, returned as data), permissions needed, or size limits. The output is not described, though an output schema exists.
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 (5 lines), front-loaded with the main action, and includes parameter descriptions in a clear args block. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a download tool with 3 parameters and an output schema (acknowledged by context signals), the description sufficiently covers what the tool does and parameter semantics. The existence of an output schema means return values need not be explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains each parameter's purpose: blob_id as 'The blobId of the attachment (from email attachments list)', name as 'The filename to use for the download', and content_type with its default value. This adds significant meaning beyond the schema titles.
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 'Download an attachment blob by blobId', providing a specific verb and resource. It distinguishes itself from sibling tools like mail_upload_attachment and mail_parse_email by focusing on downloading blobs.
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 context by specifying the blob_id comes from 'email attachments list', but does not explicitly state when to use this tool over others or provide exclusions. No alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool returns all mailboxes, explains the data model (folders/labels, parentId for nesting, role for system mailboxes), and implies a read-only operation. It adds value beyond the empty input schema.
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 paragraph that includes both factual listing and conceptual explanation. It is fairly concise but the background on folder/label semantics could be shortened or moved to documentation. Still, 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?
Given an output schema exists (though not shown), the description adequately explains what is returned and provides context on the mailbox hierarchy and system roles. It is complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so schema coverage is 100%. The description adds no parameter information because none exists. Baseline for no 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 tool lists all JMAP mailboxes with specific fields (id, name, role, email counts, parentId), and explains the distinction between folders and labels in Fastmail. This is a specific verb-resource combination that distinguishes it from siblings like mail_create_mailbox or 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a full list of mailboxes, but does not explicitly state when to use it versus alternatives (e.g., when to use mail_list_mailboxes vs. mail_get_email or mail_search_emails). It lacks explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, description carries burden. Notes that 'deleted' state soft-deletes and mail bounces, but no details on reversibility, permissions, or other side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise list with clear parameter explanations, though slightly unstructured (no bullet points). No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers what the tool does and all parameter meanings, including special state effect. Output schema exists so return details unnecessary. Lacks preconditions or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning for all 5 parameters, including examples and allowed values for 'state'.
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 a masked email address', with a specific verb and resource. Distinct from siblings like 'create' and 'list'.
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 use for updating existing masked emails, but lacks explicit when-to-use/when-not-to-use guidance or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses parameter formats (ISO string, all_day handling) and optional fields, but fails to mention what the tool returns (e.g., event ID) or any side effects, leaving behavioral gaps.
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 appropriately sized with a clear front-loaded purpose statement followed by a structured arg list. It is not verbose, but could be slightly more concise without losing clarity.
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?
Despite having an output schema (not provided), the description fully covers input parameters and their semantics. However, it lacks information about the return value, which is important for a creation tool. It adequately differentiates from siblings by name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It explains each parameter: calendar_href sourced from another tool, start/end as ISO strings with all-day differentiation, and optional location/description. This greatly clarifies parameter usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb (Create) and resource (new event in a CalDAV calendar), which clearly distinguishes it from sibling tools like calendar_update_event or calendar_delete_event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a prerequisite for the calendar_href parameter (from calendar_list_calendars), providing context for when to use this tool. However, it does not explicitly compare with alternatives or state 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?
No annotations are provided, so the description carries the burden. It describes the return of body content and attachment metadata, and explains the header fetching limitation. However, it does not cover potential errors, rate limits, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with paragraphs and a bullet-point list for common headers. It is concise but could be slightly more streamlined without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is an output schema, the description does not need to detail return values. However, it lacks information about error conditions, such as what happens if the email ID is invalid or not found, 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.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates fully. It explains email_id as the JMAP ID, prefer_html with default behavior, and headers with a list of examples and common useful headers, adding significant 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 it gets a single email by ID with full body and attachment metadata, and optionally fetches specific headers. It distinguishes from sibling tools like mail_export_email and mail_get_email_thread.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides when to use this tool vs. mail_export_email for raw headers, and notes JMAP's requirement to request headers by name. It does not explicitly state when not to use, but gives clear 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?
No annotations provided, so description carries burden. It explains the 'pending' state behavior well but does not disclose read-only nature, pagination, or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and front-loaded with the main verb, followed by clear parameter details. 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 the presence of an output schema and two optional parameters, the description covers essential usage. However, it lacks details on pagination, ordering, or limits, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so description fully compensates by explaining domain as 'partial match' and state with enumerated values and behavior, adding significant 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 it lists masked email addresses with optional filters, distinguishing it from sibling tools like mail_create_masked_email and mail_update_masked_email.
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 other list tools (e.g., mail_list_mailboxes). It mentions optional filters but does not provide context for selecting this tool over alternatives.
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?
Discloses output format (base64) but misses details like error handling, size limits, or authentication requirements. With no annotations, description carries burden but is minimally 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, no fluff. Immediate clarity on what the tool does and how to use it.
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 one-parameter tool, covers purpose and param adequately. Could mention base64 implications or error cases, but not severely lacking.
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?
Only param 'path' described with example ('/Documents/report.pdf'), adding meaning beyond schema. Schema coverage 0% so 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?
States specific verb 'Download' and resource 'file from Fastmail Files' with output format 'base64'. Clearly distinguishes from siblings like files_list, files_upload, files_delete.
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?
Clear that this is for downloading files, implied usage from name and description. No explicit when-not or alternatives, but context suffices for a simple tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fails to explicitly state that the tool is read-only or has no side effects. It only mentions 'verify connectivity' and 'return account info' without detailing behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words, earning its place efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, a simple purpose, and an existing output schema, the description is adequate. It does not detail 'account info', but the output schema likely covers that.
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 (100% coverage), so no additional parameter info is needed. The description does not add parameter semantics, but that is acceptable given zero 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 uses the verb 'verify' with resources 'connectivity to Fastmail' and 'account info', clearly distinguishing it from sibling tools that perform mail, calendar, or contact operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose as a health check is self-evident, and sibling tools are all data operations, so usage context is clear. However, there are no explicit when-not or alternative suggestions.
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 implies read-only nature ('list'), but does not explicitly declare it safe or non-destructive. With no annotations, this is adequate but could be more explicit about 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 sentences, front-loaded with purpose, no redundant information. Efficient and clear.
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?
Tool is simple with no parameters, and description covers purpose and output. Could mention that authentication is required, but given context of MCP server, it's assumed.
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?
Tool has no parameters, so schema coverage is 100%. The description focuses on output, not input, which is acceptable. 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 'sender identities', distinguishing it from sibling tools like mail_set_identity which modify or create identities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. It simply states its function without context on when not to use it or comparison to other 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?
No annotations are provided, so the description bears the full burden. It correctly implies a read-only operation but does not explicitly state non-destructiveness or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The purpose is front-loaded and the parameter explanation is efficient.
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 simple get operation with an output schema available, the description is complete. It explains the single required parameter and where to obtain it, satisfying contextual needs.
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 0% schema description coverage, the description adds significant value by explaining the href parameter as 'the href/URL path of the .ics resource (as returned by calendar_list_events).' This goes 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 'Get full details of a single CalDAV event by its href,' specifying the verb, resource, and method. It distinguishes itself from sibling tools like calendar_list_events (list) and calendar_update_event (update).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains that the href comes from calendar_list_events, implying a prerequisite. However, it does not explicitly state when not to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description discloses that a bare body without proper headers will be rejected and explains the required headers. It does not mention side effects (e.g., indexing, notifications), but the information provided is sufficient for understanding core behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary followed by an Args list. It is front-loaded with the main action and each sentence adds value. Slightly verbose but efficient overall.
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?
With an output schema present, the description does not need to detail return values. It covers the import process, prerequisite, and parameter behavior adequately for a complex operation. It could mention where to obtain mailbox_ids, but overall 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?
Schema description coverage is 0%, so the description compensates by explaining each parameter (blob_id, mailbox_ids, keywords, received_at) with examples and constraints (e.g., ISO 8601). It adds meaning beyond the schema's field names and types.
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 imports a raw RFC 5322 message blob into the mail store. It differentiates from sibling tools like mail_upload_attachment (uploads blob) and mail_export_email (exports), establishing a unique purpose.
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 specifies prerequisites: the blob must be uploaded via mail_upload_attachment and must have valid headers. It does not explicitly state when not to use this tool compared to alternatives like mail_parse_email, but the prerequisite and parameter details provide 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?
Without annotations, the description carries full burden. It mentions server-side setting of 'createdBy' and origin-only constraint for for_domain. It lacks details on idempotency or error handling, but 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?
The description is concise and well-structured: a purpose sentence followed by an Args section. Every sentence adds value, 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?
Despite lacking annotations, the description covers parameter constraints and a behavioral note (createdBy). Output schema exists to explain return values. Missing error cases, but complete enough for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining each parameter's purpose and constraints (e.g., for_domain must be origin-only, email_prefix allowed characters, url optional deep link).
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 masked email address', which is a specific verb+resource. It distinguishes from sibling tools like mail_list_masked_emails and mail_update_masked_email.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on what the tool does and parameter usage, but does not explicitly state when to use it vs alternatives like update. However, sibling tool names imply the distinction.
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 the operation (add/remove keywords), examples of effects (pin, mark read, etc.), and the constraint that at least one of add or remove must be provided. However, it lacks details on idempotency, error cases, or permissions, which would be helpful given no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It starts with the purpose, then provides usage guidance, common keywords, the constraint, and parameter details in a logical order. No unnecessary information.
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 moderate complexity (3 params, no nested objects, output schema exists), the description covers all parameters and behavior adequately. It could mention the existence of the output schema but is otherwise complete for a management tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter: email_ids as 'List of JMAP email IDs to update,' and add/remove with examples and common keywords. It also adds a constraint ('At least one of add or remove must be provided') that is not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add or remove keywords/labels on one or more emails.' It provides specific examples (pin/flag, mark read/unread, apply custom labels) and distinguishes itself from sibling tools like mail_pin_email and mail_mark_email_read by being a general-purpose label management tool.
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 ('Use this to pin/flag, mark read/unread, or apply custom labels') and what common keywords to use. It implicitly suggests this tool can replace more specific sibling tools, though it does not explicitly list alternatives 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?
No annotations are provided, so the description carries the full burden. It discloses that metadata fields will be null since the message is not in the mail store, and hints that blob_ids come from mail_download_attachment. This provides sufficient behavioral context for a read-only parse operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and well-structured: a one-line summary, then a blank line, then practical usage context, then parameter details. Every sentence is informative and there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter), the description covers the use case, parameter origin, and special behavior of metadata. The output schema exists to document the return format, so no further explanation 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 description explains the single parameter blob_ids as 'list of blobIds to parse' and provides a helpful hint about its origin (e.g., from mail_download_attachment). This adds value beyond the schema, which has no description 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 'Parse one or more blobs as RFC 5322 messages without importing them', which distinguishes it from mail_import_email and other mail tools. It also mentions specific use cases like viewing .eml attachments.
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 the tool is useful for viewing .eml attachments or forwarded messages stored as blobs. It implies when not to use (for importing messages) but does not compare with other siblings like mail_export_email or mail_get_email.
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 key behaviors: preserving threading headers, quoting the original message, and the effect of reply_all. With no annotations, this is good transparency. However, it does not mention whether the reply is sent immediately or any side effects like marking the original as replied.
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 a brief opening sentence followed by a clean Args list. Every sentence is informative and there is no redundant information. It is well-structured and 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?
The description covers the main parameters and behavior adequately for a reply action. With an output schema present, it need not explain return values. However, it could mention that the reply is sent immediately and any error conditions (e.g., invalid email_id) to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. It explains each parameter: email_id as 'ID of the email to reply to', text_body including that the original is quoted below, reply_all as CC all recipients, identity_id with auto-selection logic. This adds significant meaning beyond the schema titles.
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 'Reply to an email, preserving threading headers and quoting the original.' This is a specific verb+resource combination, and it distinguishes this tool from siblings like mail_send_email (new email) and mail_forward_email (forwarding) by emphasizing the reply action and threading behavior.
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 implies when to use (when replying to an email) and provides context for parameters like identity_id ('auto-selects first if omitted'). However, it does not explicitly state when not to use or mention prerequisites (e.g., the email must exist), which would improve 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?
Without annotations, the description carries the full disclosure burden. It reveals the capability requirement and a failure condition for destroy (mayDelete). It also explains the format for replyTo and bcc. However, it does not mention idempotency, rate limits, or potential side effects beyond the described operations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear line breaks separating the three operations. It is concise, with each sentence serving a distinct purpose, and front-loads the main verb (create, update, destroy) without extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, multiple operations) and the presence of an output schema, the description explains the three modes, required capability, failure condition, and nested object format. It covers all essential aspects 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?
Schema description coverage is 0%, so the description must compensate. It groups parameters by operation (create, update, destroy) and specifies that replyTo and bcc are lists of EmailAddress objects with an example format. This adds meaning beyond the bare schema titles, though a few parameters (e.g., update_text_signature) are only mentioned by name without further detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool can 'Create, update, or destroy a sender identity' and lists specific parameter groups for each operation, clearly differentiating from sibling tools like mail_list_identities.
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 each mode (create, update, destroy) and the required parameters, and mentions the required capability. It implicitly guides usage by structuring the parameter descriptions per operation, but could be more explicit about when not to use it (e.g., for reading identities).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses that it returns full raw message including headers and MIME parts, and explains optional blob_id auto-fetching. Lacks authentication details but sufficient for a download tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Short, front-loaded with main action, then details and parameter explanations. No redundant 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 output schema exists, description doesn't need return value details. It covers purpose, usage, and parameters adequately. Could mention prerequisites like having an email_id from other tools.
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 has 0% description coverage, but description explains both email_id and blob_id, adding meaning by stating blob_id is optional and automatically fetched if not provided.
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 downloads the raw RFC 5322 .eml source, distinguishing it from mail_get_email which only fetches specific headers.
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 this tool ('when you need all headers') and contrasts with mail_get_email, providing clear guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: it states that system mailboxes are protected, deleting a folder does not delete children (so separate steps needed), and the server rejects deletion if emails exist and on_destroy_remove_emails is not True. This is comprehensive 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?
The description is concise and well-structured. It starts with a clear action statement, then lists key caveats in bullet-like fashion, and ends with an 'Args' section. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, the description is fully complete for a delete operation with constraints. It covers purpose, usage boundaries, parameter behavior, and prerequisites (remove nested folders). The presence of an output schema is noted, so description does not need to explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the full burden. It defines mailbox_id as 'ID of the mailbox to delete' and explains on_destroy_remove_emails: if True, delete all emails; default False causes rejection. This adds significant meaning beyond the schema's property names and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a mailbox (folder or label) by its ID.' It distinguishes from siblings like mail_delete_email and mail_rename_mailbox by specifying the object (mailbox) and noting that system mailboxes cannot be deleted. The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool: to delete a mailbox. It also provides when not to use it: system mailboxes cannot be deleted, and nested folders must be removed first. It explains the on_destroy_remove_emails parameter's role when emails exist. This gives clear guidance on usage and alternatives.
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:

[![pyfastmail-mcp MCP server](https://glama.ai/mcp/servers/pjosols/pyfastmail-mcp/badges/card.svg)](https://glama.ai/mcp/servers/pjosols/pyfastmail-mcp)

Score Badge

Copy to your README.md:

[![pyfastmail-mcp MCP server](https://glama.ai/mcp/servers/pjosols/pyfastmail-mcp/badges/score.svg)](https://glama.ai/mcp/servers/pjosols/pyfastmail-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/pjosols/pyfastmail-mcp'

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