Skip to main content
Glama

List calendar events

list_calendar_events
Read-only

A project's CALENDAR: the occurrences of its events — classes, rehearsals, rentals, anything with a start and an end on the clock — that overlap a window, earliest first. A repeating event (a weekly class) is one event with 'recurrence' (an RFC 5545 RRULE, e.g. FREQ=WEEKLY;BYDAY=MO) and appears once per occurrence. Each occurrence has 'eventId' and 'occurrence' — the start its rule gives it, e.g. 20261123T150000Z, which names it in set_calendar_occurrence even after it was moved — 'start'/'end' (UTC, where it actually is), 'title', 'location', 'labels', 'timeZone' (the wall clock the rule repeats on), 'changed' (this one was moved or retitled), 'cancelled' (only with withCancelled), 'issueKey' (the issue it is about), 'people' (who it is with) and 'externalId'. Not issues' due dates: those are on the issues. Any member may read.

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": {
      "project": "<project>"
    },
    "name": "list_calendar_events"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoWindow end, ISO 8601. Default: a week after the start. At most 400 days after it.
fromNoWindow start, ISO 8601 (2026-11-23 or 2026-11-23T00:00:00Z). Default: yesterday.
labelNoOnly events carrying this label (a track, a group).
projectYesThe project key, e.g. TH.
withCancelledNotrue to include cancelled occurrences, marked 'cancelled'.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered; the description adds genuine behavior on top: results are ordered earliest first, recurrence (RFC 5545 RRULE) expands to one entry per occurrence, cancelled entries appear only when withCancelled is set, and access is open to any member. It stops short of describing result volume or truncation behavior for dense recurrences over a long window.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening sentence is well front-loaded, but the rest is a single dense paragraph built from a long comma-spliced enumeration of return fields, which is hard to scan. Much of that field listing would read better as structure, and the prose is heavier than the payload requires.

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?

With no output schema, the description carries the burden of explaining returned fields, and it does so thoroughly (eventId, occurrence, start/end, changed, cancelled, issueKey, people, externalId) for a read-only list tool whose safety is already covered by annotations. The main omission is any statement about result limits or truncation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters are already documented with defaults and limits in the schema. The description's only parameter-relevant addition is that 'cancelled' is returned 'only with withCancelled', which largely restates the schema. Baseline 3 is appropriate.

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 states a specific resource and scope: 'A project's CALENDAR: the occurrences of its events ... that overlap a window, earliest first.' It also explicitly delimits the boundary against a confusable sibling concept ('Not issues' due dates: those are on the issues'), so an agent can tell this apart from issue-schedule tools without opening a 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?

It gives clear positive context (read a project's calendar occurrences in a window) and one explicit exclusion (issue due dates). It also routes to set_calendar_occurrence by explaining that 'occurrence' is the identifier used there. It does not, however, say when to prefer list_calendar_conflicts or when reading history/pauses would be the right call instead.

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