What can you do with this server?

This server bridges AI agents with Apple Mail on macOS, enabling full email management via MCP tools: * Message Operations: Search, list, read, send, reply, forward, and manage threads. Support for attachments (list, save, fetch base64) and batch actions (delete, move, mark read/unread, flag/unflag up to 100 messages). * Draft & Scheduled Sends: Create, read, update, delete drafts with stable IDs; schedule future sends via launchd, with reschedule/cancel/resolve-status commands. * Mailbox & Account Management: List, create, rename, delete mailboxes; manage smart mailboxes (including auto-discovery for newsletters); list accounts and sending identities; set default identity. * Rules & Contacts: List, enable/disable, create, delete mail rules; search Contacts.app; save, list, get, and use email templates with placeholder substitution. * Diagnostics: Health check, full doctor diagnostic, mail statistics (per-account counts and recent activity), sync status. * Advanced (Opt-in): IMAP backend for fast server-side operations and push notifications (IDLE); SMTP transport for clean sending with Keychain-stored passwords; standalone CLI (apple-mail-send); multi-account support; MCP resources and prompts for triage, reply, and weekly summaries.

Which integrations are available for this server?

Integrates with Apple Mail on macOS, providing tools to manage emails, drafts, mailboxes, rules, contacts, and scheduled sends via AppleScript and MCP. Supports Gmail accounts via IMAP/SMTP for fast server-side searches, large mailbox handling, and clean MIME message sending, bypassing AppleScript limitations. Supports iCloud email accounts via IMAP/SMTP for improved performance and reliability over AppleScript alone.

How do I use Apple Mail?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Apple Mail check my inbox for unread messages" 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.

Apple Mail

by yu2001-s

Overview Schema Source Related Servers Score Discussions Admin

JavaScript

Local

Apple Mail

A self-contained Codex Plugin and Model Context Protocol (MCP) server for Apple Mail on macOS. It adds Gmail-like stable draft IDs, explicit sending identities, confirmation-gated sending, and persistent scheduled sends.

platform: macOS License: MIT MCP

What is This?

This server acts as a local bridge between Codex and Apple Mail. Once installed, you can ask Codex to:

"Check my inbox for unread messages"
"List my saved drafts and verify their From identities"
"Create a draft from my work alias"
"Schedule these reviewed drafts for tomorrow at 7:00 AM"
"Show the status of my scheduled sends"

Mail access and the scheduled-send registry stay local on the Mac.

Related MCP server: Errol-Mail

Quick Start

Install in Codex

codex plugin marketplace add yu2001-s/apple-mail
codex plugin add apple-mail@apple-mail-public

The Plugin contains its bundled MCP server, so installation does not depend on an npm package or a developer-specific absolute path. Open a new Codex task after installation so the tools and skill are reloaded.

On first use, macOS asks for permission to automate Mail.app. Allow the Codex host process that launched the Plugin.

Local development

corepack enable
pnpm install --frozen-lockfile
pnpm build:plugin
pnpm test

Configuring email (IMAP & SMTP)

The server works out of the box over AppleScript with no configuration. Two opt-in power features take a one-time setup:

Fast IMAP reads — server-side search, counts, and large-mailbox handling that AppleScript is too slow for (it times out on big Gmail mailboxes).
Clean SMTP sending — send-email submits clean MIME directly, avoiding the macOS 15+ Mail.app <blockquote> wrapping that otherwise makes sent mail look quoted/indented like a reply.

Both are driven by non-secret APPLE_MAIL_MCP_* settings — supplied via an env block or a config.json file (for hosts like Claude Desktop that strip env) — with passwords kept in the macOS Keychain, never in config.

👉 IMAP / SMTP Setup Guide — step-by-step: app passwords, Keychain, both config methods, multi-account, SMTP, verification with the doctor tool, and troubleshooting. Verify any time by running the doctor tool.

Requirements

macOS - Apple Mail and AppleScript are macOS-only
Node.js 20+ - Required for the MCP server
Apple Mail - Must have at least one account configured (iCloud, Gmail, Exchange, etc.)

Features

Messages

Feature	Description
List Messages	List messages with pagination, sender filter, date display
Search Messages	Search by sender, subject, content, date range, read/flagged status — across all accounts
Read Messages	Get full email content (plain text or HTML)
Send Email	Compose and send new emails (attach by file path or inline base64 content)
Send Serial Email	Mail merge — send personalized emails to a list of recipients with {{placeholder}} support
Create Draft	Save emails to Drafts folder (attach by file path or inline base64 content)
Reply	Reply to messages (with reply-all support)
Forward	Forward messages to new recipients
Get Thread	Group a conversation by normalized subject (across AppleScript or IMAP)
Mark Read/Unread	Change read status (single or batch)
Flag/Unflag	Flag or unflag messages (single or batch)
Delete Messages	Move messages to trash (single or batch)
Move Messages	Organize into mailboxes (single or batch)
List Attachments	View attachment metadata (name, type, size)
Save Attachment	Save attachments to disk
Fetch Attachment	Get an attachment's bytes as base64 (no disk write)

Read/list/get tools also return structured JSON (structuredContent) alongside the text, so agents can consume results without parsing prose.

Mailbox & Account Management

Feature	Description
List Mailboxes	Show all folders with message/unread counts
Create/Delete/Rename Mailbox	Full mailbox lifecycle management
List Accounts	Show configured accounts
Unread Count	Get unread counts per mailbox

Rules, Contacts & Templates

Feature	Description
List Rules	View all mail rules and their enabled status
Enable/Disable Rules	Toggle mail rules on or off
Create/Delete Rules	Create rules with conditions + actions, or delete by name
Search Contacts	Look up contacts from Contacts.app by name
Email Templates	Save, list, use, and delete reusable email templates (persisted to disk across restarts)

Diagnostics

Feature	Description
Health Check	Verify Mail.app connectivity
Doctor	Diagnose Mail permission, account state, and each IMAP/SMTP backend with actionable messages
Statistics	Message and unread counts per account, recently received stats
Sync Status	Check if Mail.app is actively syncing

MCP resources & prompts

Resources expose read-only context the client can attach without a tool call: mail://accounts, mail://templates, and mail://mailboxes/{account}. Prompts package common workflows: triage-inbox, compose-reply, weekly-summary.

Tool Reference

This section documents all available tools. AI agents should use these tool names and parameters exactly as specified.

Message Operations

`search-messages`

Search for messages matching criteria. Searches all accounts by default.

Parameter	Type	Required	Description
`query`	string	No	Text to search in subject/sender
`from`	string	No	Filter by sender email address
`subject`	string	No	Filter by subject line
`mailbox`	string	No	Mailbox to search in (omit to search all mailboxes)
`account`	string	No	Account to search in (omit to search all accounts)
`isRead`	boolean	No	Filter by read status
`isFlagged`	boolean	No	Filter by flagged status
`dateFrom`	string	No	Start date filter (e.g., "January 1, 2026")
`dateTo`	string	No	End date filter (e.g., "March 1, 2026")
`limit`	number	No	Max results, 1–500 (default: 50)

Large mailboxes & partial results. Apple Mail's AppleScript bridge cannot search very large IMAP/Gmail mailboxes (tens of thousands of messages) before the Apple Event times out — empirically even reading the newest 20 messages of a 44k-message mailbox takes ~45s. To avoid burning minutes only to return a misleading empty result, an unscoped (all-mailboxes) search skips mailboxes whose message count exceeds a threshold (default 5000), enforces a per-account time budget, and reports anything it skipped or that timed out rather than silently returning nothing. When coverage is incomplete the result includes an explicit warning, e.g.:

⚠️  Partial results — this is NOT a confirmed "no such mail":
  - skipped mailbox(es) too large to search via AppleScript: Gmail / All Mail (44287) — scope the search with `mailbox` + a `dateFrom`/`dateTo` window to target them

To search inside a large mailbox, scope the call with mailbox (and ideally a dateFrom/dateTo window). Tune or disable the skip threshold with the APPLE_MAIL_MAX_SEARCH_MAILBOX environment variable (default 5000; set to 0 to disable the guard and attempt every mailbox regardless of size). (#24)

`get-message`

Get the full content of a message.

Parameter	Type	Required	Description
`id`	string	Yes	Message ID
`preferHtml`	boolean	No	Return HTML source instead of plain text

Returns: Subject line and message body (plain text by default, HTML if preferHtml is true and HTML content is available).

Large messages / attachments: reading a full message routes through osascript, whose captured output buffer defaults to 64 MB. Override it with the APPLE_MAIL_MCP_MAX_BUFFER environment variable (in bytes) if you work with messages whose raw MIME (e.g. a large embedded attachment) exceeds that — a value below the message size makes the read fail with a buffer-overflow error rather than truncating (#27).

`read-message`

Read one message as a complete resource. It returns From/Reply-To/To/Cc/Bcc, date, account, mailbox, flags, both decoded plain-text and HTML bodies, attachment metadata, and the RFC Message-ID.

Set include_raw_mime: true only when exact header or MIME verification is needed; attachments make the source large. Use batch-read-messages to read up to 20 inspected message IDs without dropping individual failures.

`list-messages`

List messages in a mailbox.

Parameter	Type	Required	Description
`mailbox`	string	No	Mailbox name (omit to list from all mailboxes)
`account`	string	No	Account name
`limit`	number	No	Max messages, 1–500 (default: 50)
`offset`	number	No	Number of messages to skip, ≥ 0 (for pagination)
`from`	string	No	Filter by sender email address or name
`unreadOnly`	boolean	No	Only show unread messages

Returns: List of messages with ID, date, subject, and sender.

`send-email`

Send a new email immediately.

⚠️ Safety: Sends real mail immediately and cannot be unsent. Confirm the recipients, subject, and body with the user before calling.

Parameter	Type	Required	Description
`to`	string[]	Yes	Recipient addresses
`subject`	string	Yes	Email subject
`body`	string	Yes	Email body (plain text)
`html_body`	string	No	Optional HTML alternative; `body` remains the plain-text fallback
`cc`	string[]	No	CC recipients
`bcc`	string[]	No	BCC recipients
`from`	string	No	Exact `identity_id`, email, or formatted sender returned by `list-sending-identities`
`account`	string	No	Deprecated compatibility selector; do not pass together with `from`
`attachments`	(string \| {filename, contentBase64})[]	No	Up to 20 attachments: absolute file paths (e.g., `"/Users/me/report.pdf"`) and/or inline `{filename, contentBase64}` objects up to 25 MiB decoded each
`transport`	`"applescript"` \| `"smtp"`	No	Send transport. If omitted, SMTP is used automatically when configured (otherwise AppleScript). Pass `"smtp"` to require clean MIME, or `"applescript"` to force the Mail.app path — see SMTP transport

Example:

{
  "to": ["colleague@company.com"],
  "subject": "Meeting Tomorrow",
  "body": "Hi, just confirming our meeting at 2pm tomorrow.",
  "from": "me@company.com",
  "attachments": ["/Users/me/Documents/agenda.pdf"]
}

SMTP transport

On macOS 15+ (Sequoia/Tahoe), Mail.app wraps any AppleScript-injected body in <blockquote type="cite"> under the Apple-Mail-URLShareWrapperClass template, so emails sent through the default applescript transport render to recipients as if they were quoted/forwarded (Apple radar FB11734014, open since Ventura). The SMTP transport bypasses Mail.app entirely and submits clean MIME directly. Once SMTP is configured, send-email uses it automatically (no need to pass transport per call); pass transport: "applescript" to force the Mail.app path.

Two differences to know when SMTP is auto-preferred:

Direct send-email has no connector-managed Sent copy. The provider may save one automatically. IMAP-backed send-draft is different: it verifies the provider copy and appends one when needed, so Mail.app can sync it.
Sending identity and transport account are separate resources. Pass from using an identity returned by list-sending-identities. The connector resolves that identity to an authorized SMTP profile and refuses missing or ambiguous mappings instead of silently changing the sender.

Both plain-text and HTML bodies are supported — over SMTP an HTML body (CLI --html-body-file) is sent as multipart/alternative with the plain-text fallback.

Configure SMTP via environment variables on the MCP server. The password is read from the macOS Keychain by default, so no secret goes in config:

Variable	Required	Default	Description
`APPLE_MAIL_MCP_SMTP_HOST`	Yes	—	SMTP server hostname (e.g. `smtp.fastmail.com`)
`APPLE_MAIL_MCP_SMTP_USER`	Yes	—	SMTP username
`APPLE_MAIL_MCP_SMTP_PORT`	No	`465` if secure, else `587`	SMTP port
`APPLE_MAIL_MCP_SMTP_SECURE`	No	`false`	`true` for implicit TLS (port 465); otherwise STARTTLS
`APPLE_MAIL_MCP_SMTP_FROM`	No	= user	From address
`APPLE_MAIL_MCP_SMTP_ALLOWED_FROM`	No	—	Comma-separated sender aliases permitted as per-message From overrides
`APPLE_MAIL_MCP_SMTP_PASSWORD`	No	—	Password (if set, used instead of the Keychain)
`APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE`	No	= host	Keychain item service/server name
`APPLE_MAIL_MCP_SMTP_KEYCHAIN_ACCOUNT`	No	= user	Keychain item account
`APPLE_MAIL_MCP_SMTP_ACCOUNTS`	No	—	JSON array of additional profiles (`account`, `host`, `port`, `secure`, `user`, `from`, `allowedFrom`, Keychain references)

For multiple accounts or aliases, configure one profile per authenticated SMTP account. allowedFrom may be an array or comma-separated string:

[
  {
    "account": "Personal",
    "host": "smtp.mail.me.com",
    "port": 587,
    "user": "person@icloud.com",
    "from": "person@icloud.com",
    "allowedFrom": ["alias@icloud.com"],
    "keychainService": "smtp.mail.me.com",
    "keychainAccount": "person@icloud.com"
  }
]

Store that JSON as the value of APPLE_MAIL_MCP_SMTP_ACCOUNTS. Passwords should remain in Keychain rather than in the JSON.

Store the password in the Keychain once (an app-specific password for Gmail/ iCloud). A generic-password item with an explicit service name keeps it from colliding with the system mail account password, and matches APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE:

# Fastmail (Keychain service defaults to the host)
security add-internet-password -s smtp.fastmail.com -a you@example.com -w

# Gmail / Google Workspace, using a dedicated Keychain service name:
#   APPLE_MAIL_MCP_SMTP_HOST=smtp.gmail.com
#   APPLE_MAIL_MCP_SMTP_USER=you@gmail.com
#   APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE=apple-mail-mcp-smtp
security add-generic-password -s apple-mail-mcp-smtp -a you@gmail.com -w

Once the env vars are set, a plain send-email (no transport) already goes out clean:

{
  "to": ["colleague@company.com"],
  "subject": "Standings",
  "body": "Plain body — no blockquote wrapping."
}

`apple-mail-send` CLI (no MCP server required)

The package also installs an apple-mail-send binary — a standalone CLI over the same SMTP path, for cron jobs, scheduled tasks, and scripts that can't run an MCP session. It reads the identical APPLE_MAIL_MCP_SMTP_* env + Keychain config:

apple-mail-send \
  --from you@example.com --to colleague@company.com \
  --subject "Standings" --body-file /tmp/body.txt \
  [--html-body-file /tmp/body.html] [--attach /tmp/report.pdf]

Repeatable --to/--cc/--bcc/--attach; an --html-body-file is sent as a multipart/alternative alongside the plain --body-file. Exit codes follow sysexits.h: 0 success, 64 usage error, 66 unreadable body file, 78 SMTP not configured.

IMAP backend — opt-in

📘 For step-by-step setup (app passwords, Keychain, config methods, multi-account, upgrading, troubleshooting), see the IMAP / SMTP Setup Guide. The summary below is the reference; the guide is the walkthrough.

AppleScript runs search/list predicates client-side over the Apple Event bridge, which is slow and can time out (false-empty) on large Gmail/IMAP mailboxes (see #24), and its delete/rename mailbox and draft handlers don't work on server-side accounts at all (#42). When an account is configured for IMAP, the MCP routes to a server-side IMAP backend (#43) that is fast and correct on exactly those mailboxes. This is opt-in and additive: any account without IMAP configured behaves exactly as before (AppleScript).

What routes to IMAP when an account is IMAP-configured:

Read: search-messages, list-messages (server-side SEARCH, typically sub-second), and get-message.
Folder ops: create-mailbox, rename-mailbox, delete-mailbox — IMAP's CREATE/RENAME/DELETE succeed on the iCloud/Gmail/Workspace/Exchange mailboxes Mail.app's AppleScript bridge can't touch (#42).
Message mutations: mark-as-read/unread, flag-message/unflag-message, move-message, delete-message.
Batch mutations (2.1): batch-mark-as-read/unread, batch-flag/unflag-messages, batch-move-messages, batch-delete-messages — imap: ids are grouped by mailbox and applied as a single UID STORE/UID MOVE; numeric ids in the same batch still use AppleScript.
Counts & stats (2.1): get-unread-count and list-mailboxes use STATUS; get-mail-stats uses STATUS + SEARCH SINCE — authoritative and fast even on huge mailboxes. As of v2.6.0 these prefer IMAP whenever it's configured (see Read routing below), merging across accounts when no account is given.
Attachments (2.1): list-attachments, save-attachment, fetch-attachment use BODYSTRUCTURE + FETCH BODY[part] for imap: ids — faster and able to see MIME-embedded attachments AppleScript misses.
Threading (2.1): get-thread links a conversation via References/Message-ID (HEADER SEARCH) for an imap: seed, falling back to subject grouping otherwise.

Message ids are backend-tagged. The IMAP read path emits self-describing ids of the form imap:<token> (the token encodes the account, mailbox path, and UID). Pass that id back to get-message, a message mutation, a batch op, or the attachment/thread tools and it routes to IMAP automatically; bare numeric ids continue to use AppleScript. So an agent never has to know which backend a message came from — the id carries it.

Read routing (v2.6.0): reads PREFER direct IMAP whenever IMAP is configured. The read tools — search-messages, get-thread, list-messages, list-mailboxes, get-unread-count, get-mail-stats — now go to IMAP whenever any APPLE_MAIL_MCP_IMAP_* account is configured, not just when an explicit matching account is passed. There are three cases:

Explicit IMAP account — single-account IMAP (fast server-side path).
Explicit non-IMAP account — AppleScript (that account isn't on IMAP).
No account given — merge across all accounts: the query fans out over every configured IMAP account, and AppleScript runs only for the accounts no IMAP config covers (the account list is partitioned — accounts already served by IMAP are not re-scanned via AppleScript). If every Mail account is IMAP-configured, AppleScript is skipped entirely. The results are merged so no account is dropped. Message lists still de-duplicate as a safety net (preferring the IMAP copy, which carries the round-trippable imap: id) and sort newest-first; count tools (get-unread-count, get-mail-stats) count each account via exactly one backend so a coverage mismatch can never double- (or under-) count.
- Default mailbox is resolved per account. When you don't pin a mailbox, a fan-out search scopes each account to its own default — Gmail/Workspace to [Gmail]/All Mail, every other IMAP host (iCloud, etc.) to INBOX (since [Gmail]/All Mail is Gmail-only and selecting it elsewhere would silently drop that account). Pin a mailbox to search a wider scope on non-Gmail accounts.

If IMAP is not configured at all, every read behaves exactly as before (pure AppleScript). The three mailbox-write ops (create-mailbox, delete-mailbox, rename-mailbox) remain conservative — they route to IMAP only for an explicitly-named IMAP account, never on an omitted account.

Variable	Required	Default	Description
`APPLE_MAIL_MCP_IMAP_USER`	Yes	—	Login address; setting it enables IMAP
`APPLE_MAIL_MCP_IMAP_ACCOUNT`	No	= user	Mail account name to match for routing
`APPLE_MAIL_MCP_IMAP_HOST`	No	`imap.gmail.com`	IMAP server hostname
`APPLE_MAIL_MCP_IMAP_PORT`	No	`993`	IMAP port (993 = implicit TLS)
`APPLE_MAIL_MCP_IMAP_PASSWORD`	No	—	Password (if set, used instead of the Keychain)
`APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE`	No	—	Keychain item service/server name
`APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT`	No	= user	Keychain item account
`APPLE_MAIL_MCP_IMAP_ACCOUNTS`	No	—	JSON array of additional IMAP accounts for multi-account setups (see below)
`APPLE_MAIL_MCP_IMAP_IDLE`	No	`0`	Set `1` to enable IMAP IDLE push notifications (new-mail alerts) for every configured account
`APPLE_MAIL_MCP_IMAP_IDLE_MS`	No	`30000`	Idle timeout (ms) before a pooled IMAP connection is closed (`0` = never close)

Multiple IMAP accounts (C2): set APPLE_MAIL_MCP_IMAP_ACCOUNTS to a JSON array, e.g. [{"account":"Work","user":"me@co.com","host":"imap.co.com","keychainService":"imap.co.com"}]. Each entry accepts account, user, host, port, password, keychainService, keychainAccount. Calls route to the account matching their account argument (or the decoded imap: id), and each account keeps its own pooled connection.

As with SMTP, the password is read from the macOS Keychain by default (use an app-specific password for Gmail/Workspace/iCloud), so no secret goes in config. Gmail label semantics: common names (All Mail, Sent, Trash, Spam, Important, …) map to their [Gmail]/… IMAP paths automatically.

Note: IMAP connections are pooled — one kept-alive connection per account is reused across calls (verified with a NOOP, closed after APPLE_MAIL_MCP_IMAP_IDLE_MS of inactivity), so there's no per-call connection overhead (#50).
iCloud: set APPLE_MAIL_MCP_IMAP_HOST=imap.mail.me.com, APPLE_MAIL_MCP_IMAP_USER to your iCloud address, APPLE_MAIL_MCP_IMAP_ACCOUNT to the Mail account name (e.g. iCloud), and use an app-specific password (from appleid.apple.com) stored in the Keychain.

Connection footprint (playing nice with Gmail)

IMAP connections are a shared, capped resource: Gmail allows at most 15 simultaneous IMAP connections per account, and Apple Mail itself needs some of those slots. This server keeps its footprint small:

One pooled connection per account, reused across calls and closed after ~30s idle (tune with APPLE_MAIL_MCP_IMAP_IDLE_MS; 0 = never close). So a server that isn't actively serving IMAP calls holds zero connections.
IMAP IDLE is opt-in (APPLE_MAIL_MCP_IMAP_IDLE=1). When on, it adds one persistent connection per account (a long-lived watcher), on top of the pooled request connection — leave it off if you don't need push notifications.
Connections are dropped on shutdown — SIGINT/SIGTERM and stdin-EOF (the MCP client/parent going away). As of v2.6.1 the server also self-exits if it becomes orphaned (parent force-quit/crashed → reparented to launchd), polling every 30s, so it can't linger holding sockets after its session is gone.

The catch is multiple concurrent instances. A host like the Claude desktop app spawns a separate set of MCP servers per open conversation (and respawns them after a crash), so the footprint is per instance × accounts. With IDLE off, an idle instance trends to 0 connections; with many active conversations or IDLE on, the per-account total climbs toward Gmail's 15-connection cap and can starve Apple Mail of slots (→ intermittent "cannot connect"). If you hit that, close idle Claude conversations, keep APPLE_MAIL_MCP_IMAP_IDLE off unless you need push, and/or lower APPLE_MAIL_MCP_IMAP_IDLE_MS.

Configuration file (when the host strips `env`)

Some host apps (e.g. Claude Desktop) launch the MCP server with a scrubbed environment and ignore the env block in their server config, so there's no way to pass APPLE_MAIL_MCP_* settings through it. In that case, put them in a JSON file the host doesn't manage — APPLE_MAIL_MCP_CONFIG_FILE, or by default ~/Library/Application Support/apple-mail-mcp/config.json:

{
  "APPLE_MAIL_MCP_IMAP_USER": "you@gmail.com",
  "APPLE_MAIL_MCP_IMAP_HOST": "imap.gmail.com",
  "APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE": "imap.gmail.com",
  "APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT": "you@gmail.com",
  "APPLE_MAIL_MCP_IMAP_IDLE": "1"
}

The server reads it at startup and merges values into the environment without overriding anything already set there (so an explicit env still wins). Store only non-secret config here — passwords belong in the Keychain, never in this file.

Push notifications (IMAP IDLE) — opt-in

When APPLE_MAIL_MCP_IMAP_IDLE=1, the server opens a dedicated, long-lived connection to each configured IMAP account and watches its INBOX for new mail. On arrival it pushes two MCP notifications to the client (no polling by the client required):

notifications/message (logging) — a human-readable line, e.g. New mail in "Work": 2 new message(s) (INBOX now 1843).
notifications/resources/updated — for the affected account's resource mail://mailboxes/{account}, so a client subscribed to that resource knows to re-read it.

This requires an IMAP account to be configured (single-account env or APPLE_MAIL_MCP_IMAP_ACCOUNTS); accounts that only use AppleScript aren't watched. Detection is real-time via the IMAP IDLE EXISTS event where the server pushes it, with an automatic polling fallback for servers that don't. Dropped connections reconnect with backoff, and the watchers shut down cleanly on SIGINT/SIGTERM.

Enable it in your MCP client config alongside the IMAP settings:

{
  "mcpServers": {
    "apple-mail": {
      "command": "node",
      "args": ["/path/to/apple-mail-mcp/build/index.js"],
      "env": {
        "APPLE_MAIL_MCP_IMAP_USER": "you@gmail.com",
        "APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE": "imap.gmail.com",
        "APPLE_MAIL_MCP_IMAP_IDLE": "1",
      },
    },
  },
}

Note: this is most useful with clients that surface MCP logging messages or subscribe to resource-update notifications. Clients that ignore notifications are unaffected — the feature is opt-in and adds no behavior unless enabled.

`send-serial-email`

Send individual personalized emails to a list of recipients (mail merge). Each recipient receives their own email — recipients don't see each other. Supports {{placeholder}} tokens in both subject and body.

Parameter	Type	Required	Description
`recipients`	object[]	Yes	List of recipients, max 100 (see below)
`subject`	string	Yes	Email subject — use `{{Key}}` for placeholders
`body`	string	Yes	Email body — use `{{Key}}` for placeholders
`account`	string	No	Send from specific account
`delayMs`	number	No	Delay between sends in ms (default: 500, max 10000)

Each recipient object:

Field	Type	Required	Description
`email`	string	Yes	Recipient email address
`variables`	object	Yes	Key-value pairs for placeholder replacement

Example:

{
  "recipients": [
    { "email": "alice@example.com", "variables": { "Name": "Alice", "Company": "Acme" } },
    { "email": "bob@example.com", "variables": { "Name": "Bob", "Company": "Globex" } }
  ],
  "subject": "Hello {{Name}}!",
  "body": "Dear {{Name}},\n\nGreat to connect about {{Company}}.\n\nBest regards"
}

Returns: Per-recipient success/failure results with a summary count.

⚠️ Safety: Sends real mail immediately to every recipient and cannot be unsent. Confirm the recipient list, subject, and body with the user before calling.

`create-draft`

Save an email to Drafts without sending.

Parameter	Type	Required	Description
`to`	string[]	Yes	Recipient addresses
`subject`	string	Yes	Email subject
`body`	string	Yes	Email body (plain text)
`cc`	string[]	No	CC recipients
`bcc`	string[]	No	BCC recipients
`from`	string	No	Exact sending identity returned by `list-sending-identities`
`account`	string	No	Deprecated compatibility selector
`attachments`	(string \| {filename, contentBase64})[]	No	Up to 20 attachments: absolute file paths and/or inline `{filename, contentBase64}` objects up to 25 MiB decoded each

Returns: Stable draft_id, content revision, and actual From identity.

read-draft returns the current revision. Pass it back as expected_revision to update-draft and send-draft; the connector rejects the operation if Mail.app or an iPhone changed the draft after it was reviewed.

When the selected identity has an IMAP profile, the draft is stored as clean RFC 5322 MIME in that provider's Drafts mailbox. It therefore synchronizes with Mail.app and iPhone instead of existing only in a local compose window. update-draft supports targeted text/HTML edits plus:

attachments_to_add: the same path/inline-base64 format as create-draft.
attachment_names_to_remove: exact filenames to remove; omitted attachments are preserved byte-for-byte through the edit.

The stable draft_id does not change when an edit replaces the underlying IMAP message. send-draft submits the exact reviewed revision over the SMTP profile authorized for its From identity, verifies or appends the Sent copy, and removes the Drafts copy only after SMTP acceptance. Older drafts indexed through AppleScript remain readable for compatibility; full MIME/attachment editing requires an IMAP-backed draft.

If a network failure leaves the SMTP outcome uncertain, the draft is locked as needs_review to prevent an automatic duplicate. After manually checking Sent, use resolve-draft-send-status with the explicitly confirmed sent or not_sent outcome. That recovery tool records/unlocks state and never submits mail itself.

Scheduled draft sends

The draft API exposes stable draft_id values through list-drafts and read-draft. A reviewed batch can be scheduled with schedule-drafts:

{
  "draft_ids": ["apple-draft:00000000-0000-4000-8000-000000000001"],
  "send_at": "2026-07-29T07:00:00+08:00",
  "confirmed": true
}

send_at must be RFC 3339 with an explicit timezone. The tool installs a per-user launchd worker that checks every 30 seconds; if the Mac is asleep, an overdue job is processed after wake/login. This is a local scheduler, not Mail.app's native Send Later mailbox, because Mail does not expose Send Later in its public scripting dictionary.

Before sending, the worker re-reads the draft and verifies its exact reviewed revision, including HTML and attachments. A changed or missing draft fails without sending. A job is durably marked sending before Mail is called; after a worker crash it becomes needs_review and is not automatically retried, preventing accidental duplicates. Attached IMAP-backed drafts are supported; older AppleScript-backed attached drafts remain read-only in the connector.

list-scheduled-sends — inspect pending and terminal jobs.
reschedule-scheduled-send — change the time of a pending job.
cancel-scheduled-send — cancel a pending job; the draft remains in Drafts.

⚠️ Safety: scheduling creates a real future send. Confirm the exact drafts, recipients/content, From identity, time, and timezone before passing confirmed: true.

`get-thread`

Group a conversation by normalized subject (across the AppleScript or IMAP backend).

Parameter	Type	Required	Description
`id`	string	Yes	A message ID in the conversation (numeric or `imap:…`)
`account`	string	No	Account to search (omit to search all)
`mailbox`	string	No	Mailbox to search (omit to search all)
`limit`	number	No	Max messages in the thread (default 50)
`includeBodies`	boolean	No	Return complete message resources instead of summaries

Returns: The conversation's messages, oldest-first.

`fetch-attachment`

Return an attachment's bytes as base64 (the read counterpart to inline-base64 send).

Parameter	Type	Required	Description
`id`	string	Yes	Numeric message ID
`attachmentName`	string	Yes	Attachment filename (from `list-attachments`)

Returns: The attachment bytes, base64-encoded (also in structuredContent.contentBase64).

`reply-to-message`

Reply to an existing message.

Parameter	Type	Required	Description
`id`	string	Yes	Message ID to reply to
`body`	string	Yes	Reply body
`from`	string	No	Exact sending identity returned by `list-sending-identities`
`replyAll`	boolean	No	Reply to all recipients (default: false)
`send`	boolean	No	Send immediately (default: true, false = save as draft)

Example - Reply to sender only:

{
  "id": "12345",
  "body": "Thanks for the update!"
}

Example - Reply all, save as draft:

{
  "id": "12345",
  "body": "I'll review this and get back to everyone.",
  "replyAll": true,
  "send": false
}

Transport (v2.5.0): when SMTP is configured, reply-to-message sends via clean SMTP, threading the reply with proper RFC 5322 In-Reply-To/References headers (built from the original message) so it lands in the same conversation. When SMTP is not configured (or the original lacks the headers needed to thread), it falls back to Mail.app's AppleScript reply … without opening window — same reliable-from-background-process path as before. See SMTP transport.

⚠️ Safety: With the default send: true, sends real mail immediately and cannot be unsent. Confirm the recipients, subject, and body with the user before calling (or pass send: false to save a draft for review).

`forward-message`

Forward a message to new recipients.

Parameter	Type	Required	Description
`id`	string	Yes	Message ID to forward
`to`	string[]	Yes	Recipients to forward to
`body`	string	No	Message to prepend
`send`	boolean	No	Send immediately (default: true, false = save as draft)

Transport (v2.5.0): when SMTP is configured, forward-message sends via clean SMTP (a fresh message with the original quoted, no threading headers — a forward starts a new conversation). When SMTP is not configured it falls back to Mail.app's AppleScript forward … without opening window. See SMTP transport.

`mark-as-read` / `mark-as-unread`

Change read status of a message.

Parameter	Type	Required	Description
`id`	string	Yes	Message ID

`flag-message` / `unflag-message`

Flag or unflag a message. flag-message optionally takes a flag color; unflag-message removes the flag entirely (which also clears any color).

Parameter	Type	Required	Description
`id`	string	Yes	Message ID
`color`	string	No	(`flag-message` only) Flag color: `red`, `orange`, `yellow`, `green`, `blue`, `purple`, `gray` (`grey` accepted). Omit for Mail's default flag.

Flag colors are an Apple Mail feature, applied via AppleScript as the message's flag index (0 red, 1 orange, 2 yellow, 3 green, 4 blue, 5 purple, 6 gray) — the same property a Mail smart mailbox can match on. For an IMAP-routed message id (imap:…) the flag is still set, but the color is not applied, because IMAP's \Flagged flag is colorless. To color a flag, use the message's AppleScript (numeric) id.

`delete-message`

Delete a message (move to trash).

Parameter	Type	Required	Description
`id`	string	Yes	Message ID

⚠️ Safety: Destructive. Requires explicit user confirmation; search/list first to confirm the message id.

`move-message`

Move a message to a different mailbox.

Parameter	Type	Required	Description
`id`	string	Yes	Message ID
`mailbox`	string	Yes	Destination mailbox
`account`	string	No	Account containing mailbox

`list-attachments`

List attachments on a message.

Parameter	Type	Required	Description
`id`	string	Yes	Message ID

Returns: List of attachments with name, MIME type, and size.

`save-attachment`

Save a message attachment to disk.

Parameter	Type	Required	Description
`id`	string	Yes	Message ID
`attachmentName`	string	Yes	Filename of the attachment
`savePath`	string	Yes	Directory to save to

Batch Operations

All batch operations accept an array of message IDs (max 100 per batch) and return per-item success/failure results.

`batch-delete-messages`

Parameter	Type	Required	Description
`ids`	string[]	Yes	Message IDs to delete (max 100)

⚠️ Safety: Destructive. Requires explicit user confirmation; search/list first to confirm the message ids.

`batch-move-messages`

Parameter	Type	Required	Description
`ids`	string[]	Yes	Message IDs to move (max 100)
`mailbox`	string	Yes	Destination mailbox
`account`	string	No	Account containing mailbox

`batch-mark-as-read` / `batch-mark-as-unread`

Parameter	Type	Required	Description
`ids`	string[]	Yes	Message IDs (max 100)

`batch-flag-messages` / `batch-unflag-messages`

Parameter	Type	Required	Description
`ids`	string[]	Yes	Message IDs (max 100)
`color`	string	No	(`batch-flag-messages` only) Flag color applied to AppleScript (numeric) ids — see `flag-message`. Any `imap:` ids in the batch are flagged but not colored.

Mailbox Operations

`list-mailboxes`

List all mailboxes for an account.

Parameter	Type	Required	Description
`account`	string	No	Account to list from

Returns: List of mailbox names with message and unread counts.

`get-unread-count`

Get unread message count.

Parameter	Type	Required	Description
`mailbox`	string	No	Mailbox to check (omit for total)
`account`	string	No	Account to check

`create-mailbox`

Create a new mailbox.

Parameter	Type	Required	Description
`name`	string	Yes	Mailbox name
`account`	string	No	Account to create in

`delete-mailbox`

Delete a mailbox.

Parameter	Type	Required	Description
`name`	string	Yes	Mailbox name
`account`	string	No	Account containing mailbox

⚠️ Safety: Destructive — deletes the mailbox and its contents. Requires explicit user confirmation; list mailboxes first to confirm the name.

`rename-mailbox`

Rename a mailbox (creates new, moves messages, deletes old).

Parameter	Type	Required	Description
`oldName`	string	Yes	Current mailbox name
`newName`	string	Yes	New mailbox name
`account`	string	No	Account containing mailbox

Smart Mailbox Operations (intelligente Postfächer)

Smart mailboxes are Apple Mail's criteria-based virtual views — not real folders, so no messages are moved. AppleScript's smart mailbox / intelligentes Postfach terms don't compile reliably on localized (e.g. German) macOS, so these tools read and edit ~/Library/Mail/V*/MailData/SyncedSmartMailboxes.plist directly.

How writes stay safe: creating or deleting a smart mailbox first backs the plist up to SyncedSmartMailboxes.plist.bak, edits a temp copy with plutil/PlistBuddy, validates it with plutil -lint, and only then atomically renames it into place. Your existing smart mailboxes — including any with date/data criteria — are never rewritten, only the single target entry is added or removed. These tools do not quit or restart Mail: quit Mail first for reliable results, since a running Mail may not show a new smart mailbox until it's relaunched and can overwrite plist edits it didn't make.

`list-smart-mailboxes`

List existing smart mailboxes.

Parameters: None

Returns: List of smart mailbox names + criteria summary.

`create-smart-mailbox`

Create a smart mailbox with a simple contains rule.

Parameter	Type	Required	Description
`name`	string	Yes	Name for the smart mailbox
`fromContains`	string	No	Match if From contains this
`subjectContains`	string	No	Match if Subject contains this
`bodyContains`	string	No	Match if Body contains this

Provide at least one of the three *Contains fields.

⚠️ Safety: edits SyncedSmartMailboxes.plist (backed up + atomic, existing smart mailboxes preserved). Quit Mail first for reliable results; the new smart mailbox appears the next time Mail launches.

`delete-smart-mailbox`

Delete a smart mailbox by name.

Parameter	Type	Required	Description
`name`	string	Yes	Smart mailbox name

⚠️ Safety: destructive — removes the smart mailbox from SyncedSmartMailboxes.plist (backed up + atomic; every other smart mailbox is preserved). Not undoable in-app. Confirm the exact name with list-smart-mailboxes first, and quit Mail first for reliable results.

`create-newsletter-smart-mailboxes`

High-level tool: scan recent messages in your INBOXes, detect likely newsletters (volume + signals like List-Unsubscribe, noreply, repetitive subjects), and create smart mailboxes for them (names prefixed "NL: ...").

Parameter	Type	Required	Description
`dryRun`	boolean	No	Default true — only propose, do not create
`minCount`	number	No	Min messages from a sender (default 3)
`days`	number	No	Lookback window in days (default 90)

Defaults to a safe dry run that only proposes. Pass dryRun: false to actually create the smart mailboxes for newsletters cluttering your Inbox.

⚠️ Safety: with dryRun: false this edits SyncedSmartMailboxes.plist (backed up + atomic, existing entries preserved) and can create many smart mailboxes at once — review a dry run first. Scans up to ~400 recent messages per inbox via AppleScript, which can be slow on large mailboxes.

Account Operations

`list-accounts`

List all configured Mail accounts.

Parameters: None

Returns: List of account names and email addresses.

Rules

`list-rules`

List all mail rules.

Parameters: None

Returns: List of rule names and enabled status.

`enable-rule` / `disable-rule`

Enable or disable a mail rule.

Parameter	Type	Required	Description
`name`	string	Yes	Rule name

`create-rule`

Create a Mail rule with one or more conditions and actions.

Parameter	Type	Required	Description
`name`	string	Yes	Rule name (must be unique)
`conditions`	object[]	Yes	One or more `{field, operator, value}` (see below)
`actions`	object	Yes	At least one of `markRead`, `markFlagged`, `delete`, `moveTo`
`matchAll`	boolean	No	`true` (default) = all conditions must match; `false` = any
`enabled`	boolean	No	Whether the rule is enabled on creation (default `true`)

Each condition is { field, operator, value } where field is one of from, to, cc, subject, content and operator is one of contains, notContains, equals, beginsWith, endsWith. Actions: markRead / markFlagged / delete (booleans), moveTo (mailbox name) with optional moveToAccount.

Example:

{
  "name": "Newsletters",
  "conditions": [{ "field": "from", "operator": "contains", "value": "newsletter" }],
  "actions": { "markRead": true, "moveTo": "Reading" }
}

`delete-rule`

Delete a mail rule by name.

Parameter	Type	Required	Description
`name`	string	Yes	Rule name

⚠️ Safety: Destructive. Requires explicit user confirmation; list rules first to confirm the name.

Contacts

`search-contacts`

Search contacts in Contacts.app.

Parameter	Type	Required	Description
`query`	string	Yes	Name to search for
`limit`	number	No	Max results (default: 10)

Returns: List of contacts with name, email addresses, and phone numbers.

Templates

Email templates are persisted to disk so they survive server restarts, stored as JSON at APPLE_MAIL_MCP_TEMPLATES_FILE (default ~/Library/Application Support/apple-mail-mcp/templates.json).

`save-template`

Save or update an email template.

Parameter	Type	Required	Description
`name`	string	Yes	Template name
`subject`	string	Yes	Default subject line
`body`	string	Yes	Template body
`to`	string[]	No	Default recipients
`cc`	string[]	No	Default CC recipients
`id`	string	No	Template ID (for updating)

`list-templates`

List all saved templates.

Parameters: None

`get-template`

Get a template by ID.

Parameter	Type	Required	Description
`id`	string	Yes	Template ID

`delete-template`

Delete a template.

Parameter	Type	Required	Description
`id`	string	Yes	Template ID

⚠️ Safety: Destructive — removes the template from the on-disk store. Requires explicit user confirmation; list templates first to confirm the id.

`use-template`

Create a draft from a template, with optional overrides.

Parameter	Type	Required	Description
`id`	string	Yes	Template ID
`to`	string[]	No	Override recipients
`cc`	string[]	No	Override CC
`subject`	string	No	Override subject
`body`	string	No	Override body

Diagnostics

`health-check`

Verify Mail.app connectivity and permissions.

Parameters: None

Returns: Status of all health checks (app running, permissions, account access).

`doctor`

Run a full setup diagnostic: Mail.app automation permission, account state (flagging disabled accounts), and each configured IMAP/SMTP backend — each reported as ok / warn / fail with an actionable message.

Parameters: None

Returns: A per-check report (structuredContent carries the raw {healthy, checks[]}).

`get-mail-stats`

Get mail statistics.

Parameters: None

Returns: Total and per-account message/unread counts, plus recently received stats (24h, 7d, 30d).

`get-sync-status`

Check Mail.app sync activity.

Parameters: None

Returns: Whether sync is detected, pending uploads, recent activity, and seconds since last change.

Usage Patterns

Basic Workflow

User: "Check my inbox for new emails"
AI: [calls list-messages]
    "You have 12 messages. Here are the most recent..."

User: "Show me emails from Sarah"
AI: [calls search-messages with query="Sarah"]
    "Found 3 emails from Sarah across all mailboxes..."

User: "Read the first one"
AI: [calls get-message with id="..."]
    "Subject: Project Update..."

Working with Accounts

By default, operations use Mail.app's configured default send account. Search operations check all accounts when no account is specified. To work with specific accounts:

User: "What email accounts do I have?"
AI: [calls list-accounts]
    "You have 3 accounts: iCloud, Gmail, Work Exchange"

User: "Show unread emails in my Work account"
AI: [calls list-messages with account="Work Exchange", mailbox="INBOX"]
    "Your Work account has 5 unread messages..."

To pin which account is used when a tool call omits account, set the APPLE_MAIL_MCP_DEFAULT_ACCOUNT environment variable to an account name or email. When unset (the default), the server falls back to Mail.app's default-send account if it is enabled, otherwise the first enabled account. A disabled account is never selected implicitly — this env var (an explicit, deliberate pin) is one of the few ways to target one (#47).

Sending Emails Safely

User: "Draft an email to the team about the deadline"
AI: [calls create-draft with to=["team@..."], subject="...", body="..."]
    "I've created a draft. Please review it in Mail.app before sending."

User: "Send it"
AI: [User opens Mail.app and sends manually, or AI calls send-email]

Sending Personalized Emails (Mail Merge)

User: "Send a personalized email to Alice (alice@acme.com), Bob (bob@globex.com),
       and Carol (carol@initech.com). Subject: 'Project Update for {{Company}}',
       Body: 'Hi {{Name}}, here is the latest update for {{Company}}.'"
AI: [calls send-serial-email with recipients, subject template, and body template]
    "Successfully sent 3 email(s):
      - alice@acme.com: sent
      - bob@globex.com: sent
      - carol@initech.com: sent"

Organizing Messages

User: "Move all newsletters to Archive"
AI: [calls search-messages to find newsletters]
AI: [calls move-message for each, with mailbox="Archive"]
    "Moved 8 newsletters to Archive"

Running from source

git clone https://github.com/yu2001-s/apple-mail.git
cd apple-mail
corepack enable
pnpm install --frozen-lockfile
pnpm build:plugin

The repository ships prebuilt bundles for both local development and the Codex Plugin. Re-run pnpm build:plugin after changing server source.

If installed from source, use this configuration:

{
  "mcpServers": {
    "apple-mail": {
      "command": "node",
      "args": ["/path/to/apple-mail/build/index.js"]
    }
  }
}

Running from a clone in Claude Code (project-scope `.mcp.json`)

This repo ships a .mcp.json at its root so that, when you run claude from inside a clone, the server is registered automatically as a project-scope server — no manual config needed. Just launch Claude Code from the repo directory and approve the server when prompted (the bundled build/index.js is committed, so no build step is required).

The entrypoint is written as:

"args": ["${CLAUDE_PROJECT_DIR:-.}/build/index.js"]

CLAUDE_PROJECT_DIR is the variable Claude Code injects into a project/user-scoped server's environment, and it resolves to the repo root. You must launch claude from inside the repo for this to work — the bare . fallback is only a last resort and is not reliable, because it resolves against the launching process's working directory, not the repo.

Why not ${CLAUDE_PLUGIN_ROOT}? CLAUDE_PLUGIN_ROOT is set only for marketplace plugin installs, never for a project-scope clone, so it can't drive the clone workflow. Conversely, a plugin install can't use CLAUDE_PROJECT_DIR (in a plugin, that points at the user's project, not the plugin's own directory). Claude Code does not support nested defaults like ${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-.}}, so a single entrypoint string cannot serve both contexts. The two distribution paths are therefore decoupled: the plugin carries its own MCP config in .claude-plugin/plugin.json (using ${CLAUDE_PLUGIN_ROOT}), while the root .mcp.json is dedicated to the clone workflow (using ${CLAUDE_PROJECT_DIR:-.}). Because plugin.json declares its own mcpServers, the plugin does not also auto-load the root .mcp.json, so there is no double-registration.

Heads-up on scope precedence: project-scope (.mcp.json) outranks user-scope. If you also have an apple-mail entry registered at user scope (e.g. an absolute path in ~/.claude.json), the project-scope entry wins and the user-scope one is ignored entirely. Pick one — for local development on this repo, the project-scope .mcp.json is the intended source. To pin a specific local build instead, register it at local scope (claude mcp add apple-mail -s local -- node /abs/path/build/index.js), which outranks project scope.

Security and Privacy

Local only - All operations happen locally via AppleScript. No data is sent to external servers.
Permission required - macOS will prompt for automation permission on first use.
No credential storage - The server doesn't store any passwords or authentication tokens.
Email safety - Use create-draft to review emails before sending.

Known Limitations

Limitation	Reason
macOS only	Apple Mail and AppleScript are macOS-specific
MCP `send-email` is plain-text	The `send-email` tool sends plain text (reading HTML content is supported). To send HTML, use the bundled `apple-mail-send` CLI with `--html-body-file` (sends `multipart/alternative` via SMTP)
Attachments require absolute paths	File attachments must use full absolute paths (e.g., `/Users/me/file.pdf`)
No smart mailboxes	Cannot access Smart Mailboxes via AppleScript
Very large mailboxes not searchable via AppleScript	Apple Mail's AppleScript bridge times out on mailboxes with tens of thousands of messages, so unscoped `search-messages` skips mailboxes above `APPLE_MAIL_MAX_SEARCH_MAILBOX` (default 5000) and reports them as a partial result. Scope with `mailbox` + a date window — or configure the IMAP backend, which searches these server-side in well under a second. (#24)
Can't delete/rename server-side mailboxes or mutate drafts via AppleScript	Mail.app's AppleScript bridge can only `delete`/`rename` local "On My Mac" mailboxes and cannot delete/move drafts — it throws `AppleEvent handler failed` for IMAP/Gmail/Workspace/iCloud/Exchange mailboxes (the GUI can do it). Without IMAP configured, `delete-mailbox`/`rename-mailbox`/`delete-message`/`move-message` return a clear "do it in Mail.app directly" error instead of a generic failure. With the IMAP backend configured for the account, these operations run via IMAP and succeed. (#42)
Message ID format	Message IDs must be numeric (AppleScript ids) or `imap:…` tokens from the IMAP read path (validated by schema)
Batch size cap	Batch operations are limited to 100 messages per request
Date filter format	Date filters must be valid parseable dates (e.g., "January 1, 2026" or "2026-03-15"); bare numbers or non-date strings are rejected
Attachment save path restrictions	`save-attachment` only allows saving to home directory, `/tmp`, `/private/tmp`, and `/Volumes`; path traversal is blocked
Attachment count limit	`send-email` and `create-draft` accept a maximum of 20 file attachments

Mail.app `<blockquote>` wrapping on macOS 15+ (workaround in v1.6.0)

On macOS 15+ Mail.app wraps AppleScript-injected message bodies in <blockquote type="cite"> under the Apple-Mail-URLShareWrapperClass template, so mail sent via the default applescript transport renders to recipients as quoted/forwarded content (Apple radar FB11734014, open since Ventura, no fix). Since v1.6.0, send-email accepts transport: "smtp" to bypass Mail.app and send clean MIME directly — see SMTP transport. The AppleScript path is still the default and still exhibits Apple's wrapping. (#12)

Reply / Forward from Background Processes (Fixed in v1.4.0)

Prior to v1.4.0, reply-to-message and forward-message would send messages with empty body text when the MCP server ran as a background process (e.g., spawned via execSync from Node.js, which is how Claude Code invokes it).

Root cause: The AppleScript reply msg with opening window command creates a GUI compose window asynchronously. When set content runs immediately after, the window may not be ready, and the content assignment is silently ignored. Delays (delay 1, delay 2) were unreliable — the compose window's readiness depends on system load, Mail.app state, and whether the process has GUI access.

Fix: Replaced with opening window with without opening window for both reply and forward commands. With this approach, set content works immediately and reliably from background processes. In-Reply-To and References headers are still set correctly by Mail.app, and no GUI compose window is opened.

Update (v2.5.0): when SMTP is configured, reply-to-message and forward-message now prefer clean direct SMTP instead of AppleScript — the same prefer-direct model as send-email. Replies are threaded with RFC 5322 In-Reply-To/References headers built from the original message; forwards start a new conversation. The AppleScript without opening window path above remains the fallback when SMTP is not configured (or, for replies, when the original message lacks the headers needed to thread).

See #7 for full details and the list of approaches that were tested.

Backslash Escaping (Important for AI Agents)

When sending content containing backslashes (\) to this MCP server, you must escape them as \\ in the JSON parameters.

Why: The MCP protocol uses JSON for parameter passing. In JSON, a single backslash is an escape character. To include a literal backslash in content, it must be escaped as \\.

Example - Email with file path:

{
  "to": ["colleague@company.com"],
  "subject": "File Location",
  "body": "The file is at C:\\\\Users\\\\Documents\\\\report.pdf"
}

The \\\\ in JSON becomes \\ in the actual string, which represents a single \ in the email.

Common patterns requiring escaping:

Windows paths: C:\Users\ → C:\\\\Users\\\\ in JSON
Shell escaped spaces: Mobile\ Documents → Mobile\\\\ Documents in JSON
Regex patterns: \d+ → \\\\d+ in JSON

If you see errors when sending emails with backslashes, double-check that backslashes are properly escaped in the JSON payload.

Troubleshooting

"Mail.app not responding"

Ensure Mail.app is not frozen
Try opening Mail.app manually
Restart the MCP server

"Permission denied"

macOS needs automation permission
Go to System Settings > Privacy & Security > Automation
Ensure your terminal/Claude has permission to control Mail

"Message not found"

Message may have been deleted or moved
Message IDs change if the message is moved between mailboxes
Use search-messages to find the current message ID

`search-messages` says "Partial results" or skips a mailbox

This is expected for very large IMAP/Gmail mailboxes (e.g. Gmail's All Mail, Important): Apple Mail can't scan them via AppleScript before timing out, so they're skipped and named in the result rather than silently returning empty.
To search inside one, scope the call with mailbox and a dateFrom/dateTo window.
Raise or disable the threshold with APPLE_MAIL_MAX_SEARCH_MAILBOX (default 5000; 0 disables the guard) — note that disabling it can make a single search take minutes.
A Partial results warning means coverage was incomplete; it is not a confirmed "no such mail."

"Account not found"

Account names must match exactly (case-sensitive)
Use list-accounts to see exact account names

"Failed to send email"

Check your network connection
Verify Mail.app can send emails manually
Check if the account is configured correctly in Mail.app

`apple-mail` server fails to connect when run from a clone

The root .mcp.json resolves its entrypoint via ${CLAUDE_PROJECT_DIR:-.}/build/index.js. Launch claude from inside the repo directory — CLAUDE_PROJECT_DIR only resolves to the repo root in that case; the bare . fallback uses the launching shell's working directory and will point at the wrong place otherwise.
If you've been editing the source, rerun npm run build — the server is build/index.js, and the committed bundle only reflects your changes after a rebuild.
Run claude mcp list to check status. If you see a conflicting scopes warning for apple-mail, you have it registered at more than one scope; project-scope wins. See Running from a clone for how scope precedence resolves.
If claude mcp get apple-mail shows ⏸ Pending approval, approve the project-scope server (Claude Code prompts on startup, or run it again after approving).

Development

npm install            # Install dependencies
npm run build          # Typecheck, then bundle src/index.ts + src/cli.ts into build/ (esbuild)
npm test               # Run unit tests
npm run test:integration  # Run integration tests (requires Mail.app)
npm run test:all       # Run all tests (unit + integration)
npm run lint           # Check code style
npm run format         # Format code

Acknowledgements

This project is derived from sweetrb/apple-mail-mcp, created by Rob Sweet and released under the MIT License. The original copyright notice is preserved.

License

MIT License — see LICENSE for details.

Contributing

Contributions are welcome. See CONTRIBUTING.md.

Recurring macOS permission prompts

If macOS keeps re-prompting for Full Disk Access or Automation for node (often after a brew upgrade), see docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md.

Available Tools

61 tools

batch-delete-messagesA

Use when: deleting multiple messages in one call (1–100 ids; moves them to Trash). Returns: counts of how many were deleted and how many failed. Do not use when: deleting just one (use delete-message) or filing messages away (use batch-move-messages). Safety: destructive and applies to many messages at once — require explicit user confirmation, and search-messages/list-messages first to confirm every id is correct before deleting.

ParametersJSON Schema

Name	Required	Description	Default
`ids`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`failed`	No
`mailbox`	No
`success`	No

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses destructive nature, moves to Trash, requires user confirmation, and suggests prior message verification. Returns counts of deleted and failed. Lacks mention of authorization requirements but overall thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is structured with clear sections (use, do not use, safety, returns). Front-loaded with purpose. Slightly verbose in safety section but overall well-organized and concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, guidelines, safety, and return values. With output schema present, explanation of return values is adequate. Could mention partial failure handling or idempotency, but sufficient for a batch delete tool among many siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter 'ids'. Schema already specifies array of strings with pattern and min/max. Description adds that it's multiple messages and they are moved to Trash, but doesn't elaborate on the nature of IDs (e.g., message IDs). With 0% schema description coverage, some extra context is provided, but not fully compensating.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it deletes multiple messages in one call, distinguishing from delete-message (single) and batch-move-messages (filing). The verb 'deleting' and resource 'multiple messages' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use when: deleting multiple messages in one call' and 'Do not use when: deleting just one (use delete-message) or filing messages away (use batch-move-messages)'. Provides clear context and alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

batch-flag-messagesA

Use when: flagging multiple messages (1–100 ids) in one call, optionally with a color (red/orange/yellow/green/blue/purple/gray). Returns: counts of how many were flagged and how many failed. Do not use when: flagging just one (use flag-message) or removing flags (use batch-unflag-messages). Get the ids from search-messages or list-messages first. Note: flag colors are applied via Mail.app (AppleScript); any IMAP-routed ids in the batch are flagged but not colored (IMAP flags are colorless).

ParametersJSON Schema

Name	Required	Description	Default
`ids`	Yes
`color`	No	Optional flag color (Apple Mail palette: red, orange, yellow, green, blue, purple, gray — 'grey' accepted). Omit for Mail's default flag. Colors are applied via Mail.app (AppleScript); for an IMAP-routed message id the flag is set but the color is not applied (IMAP flags are colorless).

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`failed`	No
`mailbox`	No
`success`	No

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It discloses that colors are applied via Mail.app (AppleScript) and that IMAP-routed ids are flagged but not colored. It also states the return value: counts of flagged and failed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences in a single paragraph. Clear and front-loaded with the main action. Could be slightly more structured (e.g., bullet points) but is efficient and readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers prerequisites, return value, and color behavior nuance. An output schema exists but is not shown; the description fills in the return format. Still, could mention how to interpret the counts or error handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Two parameters with 50% schema description coverage. The description adds context: explains the color enum values and notes that IMAP ids get colorless flags. For ids, it mentions the range (1-100) already in schema but adds guidance on sourcing ids.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool batches flagging of multiple messages (1-100 ids), optionally with a color. It explicitly distinguishes from single-flag and unflag tools, leaving no ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use (flagging multiple messages) and when-not-to-use (single flag -> use flag-message, removing flags -> use batch-unflag-messages). Also gives a prerequisite: get ids from search-messages or list-messages.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

batch-mark-as-readA

Use when: marking multiple messages (1–100 ids) as read in one call. Returns: counts of how many were marked read and how many failed. Do not use when: marking just one (use mark-as-read) or marking unread (use batch-mark-as-unread). Get the ids from search-messages or list-messages first.

ParametersJSON Schema

Name	Required	Description	Default
`ids`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`failed`	No
`mailbox`	No
`success`	No

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so description carries full burden. It discloses return counts but omits details like idempotency, error handling, or side effects. Basic but adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences front-loading usage and boundaries. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema (indicated) and good usage guidance, description is mostly complete. Missing a note on handling already-read messages or failure scenarios.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description only says 'marking multiple messages (1–100 ids)' without detailing the ID format or parameter syntax. Leaves agent to infer from schema pattern.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool marks multiple messages as read in one call, specifying the range of 1-100 IDs. It distinguishes itself from siblings like mark-as-read and batch-mark-as-unread.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use (multiple messages), when not to (single or unread), provides alternative tools, and advises to get IDs from search-messages or list-messages first.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

batch-mark-as-unreadA

Use when: marking multiple messages (1–100 ids) as unread in one call. Returns: counts of how many were marked unread and how many failed. Do not use when: marking just one (use mark-as-unread) or marking read (use batch-mark-as-read). Get the ids from search-messages or list-messages first.

ParametersJSON Schema

Name	Required	Description	Default
`ids`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`failed`	No
`mailbox`	No
`success`	No

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses that it marks messages as unread and returns success/failure counts, but lacks details on side effects, reversibility, permissions, or rate limits. Adequate but incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Efficiently structured with labeled sections: Use when, Returns, Do not use when, and prerequisite. Every sentence is valuable with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple batch mutation tool with one parameter and existing output schema, description covers usage, return, exclusions, and prerequisite. Lacks mentions of threading or access implications, but largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage 0% (description does not describe parameter format), but the schema provides a pattern for ids. Description adds context that ids come from search/list results. Baseline 3 due to low coverage, with partial compensation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool marks multiple messages (1-100) as unread in one call. It distinguishes from siblings like mark-as-unread (single) and batch-mark-as-read (read instead of unread).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use when' and 'Do not use when' with specific alternatives. Also provides prerequisite: get ids from search-messages or list-messages first.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

batch-move-messagesA

Use when: moving multiple messages (1–100 ids) into the same destination mailbox/folder in one call, e.g. bulk archiving. Returns: counts of how many were moved and how many failed. Do not use when: moving just one (use move-message) or deleting (use batch-delete-messages). Use list-mailboxes to confirm the destination name exists. Safety: moves many real messages at once — confirm the destination mailbox, and search-messages/list-messages first to confirm the ids.

ParametersJSON Schema

Name	Required	Description
`ids`	Yes
`account`	No	Account containing the destination mailbox
`mailbox`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`failed`	No
`mailbox`	No
`success`	No

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses that it moves many real messages, warns to confirm destination and ids, and explains return values (counts of moved and failed). Clearly a mutation operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, each with a distinct role: use case, returns, exclusions, safety. Front-loaded with main purpose. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Includes references to sibling tools and prerequisites, return value description, and safety note. Adequate for a batch move operation with output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description clarifies that ids are message identifiers (1-100) and mailbox is destination folder, adding value to the schema. However, it does not mention the optional account parameter, which has a description in schema but could be reinforced.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it moves multiple messages (1-100 ids) into the same destination mailbox, with an example of bulk archiving. It distinguishes from sibling tools like move-message (single) and batch-delete-messages (deleting).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use when' and 'Do not use when' sections, referencing specific alternatives (move-message, batch-delete-messages) and prerequisite (list-mailboxes).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

batch-unflag-messagesA

Use when: removing flags from multiple messages (1–100 ids) in one call. Returns: counts of how many were unflagged and how many failed. Do not use when: unflagging just one (use unflag-message) or adding flags (use batch-flag-messages). Get the ids from search-messages or list-messages first.

ParametersJSON Schema

Name	Required	Description	Default
`ids`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`failed`	No
`mailbox`	No
`success`	No

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses return counts (how many unflagged and failed), batch size limit (1-100), and prerequisite ids. Does not mention idempotency or invalid id handling, but overall informative.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, front-loaded with 'Use when'. Every sentence adds value: purpose, limits, return, alternatives, prerequisites. No redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple batch tool with one parameter and output schema, description covers core usage, return value, prerequisites, and differentiation from siblings. Lacks error handling details but adequate for effective agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description mentions 'removing flags from multiple messages (1–100 ids)' which explains the ids parameter implicitly. Also advises getting ids from other tools, adding context beyond schema pattern. However, does not elaborate on parameter format or validation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'removing flags from multiple messages (1–100 ids) in one call.' Verb is specific (removing flags), resource is messages, scope is batch. Distinguishes from unflag-message and batch-flag-messages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides 'Use when' and 'Do not use when' conditions, including alternatives (unflag-message, batch-flag-messages) and prerequisite to get ids from search-messages or list-messages.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cancel-scheduled-sendA

Use when: preventing one pending Apple Mail scheduled send after the user explicitly confirms the exact schedule_id. Returns: the cancelled schedule and leaves the original draft in Drafts. Do not use when: the job is already sending or terminal. Safety: cancellation prevents a future external action; require explicit confirmation before passing confirmed=true.

ParametersJSON Schema

Name	Required	Description	Default
`confirmed`	Yes
`schedule_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`schedule`	No

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses the safety implication (prevents future action), return value (cancelled schedule, leaves draft), and need for confirmation. Does not cover all potential errors but adequate for main behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very concise with 4 sentences, each serving a distinct purpose (use case, return, exclusions, safety). Well-structured and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simple nature and existence of output schema (not shown but signaled), the description covers all needed aspects: when to use, when not, safety, return, and parameter semantics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% but description explains that 'confirmed' requires explicit confirmation before setting to true, and 'schedule_id' must be the exact one from user. Adds meaning beyond schema pattern and required fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action: 'preventing one pending Apple Mail scheduled send'. It uses a specific verb (cancel) and resource (scheduled send), and distinguishes from sibling tools like reschedule-scheduled-send.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides 'Use when:' and 'Do not use when:' conditions, including when the job is already sending or terminal. Also includes safety warning requiring explicit confirmation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create-draftA

Use when: composing an email the user should review in Mail.app before sending — the safe default for any new message. Select a concrete From alias with from after list-sending-identities; account remains as a backwards-compatible account/identity selector. Returns: the stable draft_id, actual From identity, recipients, subject, and attachment count. Do not use when: editing an existing draft (use update-draft) or the user wants it sent now (use send-email). Safety: creates and saves a draft only; it sends nothing.

ParametersJSON Schema

Name	Required	Description
`cc`	No	CC recipients
`to`	Yes
`bcc`	No	BCC recipients
`body`	Yes
`from`	No	Sending identity id, email address, or formatted sender from list-sending-identities
`account`	No	Deprecated compatibility selector: Mail account name or sender address
`subject`	Yes
`attachments`	No	Files to attach: absolute paths (e.g. '/Users/me/report.pdf') and/or inline {filename, contentBase64} objects up to 25 MiB decoded each.

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`from`	No
`subject`	No
`draft_id`	No
`recipients`	No
`attachmentCount`	No

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description explicitly states that the tool only creates and saves a draft and sends nothing, and lists the return values, providing full behavioral clarity. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured, concise, and front-loaded with the primary usage condition. Every section serves a distinct purpose: usage, parameter guidance, return details, exclusion conditions, and safety note. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose, usage conditions, parameter guidance for non-obvious ones, return summary, and safety assurance. Given that the output schema is available (and the description lists key return fields), and the input schema provides details, the description is sufficiently complete for an agent to decide and use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds value by explaining the intended use of `from` (alias selection after list-sending-identities) and marking `account` as deprecated, which goes beyond the schema. For other parameters, the schema descriptions (63% coverage) already provide basic info, and the return description hints at their role. This combination effectively compensates for the schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose: composing an email for user review before sending, positioning it as the safe default for new messages. It distinguishes it from related actions (editing drafts, sending immediately) and provides usage guidance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage conditions (when to use and when not to use with specific alternative tool names), and advises on how to select a From alias, making it easy for an agent to decide.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create-mailboxA

Use when: creating a new mailbox/folder in an account. Returns: a confirmation that the mailbox was created. Do not use when: renaming an existing one (use rename-mailbox) or deleting one (use delete-mailbox). Use list-mailboxes to see what already exists. Safety: creates a real folder in the mail account — confirm the name and target account first.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`account`	No	Account to create the mailbox in

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`name`	No

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It discloses that the tool creates a real folder, returns a confirmation, and includes a safety warning to confirm name and account. It does not detail side effects or auth requirements, but provides sufficient context for a simple create operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured with clear sections (Use when, Returns, Do not use, Safety). Every sentence is meaningful and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple creation tool with an output schema, the description covers purpose, usage, result, and safety. It could mention prerequisites (e.g., account must exist), but overall it is complete enough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50% (name lacks description; account is described). The description mentions 'name and target account' in safety but adds no new details beyond the schema, such as name format or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb and resource ('creating a new mailbox/folder in an account') and explicitly distinguishes from sibling tools like rename-mailbox and delete-mailbox.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (creating a new mailbox), when not to use (renaming or deleting), and names alternative tools (rename-mailbox, delete-mailbox). Also advises checking existing mailboxes with list-mailboxes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create-newsletter-smart-mailboxesA

Use when: auto-discovering newsletter/bulk senders in your INBOX(es) and (optionally) creating a dedicated smart mailbox per sender (named "NL: "). Defaults to a safe dry run that only proposes. Returns: the proposed or created smart mailboxes with their match scores. Do not use when: you already know the exact sender (use create-smart-mailbox) or want real folders (use create-mailbox). Safety: with dryRun=false it edits Apple Mail's SyncedSmartMailboxes.plist (backed up, atomic, existing entries preserved) and can create many smart mailboxes at once — review a dryRun first. It scans up to ~400 recent messages per inbox via AppleScript, which can be slow on large mailboxes.

ParametersJSON Schema

Name	Required	Description
`days`	No	Look back this many days in INBOXes
`dryRun`	No	If true (default), only propose; if false, actually create
`minCount`	No	Minimum messages from sender in the period

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No
`dryRun`	No

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries full burden. It discloses default dry run behavior, edits to Apple Mail plist (with backup/atomic preservation), potential creation of many smart mailboxes, scanning of ~400 messages, and performance impact on large mailboxes. Safety advice to review dry run first is included.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured with clear sections (Use when, Returns, Do not use when, Safety). Every sentence adds necessary information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given tool complexity and no annotations, the description covers usage, safety, performance, return values (with output schema present), and behavioral traits. It provides all necessary context for safe and effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. The description adds value by explaining how parameters work together (e.g., dryRun controls creation vs. proposal) and providing context beyond schema descriptions (e.g., scanning range). While not per-parameter, it enhances overall understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: auto-discovering newsletter/bulk senders in INBOXes and optionally creating smart mailboxes per sender. It distinguishes from sibling tools 'create-smart-mailbox' and 'create-mailbox' by specifying when to use each.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly provides 'Use when' and 'Do not use when' conditions, including alternative tools (create-smart-mailbox for known senders, create-mailbox for real folders). This gives clear guidance on tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create-ruleA

Use when: creating a new Mail rule with one or more conditions (field/operator/value) and at least one action (markRead, markFlagged, delete, or moveTo). Set matchAll to require all conditions vs. any. Returns: a confirmation naming the rule and its condition count. Do not use when: toggling an existing rule (use enable-rule / disable-rule) or removing one (use delete-rule). Use list-rules to avoid duplicating an existing rule. Safety: creates a rule that automatically acts on real mail (including delete/move actions) on an ongoing basis — confirm the conditions and actions with the user before calling.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`actions`	Yes
`enabled`	No
`matchAll`	No
`conditions`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`name`	No
`created`	No

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses key behavioral traits: the rule automatically acts on real mail on an ongoing basis, includes delete/move actions, and that actions are irreversible. It also advises user confirmation for safety. This fully compensates for missing annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is 3-4 sentences, front-loaded with the 'Use when' directive. Every sentence serves a purpose: usage conditions, behavioral caution, and alternative guidance. No redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, complex nested schema, and presence of an output schema, the description covers safety, usage guidelines, and key parameter behaviors. It lacks detailed parameter syntax but provides sufficient context for an agent to understand the tool's purpose and risks. Could be slightly more thorough on condition/action structures but overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. It mentions condition components (field/operator/value) and actions (markRead, markFlagged, delete, moveTo) and explains the matchAll flag's purpose. While not detailing every parameter format (e.g., operator enum values), it adds essential context beyond the schema such as the matchAll behavior and mandatory actions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('creating') and resource ('a new Mail rule'), and details the components (conditions and actions). It distinguishes from sibling tools like enable-rule, disable-rule, and delete-rule, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides 'Use when' and 'Do not use when' conditions, naming specific alternative tools (enable-rule, disable-rule, delete-rule) and advising to use list-rules to avoid duplicates. This gives clear guidance on when and when not to use the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create-smart-mailboxA

Use when: creating an Apple Mail smart mailbox (a criteria-based virtual view) that matches a sender, subject, or body substring — works on German-localized macOS where AppleScript's smart-mailbox terms fail. Returns: confirmation of creation, or a note that a smart mailbox with that name already existed. Do not use when: creating a real folder (use create-mailbox). Safety: edits Apple Mail's SyncedSmartMailboxes.plist directly. It backs the file up (.bak) and writes atomically, and never rewrites your existing smart mailboxes. It does not quit Mail — quit Mail first for reliable results, since a running Mail may not show the new smart mailbox until relaunched and can overwrite plist edits it did not make.

ParametersJSON Schema

Name	Required	Description
`name`	Yes
`bodyContains`	No	Match body (contains)
`fromContains`	No	Match sender (From contains)
`subjectContains`	No	Match subject (contains)

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`name`	No
`alreadyExisted`	No

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description thoroughly covers behavioral traits: it edits SyncedSmartMailboxes.plist directly with backup and atomic write, never rewrites existing smart mailboxes, and warns that Mail should be quit first for reliability. This exceeds typical transparency expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear headings ('Use when:', 'Returns:', 'Do not use when:', 'Safety:') and front-loads the purpose. Every sentence adds value, though it could be slightly more concise. Overall, it is effective and not verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (plist editing, multiple criteria, output confirmation) and the presence of an output schema, the description covers essential aspects: usage context, return values, safety precautions, and prerequisites (quit Mail). It does not detail the return schema structure, but that is handled by the output schema. The explanation is sufficient for an AI agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes the optional parameters (bodyContains, fromContains, subjectContains) as substring matches. The description reinforces this by mentioning 'matches a sender, subject, or body substring'. It does not add syntax or format details beyond the schema, but the 75% schema coverage means the description is not burdened heavily. There is slight room to explain how multiple criteria combine (AND/OR), but it is not necessary for basic usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates an Apple Mail smart mailbox, a criteria-based virtual view matching sender, subject, or body substring. It distinguishes from creating a real folder by explicitly mentioning the sibling tool 'create-mailbox' in the usage guidance, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Use when' and 'Do not use when' instructions, including the alternative 'create-mailbox' for real folders. It also notes the specific German-localized macOS use case where AppleScript fails, offering clear context for when this tool is preferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete-draftA

Use when: moving one inspected Apple Mail draft to Trash by its draft_id. The connector locates the exact saved Drafts mailbox message by account, mailbox, and native message id. Returns: the deleted draft_id and subject. Do not use when: deleting ordinary mail (use delete-message). Safety: destructive — require explicit user confirmation of this exact draft_id after read-draft.

ParametersJSON Schema

Name	Required	Description	Default
`draft_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`subject`	No
`draft_id`	No

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It declares the tool as destructive, requires explicit user confirmation, and explains the internal locating logic (account, mailbox, native message id). Lacks details on error cases (e.g., draft not found) but sufficiently covers main behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: use-case, return values, exclusions, safety. Front-loaded with 'Use when'. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given one parameter, safety warning, and mentioned return values (draft_id, subject), the description is nearly complete. It could mention prerequisites (from list-drafts/read-draft) more explicitly, but the implied workflow is clear. Output schema existence reduces burden on description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter draft_id is described only by the schema's pattern. The description does not explain its purpose, origin, or format beyond the schema. With 0% schema coverage, the description should compensate but fails to add any meaningful context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool deletes an Apple Mail draft by draft_id, distinguishing it from deleting ordinary mail via the sibling tool delete-message. It specifies the verb 'delete' and resource 'draft', and the 'Use when' phrase sets clear scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides when to use ('moving one inspected Apple Mail draft to Trash'), when not to use ('deleting ordinary mail'), and recommends an alternative tool (delete-message). Also implies appropriate preceding step (read-draft).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete-mailboxA

Use when: deleting a mailbox/folder from an account. Returns: a confirmation that the mailbox was deleted. Do not use when: renaming it (use rename-mailbox) or deleting messages within it (use delete-message / batch-delete-messages). Safety: destructive — deleting a mailbox removes the folder and any messages it contains. Require explicit user confirmation and use list-mailboxes first to confirm the exact name.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`account`	No	Account containing the mailbox

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`name`	No

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully carries the transparency burden. It labels the operation as 'destructive', explains 'removes the folder and any messages it contains', and states that explicit user confirmation is required. It could additionally mention irreversibility but 'destructive' implies permanence.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is highly concise and well-structured with clear sections: 'Use when:', 'Returns:', 'Do not use when:', 'Safety:'. Every sentence provides essential information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a deletion tool, the description covers purpose, usage boundaries, safety implications, prerequisite actions, and return value. With an output schema present (not shown but noted), the description is sufficiently complete for agent decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 2 parameters with 50% description coverage (account has description, name does not). The description adds indirect guidance for name ('use list-mailboxes first to confirm the exact name') but does not directly describe the name parameter's format or meaning. Account's description is already in the schema. Overall, marginal added value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'deleting a mailbox/folder from an account.' It also distinguishes from siblings like rename-mailbox and delete-message, making the function unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides 'Use when:' and 'Do not use when:' conditions with alternative tools named (rename-mailbox, delete-message, batch-delete-messages). Also advises prerequisite actions: 'use list-mailboxes first to confirm the exact name' and 'Require explicit user confirmation.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete-messageA

Use when: deleting a single message by id (moves it to Trash). Returns: a confirmation that the message was deleted. Do not use when: deleting several at once (use batch-delete-messages) or just filing it away (use move-message). Safety: destructive — require explicit user confirmation, and search-messages/list-messages first to confirm you have the right id before deleting.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	No
`ok`	No

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses the action (move to Trash, not permanent delete), returns confirmation, and warns of destructiveness. However, it doesn't mention rate limits or auth requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very concise, front-loaded with use guidance. Every sentence is necessary and no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given it has an output schema (mentioned in context), the description doesn't need to detail return values. It covers the essential purpose, usage, and safety. Could add more about output, but sufficient for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description adds minimal parameter info: just 'by id'. The schema has a pattern, but the description doesn't explain what the pattern means or provide usage context for the id parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it deletes a single message by id and moves it to Trash. Distinguishes from batch-delete-messages and move-message, so the agent can differentiate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides 'Use when' and 'Do not use when' with specific sibling tools (batch-delete-messages, move-message). Also includes safety steps like requiring confirmation and searching first.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete-ruleA

Use when: permanently removing a Mail rule by name. Returns: a confirmation that the rule was deleted. Do not use when: you only want to pause it (use disable-rule) or create one (use create-rule). Safety: destructive — the rule is removed permanently. Require explicit user confirmation and use list-rules first to confirm the exact name.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`name`	No
`deleted`	No

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully bears the transparency burden. It clearly states the tool is destructive ('the rule is removed permanently'), requires explicit user confirmation, and suggests a prerequisite step (list-rules). It also describes the return value (confirmation). This fully discloses behavioral impact.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise: four short, front-loaded sections covering use, return, alternatives, and safety. Every sentence adds value with zero redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter delete tool with no annotations, the description covers purpose, usage, return, and safety. However, it lacks information about error cases (e.g., behavior if rule does not exist) or idempotency. The output schema exists but is not described; the description says 'returns a confirmation' which is sufficient. Overall, very good but not fully exhaustive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description should add parameter meaning. It mentions 'by name' and advises using list-rules to confirm the exact name, implying case-sensitive exact match. However, it does not directly describe the 'name' parameter's format or constraints beyond the schema (minLength 1). The extra guidance helps but is indirect.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool permanently removes a Mail rule by name, and explicitly distinguishes it from disable-rule (pause) and create-rule. The verb 'deleting' and the resource 'Mail rule' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use ('permanently removing a Mail rule') and when-not-to-use ('only want to pause it' or 'create one') with named alternatives (disable-rule, create-rule). Also advises to use list-rules first for confirmation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete-smart-mailboxA

Use when: deleting an Apple Mail smart mailbox (virtual view) by name. Returns: confirmation of deletion. Do not use when: deleting a real folder (use delete-mailbox) or messages (use delete-message / batch-delete-messages). Safety: destructive — removes the smart mailbox from Apple Mail's SyncedSmartMailboxes.plist. It backs the file up (.bak) and writes atomically, preserving every other smart mailbox, but the removal is not undoable in-app. Confirm the exact name with list-smart-mailboxes first, and quit Mail first for reliable results.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`name`	No

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description fully discloses destructive nature, backup mechanism, atomic write, and irreversibility, plus the need to quit Mail for reliability.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is concise, well-organized into sections, and every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and the presence of an output schema, the description covers purpose, usage, safety, and prerequisites completely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description's usage context (e.g., 'by name', 'confirm exact name') compensates. However, it doesn't restate parameter details, which is acceptable given the single parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool deletes an Apple Mail smart mailbox (virtual view) by name, and distinguishes it from siblings like delete-mailbox (real folder) and delete-message.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides 'Use when' and 'Do not use when' conditions, including references to alternatives and prerequisites like confirming the name with list-smart-mailboxes and quitting Mail.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete-templateA

Use when: permanently removing a saved email template by id. Returns: a confirmation that the template was deleted. Do not use when: you only want to view it (use get-template) or update it (use save-template with the existing id). Safety: destructive — removes the template from the on-disk store permanently. Require explicit user confirmation and use list-templates first to confirm the id.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	No
`ok`	No

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses destructiveness ('removes permanently from on-disk store') and safety advice. It lacks detail on the return value beyond 'confirmation', but an output schema exists, so that is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (4 sentences), front-loaded with 'Use when', and every sentence adds unique value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-param deletion tool, the description covers purpose, usage guidelines, safety, and confirmation advice. With an output schema existing, it is fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage for the id parameter. The description adds context by explaining it's a template id and instructs to confirm it with list-templates, aiding the agent beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool is for 'permanently removing a saved email template by id'. It distinguishes from siblings like get-template (view) and save-template (update).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('permanently removing'), when not to use (view/update), and provides alternatives. Also advises using list-templates first to confirm id, and notes the need for explicit user confirmation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

disable-ruleA

Use when: turning off an existing Mail rule by name (without deleting it). Returns: a confirmation that the rule was disabled. Do not use when: turning a rule on (use enable-rule), creating one (use create-rule), or removing it permanently (use delete-rule). Use list-rules to confirm the exact rule name.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`name`	No
`enabled`	No

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses that the tool disables without deleting and returns a confirmation. It does not mention any destructive behavior, which is appropriate as it is non-destructive. There is no contradiction. However, it could add context on whether the rule remains visible or its state after disabling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, using two sentences to convey purpose, usage guidelines, and a helpful tip. Every sentence is value-adding, and it is front-loaded with the primary use case.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (one parameter, no annotations, output schema exists), the description covers the main aspects: action, return type, and precondition. It does not mention error handling or what happens if the rule doesn't exist, which might be covered in the output schema. Slight room for improvement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'name' has no description in the schema (0% coverage). The description adds value by specifying it is the exact rule name and advising to use list-rules to confirm. This helps the agent understand the required input beyond the schema's minimal definition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: disabling an existing Mail rule by name without deleting it. It uses a specific verb (disable) and a resource (Mail rule). It also distinguishes itself from sibling tools like enable-rule, create-rule, and delete-rule.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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 (turning off an existing rule) and when not to use (for enabling, creating, or deleting). It mentions specific alternative tools (enable-rule, create-rule, delete-rule) and advises using list-rules to confirm the exact rule name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

doctorA

Use when: troubleshooting setup problems — diagnoses Mail.app automation permissions, account state, and the IMAP/SMTP backends with actionable remediation messages. Returns: a detailed diagnostic report (formatted text plus structured checks). Do not use when: you just want a quick up/down status (use health-check) or message counts (use get-mail-stats).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`checks`	No
`healthy`	No

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but description explains return format ('detailed diagnostic report with structured checks') and mentions actionable remediation messages. Could explicitly state read-only nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with usage context, no unnecessary words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With zero parameters and an output schema present, description covers purpose, usage boundaries, and return format completely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters; baseline 4 applies as per rules. Description adds no param info, which is acceptable given zero parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb 'diagnoses' and specific resources 'Mail.app automation permissions, account state, and IMAP/SMTP backends', differentiating from sibling tools like health-check and get-mail-stats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('troubleshooting setup problems'), when not to use, and provides alternative tool names (health-check, get-mail-stats).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

enable-ruleA

Use when: turning on an existing Mail rule by name. Returns: a confirmation that the rule was enabled. Do not use when: turning a rule off (use disable-rule), creating one (use create-rule), or deleting one (use delete-rule). Use list-rules to confirm the exact rule name.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`name`	No
`enabled`	No

TDQS

A4.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that the tool returns a confirmation and does not have annotations, so it carries the full burden. However, it does not describe what happens if the rule is already enabled, whether the operation is idempotent, or any potential side effects. Basic behavior is covered, but edge cases are missing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, consisting of three brief sentences. It front-loads the purpose and returns, then immediately provides usage boundaries. Every sentence serves a clear purpose, with no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-parameter tool with an output schema, the description covers the key aspects: purpose, return value, and usage boundaries. It could mention idempotency or what happens if the rule does not exist, but overall it is adequately complete for the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must add meaning for the 'name' parameter. The description indicates that the parameter is the rule name and advises using list-rules to confirm the exact name, providing valuable guidance. However, it does not specify format, case sensitivity, or validation beyond the schema's minLength.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose: 'turning on an existing Mail rule by name.' It clearly identifies the action (enable), the resource (Mail rule), and the required input (name). This differentiates it effectively from sibling tools like disable-rule, create-rule, and delete-rule.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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 the tool ('Use when: turning on an existing Mail rule by name'), when not to use it ('Do not use when: turning a rule off, creating one, or deleting one'), and suggests an alternative tool (list-rules) to confirm the exact rule name. This leaves no ambiguity for the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fetch-attachmentA

Use when: retrieving an attachment's raw bytes inline as base64 (by message id and attachmentName), e.g. to process its contents without touching disk. Returns: the attachment's bytes base64-encoded, with its size and (for IMAP) MIME type. Do not use when: you don't know the attachment name (use list-attachments first) or you just want it saved to disk (use save-attachment).

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes
`attachmentName`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`bytes`	No
`mimeType`	No
`contentBase64`	No
`attachmentName`	No

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that the operation is read-only (retrieving inline), returns base64-encoded bytes with size and MIME type, and does not save to disk. No annotations exist, so the description fully covers behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact with front-loaded usage conditions and return value summary. Every sentence serves a purpose with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and the tool has only two required parameters, the description provides complete guidance on when to use and the return format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description maps the two parameters to 'message id' and 'attachmentName', adding meaning over raw schema names. However, it does not explain the format of 'id' (e.g., regex pattern), which is a minor gap for 0% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves attachment raw bytes inline as base64 by message id and attachment name, and distinguishes it from list-attachments and save-attachment.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides 'Use when' and 'Do not use when' with alternatives (list-attachments, save-attachment), guiding the agent on appropriate contexts.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

flag-messageA

Use when: flagging a single message (by id), optionally with a color (red/orange/yellow/green/blue/purple/gray). Returns: a confirmation that the message was flagged (and the color, when applied). Do not use when: flagging several at once (use batch-flag-messages) or removing a flag (use unflag-message). Get the id from search-messages or list-messages first. Note: flag colors are a Mail.app feature applied via AppleScript; for an IMAP-routed id the flag is set but the color is not applied (IMAP flags are colorless).

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes
`color`	No	Optional flag color (Apple Mail palette: red, orange, yellow, green, blue, purple, gray — 'grey' accepted). Omit for Mail's default flag. Colors are applied via Mail.app (AppleScript); for an IMAP-routed message id the flag is set but the color is not applied (IMAP flags are colorless).

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	No
`ok`	No
`color`	No
`colorApplied`	No

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so description must cover behavior. It explains the color limitation for IMAP IDs, which is a significant nuance. However, it does not explicitly state that flagging modifies the message (though implied).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with clear sections: 'Use when', 'Returns', 'Do not use when', 'Note'. Front-loaded with purpose and no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 params, output schema exists), the description covers usage boundaries, parameter specifics, and a notable behavioral quirk. It is complete and self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds context beyond the schema: id must be obtained beforehand, color options are repeated, and the IMAP color limitation is explained. Schema coverage is 50%, but the description compensates well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool flags a single message by ID, optionally with a color, and distinguishes it from related tools like batch-flag-messages and unflag-message. The verb 'flag' and resource 'message' are explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use when' and 'Do not use when' sections provide clear guidance, including getting the ID from search-messages or list-messages. Alternatives are named directly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

forward-messageA

Use when: forwarding an existing message (by id) to new recipients (to is an array), with an optional body to prepend. Set send=false to save as a draft. Returns: a confirmation that the message was forwarded or saved as a draft. Do not use when: replying to the sender/recipients (use reply-to-message) or composing a new message (use send-email / create-draft). Safety: with the default send=true this SENDS real email immediately and cannot be unsent — require explicit user confirmation of the recipients and any prepended body, or pass send=false to let the user review.

ParametersJSON Schema

Name	Required	Description
`id`	Yes
`to`	Yes
`body`	No	Optional message to prepend
`send`	No	Send immediately (false = save as draft)

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	No
`ok`	No
`sent`	No
`recipients`	No

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Since no annotations are provided, the description fully bears the burden of transparency. It warns that with send=true the message is sent immediately and cannot be unsent, requiring explicit user confirmation. It also describes the draft-saving behavior. No contradicting annotations exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (3 sentences) and well-structured: it starts with a usage directive, then lists parameters, then exclusions, then safety notes. Every sentence is essential and additive. No redundant or missing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (4 params, output schema exists) and the rich context from sibling tools, the description covers all necessary aspects: purpose, parameter meanings, usage boundaries, behavioral implications, and safety. The output schema handles return value documentation, so no further detail is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds context beyond the schema: it clarifies that 'id' is the message being forwarded, 'to' is an array of new recipients, 'body' is optional prepended text, and 'send' controls immediate send vs. draft. However, it does not detail the format constraints for 'id' (regex) or 'to' (email validation), which the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (forward) and resource (existing message), and distinguishes it from siblings like reply-to-message and send-email/compose. It uses specific verbs and lists key parameters (id, to, body, send).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use (forwarding an existing message) and when not to use (replying or composing new), with references to alternative tools (reply-to-message, send-email, create-draft). Also provides guidance on using send=false to save as draft.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-mail-statsA

Use when: you want aggregate mailbox statistics — total and unread message counts, recently-received counts (last 24h/7d/30d), and (for the all-accounts path) a per-account breakdown. Returns: totals, unread counts, recent-activity counts, and per-account figures. Do not use when: you only need a single unread number (use get-unread-count) or want to list the messages themselves (use list-messages / search-messages).

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Limit to one account; uses fast IMAP STATUS if that account is IMAP-configured

Output Schema

ParametersJSON Schema

Name	Required	Description
`recent`	No
`account`	No
`accounts`	No
`totalUnread`	No
`totalMessages`	No
`recentlyReceived`	No

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so description carries full burden. It describes return data (totals, unread, recent activity, per-account breakdown) and mentions IMAP STATUS optimization for the account parameter. Lacks explicit mention of read-only nature or potential performance impact, but overall transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise multi-sentence structure, front-loaded with usage context, then lists returns and exclusions. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description adequately covers the tool's purpose and parameters. Additional details about per-account breakdown structure could be inferred from schema, but the description is sufficiently complete for selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one optional parameter with schema coverage 100%. The description adds extra semantic context beyond the schema by noting the IMAP STATUS optimization for configured accounts, which aids agent understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides 'aggregate mailbox statistics' including total, unread, and recent counts, and distinguishes itself from sibling tools like get-unread-count and list-messages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use when' and 'Do not use when' sections, with specific alternative tool names (get-unread-count, list-messages, search-messages), providing clear guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-messageA

Use when: reading the full body of one message whose id you already have (numeric or imap:…); set preferHtml to get the HTML body instead of plain text. Returns: the message subject, body (plain text by default, HTML when preferHtml is true), and its stable RFC Message-ID (rfcMessageId) for dedup/threading. Tip: pass the mailbox+account you got the id from (e.g. from search-messages) to fetch it directly — required for reliable reads of large folders like "Sent Items", which otherwise time out. Do not use when: you don't yet have an id (use search-messages or list-messages first), or you want the whole conversation (use get-thread).

ParametersJSON Schema

Name	Required	Description
`id`	Yes
`account`	No	Account that holds the message. Pair with `mailbox` for a direct, scan-free fetch.
`mailbox`	No	Mailbox that holds the message (e.g. "Sent Items"). Numeric ids are unique per mailbox; supplying this (with account) opens that mailbox directly instead of scanning every mailbox, which is required to read large folders like Sent Items without timing out.
`preferHtml`	No	Return the HTML body (extracted from the message source) instead of plain text

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	No
`body`	No
`isHtml`	No
`subject`	No
`rfcMessageId`	No	Stable RFC 5322 Message-ID (angle brackets stripped); empty when the message has none

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes return fields (subject, body, rfcMessageId), the effect of preferHtml, and reliability requirements for large folders, despite no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with 'Use when', then returns, tip, and 'Do not use'. Every sentence is necessary and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, usage, parameter nuances, return format, and exclusions. With output schema present, it is fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds important meaning beyond schema: id format, mailbox+account requirement for large folders, and preferHtml behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool reads the full body of one message given an ID, distinguishing it from search-messages and get-thread.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (reading a message by ID) and when not to use (without an ID or wanting a conversation), with a tip for large folders.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-sync-statusA

Use when: checking whether Mail.app is running and actively syncing, e.g. to explain why new mail hasn't appeared yet. Returns: whether Mail.app is running and whether sync activity was detected. Do not use when: you need message counts (use get-mail-stats) or a full setup diagnosis (use doctor).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`error`	No
`syncDetected`	No
`pendingUpload`	No
`recentActivity`	No
`secondsSinceLastChange`	No

TDQS

A4.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It discloses that the tool returns whether Mail.app is running and sync activity detected. It does not mention side effects, rate limits, or whether it triggers any action, but for a read-only check the transparency is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise—two sentences that front-load the purpose and return value. No wasted words; every sentence adds essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and an available output schema, the description covers all necessary context: when to use, what it returns, and how it differs from siblings. It is fully complete for a simple check tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters and schema description coverage is trivially 100%. The description does not need to add parameter information, and it appropriately omits any. The baseline for 0 params is 4, but the tool's simplicity and clarity merit a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks if Mail.app is running and actively syncing, with a concrete use case (explaining missing new mail). It distinguishes itself by specifying what not to use it for and naming alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Use when' and 'Do not use when' statements with specific alternatives (get-mail-stats for message counts, doctor for full diagnosis). This fully guides the agent on when to invoke this tool vs siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-templateA

Use when: reading the full contents of one saved template by id — its name, subject, default to/cc, and body. Returns: the template's name, subject, default recipients, and body text. Do not use when: you don't have the id (use list-templates first) or want to apply the template into a draft (use use-template).

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`cc`	No
`id`	No
`to`	No
`body`	No
`name`	No
`subject`	No

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description implies read-only behavior by stating 'reading full contents' and listing return values, but does not explicitly mention safety, permissions, or side effects. However, the description is clear enough for a simple retrieval tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences: first states usage, second states returns, third states when not to use with alternatives. Front-loaded and concise with no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, output schema present), the description covers all necessary aspects: what the tool does, when to use it, what it returns, and how it differs from related tools. The output schema handles remaining details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter (id) with no description in schema. The description adds meaning by stating 'by id' and clarifying that 'id' refers to the template's identifier. The usage guidelines further advise using list-templates to obtain the ID if unavailable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads the full contents of one saved template by its ID, listing specific fields (name, subject, default to/cc, body). It distinguishes from siblings like list-templates and use-template by providing when-not-to-use guidance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (reading full contents of a template by ID) and when not to use (no ID or want to apply template). Provides clear alternatives: list-templates to get IDs and use-template to apply the template into a draft.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-threadA

Use when: you have one message id and want the whole conversation it belongs to, oldest-first. With an imap: id it threads by References/Message-ID; otherwise it groups by normalized subject. Returns: the thread's normalized subject and its messages (id, date, subject, sender, read state). Do not use when: you only need the single message (use get-message) or are searching by arbitrary criteria (use search-messages).

ParametersJSON Schema

Name	Required	Description
`id`	Yes	A message ID in the conversation (numeric or imap:…)
`limit`	No	Max messages in the thread (default 50)
`account`	No	Account to search (omit to search all)
`mailbox`	No	Mailbox to search (omit to search all)

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No
`partial`	No
`subject`	No
`messages`	No

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It discloses that results are returned oldest-first, explains the threading algorithm (imap: id vs normalized subject), and lists the exact return fields (normalized subject, id, date, subject, sender, read state). No contradictions exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four sentences, front-loaded with the use condition. Every sentence serves a purpose: usage, threading logic, return format, and when-not-to-use. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, the description adds extra value by detailing the return fields and behavior. It covers all necessary aspects: input requirements, threading behavior, output format, and exclusion cases. Complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 new information about the parameters beyond what the schema already provides; the only extra detail is the pattern hint for id, which is already captured in the schema's pattern. No elaboration on limit, account, or mailbox beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb-resource ('get-thread') and clearly states the tool's purpose: take one message id and return the whole conversation. It distinguishes itself from siblings like get-message and search-messages by explaining the threading logic based on References/Message-ID vs normalized subject.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use ('have one message id and want the whole conversation') and when not to use ('only need the single message' or 'searching by arbitrary criteria'), naming alternative tools (get-message, search-messages). This provides clear guidance for agent decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-unread-countA

Use when: you only need the number of unread messages — INBOX by default, or scoped to one mailbox and/or account — without listing the messages themselves. Returns: the unread count for the requested scope (INBOX when no mailbox is given). Do not use when: you need the actual unread messages and their ids (use list-messages with unreadOnly, or search-messages with isRead=false) or broader totals across every mailbox (use get-mail-stats).

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Account to check
`mailbox`	No	Mailbox to check (default: INBOX)

Output Schema

ParametersJSON Schema

Name	Required	Description
`unread`	No
`account`	No
`mailbox`	No

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It explains scope and default behavior, but could mention if there are any side effects or rate limits. However, for a simple read operation, it is transparent enough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, front-loaded with usage condition. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and presence of output schema, the description is sufficient for an agent to decide when to use it. Lacks mention of error handling but acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with parameter descriptions. The description adds context by explaining scoping and default INBOX, going beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns the number of unread messages without listing them. It specifies default scope (INBOX) and distinguishes from siblings like list-messages and get-mail-stats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides when to use (need count only) and when not to use (need actual messages or broader totals) with specific sibling tool names. Also explains default and scoping behavior.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

health-checkA

Use when: doing a quick check that Mail.app is reachable and the server's basic checks pass. Returns: an overall healthy/unhealthy status with a pass/fail line per check. Do not use when: you need detailed permission/account/IMAP/SMTP diagnostics with remediation steps (use doctor).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`checks`	No
`healthy`	No

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses the tool's read-only nature (health check, returns status), what it does not do, and the result format. It does not mention permissions or side effects, but for a simple health check, this is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is only two sentences, front-loading usage context and return format. Every word contributes value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the description covers all essential aspects: purpose, usage conditions, and return format. An output schema exists (context signal), so detailed return structure is not needed in the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. No parameter details needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks Mail.app reachability and basic server health, returning overall status with per-check pass/fail. It distinguishes itself from the sibling 'doctor' tool by specifying what it does not do (detailed diagnostics).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides 'Use when' and 'Do not use when' sections, naming the alternative 'doctor' for cases needing detailed diagnostics. This offers clear guidance on when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-accountsA

Use when: discovering the configured Mail accounts (e.g. iCloud, Gmail) so you can pass an exact account name to other tools. Returns: the account names and a count. Do not use when: you want the folders within an account (use list-mailboxes) or messages (use list-messages / search-messages).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No
`accounts`	No

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It states it returns account names and a count, implying no side effects. However, it does not mention authentication requirements or potential limitations, though the operation appears simple and read-only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, focused sentences. Front-loaded with use case, no unnecessary words. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter list tool with an output schema, the description is sufficient. It states what is returned (account names and count). Given the context of sibling tools, this is complete for an agent to understand usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters, and schema coverage is 100% (empty). Description adds value by explaining the return value (account names and count), which is not in the schema. Baseline 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it discovers configured Mail accounts (e.g., iCloud, Gmail) to provide account names for other tools. It distinguishes from sibling tools by specifying when not to use it (folders or messages).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use (discovering accounts for passing name) and when not to use (use list-mailboxes instead for folders, list-messages/search-messages for messages). Provides clear alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-attachmentsA

Use when: enumerating a message's attachments (by id) to discover their names, MIME types, and sizes — typically before saving or fetching one. Returns: each attachment's name, MIME type, and size, plus a count. Do not use when: you want the bytes (use fetch-attachment for inline base64, or save-attachment to write to disk). Get the message id from search-messages or list-messages first.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No
`attachments`	No

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, but description discloses it returns metadata only, not bytes. It is read-only in nature, though not explicitly stated as such.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences structured with usage context, return value, and exclusions. Slightly verbose but well-organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With output schema present, description covers all needed context: purpose, parameter prerequisite, and return summary (names, MIME types, sizes, count). No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter 'id' is explained as the message id, with guidance on how to obtain it. Despite 0% schema coverage, the description fully compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'enumerating', the resource 'attachments' by message id, and outputs (names, MIME types, sizes, count). It distinguishes from siblings like fetch-attachment and save-attachment.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'Use when' and 'Do not use when', directing to alternative tools for bytes and advising to obtain message id from search-messages or list-messages.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-draftsA

Use when: reviewing or selecting saved Apple Mail drafts before reading, editing, sending, or deleting one. This reads every account's actual Drafts mailbox, not just currently open compose windows. Returns: Gmail-like draft resources with stable draft_id, actual From identity, recipients, subject, attachment status, and a short body preview. Do not use when: browsing ordinary mailbox messages (use list-messages).

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum drafts to return

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No
`drafts`	No

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that it reads actual Drafts mailbox (not just open windows) and describes the return content (draft_id, identity, recipients, etc.). It lacks mention of permissions or idempotency but covers essential traits well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, front-loaded with usage context, and contains no redundant information. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one optional parameter, no required ones) and the presence of an output schema, the description covers all necessary aspects. It explains when to use, what it does, what it returns, and when not to use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single parameter (limit) described in the schema. The description does not add extra meaning beyond the schema. The baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists saved Apple Mail drafts from every account's Drafts mailbox, not just open compose windows. It uses a specific verb ('list') and resource ('drafts') and explicitly distinguishes from list-messages for ordinary mailbox messages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use when:' and 'Do not use when:' sections provide clear context for when to use this tool versus alternatives. The sibling tool list-messages is named as the appropriate alternative for ordinary messages.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-mailboxesA

Use when: discovering the mailbox/folder names (and unread/message counts) available in an account, e.g. before moving messages or searching a specific mailbox. Returns: each mailbox's name with its unread (and, for IMAP, total message) count, plus a count. Do not use when: you want the messages inside a mailbox (use list-messages or search-messages) or the list of accounts (use list-accounts).

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Account to list mailboxes from

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No
`mailboxes`	No

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but description details return values (names, counts). It implies a read-only operation; however, it doesn't explicitly state safety or permissions, which would enhance transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise, front-loaded sentences covering purpose, returns, and exclusions. No redundancy or unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a single optional parameter and existing output schema, the description fully covers what the agent needs to know: when to use, what it returns, and what not to use it for.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and schema description is clear. Description adds usage context but does not significantly extend parameter meaning beyond what schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool lists mailbox/folder names and unread/message counts, and distinguishes it from siblings like list-messages and list-accounts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear 'Use when' and 'Do not use when' sections with specific alternative tools, giving explicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-messagesA

Use when: browsing a mailbox's recent messages (optionally filtered by sender or unread-only) with pagination via limit/offset, and you need their ids. Returns: messages with id, date, subject, and sender (plus partial-coverage diagnostics when some mailboxes were skipped). Do not use when: you have specific search criteria like subject/date/flags (use search-messages) or already have an id and want the body (use get-message). Like search-messages, use this to obtain the ids that read/mark/delete/move and batch tools require.

ParametersJSON Schema

Name	Required	Description
`from`	No	Filter by sender email address or name
`limit`	No	Maximum number of messages (default: 50, max: 500)
`offset`	No	Number of messages to skip (for pagination)
`account`	No	Account to list messages from
`mailbox`	No	Mailbox to list messages from. Omit to list from all mailboxes.
`unreadOnly`	No	Only show unread messages

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No
`partial`	No
`messages`	No
`timedOutAccounts`	No
`notSearchedMailboxes`	No
`skippedLargeMailboxes`	No

TDQS

A4.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so description must carry full burden. It describes return fields (id, date, subject, sender) and mentions diagnostics for skipped mailboxes. However, it does not explicitly state read-only nature, auth requirements, or side effects. With zero annotation coverage, more behavioral context would be prudent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Succinct and front-loaded: starts with 'Use when', each sentence adds value. No redundant or vague statements. Efficient use of words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema, the description still explains return format (fields and diagnostics). It covers usage scenarios, parameter roles, and how it integrates with sibling tools. Complete for a listing tool with six parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions. The description adds meaningful context: explains pagination (limit/offset), filtering by sender and unreadOnly, and optional mailbox vs. all mailboxes. It does not mention the 'account' parameter but covers the primary functional parameters well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists recent messages from a mailbox with optional filters (sender, unreadOnly) and pagination. It differentiates from siblings: search-messages (for specific criteria) and get-message (for body by ID). The verb 'browse' and resource 'recent messages' are precise.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use when' and 'Do not use when' sections with concrete alternatives. It specifies pagination via limit/offset, obtaining IDs for other tools, and when to use search-messages or get-message instead. No ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-rulesA

Use when: discovering the Mail rules that exist and whether each is enabled or disabled, e.g. before enabling/disabling/deleting one. Returns: each rule's name and enabled/disabled state. Do not use when: you want to change a rule (use enable-rule / disable-rule / create-rule / delete-rule).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No
`rules`	No

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must cover behavioral traits. It states the output (each rule's name and enabled/disabled state), implying a read-only, non-destructive operation. It does not mention authentication, rate limits, or return volume, but for a simple list tool this is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with three sentences, front-loads the purpose, and contains no unnecessary words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and presence of an output schema, the description covers all necessary context: purpose, usage guidance, and basic output. No gaps remain for a minimal list operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, and schema coverage is 100% (trivially). With 0 parameters, the baseline is 4. The description adds no parameter info because none exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: discovering Mail rules and their enabled/disabled states. It uses a specific verb ('discovering') and resource ('Mail rules'), and distinguishes from sibling tools for changing rules.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly outlines when to use (discovering rules before enabling/disabling/deleting) and when not to use (changing rules), and names alternative tools (enable-rule, disable-rule, create-rule, delete-rule).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-scheduled-sendsA

Use when: reviewing future Apple Mail sends, checking whether scheduled drafts were sent, or diagnosing a failed/needs_review job. Returns: schedule IDs, draft IDs, requested/UTC send times, status, From, recipients, subject, and any error. Do not use when: listing ordinary drafts (use list-drafts). This is read-only.

ParametersJSON Schema

Name	Required	Description	Default
`status`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No
`schedules`	No

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description fully discloses behavior: it is read-only, lists scheduled sends, and provides details on returned fields. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three highly informative sentences front-loaded with intent, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description covers return fields and use cases sufficiently. Simple tool with one optional param, no gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The sole parameter 'status' (optional enum) is not explicitly explained in the description, but the enum values are clear and the use cases imply filtering by status. Given 0% schema coverage, the description could add more, but it's adequate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists scheduled sends, with specific use cases (reviewing future sends, checking status, diagnosing failed/needs_review jobs) and explicitly distinguishes from list-drafts for ordinary drafts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use when' and 'Do not use when' sections provide clear context and name the alternative tool (list-drafts), meeting the highest standard for usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-sending-identitiesA

Use when: discovering the concrete From addresses/aliases configured in Apple Mail before creating, editing, or sending mail. Accounts and sending identities are different resources: one account can expose several aliases. Returns: identity_id, account, email, formatted sender, enabled state, and default state for every configured identity. Do not use when: you only need receiving-account names (use list-accounts).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No
`identities`	No
`default_identity_id`	No

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It explains it returns identity_id, account, email, formatted sender, enabled state, and default state. Since it's a read-only list operation, the behavior is transparent enough. Could mention that it does not modify data, but the context implies that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with a clear structure: usage guidance, return fields, and exclusion. Every sentence is necessary and no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, a list operation, and the existence of an output schema, the description is complete. It covers purpose, when to use, and return data.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so baseline is 4. The description adds value by explaining what fields are returned, which is more than the empty schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verb 'list' and resource 'sending identities', clearly stating it discovers 'From addresses/aliases' in Apple Mail. It distinguishes from sibling 'list-accounts' by noting the difference between accounts and aliases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use when' and 'Do not use when' sections provide clear context and an alternative ('list-accounts'). This helps the agent select the correct tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-smart-mailboxesA

Use when: listing Apple Mail smart mailboxes (criteria-based virtual views), including on German-localized macOS where AppleScript's smart-mailbox terms do not compile. Returns: each smart mailbox's name and a short criteria summary. Do not use when: listing real folders/mailboxes (use list-mailboxes).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No
`smartMailboxes`	No

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully carries the burden. It discloses that the tool lists smart mailboxes and returns their names and criteria summaries, implying a read-only operation without side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences: when to use, what it returns, when not to use. Every sentence is necessary and front-loaded with the most important usage context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With zero parameters and an output schema (which would explain return values), the description provides complete context: the purpose, usage cues, and a brief description of return data. Nothing is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so the baseline is 4. The description adds no parameter-specific information, which is fine as none exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists 'Apple Mail smart mailboxes (criteria-based virtual views)', using a specific verb and resource, and distinguishes from its sibling tool list-mailboxes which lists real folders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use when:' and 'Do not use when:' sections provide clear usage guidance, including a localization issue on German macOS, and directly names the alternative tool list-mailboxes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-templatesA

Use when: discovering the saved email templates and their ids, e.g. before using or editing one. Returns: each template's id, name, and subject. Do not use when: you want a single template's full body (use get-template) or want to apply one (use use-template).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No
`templates`	No

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, description explains output fields (id, name, subject) and side-effect-free listing. It does not mention pagination or limits, but given no parameters, it's sufficiently transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: when to use, what returns, when not to use. No redundancy, highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and output schema existence, description fully covers purpose, usage context, and return content. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters present, so baseline 4 applies. Schema coverage is 100% (trivial), and description adds value by explaining what the output contains.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool lists saved email templates with their ids, names, and subjects, using specific verb (discovering) and resource (templates). It implicitly distinguishes from siblings by listing use cases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides when to use (before using/editing a template) and when not to use (when wanting full body or applying a template), with direct alternatives (get-template, use-template).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mark-as-readA

Use when: marking a single message (by id) as read. Returns: a confirmation that the message was marked read. Do not use when: marking several at once (use batch-mark-as-read) or marking unread (use mark-as-unread). Get the id from search-messages or list-messages first.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	No
`ok`	No

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but description states the action is marking as read (non-destructive) and return is a confirmation. Lacks details on permissions or idempotency, but sufficient for this simple action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise, front-loaded purpose, returns, exclusions, and prerequisites in a clear structure with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with output schema, description covers purpose, usage guidelines, parameter source, and return value. Complete and sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage. Description mentions 'by id' and source of id, but does not explain id format or pattern. Adequate but minimal additional meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool's action: marking a single message as read. It explicitly distinguishes from siblings like batch-mark-as-read and mark-as-unread.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when to use (single message) and when not to (batch, unread), and directs to retrieve id from search-messages or list-messages.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mark-as-unreadA

Use when: marking a single message (by id) as unread. Returns: a confirmation that the message was marked unread. Do not use when: marking several at once (use batch-mark-as-unread) or marking read (use mark-as-read). Get the id from search-messages or list-messages first.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	No
`ok`	No

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must bear full transparency burden. It discloses the return ('a confirmation that the message was marked unread'), which is adequate for a simple state toggle. However, it does not mention idempotency or permissions, though these are implied by the tool's simplicity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with three sentences—no superfluous words. It fronts the usage guidance and return value, making it easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with an output schema, the description covers purpose, usage context, prerequisites (getting the id), and return value. It lacks only minor details like whether marking an already unread message is a no-op, but overall it is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains that the id parameter identifies the message and where to obtain it ('Get the id from search-messages or list-messages first'), but does not clarify the pattern or accepted formats, leaving some ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'marking a single message (by id) as unread,' clearly defining the verb and resource. It distinguishes from sibling tools like 'batch-mark-as-unread' and 'mark-as-read' by specifying single vs. batch and unread vs. read.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use ('marking a single message as unread') and when-not-to-use ('Do not use when: marking several at once... or marking read'), with direct references to alternative tools (batch-mark-as-unread, mark-as-read). Also instructs to obtain id from search-messages or list-messages.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

move-messageA

Use when: moving a single message (by id) into another mailbox/folder, e.g. archiving or filing. Returns: a confirmation naming the destination mailbox. Do not use when: moving several at once (use batch-move-messages) or deleting (use delete-message). Use list-mailboxes to confirm the destination name exists. Safety: moves a real message between folders — confirm the destination mailbox, and search-messages/list-messages first to confirm the id.

ParametersJSON Schema

Name	Required	Description
`id`	Yes
`account`	No	Account containing the destination mailbox
`mailbox`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	No
`ok`	No
`mailbox`	No

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must carry the burden. It mentions 'moves a real message' and returns a confirmation, but lacks details on authentication or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise, well-structured with clear sections (Use when, Returns, Do not use when, Safety), and every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the main use case and return value. The output schema exists and description addresses it. Minor gap: 'account' parameter not explained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 33%, and the description does not explain the 'account' parameter or provide additional meaning beyond naming 'id' and 'mailbox'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the action (moving a single message by id into another mailbox/folder) and distinguishes from siblings like batch-move-messages and delete-message.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides 'Use when' and 'Do not use when' conditions, names alternative tools, and advises using list-mailboxes to confirm destination.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read-draftA

Use when: reading the full current contents of one draft selected from list-drafts. Returns: the stable draft_id, actual From identity, recipients, subject, and full body. Do not use when: you only need draft summaries (use list-drafts).

ParametersJSON Schema

Name	Required	Description	Default
`draft_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`draft`	No

TDQS

A4.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries the burden. While it implies a read-only operation, it does not explicitly state behavioral traits like non-destructiveness, idempotency, or authorization needs. The description is adequate but lacks full transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, each essential: usage indication, return description, and exclusion of alternative. Front-loaded with the primary use case. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description does not need to detail return structure. It lists key returned fields and distinguishes from list-drafts. Missing minor details like error conditions or prerequisites, but sufficient for a read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description adds context by stating the tool reads a draft selected from list-drafts, implying the draft_id parameter comes from that source. The parameter name and pattern are self-explanatory, and the description adds value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads the full current contents of a draft, lists the returned fields (draft_id, From, recipients, subject, full body), and distinguishes itself from list-drafts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use ('reading the full current contents of one draft selected from list-drafts') and when not to use ('only need draft summaries – use list-drafts').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rename-mailboxA

Use when: renaming an existing mailbox/folder from oldName to newName within an account. Returns: a confirmation naming the old and new mailbox names. Do not use when: creating a new folder (use create-mailbox) or deleting one (use delete-mailbox). Use list-mailboxes to confirm the current name. Safety: renames a real folder in the mail account — confirm oldName matches exactly (case-sensitive) before calling.

ParametersJSON Schema

Name	Required	Description
`account`	No	Account containing the mailbox
`newName`	Yes
`oldName`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`newName`	No
`oldName`	No

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It states the operation renames a real folder, warns about case-sensitive exact match for oldName, and mentions return value. However, it does not disclose permissions, rate limits, or side effects on messages inside the folder, but the safety warning adds value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, using bullet-like phrases ('Use when:', 'Returns:', 'Do not use when:', 'Safety:'). It front-loads the key purpose and contains no unnecessary words, earning its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple operation (rename mailbox) with 3 parameters and no nested objects, the description covers when to use, how to use (case-sensitive match), return value, and alternatives. It could mention error handling or prerequisites, but is largely complete for this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is low (33% - only account described). The description clarifies the roles of oldName and newName by framing the rename action, but does not explain the account parameter. It adds partial meaning but does not fully compensate for the missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: renaming an existing mailbox/folder. It specifies the verb 'rename' and the resource 'mailbox/folder', and distinguishes from siblings by explicitly mentioning create-mailbox and delete-mailbox as alternative tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Use when' and 'Do not use when' guidance, including alternative tools (create-mailbox, delete-mailbox) and a recommendation to use list-mailboxes to confirm the current name. This helps the agent choose correctly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reply-to-messageA

Use when: replying to an existing message by id, preserving its threading headers. Set replyAll for all recipients; set send=false to save as a draft instead of sending. Returns: a confirmation that the reply was sent or saved as a draft. Do not use when: composing a brand-new message (use send-email / create-draft) or forwarding to new recipients (use forward-message). Safety: with the default send=true this SENDS real email immediately and cannot be unsent — require explicit user confirmation of the recipients and body, or pass send=false to let the user review.

ParametersJSON Schema

Name	Required	Description
`id`	Yes
`body`	Yes
`send`	No	Send immediately (false = save as draft)
`replyAll`	No	Reply to all recipients

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	No
`ok`	No
`sent`	No

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description fully discloses critical behavior: sending sends real email immediately and cannot be unsent, requiring explicit user confirmation. It also mentions the draft-saving option and threading preservation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (6 sentences) and well-structured with clear sections: action, usage, parameters, returns, exclusions, safety. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of email actions and many sibling tools, the description is complete: it covers purpose, when to use, when not to use, parameter roles, safety, and return value. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions cover 50% of parameters (send, replyAll have descriptions). The description adds meaning for id and body by context (replying to an existing message) and clarifies the effect of send and replyAll beyond their boolean labels.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'replying to an existing message by id, preserving its threading headers.' It specifies key options (replyAll, send) and distinguishes from sibling tools like send-email, create-draft, and forward-message.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use when' and 'Do not use when' sections provide clear usage boundaries, including naming alternative tools for other scenarios (send-email, create-draft, forward-message).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reschedule-scheduled-sendA

Use when: changing the future time of one pending Apple Mail scheduled send after the user explicitly confirms the schedule_id and new timezone-aware time. Returns: the updated schedule. Do not use when: the job is already sending, sent, failed, cancelled, or needs_review. Safety: changes when a real email will be sent; require explicit confirmation before passing confirmed=true.

ParametersJSON Schema

Name	Required	Description
`send_at`	Yes	RFC 3339 date/time with explicit offset, e.g. "2026-07-29T07:00:00+08:00"
`confirmed`	Yes
`schedule_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`schedule`	No

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries the full burden. It discloses the mutating effect ('changes when a real email will be sent') and the need for confirmation. It could be improved by covering edge cases (e.g., if send_at is in the past) but is generally transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise, purposeful sentences: usage guidelines, return value, and safety warning. No fluff, front-loaded with the key use case.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with an output schema, the description covers behavior, conditions, and return value. Minor gaps exist (e.g., error cases, validation of send_at), but overall it is sufficiently complete for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds value beyond the schema: it contextually explains 'schedule_id' and 'send_at' as a 'timezone-aware time', and clarifies 'confirmed' as requiring explicit user confirmation. Schema coverage is 33% (only send_at described), and the description compensates well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('changing the future time') and resource ('pending Apple Mail scheduled send'). It differentiates from siblings like 'cancel-scheduled-send' by focusing on rescheduling rather than cancellation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use when' and 'Do not use when' conditions are given, including specific statuses (e.g., 'already sending, sent, failed, cancelled, needs_review') and the requirement for explicit confirmation before setting 'confirmed=true'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolve-message-idA

Use when: you have imap: message id(s) and need the numeric Mail.app id(s) — most importantly to apply a flag COLOR, which only sticks on the AppleScript numeric-id path (IMAP \Flagged is colorless, so a smart mailbox keyed on flag color never matches an IMAP-flagged message). Each imap: id is resolved via its RFC822 Message-ID. Returns: for each input id, its numericId (the AppleScript id) or null when it can't be resolved, plus the messageId used; and a resolvedCount. Do not use when: your ids are already numeric (they pass straight through), or you don't need a color — flag/move/mark tools operate on imap: ids directly.

ParametersJSON Schema

Name	Required	Description	Default
`ids`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No
`resolved`	No
`resolvedCount`	No

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but description fully discloses the behavioral context: why numeric IDs are needed for color flags, resolution via RFC822 Message-ID, and return format including null for unresolvable IDs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise 4-sentence description with front-loaded key use case, no unnecessary words, and clear separation between usage guidance and output specification.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, description covers input format, output structure, motivation, and alternative tools—complete for a single-parameter resolution tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description adds meaning by explaining the imap: prefix, the resolution process, and the pass-through for numeric IDs, compensating fully for lack of param documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it resolves imap: message IDs to numeric Mail.app IDs, specifically for applying flag colors. It distinguishes from sibling tools like flag-message by explaining the color limitation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides 'Use when' and 'Do not use when' conditions, including when to use alternative tools (flag/move/mark for non-color operations).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

save-attachmentA

Use when: writing one of a message's attachments to disk, by message id and attachmentName, into the savePath directory (saved as savePath/attachmentName). Returns: a confirmation of the saved file path. Do not use when: you don't know the attachment name (use list-attachments first) or want the bytes inline rather than on disk (use fetch-attachment). Safety: writes a file to disk — savePath must be a directory inside the configured allowed roots, and attachmentName may not contain path separators or '..'; calls outside those constraints are rejected.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes
`savePath`	Yes
`attachmentName`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`savedPath`	No
`attachmentName`	No

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It thoroughly discloses safety constraints (allowed roots, path separator rules, rejection behavior) and the return value (confirmation of saved file path). This is comprehensive for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with clear sections: when to use, return value, when not to use, and safety. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema (not shown but indicated), the description covers all necessary aspects: purpose, usage guidance, behavioral traits, and parameter semantics. No critical information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage, so description must compensate. It explains that savePath is a directory and that the file is saved as savePath/attachmentName. It also adds constraints like path separators and '..' prohibition, which are not in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'writing one of a message's attachments to disk', which is a specific verb+resource. It distinguishes from sibling tools like list-attachments and fetch-attachment by specifying when each alternative should be used.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'Use when:' and 'Do not use when:' with clear conditions and references to alternatives (list-attachments, fetch-attachment). This provides excellent guidance for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

save-templateA

Use when: creating a reusable email template (name, subject, body, optional default to/cc), or updating one by passing its existing id. Subject/body may contain placeholders for later use. Returns: the saved template's name and id (reuse the id with use-template / get-template / delete-template). Do not use when: composing a one-off message (use create-draft / send-email) or filling in a template to send (use use-template). Safety: writes the template to the on-disk templates store (APPLE_MAIL_MCP_TEMPLATES_FILE) and persists across restarts; passing an existing id overwrites that template.

ParametersJSON Schema

Name	Required	Description
`cc`	No	Default CC recipients
`id`	No	Template ID (for updating existing template)
`to`	No	Default recipients
`body`	Yes
`name`	Yes
`subject`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	No
`ok`	No
`name`	No

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses writes to disk, persistence across restarts, and overwrite behavior. Could mention permissions or reversibility, but is transparent for a typical write operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, using structured sections (Use when, Do not use when, Safety). No redundant sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 6 params and an output schema. The description covers usage, exclusions, safety, and return values. It is sufficiently complete for the complexity level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50% (3 of 6 params documented). The description adds context: 'optional default to/cc', 'passing existing id' for update, and mention of placeholders. This compensates for missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool saves or updates a reusable email template, specifying the resource (template) and action (save/update). It differentiates from siblings like use-template and create-draft, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides when to use (creating/updating a template), when not to use (one-off messages, filling in a template), and names alternative tools (create-draft, send-email, use-template). This gives clear decision criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

schedule-draftsA

Use when: the user explicitly asks to send one or more fully reviewed Apple Mail drafts at a future date/time. Returns: one persistent schedule_id per draft, the exact requested time, recipients, From identity, subject, and pending status. Requirements: send_at must be RFC 3339 with an explicit timezone offset (for example 2026-07-29T07:00:00+08:00); drafts with attachments are refused; the Mac must remain logged in, and overdue jobs run after wake/login. Do not use when: the user merely mentions a possible future send, has not reviewed the drafts, or wants Mail's native Send Later mailbox—the public Mail scripting API does not expose that UI feature. Safety: this creates a REAL FUTURE SEND. Require explicit confirmation of the exact draft_ids, recipients/content, From identity, send time, and timezone before passing confirmed=true.

ParametersJSON Schema

Name	Required	Description
`send_at`	Yes	RFC 3339 date/time with explicit offset, e.g. "2026-07-29T07:00:00+08:00"
`confirmed`	Yes	Must be true only after the user explicitly confirms the exact future sends
`draft_ids`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`count`	No
`schedules`	No

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses key behaviors: drafts with attachments refused, Mac must stay logged in, overdue jobs run after wake/login, and the real future send. It also explains the return value structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is well-structured with sections (Use when, Returns, Requirements, Do not use, Safety) and is approximately 7 sentences. Every sentence adds essential information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and 3 required parameters with partial schema coverage, the description covers use case, prerequisites, safety, return info, and constraints. It is sufficiently complete for an agent to correctly invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, and description adds meaning beyond schema by explaining the confirmation requirement and attachment restriction. It reinforces send_at format and confirmed semantics, adding value over the schema definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Use when: the user explicitly asks to send one or more fully reviewed Apple Mail drafts at a future date/time', which clearly identifies the specific verb and resource. It distinguishes from sibling tools like send-draft (immediate send) and other scheduling operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides both when to use ('Use when') and when not to use ('Do not use when'), including alternatives like Mail's native Send Later mailbox. It gives clear context and exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search-contactsA

Use when: looking up a person in Contacts by name, organization, nickname, or email to find their email address(es)/phone(s) before composing or sending mail. Reads the macOS Contacts database directly (needs Full Disk Access; does NOT require Contacts.app to be running or an Automation / Apple-Events grant). Returns: matching contacts with their names, email addresses, and phone numbers. Do not use when: searching email messages (use search-messages) — this queries Contacts, not the mailbox.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No
`contacts`	No

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses that the tool reads the macOS Contacts database directly, requires Full Disk Access, and does not need Contacts.app running or an Automation grant. This gives agents critical behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Five sentences, logically ordered: use-case, permissions, return values, exclusion. No fluff; every sentence is essential and informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with an output schema, the description covers purpose, usage, permissions, parameter meaning, and return values. It is self-contained and answers likely agent questions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% (only a bare 'query' string with minLength). The description compensates by specifying that the query can include name, organization, nickname, or email, adding semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool looks up a person in Contacts by name, organization, nickname, or email to find email addresses and phone numbers for composing mail. It distinguishes from the sibling tool search-messages, which searches email messages instead.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use when' and 'Do not use when' sections provide clear guidance. It names the alternative tool search-messages for searching email, leaving no ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search-messagesA

Use when: finding messages by query/sender/subject/date/read/flag filters and you need their ids for follow-up operations. Returns: matching messages with id, date, subject, sender, and read state (plus partial-coverage diagnostics when some mailboxes were skipped). Do not use when: you want a plain mailbox listing without filters (use list-messages), already have an id and want the body (use get-message), or want a whole conversation (use get-thread). Prefer this first to obtain the message ids that get-message/mark-as-read/delete-message/move-message and the batch tools require.

ParametersJSON Schema

Name	Required	Description
`from`	No	Filter by sender (substring match against the full sender string, i.e. display name + address — not an exact address match)
`limit`	No	Maximum number of results (default: 50, max: 500)
`query`	No	Text to search for in subject, sender, or content
`dateTo`	No	End date filter (e.g., 'March 1, 2026')
`isRead`	No	Filter by read status
`account`	No	Account to search in (omit to search all accounts)
`mailbox`	No	Mailbox to search in (e.g., 'INBOX'). Omit to search all mailboxes.
`subject`	No	Filter by subject line (substring match)
`dateFrom`	No	Start date filter (e.g., 'January 1, 2026')
`isFlagged`	No	Filter by flagged status

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No
`partial`	No
`messages`	No
`timedOutAccounts`	No
`notSearchedMailboxes`	No
`skippedLargeMailboxes`	No

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden. It discloses the return format (id, date, subject, sender, read state) and a notable behavioral detail: partial-coverage diagnostics when some mailboxes are skipped. This is sufficient for a non-destructive search tool, though additional info on rate limits or performance could enhance it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded: it starts with 'Use when', then 'Returns', then 'Do not use when', and finally 'Prefer this first'. Every sentence is functional and adds value, with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists (not shown but indicated), the description appropriately covers return fields and an edge case (partial coverage). For a search tool with 10 parameters, it provides sufficient context for an agent to use it effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with good descriptions for all 10 parameters. The description only mentions filters generically and does not add meaning beyond the schema. Baseline 3 is appropriate since the schema already provides full parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: searching messages with various filters (query, sender, subject, date, read, flag) to obtain IDs for follow-up operations. It distinguishes from siblings like list-messages (plain listing), get-message (if ID known), and get-thread (conversation), so the agent can select correctly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Use when' and 'Do not use when' instructions, naming specific alternatives (list-messages, get-message, get-thread). It also advises to prefer this tool first to get IDs needed by other tools, giving clear context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

send-draftA

Use when: sending an existing Apple Mail draft after the user has reviewed it or explicitly asked to send that draft. Saved plain-text drafts are reconstructed through Mail's compose bridge; attached drafts must be sent from Mail.app to preserve their MIME structure. Returns: the sent draft_id, subject, actual From identity, and recipients. Do not use when: the user still needs to review or edit it (use read-draft/update-draft), or when has_attachments is true. Safety: SENDS real email immediately and cannot be unsent — require explicit confirmation of this exact draft.

ParametersJSON Schema

Name	Required	Description	Default
`draft_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`from`	No
`subject`	No
`draft_id`	No
`recipients`	No

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so description bears full burden. It discloses that the tool 'SENDS real email immediately and cannot be unsent', requires explicit confirmation, and explains how drafts with attachments are handled differently. This is thorough and safety-conscious.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and concise: starts with purpose, then returns, then exclusions, then safety. Every sentence adds value without redundancy. Ideal length for an AI agent to quickly parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (sending email with MIME considerations) and presence of an output schema, the description covers all essential aspects: when to use, what it returns, safety warnings, and special cases (attachments). No significant gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter (draft_id) is defined, and the input schema has 0% description coverage. The description does not explain the parameter's origin or format beyond its pattern; the return values mention draft_id but not how to obtain it. While the parameter is simple, adding context (e.g., 'obtain from list-drafts') would improve clarity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool sends an existing Apple Mail draft and specifies when to use it (after user review or explicit request). It distinguishes from siblings like create-draft, read-draft, and update-draft by emphasizing sending, not editing or creating.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use when' and 'Do not use when' sections provide clear context: send only after review or explicit request, and avoid if user still needs to edit or if attachments are present (use send-email instead). This contrasts effectively with sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

send-emailA

Use when: the user has explicitly confirmed they want to send a single email now to the given recipients (to/cc/bcc are arrays), optionally with attachments and a chosen transport. Returns: a confirmation naming the recipients and attachment count. Do not use when: the user wants to review first (use create-draft), is replying to or forwarding an existing message (use reply-to-message / forward-message), or wants per-recipient personalized copies (use send-serial-email). Safety: this SENDS real email immediately and it cannot be unsent — require explicit user confirmation of the exact recipients, subject, and body before calling. Prefer create-draft when there is any doubt.

ParametersJSON Schema

Name	Required	Description
`cc`	No	CC recipients
`to`	Yes
`bcc`	No	BCC recipients
`body`	Yes
`account`	No	Account to send from
`subject`	Yes
`transport`	No	Send transport. 'smtp' submits clean MIME directly via SMTP, avoiding the macOS 15+ Mail.app <blockquote> wrapping (issue #12); requires APPLE_MAIL_MCP_SMTP_* env config. 'applescript' sends through Mail.app. If omitted, SMTP is used automatically when APPLE_MAIL_MCP_SMTP_* is configured, otherwise AppleScript.
`attachments`	No	Files to attach: absolute paths (e.g. '/Users/me/report.pdf') and/or inline {filename, contentBase64} objects up to 25 MiB decoded each.

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`transport`	No
`recipients`	No
`attachmentCount`	No

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that email is sent immediately and cannot be unsent, requiring explicit user confirmation. Explains transport implications (SMTP vs AppleScript, MIME wrapping). Despite no annotations, description fully covers behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with core usage conditionals, no wasted words. Every sentence provides essential guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Comprehensive for a sending tool: covers target, safety, alternatives, transport details, return value (confirmation). Remaining schema descriptions plus output schema (exists) provide full picture.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds meaning beyond schema: clarifies arrays for recipients, optional attachments, transport enum descriptions. Schema covers 63% of parameters with descriptions; description fills gaps and adds usage context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it sends a single email now with recipients, attachments, and transport. Distinguished from siblings like create-draft, reply-to-message, forward-message, send-serial-email.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides 'Use when' and 'Do not use when' conditions, listing specific alternatives for review, reply/forward, per-recipient copies.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

send-serial-emailA

Use when: the user has confirmed a mail-merge — sending individually personalized copies to many recipients (max 100), with {{Key}} placeholders in subject/body replaced per-recipient from each recipient's variables. Recipients do not see each other. Returns: a per-recipient sent/failed report with counts. Do not use when: sending one message to a shared recipient list (use send-email) or saving for review (use create-draft). Safety: this SENDS many real emails immediately and they cannot be unsent — require explicit user confirmation of the recipient list, the subject/body template, and the placeholder substitutions before calling.

ParametersJSON Schema

Name	Required	Description
`body`	Yes	Email body — use {{Key}} for placeholders
`account`	No	Account to send from
`delayMs`	No	Delay between sends in ms (default: 500, max: 10000)
`subject`	Yes	Subject line — use {{Key}} for placeholders
`recipients`	Yes	List of recipients with personalization variables (max 100)

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`sent`	No
`failed`	No
`results`	No

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations were provided, but the description fully covers behavioral traits: it SENDS many real emails immediately, cannot be unsent, requires explicit user confirmation, and returns a per-recipient report. This compensates for the lack of annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with three short paragraphs that are front-loaded with the core use case. Every sentence adds value, no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (mail merge with placeholders, safety concerns) and the presence of an output schema (referenced but not shown), the description is complete: it covers when to use, safety, return format, and distinguishes from alternatives. Little else is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds context by explaining placeholder syntax {{Key}}, default and max delayMs, and the structure of recipient variables. It integrates parameter usage into the overall workflow, providing value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states it is for mail-merge with personalized copies to many recipients, using {{Key}} placeholders. It clearly distinguishes from send-email (shared list) and create-draft (saving for review).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Use when' and 'Do not use when' conditions, naming specific alternative tools (send-email, create-draft). It also gives safety prerequisites, requiring explicit user confirmation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set-default-sending-identityA

Use when: choosing the plugin's default From identity for future create-draft calls. This changes only apple-mail-mcp's local preference; it does not alter Mail.app account settings. Returns: the selected identity. Do not use when: selecting From for only one draft (pass from to create-draft/update-draft). Safety: writes a reversible local preference and sends nothing.

ParametersJSON Schema

Name	Required	Description	Default
`identity`	Yes	Exact identity_id, email address, or formatted sender from list-sending-identities

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`identity`	No

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description discloses that the action is local, reversible, and sends nothing. It mentions return value but could add detail on authorization or side effects; still strong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with clear sections (use when, do not use when, returns, safety). Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and presence of an output schema, the description covers all necessary aspects: purpose, usage context, behavioral effects, and return type.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already describes the parameter well. The description adds the return value indication, providing additional context beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool is for setting the plugin's default From identity for future create-draft calls. It distinguishes from siblings by specifying its local scope and effect, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use when' and 'Do not use when' sections with concrete alternatives (e.g., passing 'from' to create-draft) provide clear guidance on when to invoke this tool versus others.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

unflag-messageA

Use when: removing the flag from a single message (by id). Returns: a confirmation that the message was unflagged. Do not use when: unflagging several at once (use batch-unflag-messages) or adding a flag (use flag-message). Get the id from search-messages or list-messages first.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	No
`ok`	No

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It states it returns a confirmation. It does not detail error cases or permission requirements, but for a simple, non-destructive mutation, this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four well-organized sentences: use when, returns, do not use, and a hint to get the parameter. No fluff, information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a simple mutation tool. Addresses purpose, parameter source, and exclusions. Has an output schema (not shown) so return details are covered. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage, but description explains that the 'id' parameter is a message identifier and suggests how to get it. This adds valuable context beyond the schema's pattern constraint.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the action: removing a flag from a single message. Differentiates from sibling tools flag-message and batch-unflag-messages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (removing flag from single message) and when not to (batch unflagging or adding flag). Also advises how to obtain the required id parameter from search-messages or list-messages.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update-draftA

Use when: editing an existing Apple Mail draft in place, selected by draft_id from list-drafts. Omitted fields are preserved; empty recipient arrays explicitly clear that recipient class. Mail's scripting bridge cannot safely recreate attached drafts, so update-draft refuses them instead of losing attachments. Returns: the same stable draft_id and the complete updated draft. Do not use when: creating a new draft (use create-draft), or when has_attachments is true (edit that draft in Mail.app). Safety: updates a saved draft only and sends nothing.

ParametersJSON Schema

Name	Required	Description
`cc`	No
`to`	No
`bcc`	No
`body`	No
`from`	No	Sending identity id, email address, or formatted sender from list-sending-identities
`subject`	No
`draft_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	No
`draft`	No

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It covers omitted fields preservation, empty array clearing, refusal of attached drafts, and safety (updates only, sends nothing). This is comprehensive behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections 'Use when', 'Returns', 'Do not use when', and 'Safety'. Every sentence adds value, and it is front-loaded with critical usage guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 7 parameters, large sibling set, and presence of an output schema, the description covers all essential aspects: usage scope, parameter behavior, return value, and safety. Error handling is omitted but acceptable for typical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is low (14%), so description must compensate. It explains that omitted fields are preserved, empty arrays clear recipients, and from can be identity id/email/sender. However, it does not detail subject or body beyond their existence, leaving some gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it edits an existing Apple Mail draft, selected by draft_id. It distinguishes from sibling create-draft and from editing drafts with attachments, providing a specific verb+resource+scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides 'Use when' and 'Do not use when' scenarios, with alternatives like create-draft and editing drafts with attachments in Mail.app. The description gives clear context for when to invoke this tool vs siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

use-templateA

Use when: composing a new draft from a saved template (by id), optionally overriding the recipients, subject, or body. Creates a draft in Mail.app for the user to review and send. Returns: a confirmation that a draft was created from the template. Do not use when: you want to inspect the template without composing (use get-template) or send immediately without a draft (use send-email).

ParametersJSON Schema

Name	Required	Description
`cc`	No	Override CC recipients
`id`	Yes
`to`	No	Override recipients
`body`	No	Override body
`subject`	No	Override subject

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	No
`ok`	No

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Although no annotations are provided, the description discloses key behavioral traits: it creates a draft in Mail.app for user review and sends a confirmation. It does not mention side effects beyond creating a draft, which is adequate for a non-destructive action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (3 sentences) and well-structured with clear 'Use when', 'Returns', and 'Do not use when' sections. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity and the presence of an output schema, the description sufficiently covers the core functionality and return value (confirmation). However, it could mention that the draft remains editable by the user, though this is implied.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds context to parameters beyond the schema by noting that recipients, subject, and body are optional overrides. With 80% schema coverage, the description reinforces the purpose of each override, especially clarifying that id is a template identifier.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: composing a new draft from a saved template by id, with optional overrides. It distinguishes itself from sibling tools like get-template and send-email, providing a specific verb and resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use (composing a draft from a template) and when not to use (inspecting template via get-template, or sending directly via send-email). This provides clear guidance for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

61 tool updatesv0.1.0Jul 28, 2026
- First observedbatch-delete-messages
- First observedbatch-flag-messages
- First observedbatch-mark-as-read
- First observedbatch-mark-as-unread
- First observedbatch-move-messages
- First observedbatch-unflag-messages
- First observedcancel-scheduled-send
- First observedcreate-draft
- First observedcreate-mailbox
- First observedcreate-newsletter-smart-mailboxes
- First observedcreate-rule
- First observedcreate-smart-mailbox
- First observeddelete-draft
- First observeddelete-mailbox
- First observeddelete-message
- First observeddelete-rule
- First observeddelete-smart-mailbox
- First observeddelete-template
- First observeddisable-rule
- First observeddoctor
- First observedenable-rule
- First observedfetch-attachment
- First observedflag-message
- First observedforward-message
- First observedget-mail-stats
- First observedget-message
- First observedget-sync-status
- First observedget-template
- First observedget-thread
- First observedget-unread-count
- First observedhealth-check
- First observedlist-accounts
- First observedlist-attachments
- First observedlist-drafts
- First observedlist-mailboxes
- First observedlist-messages
- First observedlist-rules
- First observedlist-scheduled-sends
- First observedlist-sending-identities
- First observedlist-smart-mailboxes
- First observedlist-templates
- First observedmark-as-read
- First observedmark-as-unread
- First observedmove-message
- First observedread-draft
- First observedrename-mailbox
- First observedreply-to-message
- First observedreschedule-scheduled-send
- First observedresolve-message-id
- First observedsave-attachment
- First observedsave-template
- First observedschedule-drafts
- First observedsearch-contacts
- First observedsearch-messages
- First observedsend-draft
- First observedsend-email
- First observedsend-serial-email
- First observedset-default-sending-identity
- First observedunflag-message
- First observedupdate-draft
- First observeduse-template

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0

Disambiguation5/5

Each tool targets a distinct resource and action, with detailed 'use when' and 'do not use when' guidance that clearly differentiates similar-sounding tools like send-email vs send-serial-email vs send-draft, or search-messages vs list-messages. No two tools overlap in purpose.

Naming Consistency5/5

All 61 tools follow a consistent verb_noun snake_case pattern (e.g., delete-template, list-messages, batch-flag-messages). The naming is uniform and predictable, making it easy to infer tool behavior from its name.

Tool Count2/5

With 61 tools, the count is far above the typical well-scoped range of 3-15. While each tool has a clear purpose, the high number—especially the proliferation of batch variants and diagnostic tools—makes the surface feel bloated and potentially overwhelming for an agent.

Completeness5/5

The tool set covers virtually every aspect of email management: sending, receiving, drafting, replying, forwarding, mailbox CRUD, rule management, template management, smart mailboxes, contacts, attachments, scheduling, and diagnostics. There are no obvious gaps for a consumer email client.

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

email A
dev.primitive
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email Communication
302
AgentMailOAuth
to.agentmail
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Email Communication
2
shipmail-mcpOAuth
io.github.shipmail-to
Shipmail MCP server for AI agent custom-domain email inboxes with REST API and webhooks.
Email Communication App Automation
21
ClawLinkOAuth
dev.claw-link
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
App Automation Workplace & Productivity
24

Related MCP Servers

apple-mail-mcp
Email OS Automation
sweetrb
A
license
A
quality
A
maintenance
This MCP server allows AI assistants to read, send, search, and manage emails in Apple Mail on macOS. It uses AppleScript to interact with the Mail app locally.
Updated 3 days ago (2026-09-05 11:35 UTC)
50
2,494
68
MIT
Errol-Mail
Email Communication
jasondk
A
license
Not graded
quality
C
maintenance
An MCP server that gives AI assistants comprehensive access to Apple Mail accounts, enabling email discovery, reading, flag management, and server-side message retrieval.
Updated 25 days ago (2026-08-14 00:29 UTC)
MIT
apple-mail-mcp-server
Email Communication
wylieswanson
A
license
A
quality
A
maintenance
An MCP server that provides programmatic access to Apple Mail, enabling AI assistants like Claude to read, send, search, and manage emails on macOS.
Updated a month ago (2026-08-01 00:43 UTC)
25
MIT
Apple Mail MCP Server
isityael
A
license
B
quality
B
maintenance
An MCP server that gives AI assistants full access to Apple Mail -- read, search, compose, organize, and analyze emails via natural language.
Updated 2 days ago (2026-09-06 04:17 UTC)
38
MIT

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/yu2001-s/apple-mail'

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

Apple Mail

What is This?

Quick Start

Install in Codex

Local development

Configuring email (IMAP & SMTP)

Requirements

Features

Messages

Mailbox & Account Management

Rules, Contacts & Templates

Diagnostics

MCP resources & prompts

Tool Reference

Message Operations

search-messages

get-message

read-message

list-messages

send-email

SMTP transport

apple-mail-send CLI (no MCP server required)

IMAP backend — opt-in

Connection footprint (playing nice with Gmail)

Configuration file (when the host strips env)

Push notifications (IMAP IDLE) — opt-in

send-serial-email

create-draft

Scheduled draft sends

get-thread

fetch-attachment

reply-to-message

forward-message

mark-as-read / mark-as-unread

flag-message / unflag-message

delete-message

move-message

list-attachments

save-attachment

Batch Operations

batch-delete-messages

batch-move-messages

batch-mark-as-read / batch-mark-as-unread

batch-flag-messages / batch-unflag-messages

Mailbox Operations

list-mailboxes

get-unread-count

create-mailbox

delete-mailbox

rename-mailbox

Smart Mailbox Operations (intelligente Postfächer)

list-smart-mailboxes

create-smart-mailbox

delete-smart-mailbox

create-newsletter-smart-mailboxes

Account Operations

list-accounts

Rules

list-rules

enable-rule / disable-rule

create-rule

delete-rule

Contacts

search-contacts

Templates

save-template

list-templates

get-template

delete-template

use-template

Diagnostics

health-check

doctor

get-mail-stats

get-sync-status

Usage Patterns

Basic Workflow

Working with Accounts

Sending Emails Safely

Sending Personalized Emails (Mail Merge)

`search-messages`

`get-message`

`read-message`

`list-messages`

`send-email`

`apple-mail-send` CLI (no MCP server required)

Configuration file (when the host strips `env`)

`send-serial-email`

`create-draft`

`get-thread`

`fetch-attachment`

`reply-to-message`

`forward-message`

`mark-as-read` / `mark-as-unread`

`flag-message` / `unflag-message`

`delete-message`

`move-message`

`list-attachments`

`save-attachment`

`batch-delete-messages`

`batch-move-messages`

`batch-mark-as-read` / `batch-mark-as-unread`

`batch-flag-messages` / `batch-unflag-messages`

`list-mailboxes`

`get-unread-count`

`create-mailbox`

`delete-mailbox`

`rename-mailbox`

`list-smart-mailboxes`

`create-smart-mailbox`

`delete-smart-mailbox`

`create-newsletter-smart-mailboxes`

`list-accounts`

`list-rules`

`enable-rule` / `disable-rule`

`create-rule`

`delete-rule`

`search-contacts`

`save-template`

`list-templates`

`get-template`

`delete-template`

`use-template`

`health-check`

`doctor`

`get-mail-stats`

`get-sync-status`

Running from a clone in Claude Code (project-scope `.mcp.json`)

Mail.app `<blockquote>` wrapping on macOS 15+ (workaround in v1.6.0)

`search-messages` says "Partial results" or skips a mailbox

`apple-mail` server fails to connect when run from a clone