Skip to main content
Glama
epinethrone

icloud-mcp

by epinethrone
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

mail_list_folders

Read-only

List all iCloud Mail folders with total and unread counts to discover exact folder names other mail tools accept, fixing unknown-folder or open errors.

Instructions

List every mail folder with its total and unread message counts, so you know the exact names other mail tools accept.

Use when: a folder name is unknown, a tool reported "Could not open the folder", or you want to see where mail is filed. Not for finding messages (use mail_search_messages) or for what changed recently (use mail_list_changes). Parameters: none; it always covers the whole account. Behavior: read-only; opens no folder and changes no flags. Folders that cannot hold mail (IMAP \Noselect) are left out. Special folders are also reachable in every mail tool by the aliases Sent, Drafts, Trash, Junk and Archive; the main folder is INBOX. Returns: a list of {name, special_use, total, unseen}; special_use is the IMAP flag such as \Sent or null. total and unseen are null when the server would not report them for that folder. The list is never empty (INBOX always exists). Errors: a sign-in or connection failure raises an error; run icloud_check_health to see which service is down.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -{
-  "properties": {
-    "result": {
-      "items": {
-        "additionalProperties": true,
-        "type": "object"
-      },
-      "title": "Result",
-      "type": "array"
-    }
-  },
-  "required": [
-    "result"
-  ],
-  "title": "mail_list_foldersOutput",
-  "type": "object"
-}New value: +null
  2. Changed1 schema field changedv0.7.0
    • removedInput schema / title
      Removed value: -"mail_list_foldersArguments"
  3. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Goes well beyond the readOnlyHint/openWorldHint annotations: states it opens no folder and changes no flags, excludes \Noselect folders, documents the Sent/Drafts/Trash/Junk/Archive aliases and INBOX, explains null total/unseen, and routes errors to icloud_check_health. This is rich behavioral context an agent could not derive from structured fields.

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?

Front-loaded with purpose, then clearly sectioned into Use when, Parameters, Behavior, Returns, and Errors. Despite its length, each sentence carries distinct, actionable information with no filler.

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?

With no output schema, the description fully compensates by describing the return shape ({name, special_use, total, unseen}), null semantics, the guarantee of a non-empty list, and error behavior. An agent has everything needed to call and interpret this tool.

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?

Zero parameters, so the baseline is 4. The description reinforces this by stating there are no parameters and that the call always covers the whole account, which usefully clarifies scope, though there is no per-parameter meaning to add.

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 (list) and resource (mail folders) plus the scope of the returned data (total and unread counts) and the practical reason (to learn names other mail tools accept). An agent can distinguish it from mail_search_messages and mail_list_changes immediately.

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?

Explicit 'Use when' triggers (unknown folder name, 'Could not open the folder' error, seeing where mail is filed) plus explicit exclusions that name the correct alternatives (mail_search_messages for messages, mail_list_changes for recent activity). 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

Other Tools