Skip to main content
Glama
devyhan

ms-graph-mcp

by devyhan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Search Microsoft 365

search_query
Read-onlyIdempotent

Search Microsoft 365 mail, files, sites, and chats by query. Returns relevance-ranked hits with summaries, URLs, and metadata to locate resources without manual browsing.

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. Traps: chatMessage cannot be combined with other entity types, so a mixed request is split into two calls and merged, and its hits ignore fields; searching driveItem, listItem or site needs Sites.Read.All, event needs Calendars.Read and chatMessage needs Chat.Read, so enable the matching tool group or the split for that type fails on its own while the rest still return; 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.7/5.0
Behavior5/5

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, but the description adds substantial behavior beyond that: results are ranked not date-sorted, fresh items may not be indexed, chatMessage cannot combine with other types, and mixed requests are split into two calls. It also explains the read-only nature despite POST, which directly complements the annotation.

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?

The description is dense but well front-loaded with the main purpose and return shape, then defaults, then traps. Every sentence adds necessary information, though the long trap section is a single block and could benefit from clearer bullet structure.

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 complex tool with multiple entity types, permissions, paging, and splitting behavior, the description covers all necessary operational details: defaults, paging, per-type permission needs, result ordering caveats, and the read-only POST behavior. Even without an output schema, it enumerates the returned fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description meaningfully extends parameter understanding with KQL syntax examples, the per-entity-type-group meaning of size, paging via from, and the chatMessage exception for fields. This goes well beyond the schema's property 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?

The description states a specific verb and resource: it runs a relevance-ranked Microsoft Search query across Microsoft 365 and returns a flattened list of hits with concrete fields. It distinguishes itself from more scoped sibling tools by emphasizing cross-Microsoft-365 coverage over multiple entity types.

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?

The description provides clear context on defaults, paging, entity-type groups, and permission requirements, making it evident this is the cross-entity search tool. It does not explicitly name alternatives like mail_search_messages or files_search for single-entity searches, so it falls just short of fully explicit when-not-to-use guidance.

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