Skip to main content
Glama
iCloud Calendar MCP Server

iCloud Calendar MCP Server

by Glob0x17

list_events

Read-only

Fetch iCloud Calendar events for an inclusive date range and optionally filter by calendar name to locate scheduled items.

Instructions

List calendar events in a date range.

The start_date should always use the time such that it represents the beginning of that day (00:00:00). The end_date should always use the time such that it represents the end of that day (23:59:59). This way, range based searches are always inclusive and can locate all events in that date range.

Args: start_date: Start date in ISO8601 format (YYYY-MM-DDT00:00:00). end_date: Optional end date in ISO8601 format (YYYY-MM-DDT23:59:59). calendar_name: Optional calendar name to filter by

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": {
      "start_date": "<start_date>",
      "end_date": "<end_date>"
    },
    "name": "list_events"
  }
}

Input Schema

NameRequiredDescriptionDefault
end_dateYes
start_dateYes
calendar_nameNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.1

TDQS

A3.5/5.0
Behavior3/5

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine context about the inclusivity semantics of the range (00:00:00 to 23:59:59), but says nothing about result limits, pagination, timezone handling, or recurring-event expansion — relevant gaps for an open-world list call.

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 purpose is front-loaded in one sentence, followed by the range convention and a compact Args block. The Args entries mostly restate schema titles, but they carry the format details, so little is wasted.

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?

An output schema exists, so return values need not be described, and annotations cover read-only behavior. What remains thin for a three-parameter, open-world list tool is the absence of any statement on result volume, pagination, or timezone assumptions.

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 0%, so the description must carry the parameters, and it does document all three with ISO8601 formats and the day-boundary convention — real added meaning. However, it labels end_date "Optional" while the schema lists it under required, a contradiction that could lead an agent to omit a mandatory argument.

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 opening sentence states a specific verb and resource plus scope: "List calendar events in a date range." That is enough to separate it from create_event, update_event, and delete_event, though it never names list_calendars or explains the relationship between listing calendars and listing their events.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: it is a read/list operation over a required date range, and the inclusive-range rule tells the agent how to build the query. There is no explicit when-to-use versus when-not-to-use guidance, and nothing about whether this is the right call before create/update/delete or how it relates to list_calendars.

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