IMAP Mini MCP is a lightweight MCP server that enables AI agents to interact with email accounts via IMAP for reading, organizing, and creating drafts — but cannot send or delete emails.
Email Reading & Search
List emails by date range (last 24h, 7 days, 30 days, 90 days, 365 days, or all)
Filter by sender address, domain, subject, unread status, or presence of attachments
Fetch full email content (subject, from, to, date, body, attachment metadata)
Download attachment files by ID
Folder Management
List all folders and create new folders (including subfolders)
Move individual emails between folders
Bulk move all emails from a specific sender or domain to a folder
Email Organization
Star/unstar emails and list all starred emails across folders
Mark emails as read or unread
Draft Management
Create new email drafts (with optional CC, BCC, reply threading)
Create reply drafts to existing emails (with optional reply-all)
Update/replace existing drafts
Compatibility
Works with any standard IMAP server (Gmail, Outlook, Fastmail, etc.) and local bridges like ProtonMail Bridge
Uses stable composite email IDs that remain valid when emails are moved between folders
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@IMAP Mini MCP Summarize the emails I received in the last 24 hours"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A lightweight MCP (Model Context Protocol) server for reading IMAP email and creating draft replies. Works with any standard IMAP server (Gmail, Outlook, Fastmail, etc.) and local bridges like ProtonMail Bridge.
Agents can read, search, move, star, and organize emails, and compose drafts — but cannot send or delete emails.
See CHANGELOG.md for recently added features.
I highly recommend using a speech-to-text tool (e.g. SuperWhisper on Mac or Whisperflow on Windows) and connecting your AI desktop application (Claude, Codex, etc.) to this MCP server. That way you can converse with your email inbox using speech, which will dramatically speed up your workflow.
Related MCP server: mail-mcp
Add to your MCP client config (e.g. claude_desktop_config.json):
{
"mcpServers": {
"imap-mini-mcp": {
"command": "node",
"args": ["/path/to/imap-mini-mcp/dist/index.js"],
"env": {
"IMAP_HOST": "imap.example.com",
"IMAP_USER": "you@example.com",
"IMAP_PASS": "your-password"
}
}
}
}The args path must point to the built dist/index.js. Add any optional variables to the env block as needed.
Variable | Required | Default | Description |
| yes | — | IMAP server hostname (e.g. |
| yes | — | Email address or username |
| yes | — | Password or app-specific password |
| no |
| IMAP server port |
| no |
| Use TLS for the connection |
| no |
| Upgrade to TLS via STARTTLS (when |
| no |
| Reject self-signed TLS certificates |
For most providers (Gmail, Outlook, Fastmail), the defaults work — just set host, user, and password.
For ProtonMail Bridge — all five settings below are required (the bridge listens on localhost without TLS, uses a self-signed certificate, and does not support STARTTLS):
IMAP_HOST=127.0.0.1
IMAP_PORT=1143
IMAP_SECURE=false
IMAP_STARTTLS=false
IMAP_TLS_REJECT_UNAUTHORIZED=falseOr as MCP client config:
{
"mcpServers": {
"imap-mini-mcp": {
"command": "node",
"args": ["/path/to/imap-mini-mcp/dist/index.js"],
"env": {
"IMAP_HOST": "127.0.0.1",
"IMAP_PORT": "1143",
"IMAP_SECURE": "false",
"IMAP_STARTTLS": "false",
"IMAP_TLS_REJECT_UNAUTHORIZED": "false",
"IMAP_USER": "you@proton.me",
"IMAP_PASS": "your-bridge-password"
}
}
}
}Every email is identified by a composite id (YYYY-MM-DDTHH:mm:ss.<Message-ID>) that is globally unique and stable across folder moves. Use the id returned by find_emails to fetch content, download attachments, move emails, or create reply drafts. Action tools accept an optional mailbox hint for faster lookup; if omitted, all folders are searched.
find_emailsSearch and filter emails. All parameters are optional — calling with no parameters returns all emails from INBOX, sorted newest-first.
Parameter | Type | Default | Description |
| string | — | Only emails after this time. Relative ( |
| string | — | Only emails before this time. Same formats as |
| string | — | Substring match on sender address (e.g. |
| string | — | Substring match on subject line |
| boolean |
| Only return unread emails |
| boolean |
| Only return emails with attachments |
| string |
| Folder to search |
| number | — | Maximum number of results (newest first) |
Examples:
Use case | Parameters |
Last 24 hours |
|
Last 7 days, max 10 |
|
Unread emails |
|
From a domain |
|
With attachments, last month |
|
Specific sender, in Sent folder |
|
Tool | Description | Key parameters |
| Starred emails across all folders | — |
| Full email content by id |
|
| Download an attachment |
|
| List all folders | — |
| Create a new folder |
|
| Move an email to another folder |
|
| Move all emails from a sender |
|
| Move all emails from a domain |
|
| Star an email |
|
| Unstar an email |
|
| Mark an email as read |
|
| Mark an email as unread |
|
| Create a new draft |
|
| Create a reply draft from an existing email |
|
| Replace an existing draft (Drafts folder only) |
|
This almost always means the server rejected the connection due to a TLS/STARTTLS mismatch. Verify these environment variables are set correctly in your MCP client config:
Variable | Check |
| Correct hostname or IP |
| Matches your server (993 for TLS, 143/1143 for plain) |
|
|
|
|
|
|
Local IMAP bridges (e.g. ProtonMail Bridge) typically require IMAP_SECURE=false, IMAP_STARTTLS=false, and IMAP_TLS_REJECT_UNAUTHORIZED=false. See the ProtonMail Bridge config example in the Environment variables section above.
Check that IMAP_USER and IMAP_PASS are correct. Some providers (e.g. Gmail) require an app-specific password rather than your account password.
The IMAP server is not running or not listening on the configured host and port. For local bridges, make sure the bridge application is running.
npm install
npm run build.envFor running the server directly (outside of an MCP client), copy .env.example to .env and fill in your credentials, then:
npm startWhen used through an MCP client, credentials are provided via the client config's env block instead.
Tests use vitest and mock the IMAP layer — no real server connection is needed:
npm test # run once
npm run test:watch # watch mode
npm run lint # type-check onlyCreate a new email draft in the Drafts folder. Returns {id, subject, to, date} of the created draft. Optionally set in_reply_to with an email id to create a threaded reply draft (sets In-Reply-To and References headers automatically).
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Recipient email address. | |
| subject | Yes | Email subject line. | |
| body | Yes | Plain text email body. | |
| cc | No | CC recipient(s). | |
| bcc | No | BCC recipient(s). | |
| in_reply_to | No | ID of the email being replied to (for threading). Automatically sets In-Reply-To and References headers. |
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 the tool creates a new draft (implying a write operation) and returns specific fields ({id, subject, to, date}), which is helpful. However, it lacks details on permissions needed, error conditions, rate limits, or whether the draft is saved automatically. The behavioral context is partially covered but incomplete 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by return values and optional parameter usage. Both sentences earn their place by adding distinct information (creation action and threading behavior). No wasted words, and the structure is logical and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description partially compensates by stating the return fields. However, for a mutation tool with 6 parameters, it lacks details on error handling, side effects (e.g., where the draft is stored), or interaction with siblings like 'update_draft'. The context is adequate but has clear gaps for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 6 parameters thoroughly. The description adds minimal value beyond the schema by mentioning the optional 'in_reply_to' parameter and its effect (sets headers automatically), but doesn't provide additional syntax or format details. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Create a new email draft'), resource ('in the Drafts folder'), and distinguishes it from siblings like 'update_draft' (creation vs. modification) and 'draft_reply' (general draft vs. threaded reply). The verb+resource combination is precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the optional 'in_reply_to' parameter ('to create a threaded reply draft'), which implicitly distinguishes it from creating a standalone draft. However, it doesn't explicitly state when to use this tool versus alternatives like 'draft_reply' or 'update_draft', nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new folder. Use a path with the server's delimiter for subfolders (e.g. "INBOX/Receipts" or "Projects/2024"). Use list_folders first to discover the delimiter if unsure.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Full path of the folder to create (e.g. "INBOX/Receipts"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the path delimiter requirement and suggests using list_folders first, which adds useful context about prerequisites. However, it doesn't disclose other behavioral traits like permissions needed, error conditions, or whether creation is recursive for nested paths.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences: the first states the purpose, the second provides crucial usage guidance with examples. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter creation tool with no annotations and no output schema, the description provides adequate but minimal context. It covers the basic operation and key usage guidance, but doesn't address what happens on success/failure, whether parent folders must exist, or other edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the single 'path' parameter. The description adds some value by providing examples ('INBOX/Receipts' or 'Projects/2024') and mentioning the server delimiter, but doesn't significantly expand beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and resource 'new folder', making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'create_draft' or 'update_draft', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('Create a new folder') and when to use an alternative ('Use list_folders first to discover the delimiter if unsure'). It also gives context about path formatting with server delimiter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a reply draft to an existing email. Automatically derives recipient, subject (Re: prefix), and threading headers from the original email. Set reply_all to true to include original recipients as CC. Returns {id, subject, to, date} of the created draft.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ID of the email to reply to. | |
| body | Yes | Plain text reply body. | |
| reply_all | No | Include original To/CC recipients as CC (default: false). | |
| mailbox | No | Optional folder hint for faster lookup. If omitted, searches all folders. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behaviors: automatic derivation of recipient, subject, and threading headers; the effect of 'reply_all' on CC recipients; and the return format. However, it lacks details on permissions, error handling, or rate limits, which are important 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by key behaviors and return values in two efficient sentences. Every sentence adds value without redundancy, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (mutation with 4 parameters) and no annotations or output schema, the description does a good job covering purpose, usage, and return format. However, it could improve by addressing potential errors or side effects, which would enhance completeness for an unannotated mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema, mentioning 'reply_all' and 'mailbox' briefly but not providing additional context or examples. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Create a reply draft to an existing email') and distinguishes it from sibling tools like 'create_draft' by specifying it's for replying to an existing email with automatic derivation of metadata. It uses precise verbs and identifies the resource (reply draft).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (replying to an existing email) and implicitly differentiates it from 'create_draft' (which likely creates drafts from scratch). However, it does not explicitly state when not to use it or mention alternatives like 'update_draft' for modifying existing drafts, which could be helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a specific attachment from an email. Requires the email id and the attachment id (obtained from fetch_email_content). Returns {id, filename, contentType, size, contentBase64} where contentBase64 is the base64-encoded file content.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The email identifier from list results. | |
| attachment_id | Yes | The attachment identifier from fetch_email_content results. | |
| mailbox | No | Optional folder hint for faster lookup. If omitted, searches all folders. |
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 effectively describes the operation (download), prerequisites (requires IDs from fetch_email_content), and return format (including contentBase64 encoding). It does not mention potential errors, rate limits, or authentication needs, but covers core behavior adequately for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by prerequisites and return details. Every sentence adds essential information without redundancy, making it efficient and well-structured for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (download operation with 3 parameters), no annotations, and no output schema, the description does a good job covering purpose, prerequisites, and return format. However, it lacks details on error handling or edge cases (e.g., invalid IDs, large files), which would enhance completeness for a tool without structured output documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters (id, attachment_id, mailbox). The description adds minimal value beyond the schema by mentioning that attachment_id is 'obtained from fetch_email_content', but does not provide additional syntax, format, or usage details for parameters. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Download a specific attachment from an email'), identifies the resource ('attachment'), and distinguishes it from sibling tools like fetch_email_content (which provides attachment IDs) and list_emails_* tools (which list emails rather than download attachments). The verb 'download' is precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('Requires the email id and the attachment id (obtained from fetch_email_content)'), providing clear prerequisites. However, it does not specify when NOT to use it or mention alternatives (e.g., if there are other ways to get attachments), which prevents a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full content of a single email by its id. Returns {id, subject, from, to, date, body, attachments}. The attachments array contains metadata only (id, filename, contentType, size) — use fetch_email_attachment to download actual attachment data. Use an id obtained from any of the list_emails_* tools.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The email identifier from list results. | |
| mailbox | No | Optional folder hint for faster lookup. If omitted, searches all folders. |
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 effectively describes the return structure ('Returns {id, subject, from, to, date, body, attachments}') and clarifies the limitation of attachment data ('metadata only'). However, it doesn't mention potential error conditions, rate limits, or authentication requirements that would be helpful for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in three sentences: purpose statement, return value specification with important limitation, and usage guidance. Every sentence earns its place by providing essential information without redundancy. It's appropriately sized and front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read operation with no annotations and no output schema, the description does well by specifying the return structure and attachment data limitation. However, it could benefit from mentioning error handling (e.g., what happens with invalid IDs) or performance characteristics. The guidance on sibling tool relationships is strong, making it mostly complete for this context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions the 'id' parameter contextually but doesn't provide additional semantics about format or constraints. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('fetch the full content'), resource ('a single email'), and key identifier ('by its id'). It distinguishes from sibling tools by specifying it's for retrieving content of individual emails rather than listing or managing them, and explicitly differentiates from fetch_email_attachment for attachment data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('use an id obtained from any of the list_emails_* tools') and when to use an alternative ('use fetch_email_attachment to download actual attachment data'). It clearly establishes the prerequisite relationship with list_emails_* tools and the complementary relationship with fetch_email_attachment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all emails received in the last 24 hours. Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
| Name | Required | Description | Default |
|---|---|---|---|
| mailbox | No | Mailbox to list from. Default: "INBOX". |
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 effectively describes the return format (array of objects with specific fields), sorting behavior (newest-first), and the purpose of the id field (globally unique identifier for use with fetch_email_content). However, it doesn't mention potential limitations like pagination, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely efficient with two sentences that each serve distinct purposes: the first defines the core functionality and output format, the second explains the id field's purpose. There's zero wasted language, and the most important information (what the tool does) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with no annotations and no output schema, the description provides good coverage of the essential information: what it does, what it returns, and how to use the output. It could be more complete by mentioning potential limitations or edge cases, but given the tool's straightforward nature and the absence of structured metadata, it's reasonably comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already fully documents the single parameter (mailbox). The description doesn't add any parameter-specific information beyond what's in the schema, but since the schema coverage is complete, the baseline score of 3 is appropriate. The description focuses on the tool's overall behavior rather than parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('List all emails received'), resource ('emails'), and temporal scope ('in the last 24 hours'), distinguishing it from sibling tools like list_emails_7days or list_emails_all. It provides a precise verb+resource+scope combination that makes the tool's purpose immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly suggests when to use this tool (for recent emails within 24 hours) and mentions an alternative tool (fetch_email_content) for reading full content, but doesn't explicitly compare it to other list_emails_* siblings or provide exclusion criteria. The context is clear but lacks explicit guidance on when to choose this over similar time-bound listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all emails received in the last 7 days. Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
| Name | Required | Description | Default |
|---|---|---|---|
| mailbox | No | Mailbox to list from. Default: "INBOX". |
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 clearly describes the return format (array of objects with id, subject, from, date), sorting order (newest-first), and how to use the id with another tool. However, it doesn't mention potential limitations like pagination, rate limits, or authentication needs, leaving some behavioral aspects uncovered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by return details and usage guidance. Every sentence adds value—none are redundant or wasteful—making it efficiently structured and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 optional parameter, no output schema, no annotations), the description is largely complete. It covers purpose, return format, sorting, and tool chaining. A minor gap is the lack of explicit mention of default behavior or error cases, but overall it provides sufficient context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the mailbox parameter fully documented in the schema itself. The description adds no additional parameter information beyond what the schema provides, so it meets the baseline of 3 for high schema coverage without compensating value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb ('List'), resource ('emails'), and temporal scope ('received in the last 7 days'), making the purpose specific. It clearly distinguishes from siblings like list_emails_24h, list_emails_all, etc., by specifying the 7-day timeframe.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool (for emails in the last 7 days) and when to use an alternative (fetch_email_content for full content using the returned id). It distinguishes from other list_emails_* tools by its time range, aiding in sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List ALL emails in the mailbox (no date filter). Warning: this may return a very large number of results. Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
| Name | Required | Description | Default |
|---|---|---|---|
| mailbox | No | Mailbox to list from. Default: "INBOX". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and adds valuable behavioral context: it warns about large result sets, specifies return format (array of objects with id, subject, from, date), sorting (newest-first), and how to use the id with fetch_email_content. This goes beyond basic listing to include practical usage details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with core purpose, followed by warnings and return details, all in three efficient sentences with zero waste. Each sentence adds critical information (scope, risk, output format, and usage guidance), making it appropriately sized and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description compensates well by explaining return values and behavioral traits. It covers purpose, usage context, and output semantics adequately for a list tool, though it could mention pagination or limits for very large results to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'mailbox', which is documented in the schema. The description does not add any parameter-specific information beyond what the schema provides, so it meets the baseline of 3 without compensating or detracting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'ALL emails in the mailbox', specifying scope 'no date filter'. It distinguishes from siblings like list_emails_24h, list_emails_7days, etc. which have date filters, making the purpose specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context with 'no date filter' and a warning about potentially large results, implying when to use it (for unfiltered listing). However, it does not explicitly state when not to use it or name alternatives, though siblings suggest date-filtered options exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all emails from a specific domain (e.g. "you.com" finds all emails from @you.com senders). Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain to search for (e.g. "example.com"). Do not include the @ sign. | |
| mailbox | No | Mailbox to list from. Default: "INBOX". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behaviors: it describes the return format (array of objects with id, subject, from, date), sorting order (newest-first), and how to use the returned id with another tool (fetch_email_content). It doesn't mention rate limits, authentication needs, or pagination behavior, but covers essential operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly front-loaded with the core purpose in the first sentence, followed by return format and usage guidance. Every sentence earns its place: the first explains what the tool does, the second describes output structure, and the third provides critical follow-up action guidance. Zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with no annotations and no output schema, the description provides excellent coverage: purpose, parameters (via schema), return format, sorting, and tool chaining guidance. The only minor gap is lack of explicit mention about whether this is a search across all mailboxes or just the specified one, but the schema clarifies the mailbox parameter default.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds the example 'you.com' which reinforces the domain parameter format, but doesn't provide additional semantic context beyond what's in the schema. This meets the baseline expectation when schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'emails from a specific domain', with a concrete example ('you.com' finds all emails from @you.com senders). It explicitly distinguishes from siblings like list_emails_from_sender by focusing on domain-level filtering rather than individual sender addresses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (searching by domain) and implicitly distinguishes it from time-based siblings (list_emails_24h, list_emails_7days, etc.) by not mentioning time constraints. However, it doesn't explicitly state when NOT to use it or name specific alternatives beyond the implied differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all emails from a specific sender email address (e.g. "alice@example.com"). Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
| Name | Required | Description | Default |
|---|---|---|---|
| sender | Yes | The sender email address to search for (e.g. "alice@example.com"). | |
| mailbox | No | Mailbox to list from. Default: "INBOX". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it specifies the return format (array of objects with id, subject, from, date), sorting behavior (newest-first), and how to use the returned id with another tool. However, it doesn't mention potential limitations like pagination, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly front-loaded with the core purpose in the first sentence, followed by essential behavioral details. Every sentence earns its place by providing critical information about return format, sorting, and tool integration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with no output schema, the description provides excellent coverage of what the tool does, what it returns, and how to use the results. The only minor gap is the lack of explicit mention about potential limitations or edge cases, but overall it's quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already fully documents both parameters. The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline of 3 where the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('List all emails from a specific sender email address'), identifies the resource (emails), and distinguishes it from siblings by specifying the sender-based filtering approach, unlike time-based or domain-based sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (to find emails from a specific sender) and implicitly suggests an alternative (fetch_email_content for full content), but doesn't explicitly state when NOT to use it or compare it directly to other list_emails_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all emails received in the last 30 days. Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
| Name | Required | Description | Default |
|---|---|---|---|
| mailbox | No | Mailbox to list from. Default: "INBOX". |
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 effectively describes key behaviors: it's a read operation (implied by 'List'), returns sorted data ('newest-first'), specifies the output format ('array of {id, subject, from, date} objects'), and mentions the id's purpose ('globally unique identifier — use it with fetch_email_content'). It lacks details on pagination, rate limits, or error handling, but covers essential operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured in two sentences: the first states the purpose and output format, and the second explains the id's utility. Every sentence adds value without redundancy, making it easy to parse and front-loaded with critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (1 parameter, no output schema, no annotations), the description is largely complete. It covers the action, time scope, output structure, sorting, and id usage. However, it doesn't address potential edge cases like empty results or authentication needs, leaving minor gaps in contextual coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'mailbox' parameter fully documented in the schema itself. The description adds no additional parameter information beyond what the schema provides, such as examples or constraints. This meets the baseline of 3 since the schema handles the parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('List all emails received in the last 30 days'), resource ('emails'), and scope ('last 30 days'). It explicitly distinguishes from sibling tools like list_emails_24h, list_emails_7days, etc., by specifying the time window, making the purpose unambiguous and well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (for emails in the last 30 days) and implies an alternative (fetch_email_content for full email reading). However, it doesn't explicitly state when NOT to use it or compare it to other time-based siblings like list_emails_quarter or list_emails_year, which could help avoid misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all emails received in the last 90 days. Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
| Name | Required | Description | Default |
|---|---|---|---|
| mailbox | No | Mailbox to list from. Default: "INBOX". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it's a read operation (implied by 'List'), returns sorted data (newest-first), includes a globally unique ID, and mentions a related tool (fetch_email_content). It doesn't cover rate limits, permissions, or pagination, but provides substantial context beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by details on return format and usage guidance. Every sentence adds value with no wasted words, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (filtered list operation), no annotations, and no output schema, the description does well by explaining the return format, sorting, and ID usage. It could improve by mentioning default behavior or error cases, but it covers the essentials for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the single parameter (mailbox). The description doesn't add any parameter-specific information beyond what's in the schema, but it doesn't need to since the schema is complete. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('List all emails received in the last 90 days'), identifies the resource (emails), and distinguishes it from siblings by specifying the time range (90 days vs. 24h, 7days, month, year, all). It also mentions the return format and sorting order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (emails from the last 90 days) and implicitly suggests an alternative (fetch_email_content for full content). However, it doesn't explicitly state when not to use it or compare it to other time-based siblings like list_emails_month or list_emails_year.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all emails received in the last 365 days. Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
| Name | Required | Description | Default |
|---|---|---|---|
| mailbox | No | Mailbox to list from. Default: "INBOX". |
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 key behavioral traits: the time-based filtering, sorting order ('newest-first'), return format (array of objects with specific fields), and that the id is globally unique for use with another tool. However, it doesn't mention potential limitations like pagination, rate limits, or authentication needs, which are relevant for a list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by return details and a usage tip, all in three concise sentences with zero waste. Each sentence adds value: the first defines scope, the second specifies output, and the third provides context for the id field.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description compensates well by explaining the return format and sorting, and it references another tool for extended functionality. For a simple list tool with one parameter, it's mostly complete, but lacks details on error handling or performance aspects like result limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the single parameter 'mailbox' with its type and default. The description does not add any information about parameters beyond what the schema provides, such as explaining mailbox options or constraints. Baseline 3 is appropriate as the schema handles parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List'), resource ('emails'), and scope ('received in the last 365 days'), distinguishing it from siblings like list_emails_24h or list_emails_all by specifying the time range. It explicitly mentions the output format, which helps understand what the tool returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool by specifying the time range ('last 365 days') and mentions an alternative tool ('fetch_email_content') for reading full emails, helping differentiate it from other list_emails_* siblings. It implies usage for recent email retrieval without filtering by sender or domain.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all folders in the email account. Returns an array of {path, name, delimiter} objects. Use the path value when specifying a folder in other tools.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 the return format ('array of {path, name, delimiter} objects') and a behavioral note about using the path in other tools, which is useful. However, it lacks details on permissions, rate limits, or error conditions that would be important for a listing operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by output details and a usage tip. Both sentences earn their place by adding value without redundancy, making it efficiently structured and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, no output schema), the description is mostly complete: it states the purpose, output format, and a key usage guideline. However, without annotations or output schema, it could benefit from more behavioral context like pagination or error handling, but it adequately covers the essentials for a simple listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately does not discuss parameters, focusing instead on output and usage, which aligns with the tool's simplicity. A baseline of 4 is given as it compensates well for the lack of parameters by providing clear output semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb ('List') and resource ('all folders in the email account'), distinguishing it from sibling tools like list_emails_* which handle emails rather than folders. It precisely defines what the tool does without being vague or tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('List all folders') and implicitly suggests usage for obtaining folder paths needed by other tools. However, it does not explicitly state when not to use it or name alternatives among siblings, such as create_folder for folder creation instead of listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all starred (flagged) emails across all folders, grouped by folder. Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 effectively describes the return format (array of objects with specific fields), sorting order (newest-first), grouping behavior (by folder), and how to use the output (id for fetch_email_content). It doesn't mention rate limits, authentication needs, or pagination, but covers core behavior well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences: the first states purpose and output format, the second explains the id's usage. Every sentence adds value without redundancy, and key information (what it does, what it returns, how to use the output) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with 0 parameters and no output schema, the description is quite complete. It explains the filtering (starred), grouping (by folder), return format, sorting, and how to use the result. It doesn't cover potential edge cases like empty results or error conditions, but provides sufficient context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, maintaining focus on the tool's purpose and output. This meets the baseline for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('List all starred emails'), resource ('emails'), and scope ('across all folders, grouped by folder'), distinguishing it from sibling tools like list_emails_24h or list_emails_from_sender which filter differently. It explicitly mentions the filtering criteria (starred/flagged) and organizational grouping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (to retrieve starred emails grouped by folder) and implicitly suggests an alternative (fetch_email_content for full content using the returned id). However, it doesn't explicitly state when NOT to use it or compare it directly to other list_emails_* siblings beyond the starred filtering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move an email from one folder to another. Requires the email's id (from list_emails_* or fetch_email_content) and the destination folder to move it to. Returns {id, destination}.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The email identifier. | |
| source_folder | No | Optional folder hint for faster lookup. If omitted, searches all folders. | |
| destination_folder | Yes | Folder to move the email to. |
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 the action (move) and return format ({id, destination}), but lacks details on permissions, error handling, or side effects (e.g., whether the email is removed from the source folder). It adds some context but is incomplete 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by prerequisites and return value. Every sentence earns its place with no wasted words, making it highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers the basic operation and return format but lacks details on behavioral aspects like error conditions or side effects. For a mutation tool with 3 parameters, it is adequate but has clear gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal value by mentioning id and destination_folder but does not explain source_folder's optional nature or provide additional semantics beyond the schema. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('move'), resource ('email'), and scope ('from one folder to another'), distinguishing it from sibling tools like list_emails_* (read-only) or create_draft (creation). It explicitly mentions the verb and resource without being tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool by specifying prerequisites (requires email id from list_emails_* or fetch_email_content) and the destination folder. However, it does not explicitly state when not to use it or name alternatives (e.g., vs. deleting or archiving), which prevents a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a star (flag) to an email. Requires the email's id (from list_emails_* or fetch_email_content). Returns {id, starred: true}.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The email identifier to star. | |
| mailbox | No | Optional folder hint for faster lookup. If omitted, searches all folders. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool requires an email ID and returns a confirmation object with {id, starred: true}, which is helpful. However, it doesn't mention potential side effects (e.g., whether starring affects email organization or sync), authentication needs, or error conditions, leaving gaps in 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by prerequisites and return value, all in two efficient sentences. Every sentence earns its place by adding necessary information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (a simple mutation with 2 parameters), no annotations, and no output schema, the description does well by covering purpose, prerequisites, and return format. However, it could improve by addressing error cases or confirming idempotency (e.g., what happens if the email is already starred).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters well. The description adds value by specifying that the 'id' should come from specific sibling tools ('list_emails_*' or 'fetch_email_content'), providing practical sourcing guidance beyond the schema's technical definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a star (flag)') and the resource ('to an email'), distinguishing it from sibling tools like 'unstar_email' (which removes stars) and 'list_starred_emails' (which lists starred emails). It specifies the exact operation without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by mentioning that the email ID should come from 'list_emails_*' or 'fetch_email_content', guiding the agent on how to obtain the required parameter. However, it doesn't explicitly state when NOT to use this tool or compare it with alternatives like 'unstar_email' for toggling star status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove the star (flag) from an email. Requires the email's id (from list_emails_* or fetch_email_content). Returns {id, starred: false}.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The email identifier to unstar. | |
| mailbox | No | Optional folder hint for faster lookup. If omitted, searches all folders. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the mutation behavior ('Remove') and the return format, but lacks details about permissions needed, error conditions, or rate limits. It adequately describes the core operation but misses some 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each earn their place: the first states the purpose, the second provides prerequisites and return value. It's front-loaded with the core action and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description does well by explaining the action, prerequisites, and return format. However, it could be more complete by mentioning side effects or error handling, given the tool modifies data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description mentions the 'id' parameter's source but doesn't add meaningful semantics beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Remove the star') and target resource ('from an email'), distinguishing it from sibling tools like 'star_email' and 'list_starred_emails'. It precisely defines the tool's function without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by specifying when to use it (to remove a star) and mentions prerequisites (requires email id from list_emails_* or fetch_email_content). However, it doesn't explicitly state when NOT to use it or name alternatives like 'star_email' for the opposite operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace an existing draft with new content. The id must refer to an email in the Drafts folder — this tool cannot modify emails in other folders. Returns {id, subject, to, date} of the updated draft.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ID of the existing draft to replace. | |
| to | Yes | Recipient email address. | |
| subject | Yes | Email subject line. | |
| body | Yes | Plain text email body. | |
| cc | No | CC recipient(s). | |
| bcc | No | BCC recipient(s). | |
| in_reply_to | No | ID of the email being replied to (for threading). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that this is a mutation tool ('Replace'), specifies the folder restriction, and describes the return format. However, it lacks details on permissions, error handling, or side effects like whether previous content is overwritten or archived.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by a critical constraint and return details in two concise sentences. Every sentence adds value without redundancy, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the mutation nature, 7 parameters, and no annotations or output schema, the description is mostly complete: it covers purpose, constraints, and return values. However, it could improve by addressing authentication needs or error cases, leaving minor gaps for a tool with significant parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 7 parameters. The description adds no additional parameter semantics beyond what the schema provides, such as format examples or constraints, meeting the baseline score for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Replace an existing draft with new content'), identifies the resource ('draft'), and distinguishes it from siblings by specifying it only works on emails in the Drafts folder, unlike tools like 'move_email' or 'draft_reply' that might handle other folders or operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('id must refer to an email in the Drafts folder') and implicitly excludes other folders, but does not explicitly name alternatives like 'create_draft' for new drafts or specify when not to use it beyond the folder constraint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes, but the multiple list_emails_* tools (e.g., list_emails_24h, list_emails_7days) serve overlapping functions with only time filters differing, which could cause confusion in selection. However, descriptions clarify their specific scopes, and other tools like create_draft, move_email, and star_email are clearly differentiated.
All tool names follow a consistent verb_noun pattern with snake_case, such as create_draft, list_folders, and fetch_email_content. This uniformity makes the tool set predictable and easy to navigate, with no deviations in naming conventions.
With 19 tools, the count is borderline high for an email management server, as many list_emails_* tools could be consolidated into a single tool with parameters. While it covers various use cases, the number feels heavy and may overwhelm agents, though it's not extreme.
The tool set provides comprehensive coverage for email operations, including CRUD for drafts, folder management, email listing with filters, attachment handling, and actions like starring and moving. Minor gaps include no direct send_email tool (relying on drafts) and limited search beyond sender/domain, but core workflows are well-supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Read, search, send, organize, draft and schedule email across your inboxes from any MCP client.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
A MCP server for Gmail that lets you search, read, and draft emails and replies.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/florianbuetow/imap-mini-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
