Skip to main content
Glama

graph_search_users

Search the organization directory by name or email to find users. Returns identifying fields or full records, with next-link paging for large result sets.

Instructions

Search for users in the organization directory by name or email.

Graph does not support $skip alongside $search on /users, so page with next_link instead of an offset.

Args: query: Name or email address to look up. top: Maximum number of users to return (default 10, maximum 25). compact: Whether to return only the identifying fields instead of the full record (default false). Use it to page through large collections cheaply. next_link: Opaque nextLink URL from a previous call, used to fetch the next page. Overrides the other paging arguments when supplied. include_next_link: Whether to wrap the result as {items, next_link} so paging can continue (default false, which returns a bare list).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "graph_search_users"
  }
}

Input Schema

NameRequiredDescriptionDefault
topNo
queryYes
compactNo
next_linkNo
include_next_linkNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.10.0

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations, the description carries the full disclosure burden and does reasonably well: it states the API limitation that blocks offset paging, that next_link overrides other paging arguments, and that the return shape varies between a bare list and {items, next_link}. It omits permission/auth requirements for directory search and any error or empty-result behavior.

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?

The purpose and the paging caveat are front-loaded, then a clean Args block follows with no filler. Each line adds information rather than restating the parameter names, and nothing could be deleted without losing semantics.

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 five-parameter tool with zero schema documentation and no output schema, the description covers querying, paging, projection, and return shape well enough to call it correctly. The remaining gap is operational context such as required permissions or what an empty result looks like.

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?

Schema coverage is 0%, so the description must compensate and it does: every one of the five parameters is explained with meaning absent from the schema, including a real maximum of 25 for top (the schema only says an enormous numeric bound), what compact strips out, that next_link is opaque and takes precedence, and why include_next_link exists.

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 first sentence names a specific verb and resource ('Search for users in the organization directory') and constrains the lookup keys to name or email. It is distinguishable from siblings like graph_search_files or graph_search_mail by resource, though it never explicitly contrasts with graph_search_people or graph_search_all.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage guidance is supplied at the parameter level (use compact to page cheaply, next_link overrides other paging args) but there is no guidance on when to pick this tool over sibling search tools or what happens when no match is found. The paging constraint ('Graph does not support $skip alongside $search') is a useful implied when-to-use for next_link.

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