Skip to main content
Glama

graph_list_direct_reports

Lists the people who report directly to a specified user or the signed-in user, with paging options to retrieve large sets.

Instructions

List the people who report directly to a user.

Reading someone else's direct reports requires the User.Read.All permission.

Args: user_id: User ID or email address. Empty targets the signed-in user. top: Maximum number of reports to return (default 50, maximum 50). skip: Number of items to skip before returning results (default 0). Graph returns at most 50 per call, so page by raising skip in steps of top. 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

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

Input Schema

NameRequiredDescriptionDefault
topNo
skipNo
compactNo
user_idNo
next_linkNo
include_next_linkNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.10.0

TDQS

A4.3/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 burden and does well: it discloses the permission requirement, the hard cap of 50 results per call, and that next_link overrides the other paging arguments. It also discloses the two possible return shapes (bare list vs {items, next_link}). It does not describe behavior on invalid user_id or on insufficient permissions, so it is not fully complete.

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 one-line purpose is front-loaded, followed by a permission note and a compact Args block where every entry adds distinct information. No sentence is redundant, and paging semantics are grouped logically rather than scattered.

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?

Given six parameters, zero schema coverage, no annotations, and no output schema, the description is unusually complete: it covers auth, paging, page size, return-shape toggling, and per-argument semantics. The remaining gap is that it does not say which fields `compact` returns versus the full record, which an agent may need to choose the flag.

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 document all six parameters, and it does: user_id, top, skip, compact, next_link, and include_next_link each get meaning, default, and interaction rules (next_link overrides paging args; compact for cheap paging). It also adds a real semantic constraint (top maximum 50, page in steps of top) that the schema's wide numeric bounds do not convey.

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 gives a specific verb and resource: "List the people who report directly to a user." It clearly delimits scope (direct reports only, of a specific user) and is distinguishable from org-chart or member-listing siblings. It stops short of naming an alternative such as graph_list_team_members, so it does not earn a 5.

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?

It states a concrete prerequisite ("Reading someone else's direct reports requires the User.Read.All permission") and explains the empty-user_id behavior (targets the signed-in user), which tells an agent exactly when it can call this without extra auth. It also explains when to use next_link versus top/skip paging. There is no explicit statement of when NOT to use this tool or which sibling to prefer, which keeps it at 4.

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