macos-apps-mcp

Overview Schema Source Related Servers Discussions Admin

mail_attachments

Read-only

List attachments on Apple Mail messages by scanning a mailbox or targeting one message by ID, so you can confirm files landed on a draft or find where an attachment was received.

Instructions

List attachments on messages in a Mail mailbox, or on ONE message (Automation).

mailbox: the folder value from a mail_search result passed back VERBATIM (an opaque imap://<uuid>/<path> token, not a name to retype), or a canonical system mailbox — "inbox" | "sent" | "drafts" | "trash" | "junk" (resolved via Mail's unified, cross-account accessors). query: optional subject substring — an empty/omitted query lists ALL messages in the mailbox (bounded), unlike mail/get_pointers which rejects an empty query. Use this to confirm an attachment landed on a DRAFT before it's saved (a freshly opened compose window has no stable id yet — once saved to Drafts it does, see drafts()). message_id: address ONE message instead of scanning; with no mailbox the id resolves on its own (Full Disk Access), and query is then ignored. Prefer it when you know the message — a mailbox scan stops at 25 records, so the one you meant is often past the cap. Either mailbox or message_id is required. Returns {results, truncated?} over [{id, deeplink, folder, summary, attachments: [{name, size, downloaded}]}]. id/deeplink identify the carrying message and folder names the mailbox read, so a row is actionable on its own. An unsaved draft has no message-id yet: its id is "" and it carries no deeplink — it is still listed.

Input Schema

Name	Required	Description	Default
`query`	No
`mailbox`	No
`message_id`	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.9/5.0

Behavior5/5

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

Annotations already establish readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context beyond them: bounded mailbox scans, truncation, empty-query listing behavior, Full Disk Access resolution for message_id, and the unsaved-draft edge case where id is empty and deeplink is absent.

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 front-loaded and dense with useful distinctions, but it is long and parenthetical-heavy. It also explains the return shape despite an output schema existing, which is somewhat redundant, though the return semantics around actionable rows and unsaved drafts still add 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 output schema and read-only annotations, the description is complete enough for correct invocation: it covers all parameters, alternatives, required input combinations, scan limits, and key edge cases. Nothing essential for selecting or calling the tool appears 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 description coverage is 0%, so the description must compensate, and it does for all three parameters. It explains mailbox as an opaque imap token or canonical system mailbox, query as an optional subject substring with special empty-query behavior, and message_id as a single-message selector that ignores query and can resolve without mailbox.

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

Purpose5/5

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

The opening sentence uses a specific verb and resource: 'List attachments' on messages in a Mail mailbox or on one message. It distinguishes mailbox scanning from single-message lookup, and references related tools like mail_search, mail/get_pointers, and drafts to disambiguate usage.

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 gives explicit routing guidance: use mailbox for a folder scan or message_id for one known message, prefer message_id because scans stop at 25 records, query is ignored when message_id resolves on its own, and either mailbox or message_id is required. It also states a concrete use case: confirming an attachment landed on a draft before saving.

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

Deploy Server