Skip to main content
Glama

search_mail

Read-only

Search email messages by sender, recipient, subject, date range, read status, flags, mailbox, account, or attachments. Results return newest first.

Instructions

Search mail, newest first. All filters combine. With Full Disk Access the search is fast and covers all mail. Without it, the search is slower, needs 'mailbox', and covers the date range only (default: last 30 days); 'to' and 'has_attachments' do not work then. Dates are ISO 8601, for example 2026-11-12 or 2026-11-12T09:30:00+01:00.

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_mail"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoPart of a recipient address or name.
fromNoPart of the sender address or name.
limitNoMost results to return. Default 25, maximum 200.
queryNoWords in the subject or the sender. Ignores case.
sinceNoReceived at or after this. ISO 8601, for example 2026-11-12 or 2026-11-12T09:30:00+01:00
beforeNoReceived before this. A date-only value means the start of that day.
unreadNotrue for unread only, false for read only.
accountNoAccount id or name.
flaggedNotrue for flagged only, false for not flagged.
mailboxNoMailbox name or path, for example INBOX. Ignores case.
subjectNoPart of the subject.
flag_colorNoOnly messages flagged with this color. Do not combine it with 'flagged' false.
has_attachmentsNotrue or false.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses important behavior: newest-first ordering, filter combination, performance and coverage differences under Full Disk Access, the default 30-day range without it, required mailbox usage, and which filters stop working. These are material traits an agent could not infer from annotations alone.

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 dense and front-loaded: purpose and ordering first, then filter behavior, then the Full Disk Access caveat, then date format. Every sentence carries operational information, and there is no filler.

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 13-parameter search tool with no output schema, the description covers the main behavioral caveats and date semantics well. It does not explain multi-account scoping or return-value structure in detail, but the schema already documents individual parameters and the description is otherwise complete enough to call the tool correctly.

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 schema already documents the 13 parameters. The description still adds useful parameter-level meaning by stating that all filters combine, that mailbox becomes necessary without Full Disk Access, that to and has_attachments do not work in that mode, and by giving ISO 8601 date examples.

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 opens with a specific verb and resource: "Search mail, newest first." It immediately distinguishes the tool from single-message siblings such as get_message and from non-mail search tools by naming the exact resource and ordering behavior.

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?

It gives clear operational context for using the tool, including that filters combine and how behavior changes with or without Full Disk Access. It does not explicitly name alternatives such as get_message or search_files, so the when-to-use guidance is strong but not fully comparative.

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