Skip to main content
Glama
devyhan

ms-graph-mcp

by devyhan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Search Microsoft 365

search_query
Read-onlyIdempotent

Query Microsoft 365 mail, files, calendar, SharePoint, and Teams content; returns relevance-ranked, merged hits with rank, summary, IDs, URLs, and last-modified times.

Instructions

Runs a relevance-ranked Microsoft Search query across Microsoft 365 and returns a flattened list of hits, each with its rank, a text summary and the resource's id, name or subject, web URL and last-modified time. Defaults to 10 hits per entity-type group over ['message','driveItem']; page with from. Each entity type is searched in its own request and the hits merged, because Graph rejects some combinations outright (observed: message+driveItem 400s) and ranks stay per-request; chatMessage hits ignore fields. Each split asks only for the scopes its own index needs — Sites.Read.All for driveItem, listItem and site, Mail.Read for message, Calendars.Read for event, and BOTH Chat.Read and ChannelMessage.Read.All for chatMessage. That last pair is the one to watch: ChannelMessage.Read.All needs tenant admin consent and is carried by the teams group, so a chat search needs teams enabled as well as chat, and without it Graph refuses the chatMessage split with a 403 naming both permissions while every other split still returns; results are ranked, not sorted by date, and freshly changed items may not be indexed yet. This is read-only despite using POST.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
fromNoZero-based offset of the first hit to return; use it to page. Defaults to 0.
sizeNoMaximum hits to return per entity-type group. Defaults to 10, capped at 25.
queryYesThe search terms, in Microsoft Search KQL. Free text works ("quarterly budget"), as do property restrictions such as "subject:budget", "from:sara@contoso.com", "filetype:pptx" and "lastModifiedTime>=2026-01-01", combined with AND/OR/NOT.
fieldsNoExtra resource properties to retrieve and include on each hit, for example ["from","importance"] or a SharePoint managed property. Ignored for chatMessage, which does not support field selection.
entityTypesNoWhich kinds of content to search. Defaults to ['message','driveItem'] (Outlook mail plus OneDrive/SharePoint files).

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?

Adds substantial behavior beyond the readOnly/idempotent/destructive annotations: per-split failure isolation (a chatMessage 403 while every other split still returns), the exact permission each index needs, that ChannelMessage.Read.All requires tenant admin consent, that results are ranked not date-sorted, indexing lag, and that chatMessage ignores `fields`. The read-only-despite-POST note is consistent with readOnlyHint=true, not a contradiction.

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 return format, then layers caveats, all in one dense paragraph with little redundancy. It is long and leans into implementation detail (observed 400 on message+driveItem), but nearly every sentence carries actionable content, so the size is defensible.

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?

With no output schema, the description carries the full burden and does so: it enumerates hit fields, explains merging/ranking semantics, documents the permission matrix, and warns about partial failures and index staleness. An agent can call this correctly without opening anything else.

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: `size` is per entity-type group rather than total, `from` is the paging mechanism, and `fields` is ignored for chatMessage (echoed but usefully framed). These clarifications go beyond the field-level descriptions.

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?

Opens with a specific verb+resource ('Runs a relevance-ranked Microsoft Search query across Microsoft 365') and immediately names the return shape (rank, summary, id/name/subject, web URL, last-modified). It also tells the agent the default scope (['message','driveItem']), which distinguishes it from the single-source siblings like mail_search_messages and files_search.

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 clear operational context: paging via `from`, default group size, and the permission conditionals that gate the chatMessage split. It does not explicitly name alternatives (e.g. use files_search for files only) or state when not to use this broad cross-entity search, so the routing guidance is implied rather than spelled out.

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