Skip to main content
Glama

mail

Read-only

Search the inbox by subject or sender substring and return message pointers—ID, summary, deeplink, and folder—for body retrieval. Read-only; scans inbox only.

Instructions

Search the Mail inbox by subject OR sender substring. Pointers: id = the stable RFC822 message-id, summary = subject — sender, deeplink = a message:// URL, folder = "inbox" (this scans the inbox only) — pass that folder straight to mail_body. Prefer mail_search, which reaches every mailbox and reports the account. Returns {results, truncated?} — truncated means the 25-message cap was reached and there may be more. Read-only; needs Automation access for Mail. Bodies are never fetched.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "mail"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYes

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.15.1

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already mark it read-only and non-destructive, and the description still adds meaningfully: it requires Automation access for Mail, bodies are never fetched, results are capped at 25 with a `truncated` flag signaling more may exist. It also discloses the inbox-only scan scope, which is a behavioral limit not visible in any structured field.

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?

Front-loaded with the action, then a compact "Pointers:" list mapping field names to meanings, then scope/limit and a sibling recommendation. Every clause carries information, though the pointer enumeration makes it denser than strictly necessary for a one-parameter tool.

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?

For a one-parameter search tool it covers everything an agent needs: matching semantics, inbox-only scope, output field meanings, the truncation cap, the auth prerequisite, and the routing decision to `mail_search`. An output schema exists, yet the description still clarifies the one field (`truncated`) whose meaning matters operationally.

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?

The single `query` parameter has 0% schema description coverage, so the description must carry it — and it does, explaining that matching is a subject OR sender substring. It does not specify case sensitivity, whitespace handling, or whether multiple terms are ANDed, which keeps it below a 5.

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 ("Search the Mail inbox") and narrows the matching semantics to subject OR sender substring. It also explicitly separates itself from `mail_search`, which reaches every mailbox, so an agent can pick between the two without opening 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?

Gives an explicit preference rule: "Prefer `mail_search`, which reaches every mailbox and reports the account," which is precisely the condition that selects the sibling over this tool. It also tells the caller to forward the returned `folder` value straight to `mail_body`, closing the follow-up loop.

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