Skip to main content
Glama

graph_list_calendars

Retrieve the authenticated user's calendars with optional paging, compact results, and shared or delegated calendar access by specifying a user ID.

Instructions

List the authenticated user's calendars.

Args: 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). user: Shared or delegated calendar owner address or user ID to act on. Empty targets your own calendar. Requires the delegated Calendars.Read.Shared or Calendars.ReadWrite.Shared permissions.

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_calendars"
  }
}

Input Schema

NameRequiredDescriptionDefault
skipNo
userNo
compactNo
next_linkNo
include_next_linkNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.10.0

TDQS

A4.2/5.0
Behavior5/5

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

With zero annotations the description carries the full burden and does so well: it discloses the server-side page cap ("Graph returns at most 50 per call"), the two possible return shapes (bare list vs {items, next_link}), the override precedence of next_link over other paging args, and the delegated Calendars.Read.Shared/ReadWrite.Shared permission requirement for `user`. These are exactly the non-obvious behaviors an agent needs before calling.

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 a one-sentence purpose, then a compact Args block where each entry is information-dense. The only wasted/confusing text is the reference to a nonexistent `top` argument in the `skip` entry.

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 5-parameter, zero-annotation, no-output-schema list tool, the definition covers paging, return shape, and permissions adequately. Minor gaps: `compact` only says "identifying fields" without naming them, and the phantom `top` reference leaves the paging instruction internally inconsistent.

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 0%, so the description must document all 5 parameters, and it does — defaults, meaning, and interaction (next_link overrides paging) are all stated. However, the paging guidance says to raise `skip` "in steps of `top`," yet no `top` parameter exists in the schema, which introduces a phantom parameter and could cause a malformed call.

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?

Opens with a specific verb+resource ("List the authenticated user's calendars"), which is unambiguous against siblings like graph_list_events or graph_list_mail that target different resources. It does not explicitly disambiguate from an omitted calendar-adjacent alternative, but the resource is distinct enough that an agent can select it without opening the schema.

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?

Clear context is provided: the `user` arg explains when the call acts on a shared/delegated calendar versus your own, and compact/include_next_link explain when to page cheaply or continue paging. There is no explicit when-not guidance, and the absence of a calendar-specific alternative in the sibling set means no routing statement was strictly needed.

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