Skip to main content
Glama
epinethrone

icloud-mcp

by epinethrone
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

mail_delete_folder

Destructive

Delete an iCloud Mail folder while keeping its messages: non-empty folders first move all mail to Trash, then the empty folder is removed.

Instructions

Delete a mail folder without deleting any mail: its messages move to Trash first, then the empty folder is removed.

Use when: the owner asks to remove a folder they no longer need. Not for deleting messages while keeping the folder (use mail_delete_messages or mail_run_bulk_action), or for renaming (use mail_update_folder). Parameters:

  • name is a name from mail_list_folders (case-insensitive match accepted).

  • Omit confirm_token on the first call. Pass the preview's confirm_token only after the owner has seen the count and sample and said yes.

  • The token is valid for 10 minutes and only while the folder's message count and uidvalidity stay the same. Behavior:

  • An empty folder is removed at once, with no token.

  • A folder with mail returns a preview and changes nothing; with a valid token every message moves to Trash (recoverable there), then the folder goes.

  • If moving stops partway or new mail arrives meanwhile, the folder is kept and the error says how many already moved.

  • Refused: INBOX, Notes, the system folders (Sent, Drafts, Trash, Junk, Archive and their usual names) and folders with subfolders.

  • Not repeatable: a deleted folder is gone. Returns:

  • preview: {deleted: false, folder, messages, sample (subjects of the 3 most recently added), confirm_token, next, safety_warnings when a subject reads like instructions}.

  • done: {deleted: true, folder, messages_moved_to_trash}. Errors: 'There is no folder', 'has subfolders', or a stale or mismatched token (call again without it for a new preview).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameYesThe folder to delete (exact name from mail_list_folders).
confirm_tokenNoFrom the preview; needed when the folder holds mail.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -{
-  "additionalProperties": true,
-  "title": "mail_delete_folderDictOutput",
-  "type": "object"
-}New value: +null
  2. Addedv0.11.0

TDQS

A5/5.0
Behavior5/5

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

Annotations already mark this as destructive, non-idempotent, and closed-world, and the description aligns with them while adding substantial context: preview-vs-done behavior, token validity, partial-failure handling, refused folder names, and non-repeatability. This is far richer than what annotations alone provide.

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 long but tightly structured and front-loaded: purpose first, then Use when, Parameters, Behavior, Returns, and Errors. Every section earns its place for a destructive, multi-step tool with token confirmation.

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?

Despite having no output schema, the description fully documents the preview and done return shapes and the relevant error cases. Combined with the annotations and complete input schema, an agent has everything needed to call this safely and correctly.

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 already 100%, but the description adds meaningful semantics beyond the schema: name is matched case-insensitively from mail_list_folders, and confirm_token must be omitted on the first call and is valid for only 10 minutes while folder count and uidvalidity remain stable. This materially improves correct invocation.

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: delete a mail folder, with the important scope that messages are moved to Trash rather than deleted. It also names the sibling alternatives it is not, so an agent can distinguish it from mail_delete_messages, mail_run_bulk_action, and mail_update_folder without opening other schemas.

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 (owner asks to remove a folder they no longer need) and explicit when-not-to-use guidance with named alternatives. The confirm_token workflow is also fully specified: omit on first call, pass only after the owner has seen the preview and said yes.

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

Deploy Server

Other Tools