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

TableJSON 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 all in range.
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). 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

TableJSON Schema
NameRequiredDescriptionDefault
countNo
eventsNo
end_dateNo
start_dateNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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."
  2. 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."
  3. 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."
  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. 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"
      +}
  6. 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."
  7. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare readOnlyHint/destructiveHint=false, so the safety profile is covered. The description goes further by disclosing preview truncation (200 chars, notes_truncated flag), attendee capping in list mode, the full-roster behavior of event_id, and that event_id ignores other filters — rich behavioral detail beyond structured fields.

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?

Front-loaded with the core action, then the two modes, then defaults, then the sibling alternative. Dense but every clause carries information; no filler.

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?

An output schema exists so return formatting needn't be explained, yet the description still conveys the practical difference between list previews and full single-event reads. Combined with 100% schema coverage and clear annotations, an agent has everything needed to call it correctly.

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 coverage is 100%, so the baseline is 3. The description reinforces key semantics at a high level — the today + 7 days default and the event_id-overrides-filters relationship — which helps an agent pick the right mode even before reading the schema, though it adds no syntax detail beyond what the schema already documents.

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?

States a specific verb (lists) plus resource (Mac Calendar app events) with explicit scope (date range) and a second mode (single event via event_id). It also names the sibling m365_list_events as the alternative for a different calendar source, so an agent can distinguish it without opening any 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?

Gives explicit routing: use list mode for ranges, pass event_id to get complete notes and full roster, and use m365_list_events for Microsoft 365 calendars. The condition for switching modes is spelled out (notes_truncated entries), leaving nothing to inference.

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