macos-apps-mcp

by elfensky

Overview Schema Source Related Servers Discussions Admin

Python

Local

trash_mail

Destructive

Move Mail messages to Trash for recoverable soft deletion, with a dry-run preview, backup, and undo support.

Instructions

Move Mail messages to Trash — soft delete, and the ONLY delete there is.

Mail's scripting layer cannot permanently erase a message: delete moves it to the owning account's Trash, and nothing in the dictionary empties Trash from a script. Emptying Trash is something the user does in Mail.app. So this is always recoverable, and there is no permanent-delete tool to ask for.

DESTRUCTIVE but recoverable: every message's bytes are copied to a backup directory and its source mailbox logged BEFORE anything is deleted, so mail_undo moves the batch back out of Trash. dry_run DEFAULTS TO TRUE — the preview reports, per id, whether it is actually present in mailbox. Pass dry_run=False to delete. ids are RFC822 message-ids from a mail read, comma-separated; max 25 per call and the cap is not overridable. mailbox is REQUIRED and must be the folder url from the read that produced the ids, passed back VERBATIM — not one of the canonical names: Mail files a deleted message in its OWNING account's Trash, and a unified name ("inbox") cannot say which account that is. A Gmail label folder is refused (a delete there is not a delete of the message, #287); use the message's [Gmail]/All Mail folder. Returns {op, receipt, count, succeeded, targets, destination, backup_dir, undo} — keep receipt to undo the batch. Each copy is deleted by Mail's internal id and verified by the account Trash's count rising, or every one of its copies' source reference going gone within a bounded wait (12 checks, 0.5s apart — up to 5.5s) — Mail's delete clears the source ASYNCHRONOUSLY, so "gone from the source" alone is not a signal that can be read straight after the call. A message with several stored copies gets every one of them trashed. If the call times out mid-batch, re-run the same batch or mail_undo the receipt. Needs Automation access for Mail, plus Full Disk Access to locate each message's file for the backup.

Input Schema

Name	Required	Description	Default
`ids`	Yes
`dry_run`	No
`mailbox`	Yes

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 declare destructiveHint=true, but the description adds genuinely new behavior: bytes are backed up and source mailboxes logged before deletion, dry_run defaults to true, deletion is verified by Trash-count rise or source-reference loss within a bounded 12x0.5s wait, Mail clears sources asynchronously, and a mid-batch timeout should be re-run or undone. It also states the Automation + Full Disk Access prerequisites — none of which are in the annotations.

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?

Front-loaded with the single most important fact (soft delete, only delete that exists) and organized in a logical order. It runs long for a 3-param tool and repeats the destructive-but-recoverable idea ('soft delete' then 'DESTRUCTIVE but recoverable'), but nearly every sentence carries load-bearing 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?

For a destructive, async-verifying, backup-dependent operation with 0% schema coverage, nothing an agent needs is missing: parameters, permissions, dry-run default, failure/timeout recovery, and the receipt to retain for undo are all present. It even summarizes the return shape, though an output schema already exists.

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%, so the description carries the full burden and does: ids are RFC822 message-ids from a mail read, comma-separated, capped at 25 non-overridably; mailbox is required, must be the verbatim folder url from the read that produced the ids, must not be a canonical/unified name, and Gmail label folders are refused; dry_run defaults true and must be set False to actually delete.

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?

States a specific verb and resource ('Move Mail messages to Trash') plus a distinguishing qualifier ('soft delete, and the ONLY delete there is'). An agent can immediately tell it apart from move_mail, delete_draft, or delete_note without opening a schema.

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 rules out the assumption of a permanent-delete tool, explains that emptying Trash is a user action in Mail.app, names mail_undo as the reversal path, and gives the exact substitution rule for Gmail label folders ('use the message's [Gmail]/All Mail folder'). When-to-use and when-not-to-use are both covered.

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

Deploy Server