Skip to main content
Glama

Search messages

search_messages
Read-only

Find Outlook messages by text, sender, recipient, subject, date, category, read/flag state, or attachments. Filter across mail folders; results match names, subject, and preview text only.

Instructions

Find messages by text, sender, recipient, subject, date, category, read/flag state or attachments. Works by scanning the newest messages of each folder (scanLimit per folder) and matching subject, sender, recipient display names and the ~250-character preview; it does not search full bodies or attachment contents. All given criteria must match. Searches all mail folders except Deleted Items, Junk, Drafts and Outbox unless folders is given.

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

Input Schema

NameRequiredDescriptionDefault
toNoRecipient display names contain this
fromNoSender name or address contains this
textNoWords that must all appear (subject, preview, sender or recipients); use "quotes" for phrases
afterNoOnly messages received at/after this date or time (ISO 8601)
limitNoMaximum results (default 25)
beforeNoOnly messages received before this date or time (ISO 8601)
unreadNoOnly unread messages
flaggedNoOnly flagged messages
foldersNoFolders to search (names, paths or IDs), or ["all"]
subjectNoSubject contains this
categoryNoOnly messages with this category
scanLimitNoNewest messages to scan per folder (default 1000)
hasAttachmentsNoOnly messages with (true) or without (false) attachments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior5/5

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

Goes well beyond readOnlyHint/openWorldHint by disclosing the recall model: it only matches subject, sender, recipient display names and a ~250-character preview, and does not search full bodies or attachment contents. It also states the AND semantics and the default folder exclusions, which are exactly the behaviors an agent needs to avoid false 'not found' conclusions.

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?

Three compact sentences, front-loaded with purpose followed by search mechanics and then scope exclusions; no filler. The long criteria enumeration in sentence one is dense but each item maps to an actual parameter.

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 read-only search with no output schema, the description covers what is searched, how matching works, and which folders are in scope by default. Minor gaps remain around result ordering and how the limit interacts with scanLimit across folders, but nothing essential for correct invocation 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 meaning the schema does not: scanLimit is per folder and defines the search window, folders overrides the default exclusion list, and all supplied criteria must match simultaneously. That is genuine added semantics for the two parameters whose behavior is least obvious.

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?

Opens with a specific verb and resource ('Find messages') and enumerates the matchable criteria (text, sender, recipient, subject, date, category, read/flag state, attachments), so the capability is unambiguous. It stops short of naming a sibling like list_messages to sharpen the boundary, so it is clear but not fully differentiated.

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 real operating context: results come from scanning the newest messages per folder, all criteria are ANDed, and the default folder set excludes Deleted Items, Junk, Drafts and Outbox unless folders is passed. It does not explicitly say when to prefer this over list_messages or get_message, which keeps it below a 5.

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