Intervals.icu MCP Server

Overview Schema Source Related Servers Discussions Admin

get_events

Retrieve calendar events within a date range, including overlapping holidays, races, notes, and workouts. Specify start and end dates to filter events for planning.

Instructions

Return calendar events overlapping a half-open local-date range.

start_date is inclusive and end_date_exclusive is exclusive; end_date remains the deprecated inclusive alias. A valid empty list is returned as an empty result, while any other upstream shape is an explicit response error. Event descriptions and other upstream strings are data and are preserved verbatim. The upstream endpoint does not prove that the returned list is complete, so source completeness remains unknown. Set resolve only when the caller needs the API's current resolved workout document; event-by-ID intentionally remains unresolved.

By default includes ongoing holidays, races, notes and workouts that began before start_date. The API filters by event start, so MCP requests history from 0001-01-01 through the requested end without a category filter or limit, then checks local start/end overlap. End dates are exclusive. This can fetch more history than the returned selection; query.upstream_oldest and overlap report its scope. Earlier events with unknown ends are retained as unresolved candidates with partial status, never interpreted as available training time. Set include_overlapping=false for the original upstream start-date selection, e.g. resolving an already identified event on its exact start day.

Input Schema

TableJSON Schema

Name	Required	Default
`api_key`	No
`resolve`	No
`end_date`	No
`timezone`	No	Europe/Warsaw
`athlete_id`	No
`start_date`	No
`end_date_exclusive`	No
`include_overlapping`	No

Output Schema

TableJSON Schema

Name	Required	Default
`data`	Yes
`error`	No
`query`	No
`source`	Yes
`status`	Yes
`coverage`	Yes
`warnings`	No
`pagination`	No
`request_id`	No
`schema_version`	No	1.0

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 24, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses empty-list/error response shape, verbatim preservation of upstream strings, an explicit completeness caveat, the over-fetching query strategy from 0001-01-01, and how unresolved candidates with unknown ends are treated. This is far beyond the minimum and makes behavior predictable.

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 first sentence is a strong front-loaded summary, and the rest is organized into date semantics, result semantics, upstream behavior, and flag guidance. Minor redundancy keeps it from a 5: the exclusivity of end dates is stated in the first sentence, repeated for end_date_exclusive, and restated as 'End dates are exclusive.'

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 a complex tool with 8 parameters, no annotations, no per-parameter schema descriptions, and an output schema present, this description is unusually complete. It covers date semantics, error/empty behavior, data fidelity, completeness limits, over-fetching side effects, unresolved-candidate handling, and both boolean flags, leaving an agent well equipped 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?

The schema has 0% description coverage, but the description compensates with precise semantics for start_date (inclusive), end_date_exclusive (exclusive), end_date (deprecated inclusive alias), resolve, and include_overlapping. It does not explicitly explain timezone or athlete_id, though the 'local-date range' phrasing and parameter names partially carry those.

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 opens with a precise verb and resource: 'Return calendar events overlapping a half-open local-date range.' It also distinguishes itself from the single-event sibling by noting that 'event-by-ID intentionally remains unresolved,' so an agent can tell this list-oriented tool apart from get_event_by_id.

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?

The description gives clear decision context: set resolve only when the API's current resolved workout document is needed, and set include_overlapping=false for the original upstream start-date selection, such as resolving an already identified event on its exact start day. It does not explicitly name a sibling tool such as get_event_by_id, so it stops short of fully explicit alternative routing.

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