Skip to main content
Glama
Sign In
proton-mcp

proton-mcp

by RndmJoker
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

List messages

list_messages
Read-only

Lists mailbox message headers—sender, subject, date, size, and ID—newest first, with paging and unread filtering; message bodies are omitted to avoid high token use.

Instructions

Lists the messages of a mailbox, newest first by the date the sender wrote, which also holds across pages. Returns headers only: sender, subject, date, size and the message id. It never returns message bodies, because a single message averages around 16000 tokens raw. Use get_message with an id to read one. Ordering reads one date per message in the mailbox, so a very large mailbox takes a moment; the answer says so when it does.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_messages"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoHow many messages to return, at most 100.
offsetNoHow many of the newest messages to skip. Used for paging.
mailboxNoThe mailbox path, for example "INBOX", "Archive" or "Folders/Work". Use list_folders to see them. "All Mail" holds every message including discarded ones, and there the entries that are in the trash come back marked "in trash".INBOX
unreadOnlyNoWhen true, only unread messages are listed.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.4.11
    • changedInput schema / properties / mailbox / description
      Previous value: -"The mailbox path, for example \"INBOX\", \"Archive\" or \"Folders/Work\". Use list_folders to see them."New value: +"The mailbox path, for example \"INBOX\", \"Archive\" or \"Folders/Work\". Use list_folders to see them. \"All Mail\" holds every message including discarded ones, and there the entries that are in the trash come back marked \"in trash\"."
  2. First observedv0.3.0

TDQS

A4.7/5.0
Behavior5/5

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

Goes well past the readOnlyHint annotation: it discloses the exact return fields, guarantees bodies are never returned and gives the reason (avg ~16000 tokens raw), and warns that ordering is expensive on very large mailboxes and that the response flags it. The cross-page ordering guarantee is also a real behavioral contract beyond annotations.

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?

Four sentences, all load-bearing: scope, return shape, the exclusion with its rationale, and the cost caveat. The most decision-relevant fact (headers only, no bodies) is front-loaded in the second sentence.

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?

There is no output schema, so the description must carry the return contract, and it does: sender, subject, date, size, message id, newest-first ordering, plus the 'in trash' marking behavior inherited from the mailbox parameter. Nothing needed to call it correctly is missing.

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 100%, so the baseline is 3, but the description adds genuine semantics for paging: the newest-first ordering 'holds across pages', which tells an agent that offset paging is stable. Limit/offset syntax itself is left to the schema.

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 ('Lists the messages of a mailbox') plus the ordering rule ('newest first by the date the sender wrote'). It explicitly separates itself from the read-one sibling by declaring headers-only output and pointing to get_message for bodies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear routing rule: use this to enumerate a mailbox, use get_message with an id to read a message. It does not address when an agent should prefer search_messages over a full listing, which is the main remaining ambiguity among siblings.

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