Skip to main content
Glama

List Calendar Events

list_calendar_events
Read-only

Lists events from the Mac's Calendar app (Calendar.app, local/iCloud calendars) in a date range, or reads ONE event in full via event_id. List entries preview notes (200 chars, notes_truncated flag) and cap attendees; pass event_id to get the complete notes and full roster. Defaults to today + 7 days. For a Microsoft 365 calendar use m365_list_events instead.

Input Schema

NameRequiredDescriptionDefault
limitNoMax number of events to return. Events come in start-time order, earliest first, so a limit keeps the earliest ones in the range. Optional; defaults to 100.
offsetNoSkip this many events first. A long answer is cut at 256 KB with truncated=true and next_offset: pass next_offset here to continue.
calendarNoFilter by calendar name — partial, case-insensitive (optional). To pick one of several same-titled calendars, qualify it as "Account/Calendar" (e.g. "Exchange/Calendario") using the source from list_calendar_names, or pass calendar_id.
end_dateNoISO 8601 date (YYYY-MM-DD) or datetime. Inclusive when only a date is given: 2026-10-02 returns the events of October 2 too. With a time, the range ends at that instant. Defaults to start_date + 7 days.
event_idNoRead exactly ONE event by its id (from a previous list — for a recurring event, the per-occurrence id) with FULL notes and the complete attendee roster — required before editing notes of an event whose list entry says notes_truncated. When set, all other filters are ignored.
start_dateNoISO 8601 date (YYYY-MM-DD). Defaults to today.
calendar_idNoFilter by a single calendar UUID from list_calendar_names (optional).
calendar_idsNoFilter by multiple calendar UUIDs (optional).

Output Schema

NameRequiredDescriptionDefault
countNo
eventsNo
end_dateNo
truncatedNoTrue when more events remain: see next_offset.
start_dateNo
next_offsetNoPass as offset to get the next events (present only when the answer was cut).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / end_date / description
      Previous value: -"ISO 8601 date (YYYY-MM-DD). Defaults to start_date + 7 days."New value: +"ISO 8601 date (YYYY-MM-DD) or datetime. Inclusive when only a date is given: 2026-10-02 returns the events of October 2 too. With a time, the range ends at that instant. Defaults to start_date + 7 days."
    • addedOutput schema / properties / events / items / properties / end / description
      Added value: +"ISO 8601 instant; for an all-day event, the last day (YYYY-MM-DD), inclusive: a one-day event ends on the day it starts"
    • addedOutput schema / properties / events / items / properties / start / description
      Added value: +"ISO 8601 instant; for an all-day event, the calendar date (YYYY-MM-DD)"
  2. Changed4 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Max number of events to return. Events come in start-time order, earliest first, so a limit keeps the earliest ones in the range. Optional; defaults to all in range."New value: +"Max number of events to return. Events come in start-time order, earliest first, so a limit keeps the earliest ones in the range. Optional; defaults to 100."
    • addedInput schema / properties / offset
      Added value: +{
      +  "description": "Skip this many events first. A long answer is cut at 256 KB with truncated=true and next_offset: pass next_offset here to continue.",
      +  "type": "integer"
      +}
    • addedOutput schema / properties / next_offset
      Added value: +{
      +  "description": "Pass as offset to get the next events (present only when the answer was cut).",
      +  "type": "integer"
      +}
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when more events remain: see next_offset.",
      +  "type": "boolean"
      +}
  3. Changed1 schema field changed
    • changedInput schema / properties / limit / description
      Previous value: -"Max number of events to return (most recent first within the range). Optional; defaults to all in range."New value: +"Max number of events to return. Events come in start-time order, earliest first, so a limit keeps the earliest ones in the range. Optional; defaults to all in range."
  4. Changed2 schema fields changed
    • changedInput schema / properties / event_id / description
      Previous value: -"Read exactly ONE event by its id (from a previous list) with FULL notes and the complete attendee roster — required before editing notes of an event whose list entry says notes_truncated. When set, all other filters are ignored."New value: +"Read exactly ONE event by its id (from a previous list — for a recurring event, the per-occurrence id) with FULL notes and the complete attendee roster — required before editing notes of an event whose list entry says notes_truncated. When set, all other filters are ignored."
    • addedOutput schema / properties / events / items / properties / id / description
      Added value: +"For a recurring event, this is a per-OCCURRENCE id (distinct for each of the 3 'Gym' rows below, for example) — pass it back to update_calendar_event/delete_calendar_event to target that exact occurrence, not just the series. Stable across calls; ignore its internal shape."
  5. Changed2 schema fields changed
    • changedInput schema / properties / event_id / description
      Previous value: -"Read exactly ONE event by its id (from a previous list — for a recurring event, the per-occurrence id) with FULL notes and the complete attendee roster — required before editing notes of an event whose list entry says notes_truncated. When set, all other filters are ignored."New value: +"Read exactly ONE event by its id (from a previous list) with FULL notes and the complete attendee roster — required before editing notes of an event whose list entry says notes_truncated. When set, all other filters are ignored."
    • removedOutput schema / properties / events / items / properties / id / description
      Removed value: -"For a recurring event, this is a per-OCCURRENCE id (distinct for each of the 3 'Gym' rows below, for example) — pass it back to update_calendar_event/delete_calendar_event to target that exact occurrence, not just the series. Stable across calls; ignore its internal shape."
  6. Changed2 schema fields changed
    • changedInput schema / properties / event_id / description
      Previous value: -"Read exactly ONE event by its id (from a previous list) with FULL notes and the complete attendee roster — required before editing notes of an event whose list entry says notes_truncated. When set, all other filters are ignored."New value: +"Read exactly ONE event by its id (from a previous list — for a recurring event, the per-occurrence id) with FULL notes and the complete attendee roster — required before editing notes of an event whose list entry says notes_truncated. When set, all other filters are ignored."
    • addedOutput schema / properties / events / items / properties / id / description
      Added value: +"For a recurring event, this is a per-OCCURRENCE id (distinct for each of the 3 'Gym' rows below, for example) — pass it back to update_calendar_event/delete_calendar_event to target that exact occurrence, not just the series. Stable across calls; ignore its internal shape."
  7. Changed1 schema field changed
    • addedInput schema / properties / event_id
      Added value: +{
      +  "description": "Read exactly ONE event by its id (from a previous list) with FULL notes and the complete attendee roster — required before editing notes of an event whose list entry says notes_truncated. When set, all other filters are ignored.",
      +  "type": "string"
      +}
  8. Changed1 schema field changed
    • changedInput schema / properties / calendar / description
      Previous value: -"Filter by calendar name — partial, case-insensitive match (optional). Use list_calendar_names to see available names."New value: +"Filter by calendar name — partial, case-insensitive (optional). To pick one of several same-titled calendars, qualify it as \"Account/Calendar\" (e.g. \"Exchange/Calendario\") using the source from list_calendar_names, or pass calendar_id."
  9. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description still adds real behavioral context the annotations do not: list entries truncate notes at 200 chars with a notes_truncated flag, attendee lists are capped, and event_id overrides all other filters. It stops short of describing ordering or the response envelope, but the additions are substantive.

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 core capability and the sibling exclusion are front-loaded, and the sentences are dense with load-bearing detail rather than filler. It is a single tight paragraph, though the nested parentheticals make it slightly harder to scan than a two-sentence structure would.

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 an 8-parameter tool with an output schema already present, the description covers the modes, defaults, truncation behavior, the routing decision to the M365 sibling, and the prerequisite for editing notes. Nothing an agent needs in order to call it correctly is missing.

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 100%, so the baseline is 3 and the schema already documents limit, offset, calendar, and date formats in depth. The description adds marginal but useful semantics beyond it, notably the default range and that event_id causes all other filters to be ignored.

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 names a specific verb and resource (list events from Calendar.app) and clearly defines both modes: a date-range list and a single full read via event_id. It explicitly distinguishes itself from the sibling m365_list_events by naming the Microsoft 365 alternative, so an agent can route without opening either schema.

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

Usage Guidelines5/5

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

It states the default window (today + 7 days), tells the agent to pass event_id to get full notes and roster, and gives a concrete rule ('required before editing notes of an event whose list entry says notes_truncated'). It also names the alternative tool and the condition selecting it (Microsoft 365 calendar).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources