Skip to main content
Glama

Scan Email Headers

scan_messages
Read-only

Scan Microsoft 365 message headers by folder, filter, or search to find relevant emails, then use returned refs to open messages, list attachments, or move them; follow cursors for paged results.

Instructions

Scan message headers compactly as ref|received|from|subject|flags. Scope with folder and narrow with filter or search. Pass refs to get_message, list_attachments, move_message or batch_move_messages. Both filter and search scans page using Graph nextLink cursors: when a result says INCOMPLETE, call scan_messages with the returned cursor alone until no cursor remains. A short or empty page can still have a continuation. Search returns at most 1,000 results, so use filter and exhaust its cursors when mailbox coverage matters. A header is not a message: open messages and attachments the subject cannot rule out.

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

Input Schema

NameRequiredDescriptionDefault
topNoRows per page (default 100, max 1000)
cursorNoContinuation cursor from a prior scan. Pass alone, plus mailbox if the scan named one; valid for this session
filterNoOData filter, e.g. receivedDateTime ge 2026-01-01T00:00:00Z
folderNoFolder to scan: well-known name (archive, inbox, sentitems), display name, or ID. Default: all mail
searchNoFull-text search term. Cannot be combined with date ordering
mailboxNoEmail address of another mailbox to act on (delegated or shared), e.g. 'someone@example.com'. Omit for your own mailbox; required when this server signs in as an application. Only addresses this server is configured to allow will be accepted.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.5/5.0
Behavior5/5

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

Annotations only establish readOnlyHint, and the description goes well beyond that: it discloses the INCOMPLETE marker, that continuation requires calling again with the cursor alone, that short or empty pages may still have continuations, and the 1,000-result search ceiling. It also warns about a non-obvious trap (headers are not message bodies), which is exactly the kind of behavior an agent cannot infer from structure.

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?

Roughly 110 words with the output format front-loaded in the first clause, then scoping, then pagination mechanics, then the caveat. No sentence is filler; each carries a distinct operational constraint.

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?

With no output schema, the description carries the return-format burden and mostly does: the compact row shape, the INCOMPLETE marker, and cursor continuation are all covered. The one gap is that the meaning of the 'flags' field and the structure of a ref are never explained, which matters for a tool whose whole purpose is producing actionable references.

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 description coverage is 100%, so the baseline is 3, and the description earns above that by explaining the filter-versus-search tradeoff and that the cursor must be passed alone with the mailbox if the scan named one. Those are relationships between parameters, not restatements. It does not expand on what the flag values or ref format mean.

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?

The opening sentence names a specific verb and resource and even states the return shape (ref|received|from|subject|flags), so an agent knows exactly what comes back. It also positions itself against get_message, list_attachments, and move_message via the ref handoff. It stops short of distinguishing itself from the sibling search_messages, which is the closest alternative for header discovery.

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?

Explicit routing is given at every decision point: scope with folder, narrow with filter or search, pass refs to specific follow-up tools. It states a real exclusion rule (filter over search when mailbox coverage matters, because search caps at 1,000) and warns that a header is not a message and must be followed up on.

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