Mail-MCP is an MCP server that lets an AI assistant safely manage a personal Outlook.com/Hotmail/Live mailbox through Microsoft Graph.
List folders with total and unread counts (mail_list_folders)
Create folders idempotently (mail_create_folder)
Search and page through messages with filters or full-text query (mail_search)
Read full message content and detect unsubscribe options (mail_get_message)
Aggregate a whole folder by sender to triage volume, latest message, and unsubscribe method (mail_senders_summary)
Move up to 500 messages to a folder, with old-to-new id mapping (mail_move)
Delete messages to Deleted Items by default, or permanently with an explicit flag (mail_delete)
Bulk move or delete all mail from a sender, with dry-run support (mail_bulk_by_sender)
Unsubscribe via RFC 8058 one-click POST, mailto email, or a browser URL when manual action is needed (mail_unsubscribe)
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., "@Mail-MCP Check my inbox for unread newsletters and unsubscribe me."
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 small, focused MCP server that lets Claude (Claude Desktop, Cowork, Claude Code or any MCP client) work on a personal Outlook.com / Hotmail / Live mailbox through Microsoft Graph: read and search mail, file it into folders, delete it, and unsubscribe from newsletters.
Built for one job: clean up an overflowing personal inbox with an AI assistant, safely.
Nine tools, all prefixed mail_:
Tool | What it does |
| Folder tree with total / unread counts |
| Create a folder (idempotent) |
| List / search messages (sender, date range, unread, full text), paginated |
| Full content of one message + detected unsubscribe options |
| Aggregate a whole folder by sender: volume, latest message, available unsubscribe method |
| Move up to 500 messages to a folder |
| Move to Deleted Items by default, |
| Move or delete every message from one sender ( |
| RFC 8058 one-click POST → |
Design choices:
Safe by default. Deletion goes to Deleted Items (visible and restorable in Outlook). Permanent deletion requires an explicit flag. Bulk actions support dryRun.
Efficient on big mailboxes. mail_senders_summary scans thousands of messages in a few seconds (1,000-item pages, minimal $select) and only fetches headers for the top senders through $batch.
No generic send tool. The Mail.Send permission is used solely to send mailto: unsubscribe requests.
Every tool ships a strict input schema, an output schema and MCP annotations (readOnlyHint, destructiveHint, …) so hosts can auto-approve read-only calls.
Related MCP server: outlook-mcp
Node.js 20 or newer.
A personal Microsoft account (outlook.com, hotmail.com, live.com, msn.com).
A free Microsoft Entra app registration (5 minutes, below). Password-based IMAP was switched off for personal accounts in September 2024, so an OAuth app is the only supported way in.
No Azure subscription is needed for a public client app.
Go to https://entra.microsoft.com and sign in with your personal Microsoft account.
Identity → Applications → App registrations → New registration.
Fill in:
Name: Mail-MCP
Supported account types: Personal Microsoft accounts only
Redirect URI: platform Mobile and desktop applications, value http://localhost
Click Register and copy the Application (client) ID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
Under Authentication, make sure http://localhost is listed under "Mobile and desktop applications" and Allow public client flows is Yes.
Under API permissions, add Microsoft Graph delegated permissions: Mail.ReadWrite, Mail.Send, User.Read, offline_access. No admin consent is needed; you consent at first sign-in.
No client secret is created: the server is a public client using the authorization code flow with PKCE.
No install needed, npx fetches the package from npm (@rixtay/mail-mcp, the installed command is mail-mcp):
MAIL_MCP_CLIENT_ID=<your-client-id> npx -y @rixtay/mail-mcp loginOr from a clone:
git clone https://github.com/Rixtayz/Mail-MCP.git
cd Mail-MCP
npm install && npm run build
MAIL_MCP_CLIENT_ID=<your-client-id> npm run loginThe login command opens your system browser, signs you in with Microsoft, then stores the token cache in ~/.mail-mcp/token-cache.json (file mode 600). Tokens refresh silently for 90 rolling days. If a tool ever answers "Token expired", run the same command again.
Environment variable | Purpose |
| Required. Application (client) ID from step 1 |
| Optional. Token cache location |
Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or %APPDATA%\Claude\claude_desktop_config.json on Windows), reachable through Settings → Developer → Edit Config.
{
"mcpServers": {
"mail": {
"command": "npx",
"args": ["-y", "@rixtay/mail-mcp"],
"env": {
"MAIL_MCP_CLIENT_ID": "<your-client-id>"
}
}
}
}If Claude Desktop cannot find npx (it does not inherit your shell PATH), use absolute paths instead: "command": "/absolute/path/to/node", "args": ["/absolute/path/to/Mail-MCP/dist/index.js"].
Quit Claude Desktop completely and start it again. Logs: ~/Library/Logs/Claude/mcp-server-mail.log.
Cowork runs local MCP servers only in local sessions, not in cloud sessions.
claude mcp add --scope user --env MAIL_MCP_CLIENT_ID=<your-client-id> --transport stdio mail -- npx -y @rixtay/mail-mcp"Summarise the senders in my inbox and flag the newsletters."
"Unsubscribe me from every newsletter I haven't opened in six months, then move their messages to Deleted Items."
"Create an Invoices folder and move everything from billing@vendor.com into it."
"Show me the latest email from my bank."
Typical flow: mail_senders_summary → the assistant proposes a list, you confirm → mail_unsubscribe(lastMessageId) per newsletter (when the answer is method: "browser", the assistant opens the URL in its browser and finishes there) → mail_bulk_by_sender(action: "delete").
npm test # vitest: header parsing, Graph retry/batch/pagination, service with a mocked Graph
npm run typecheck
npm run inspect # MCP Inspector against dist/index.jsLayout:
src/index.ts CLI entry point: `mail-mcp` serves stdio, `mail-mcp login` signs in
src/login.ts interactive sign-in flow
src/server.ts builds the McpServer and registers the tools
src/auth.ts MSAL public client, file-based token cache
src/graph.ts Graph client: bearer auth, 429/503 retry, pagination, $batch in chunks of 20
src/mail.ts business logic (folders, search, sender summary, move/delete, unsubscribe cascade)
src/unsubscribe.ts List-Unsubscribe / List-Unsubscribe-Post parsing, RFC 8058 one-click POST
src/tools/*.ts tool definitions (zod v4 schemas, annotations)
scripts/login.ts one-time interactive sign-inStack: @modelcontextprotocol/server v2, zod v4, @azure/msal-node v6, html-to-text.
Message ids change whenever a message changes folder. mail_move and mail_delete return the old → new id mapping.
A normal delete is a move to Deleted Items. Graph's own DELETE would drop the item into Recoverable Items, which is invisible in Outlook, so it is deliberately not used.
Microsoft throttles Outlook to 10,000 requests per 10 minutes per mailbox and 4 concurrent requests. Batches are serialised and retried on 429.
mail_search with query (full text) cannot be combined with the other filters (Graph limitation) and tops out at a few hundred results.
Whether an unsubscribe actually takes effect is up to the sender. One-click and mailto: send the request; the assistant's browser handles the rest.
The authority is login.microsoftonline.com/consumers. With common, refresh tokens for personal accounts are rejected after the first refresh.
MIT
Move or delete EVERY message from a sender (exact address) in a folder (Inbox by default). Use dryRun: true first to learn how many messages match. Deletion goes to Deleted Items unless permanent: true.
| Name | Required | Description | Default |
|---|---|---|---|
| from | Yes | Exact sender address | |
| action | Yes | move = move to targetFolder; delete = delete | |
| dryRun | No | true = count only, change nothing | |
| folder | No | Source folder. Default: inbox | |
| permanent | No | With action = delete: permanent deletion | |
| targetFolder | No | Required when action = move |
| Name | Required | Description |
|---|---|---|
| dryRun | Yes | |
| failed | Yes | |
| matched | Yes | |
| succeeded | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, but the description adds valuable nuance: 'Deletion goes to Deleted Items unless permanent: true.' This goes beyond the schema and annotations, disclosing the non-permanent default behavior and the effect of the permanent flag. It also implies the tool is safe to preview via dryRun.
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?
Two sentences with zero waste. The primary action and scope are front-loaded, followed by the critical safety tip (dryRun) and the deletion destination nuance. Every sentence earns its place.
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 complexity (6 params, destructive nature) and that an output schema exists, the description covers all essential operational aspects: what it does, the default folder, the dryRun safeguard, and deletion behavior. Nothing an agent needs to call it correctly is missing.
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%, with each parameter having a meaningful description (e.g., dryRun 'count only, change nothing', targetFolder 'Required when action = move'). The description adds no new parameter details beyond what the schema already provides, so the baseline 3 is appropriate.
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 states the exact action ('Move or delete EVERY message from a sender') with a specific resource (sender address, folder) and clearly distinguishes it from single-message tools like mail_move and mail_delete. It also specifies the default folder, leaving no ambiguity about scope.
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?
It gives an explicit usage recommendation: 'Use dryRun: true first to learn how many messages match.' This is clear operational guidance. However, it does not explicitly name alternatives or state when to use this tool versus the single-message siblings, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an Outlook folder (at the root or under a parent). Idempotent: if a folder with the same name already exists it is returned without error. Example: { name: "Newsletters" } or { name: "2025", parent: "Invoices" }.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the folder to create | |
| parent | No | Parent folder (name, path or id). Root if omitted. |
| Name | Required | Description |
|---|---|---|
| folder | Yes | |
| created | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, and the description restates this with 'if a folder with the same name already exists it is returned without error.' While the description adds a slight detail ('without error'), it does not introduce new behavioral information beyond the annotation. Other behaviors (e.g., auth requirements, error on missing parent) are not disclosed.
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 three sentences with zero fluff: action, idempotency, and examples. It front-loads the core purpose and uses a compact, informative format that an agent can parse 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 simplicity (2 params, both documented), the presence of an output schema, and annotations covering idempotency and safety, the description covers everything an agent needs to invoke it correctly. No critical information is missing.
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 coverage is 100% and both parameters are described. The description adds concrete usage examples ('Newsletters', '2025' with parent 'Invoices') that clarify how to structure calls, which goes beyond the schema's terse descriptions and helps an agent compose correct inputs.
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 states a specific verb ('Create'), a resource ('Outlook folder'), and scope ('at the root or under a parent'). It clearly differentiates from siblings like mail_list_folders and mail_move by its action, leaving no ambiguity about what the tool does.
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 tool (creating folders) and includes practical examples. It does not explicitly name alternatives or exclusions, but the purpose is so distinct among siblings that an agent can infer usage without confusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete one or more messages (up to 500 ids). By default messages go to Deleted Items (recoverable with mail_search folder=deleteditems then mail_move; their id changes). permanent: true deletes irreversibly: only use it when the user explicitly asks for it.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | Message ids (1 to 500) | |
| permanent | No | true = permanent deletion (irreversible). Default: Deleted Items. |
| Name | Required | Description |
|---|---|---|
| moved | No | |
| failed | Yes | |
| succeeded | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the irreversible nature of permanent deletion and the recoverability of default deletion. Annotations already mark destructive and idempotent, but the description adds concrete details about the default behavior and recovery path.
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?
Two concise sentences, each packed with essential information. No redundant words or unnecessary details.
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 complexity, it covers all key aspects: action, limits, default vs permanent behavior, recovery, and idempotency. The output schema exists but is not needed for the description to be 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 descriptions cover both ids and permanent with constraints. The description reinforces these by explaining the effect of permanent and the recovery mechanism, adding value beyond the schema.
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?
Clearly states the action (delete) and the resource (messages), with a specific limit of up to 500 ids. It implicitly distinguishes from sibling tools like mail_move and mail_search.
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?
Explicitly explains the default behavior (move to Deleted Items) versus permanent deletion, and notes recovery via mail_search and mail_move. It also instructs to use permanent only when explicitly requested, providing clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the full content of one message (body converted to text, recipients, attachment flag, web link) plus the unsubscribe options found in its headers (https, mailto, one-click). The body is truncated at 25,000 characters.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Message id (from mail_search or mail_senders_summary) |
| Name | Required | Description |
|---|---|---|
| to | Yes | |
| body | Yes | |
| message | Yes | |
| webLink | No | |
| truncated | Yes | |
| unsubscribe | Yes | |
| hasAttachments | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds meaningful behavioral details beyond that: body is converted to text, truncated at 25,000 characters, and includes unsubscribe options from headers. This provides concrete expectations about output format and limits, adding value without contradicting annotations.
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 two sentences with no filler. The first sentence front-loads the primary purpose and lists what is returned; the second sentence adds the truncation limit. Every piece of information earns its place, and the structure is efficient and scannable.
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 single-parameter schema, the presence of an output schema, and annotations covering safety and idempotency, the description provides all essential context: what content is returned, how it's formatted, and the truncation limit. No additional information is needed for correct invocation, so it is complete for this tool's complexity.
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 baseline is 3. The description does not add any parameter-specific information beyond the schema; it never mentions the 'id' parameter or its format. The schema already documents that the id comes from mail_search or mail_senders_summary, so the description adds no extra semantic 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 states a clear verb ('Return') and resource ('full content of one message'), and enumerates specific included elements (body as text, recipients, attachment flag, web link, unsubscribe options). This distinguishes it from siblings like mail_search (which lists messages) and mail_unsubscribe (which acts on subscriptions). The purpose is unambiguous and specific.
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 does not explicitly state when to use this tool versus alternatives, nor does it name any exclusions. However, it implies usage for retrieving a single message's full details after locating an id via mail_search or mail_senders_summary. The contrast with siblings is inferable but not spelled out, so the guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every folder of the Outlook.com mailbox with its path, total message count and unread count. Call it before filing messages to learn which folders exist. Other tools accept a folder by display name ("Invoices"), by path ("Archive/2024"), by well-known name (inbox, deleteditems, junkemail, archive) or by id.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| folders | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety. The description adds value by specifying the returned fields and the relationship to other tools' folder-identification formats. No contradictions; it doesn't address potential performance or pagination, but for a read-only list tool this is minor.
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?
Two sentences with no fluff. The primary action and output are front-loaded, followed by targeted usage context. Every sentence earns its place.
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 zero-parameter, read-only tool with an output schema and safety annotations, the description is complete. It states what it returns, when to call it, and how the results integrate with sibling tools. Nothing essential is missing.
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 tool has zero parameters, so the schema covers everything (coverage 100%). The description doesn't need to explain parameters, and it doesn't attempt to—correctly leaving that to the schema. Baseline for no parameters is 4.
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), the resource (every folder of the Outlook.com mailbox), and the specific output (path, total message count, unread count). It also distinguishes itself from sibling tools like mail_create_folder or mail_search by focusing on listing folders.
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?
It explicitly says 'Call it before filing messages to learn which folders exist,' giving a concrete use case. It also explains how other tools consume folder references (by name, path, well-known name, or id), implying this tool provides that mapping—effective guidance for when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move one or more messages (up to 500 ids) to a folder (name, path or id). Used for filing. NOTE: Outlook assigns a new id to every moved message; the moved result maps old id → new id. To move every message from a sender, prefer mail_bulk_by_sender.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | Message ids (1 to 500) | |
| folder | Yes | Destination folder |
| Name | Required | Description |
|---|---|---|
| moved | No | |
| failed | Yes | |
| succeeded | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly=false, destructive=false, and idempotentHint=true. The description adds critical behavioral context: Outlook assigns new ids and the result maps old to new. This goes beyond annotations and is essential for interpreting results.
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 two sentences plus a note, all front-loaded with the main action and limit. The note about id reassignment is placed after the main action but is concise and high-value. Zero waste.
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 two simple parameters, the description covers the essential behavior (move, limit, folder format, id mapping) and the alternative for bulk moves. It doesn't mention error handling, but with an output schema present (though not shown) and moderate complexity, it's sufficient.
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 coverage is 100% (both parameters have descriptions), giving a baseline of 3. The description adds meaning beyond the schema by specifying that the folder parameter can be a name, path, or id, which is not in the schema's generic 'Destination folder' text.
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 'Move' and resource 'messages', with limits (up to 500 ids) and destination format (folder name/path/id). It explicitly differentiates from the sibling mail_bulk_by_sender by naming it, so an agent can distinguish without opening other schemas.
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?
It states the use case ('Used for filing') and gives an explicit exclusion: 'To move every message from a sender, prefer mail_bulk_by_sender.' This provides a clear when-to-use and when-not-to-use condition with the alternative named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List messages of a folder (Inbox by default), newest first, with filters: exact sender, date range, unread only. query runs a full-text search (subject, body, sender) and cannot be combined with the other filters. Returns a compact summary (id, sender, subject, date, preview); use mail_get_message for the full content. To page, pass cursor back verbatim. For a whole-mailbox view by sender, prefer mail_senders_summary.
| Name | Required | Description | Default |
|---|---|---|---|
| from | No | Exact sender address, e.g. news@example.com | |
| limit | No | Results per page (max 100) | |
| query | No | Full-text search (simple KQL). Exclusive with from/since/until/unreadOnly. | |
| since | No | Received on or after this date (ISO) | |
| until | No | Received on or before this date (ISO) | |
| cursor | No | Page cursor returned by a previous call | |
| folder | No | Folder (name, path, well-known name or id). Default: inbox | |
| unreadOnly | No | Only unread messages |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| items | Yes | |
| nextCursor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The read-only, idempotent, non-destructive behavior is already covered by annotations, and the description adds meaningful behavioral context: newest-first ordering, compact summary output, cursor pagination, default inbox, and full-text query exclusivity. It does not mention error cases or rate limits, but those are not required given the annotation coverage.
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 compact and front-loaded; the first sentence states the core purpose and defaults, and each subsequent sentence adds a distinct useful fact (query behavior, return summary, pagination, sibling alternative). No unnecessary words or repetition.
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 an output schema is present, the description does not need to detail return fields, but it still mentions the compact summary. It covers defaults, filters, pagination, exclusivity, and sibling redirects, making it complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds extra semantic value beyond the schema: 'exact sender address' with an example, 'simple KQL' for query, exclusivity constraints, cursor reuse, and folder defaults. This goes well above 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 opens with a specific action and resource: 'List messages of a folder', and clarifies default sorting and filtering. It explicitly distinguishes itself from siblings by pointing to mail_get_message for full content and mail_senders_summary for a whole-mailbox-by-sender view.
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?
It states when to use the tool and when not to: use it for compact message listing/searching, use mail_get_message for full content, and prefer mail_senders_summary for whole-mailbox-by-sender. It also documents that the query filter is exclusive with the other filters, which is crucial usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
KEY TOOL FOR TRIAGE. Scans a whole folder (Inbox by default) and aggregates messages by sender: count, unread, latest message, and for the top senders the available unsubscribe method (oneClick / https / mailto). Sorted by volume. The scan is cached for the session. Follow up with mail_unsubscribe(lastMessageId) and mail_bulk_by_sender(address).
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Number of senders to return (max 200) | |
| since | No | Only count messages received since this date | |
| folder | No | Folder to analyse. Default: inbox |
| Name | Required | Description |
|---|---|---|
| scanned | Yes | |
| senders | Yes | |
| totalSenders | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the scan is cached for the session, which is useful behavioral information beyond the readOnly and idempotent annotations. It also clarifies that it scans a whole folder by default, implying no destructive or state-changing side effects. No contradiction exists with the provided annotations.
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 compact and informative, covering behavior, sorting, caching, and suggested follow-up actions. The opening phrase 'KEY TOOL FOR TRIAGE' is a minor stylistic flourish rather than essential information, but it does not detract much from overall clarity.
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, the description adequately covers the scanning behavior, default folder, summary fields, sorting, caching, and follow-up tools. Since an output schema exists, the description does not need to detail return structures, and no important context appears missing.
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 coverage for parameters is 100%, so the baseline is 3. The description mostly restates the folder default and does not add meaningful semantics beyond the schema descriptions for top, since, or folder. Thus the description does not significantly enhance parameter understanding.
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 that the tool scans a folder and aggregates messages by sender, which distinguishes it from siblings like mail_search, mail_get_message, and mail_bulk_by_sender. It also specifies the summary contents: count, unread, latest message, and unsubscribe method. This makes the tool's purpose 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 frames the tool as a key triage tool and suggests follow-up actions with mail_unsubscribe and mail_bulk_by_sender, giving useful workflow context. It does not explicitly state when to prefer this over mail_search or mail_list_folders, but the purpose is clear enough for an agent to choose appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Try to unsubscribe from the mailing list of a message, in order: (1) RFC 8058 one-click HTTPS POST, (2) automatic email to the List-Unsubscribe mailto address, (3) otherwise returns method: "browser" with the URL to open in a browser to finish manually, (4) method: "none" when no header exists. Deletes nothing. Preferably pass the lastMessageId returned by mail_senders_summary.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Id of a representative message of the newsletter |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| url | No | |
| from | Yes | |
| detail | Yes | |
| mailto | No | |
| method | Yes | |
| subject | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description explains the exact attempt order (RFC 8058, email, browser, none), clarifies that it deletes nothing, and describes the return method. This adds significant behavioral context not present in annotations, and does not contradict them.
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 structured with a numbered list for the method attempts, and every sentence adds value: the method order, the 'deletes nothing' note, and the parameter preference. It is detailed without being verbose.
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 complexity (multi-step unsubscription), the description covers the full behavior, the return value possibilities, and the parameter source. The output schema presumably documents the return structure, and the description fills in the behavioral nuances. Nothing essential is missing.
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?
While the schema already fully describes the id parameter (100% coverage), the description adds practical context by recommending the lastMessageId from mail_senders_summary as the source, which helps the agent pick the right value. This goes beyond the schema's generic 'Id of a representative message'.
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 tool's purpose: unsubscribing from a mailing list, with a specific verb 'unsubscribe' and a resource 'mailing list of a message'. It distinguishes itself from sibling tools (list, search, move, delete) by focusing on unsubscription, and outlines a concrete method sequence.
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?
It provides clear context on when to use (for unsubscribing) and even recommends passing the lastMessageId from mail_senders_summary, which is useful guidance. However, it does not explicitly state when not to use it or name an alternative tool, so it stops short of full explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0mail_bulk_by_sendermail_create_foldermail_deletemail_get_messagemail_list_foldersmail_movemail_searchmail_senders_summarymail_unsubscribeScored across 9 tools
Each tool targets a clearly distinct operation: folders, individual message retrieval, search, sender aggregation, move/delete by ID, bulk by sender, and unsubscribe. Overlap between search and sender summary is explicitly addressed by their descriptions and intended use cases.
The mail_ prefix and snake_case style are consistent throughout, and most names use a verb_noun pattern. A few names like mail_senders_summary and mail_bulk_by_sender are noun/adjective phrases rather than clear verb-first names, which is a minor deviation.
Nine tools is a well-scoped count for a mailbox management server. Each tool covers a meaningful operation without redundancy or unnecessary bloat.
The toolset covers the core mailbox triage workflow well: search, read, summarize, move, delete, bulk-manage, and unsubscribe. Missing operations like folder deletion/renaming, sending messages, or marking messages as read are notable but do not break the primary use case.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Manage Microsoft 365 email, calendar, contacts and inbox rules via the Graph API with OAuth 2.0.
Read, send, file and search email in any Gmail, Microsoft 365 or IMAP mailbox, plus its calendar.
Permissioned access to Outlook, OneDrive and Teams via the user's own Microsoft account
Read email/chat conversations, messages, contacts and teams; draft, send and update threads.