Skip to main content
Glama
devyhan

ms-graph-mcp

by devyhan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Search mail messages

mail_search_messages
Read-onlyIdempotent

Search Outlook messages by text and return compact results in one call. Use no date range for relevance-ranked full-text search, or add after/before to filter by received date.

Instructions

Finds messages by text, returning the same compact projection as mail_list_messages, 10 per call by default (50 max). Two modes, because Graph will not combine them: with no date range it uses $search, a relevance-ranked KQL search over subject, body and participants (results are NOT in date order, and $search supports no date syntax). Passing after or before switches to $filter on receivedDateTime, which sorts newest-first but can only match query as a substring of the subject — body text is not searched in that mode. The response reports which mode ran. To search body text within a period, search first and filter the dates yourself.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
toNoOnly messages addressed to this exact address.
topNoHow many messages to return. Defaults to 10; 50 is the ceiling.
fromNoOnly messages sent by this exact address.
afterNoOnly messages received at or after this ISO-8601 date or datetime, e.g. "2026-01-01" or "2026-01-01T09:00:00Z". A bare date starts at 00:00:00Z. Supplying this switches the tool to $filter mode.
queryYesWords to look for. Without a date range this is a KQL search across subject, body, and participants, so "subject:budget" or "quarterly review" both work. With after/before it degrades to a subject substring match — see the tool description.
beforeNoOnly messages received at or before this ISO-8601 date or datetime. A bare date ends at 23:59:59Z that day. Supplying this switches the tool to $filter mode.
hasAttachmentsNoOnly messages with (or without) attachments.
includeWebLinkNoInclude each row's Outlook webLink. Off by default: a webLink is the message id all over again, URL-encoded, and on a 50-row page it costs more than every subject and preview put together. Turn it on only when you need a link a person will click — to read or act on a message, pass its `id` to another mail tool instead.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.0
    • addedInput schema / properties / includeWebLink
      Added value: +{
+  "default": false,
+  "description": "Include each row's Outlook webLink. Off by default: a webLink is the message id all over again, URL-encoded, and on a 50-row page it costs more than every subject and preview put together. Turn it on only when you need a link a person will click — to read or act on a message, pass its `id` to another mail tool instead.",
+  "type": "boolean"
+}
  2. 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 already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description goes well beyond them: $search results are not in date order, $filter mode silently degrades `query` to a subject substring and stops searching the body, and the response reports which mode ran. Those are non-obvious behavioral traits an agent would otherwise get wrong.

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 purpose and pagination, then the mode rules, then the practical fallback for body-text-within-a-date-range. Every sentence carries information, though the two-mode section is dense enough that bullets would have made the $search vs $filter contrast easier to scan.

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 an 8-param, no-output-schema tool the description covers the return projection, the page size, the mode reporting, and the key workaround, which is most of what an agent needs. It leaves one gap: whether `to`, `from`, and `hasAttachments` are honored in $search mode or only in $filter mode is never stated.

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 per-parameter text already documents syntax and bounds (baseline 3). The description adds cross-parameter semantics the schema cannot express: that supplying `after`/`before` changes the meaning of `query` entirely, and that the output projection/pagination defaults match the list tool.

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+resource (finds mail messages by text) and immediately anchors it to the sibling tool by name ("the same compact projection as mail_list_messages"), so an agent can place it in the family without opening a schema. The two-mode explanation further pins down exactly which search capability this tool exposes.

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?

Explicitly states which mode runs under which condition (no date range -> $search; after/before -> $filter) and warns what each mode can and cannot match, which is exactly the guidance an agent needs to pick arguments. It stops short of an explicit when-to-use/when-not versus mail_list_messages or mail_fetch_thread; the alternative is only implied by comparison.

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