Skip to main content
Glama
proton-mail-mcp

proton-mail-mcp

by jasen1300

search_emails

Search a mailbox for emails by text, sender, recipient, subject, date, unseen/flagged status, attachment, or size; results are newest first and paginate for follow-up actions.

Instructions

Search a mailbox for emails (newest first); filters for text, from_, to, subject, date (since/before, YYYY-MM-DD), unseen/flagged, attachment and size. all_mail=True searches all folders ('All Mail'); limit/offset paginate.

The uid in the result is used by get_email/mark_email/move_email/
delete_email (valid in the chosen folder, with all_mail in 'All Mail');
'*' marks unread. Bridge does not search non-ASCII terms (e.g. 'café') -
this server filters them client-side against decoded headers/bodies.

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": "search_emails"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNo
textNo
from_No
limitNo
sinceNo
beforeNo
folderNoINBOX
offsetNo
subjectNo
all_mailNo
unseen_onlyNo
flagged_onlyNo
has_attachmentNo
larger_than_kbNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.0

TDQS

A3.8/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 well: it discloses ordering, pagination via limit/offset, folder-scoping of uids, the '*' unread marker, and a real backend limitation (bridge does not search non-ASCII terms; server filters client-side). It omits auth/permission requirements and read-only framing, which would matter for a 14-param search.

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?

Two dense sentences that front-load the core purpose and then layer constraints; almost no waste. The heavy parenthetical stacking (folder semantics, non-ASCII note) makes it slightly harder to scan than it needs to be.

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?

An output schema exists, so return shape needn't be explained, yet the description goes further by explaining uid reuse and unread markers. For a 14-param tool it covers nearly every filter, with only folder-default and permission behavior left implicit.

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 0%, so the description must compensate, and it largely does: it maps text, from_, to, subject, since/before (with YYYY-MM-DD format), unseen_only, flagged_only, has_attachment, size (larger_than_kb), all_mail, and limit/offset. 'size' stays vague about units and the folder default of INBOX is left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Search a mailbox for emails') plus sort order ('newest first') and enumerates the filter dimensions, so an agent immediately knows what it does. It stops short of naming a sibling it competes with (e.g., get_thread for conversation context), so differentiation relies on the verb alone.

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

Usage Guidelines3/5

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

Gives useful routing context for the downstream tools that consume the returned uid ('used by get_email/mark_email/move_email/delete_email') and explains the folder-vs-all_mail choice. It never says when to prefer this over siblings like mailbox_stats or get_thread, and offers no exclusions or prerequisites.

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