macos-apps-mcp

Overview Schema Source Related Servers Discussions Admin

create_draft

Creates a Mail draft and opens it for review without sending, so you can check recipients, subject, and body before sending.

Instructions

Create a Mail draft and OPEN it for you to review and send — it NEVER sends on its own. to a recipient address. Returns a locator dict ({"created", "subject", "mailbox", "from", "note"}) — a freshly opened compose window has no stable id yet, so this says where to find it (Drafts) instead of fabricating one; save it and drafts() resolves it by its stable message-id. If the create FAILS partway, Mail may still leave a stray autosaved draft behind (#133 — its autosave is asynchronous and cannot be suppressed); drafts() + delete_draft() clear it.

A new draft is unthreaded; it is sent from from_address (an address one of Mail's accounts owns, matched case-insensitively, Name <addr> accepted) or Mail's default account. An address no account owns is refused before Mail builds anything — Mail would otherwise use its default account silently. To answer a message use mail_reply, which is threaded and sent from the account that received it.

THE AUTOSAVE WINDOW: Mail stamps the Message-ID only when it autosaves the draft, ~10-15 SECONDS after this returns — asynchronously, and nothing can hurry it. So drafts() called immediately shows nothing. That is normal. Wait for the window, then drafts() resolves it. Do NOT retry this call because the draft has not appeared: you get two drafts and the first one still arrives. Additive (creates a draft; does not send/modify/delete); needs Automation access for Mail (the ownership read is Automation too).

Input Schema

Name	Required	Description	Default
`to`	Yes
`body`	No
`subject`	No
`from_address`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.15.1Oct 26, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Despite annotations already saying this is non-read-only and non-destructive, the description adds substantial behavioral context: it never sends, opens a compose window, may leave a stray autosaved draft on failure, requires Automation access, and refuses unowned sender addresses.

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 core purpose and the never-sends guarantee are front-loaded, and the critical no-retry/autosave warning is prominently placed. It is long and repeats some autosave timing details, but the extra length is largely justified by the tool's non-obvious asynchronous behavior and cleanup path.

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 the create flow, return locator behavior, permissions, sender ownership rules, asynchronous autosave timing, partial-failure recovery, and the correct alternative tool. With an output schema present, it does not need to fully document return structure, and it still explains the key locator 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 description coverage is 0%, so the description must carry parameter meaning. It clearly explains `to` as a recipient address and richly documents `from_address` ownership, case-insensitive matching, `Name <addr>` support, and default-account fallback; `body` and `subject` are not explicitly described but are conventional and partially implied by the return 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 states a specific verb and resource: creating a Mail draft that opens for review and never sends by itself. It also distinguishes this from `mail_reply`, which is explicitly named as the threaded alternative for answering 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?

It gives explicit when-to-use guidance versus `mail_reply`, explains the autosave wait window, and warns not to retry because that creates duplicate drafts. It also names `drafts()` and `delete_draft()` for cleanup after a partial failure.

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

Deploy Server