apple-mail-mcp

Overview Schema Source Related Servers Discussions Admin

batch-flag-messages

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.

Instructions

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. Pass sourceMailbox/sourceAccount (the mailbox you listed the ids from) so each numeric id is pinned to that mailbox; an id that matches in several mailboxes is refused, not guessed. Note: the color is applied on both routes — AppleScript sets the flag index, IMAP writes the equivalent $MailFlagBit0/1/2 keywords Mail.app reads — so a mixed batch of numeric and imap: ids all end up colored, and search-messages' flagColor filter finds the whole set again later regardless of mailbox.

Input Schema

Name	Required	Description
`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. The color is applied on both routes: AppleScript sets the flag index, and IMAP writes the equivalent $MailFlagBit0/1/2 keywords Mail.app reads — so a smart mailbox keyed on flag color matches either way.
`sourceAccount`	No	Account the numeric ids were listed from. Required when sourceMailbox is supplied; on its own it pins nothing.
`sourceMailbox`	No	Mailbox the numeric ids were listed from (e.g. 'INBOX'). Must be paired with sourceAccount to form an unambiguous scope. Ignored for imap: ids.

Output Schema

Name	Required	Description	Default
`ok`	No
`errors`	No
`failed`	No
`mailbox`	No
`success`	No
`errorsTruncated`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv2.10.24Aug 14, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / properties / sourceAccount

Added value: +{
+  "description": "Account the numeric ids were listed from. Required when sourceMailbox is supplied; on its own it pins nothing.",
+  "type": "string"
+}

addedInput schema / properties / sourceMailbox

Added value: +{
+  "description": "Mailbox the numeric ids were listed from (e.g. 'INBOX'). Must be paired with sourceAccount to form an unambiguous scope. Ignored for imap: ids.",
+  "type": "string"
+}

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / properties / errors

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / errorsTruncated
```
Added value: +{
+  "type": "boolean"
+}
```

Changed2 schema fields changedv2.10.8Aug 7, 2026

changedInput schema / properties / color / description

Previous value: -"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)."New value: +"Optional flag color (Apple Mail palette: red, orange, yellow, green, blue, purple, gray — 'grey' accepted). Omit for Mail's default flag. The color is applied on both routes: AppleScript sets the flag index, and IMAP writes the equivalent $MailFlagBit0/1/2 keywords Mail.app reads — so a smart mailbox keyed on flag color matches either way."

changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +true
```

Addedv2.8.14Jul 22, 2026
Removedv2.8.10Jul 18, 2026

Changed1 schema field changedv2.8.2Jul 4, 2026

addedInput schema / properties / color

Added value: +{
+  "description": "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).",
+  "enum": [
+    "red",
+    "orange",
+    "yellow",
+    "green",
+    "blue",
+    "purple",
+    "gray",
+    "grey"
+  ],
+  "type": "string"
+}

First observedv2.6.1Jun 29, 2026

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does so well: it discloses the ambiguous-id refusal policy, the sourceMailbox/sourceAccount pinning requirement, and the dual-route color mechanism (AppleScript flag index vs IMAP $MailFlagBit keywords). It omits auth/permission requirements and atomicity guarantees, but covers the behaviors that most affect correct invocation.

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 Use-when/Returns/Do-not-use-when structure, so the actionable content comes first and the longer Note is relegated to the end. The Note is somewhat dense but each clause carries distinct technical 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 non-annotated batch mutation tool with an output schema, this is close to complete: usage triggers, exclusions, id-format handling, parameter pinning, and return semantics are all covered. Only error handoff and permission prerequisites are absent, which is a modest gap.

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 75%, and the description adds real meaning beyond it — the pinning semantics of sourceMailbox/sourceAccount (which mailbox the numeric ids came from, and that ambiguity is refused rather than guessed) and that color applies on both routes. This compensates for the remaining 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?

States a specific verb (flag) plus resource (messages) and batch scope (1-100 ids), and explicitly distinguishes itself from flag-message and batch-unflag-messages. An agent can route correctly without opening any 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?

Gives explicit 'Use when' and 'Do not use when' clauses naming the exact alternatives (flag-message for single, batch-unflag-messages for removal) and directs the agent to search-messages/list-messages first to obtain ids. Nothing is left to inference.

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

Deploy Server