cal-scheduler
The cal-scheduler MCP server enables LLM agents to perform timezone-correct calendar scheduling on CalDAV accounts with full iCalendar compliance. It offers:
Calendar management: list, create, and delete calendars.
Event management: create, list, update, and delete single or recurring events; list expanded occurrences within a time range; mark events/occurrences as done with a timestamp.
Recurrence handling: exclude individual occurrences (EXDATE) or move them (RECURRENCE-ID) without affecting the rest of the series; validate recurrence rules.
Timezone & datetime utilities: resolve datetime strings to preview interpretation (default timezone, wall-clock mapping); store all events with timezone data to maintain correct times across DST changes.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cal-schedulerCreate a meeting tomorrow at 10am for 1 hour"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
If you are an agent installing this MCP, read AGENTS.md first.
cal-scheduler
A thin, timezone-correct MCP server for scheduling against any CalDAV calendar. It gives an LLM agent a small, strict set of calendar tools and does the deterministic, fiddly parts of iCalendar correctly so the model doesn't have to.
It is not an NLP layer: the agent phrases the request, the server validates
it, rejects bad input loudly, and persists clean zoned .ics.
Why it exists
Most calendar tooling an LLM reaches for gets three things subtly wrong. cal-scheduler fixes them by construction:
Stores zoned, not bare UTC. Events are written with
TZID/VTIMEZONE, so a weekly 9am stays 9am across a daylight-saving boundary instead of drifting an hour. Storing bare UTC is the classic cause of that drift.Validates recurrence. It rejects an
RRULEwhose anchor contradicts it (e.g. a series starting on the 30th but set to repeat on the 1st), and normalisesUNTILto UTC under a zonedDTSTARTas RFC 5545 requires.Does real single-occurrence edits. Exclude one instance (
EXDATE) or move one instance (RECURRENCE-ID) without disturbing the rest of the series — the operations naive wrappers tend to lack.
Related MCP server: ical-mcp
How it works
A small uv Python package that composes mature libraries rather than
implementing a calendar engine:
Module | Role |
| environment config ( |
| parse datetimes; naive → assume default-zone wall time, offset → normalise into the zone; report what was assumed |
| build/parse VEVENTs ( |
| CalDAV transport ( |
| the FastMCP stdio server and the tool surface |
It runs as a stdio MCP server that an MCP host (Claude, an agent harness, etc.) spawns as a subprocess.
Install
Requires Python ≥ 3.11. The package is on PyPI as
cal-scheduler-mcp:
uv tool install cal-scheduler-mcp(or pip install cal-scheduler-mcp, uvx --from cal-scheduler-mcp cal-scheduler,
etc.)
For editable dev work, install from a clone:
# run straight from the repo with uv (no global install)
uv run --directory /path/to/cal-scheduler-mcp cal-scheduler
# or install the console script into a tool environment
gh repo clone limey/cal-scheduler-mcp
uv tool install --editable /path/to/cal-scheduler-mcp
# or, with SSH GitHub access, in one step:
uv tool install git+ssh://git@github.com/limey/cal-scheduler-mcpDon't
uv add cal-scheduler-mcpfor the MCP —uv addwrites into whatever project you're sitting in, not into the tool environment. For an MCP server (spawned as a subprocess),uv tool installis the right shape.
Configure
All configuration is via environment variables:
Variable | Required | Default | Meaning |
| ✅ | — | CalDAV server URL, e.g. |
| — | CalDAV account user | |
| — | CalDAV account password | |
|
| IANA zone every event is stored in |
Many MCP hosts strip inherited environment from stdio servers, so set these in the
host's per-server env block rather than relying on the ambient shell.
Example MCP host config
The MCP runs as a stdio subprocess that the host spawns. Many hosts strip
inherited PATH from that subprocess, so wire the uv run --directory
form rather than relying on the cal-scheduler shim being on the spawn
host's PATH:
{
"mcpServers": {
"cal-scheduler": {
"command": "uv",
"args": ["run", "--directory", "/abs/path/to/cal-scheduler-mcp", "cal-scheduler"],
"env": {
"CALDAV_BASE_URL": "http://127.0.0.1:5232",
"CALDAV_USERNAME": "me",
"CALDAV_PASSWORD": "secret",
"CAL_DEFAULT_TZ": "Pacific/Auckland"
}
}
}
}/abs/path/to/cal-scheduler-mcp is the absolute path to a local clone of
this repo (see Install above).
If you installed from PyPI with uv tool install cal-scheduler-mcp, use the
installed shim directly:
{
"mcpServers": {
"cal-scheduler": {
"command": "/path/to/cal-scheduler",
"env": {
"CALDAV_BASE_URL": "http://127.0.0.1:5232",
"CALDAV_USERNAME": "me",
"CALDAV_PASSWORD": "secret",
"CAL_DEFAULT_TZ": "Pacific/Auckland"
}
}
}
}Find the shim path with which cal-scheduler or uv tool list --show-paths.
Pair it with any CalDAV server. A simple self-hosted option is
Radicale (plain http://, no TLS needed for local use).
Tool surface
Events — list_events(start, end, [calendar]), create_event(summary, start, [end, calendar, description, location, rrule]), update_event(uid, …),
delete_event(uid, [calendar]), exclude_occurrence(uid, occurrence, [calendar]),
move_occurrence(uid, occurrence, new_start, [new_end, calendar]),
mark_done(uid, [calendar]) — tag an event done and record the timestamp.
Calendars — list_calendars, create_calendar(name), delete_calendar(name).
Helper — resolve_datetime(value) — preview how a datetime will be interpreted,
without writing anything.
The timezone rule (the whole point)
Every event is stored zoned to CAL_DEFAULT_TZ.
A naive datetime (
2026-06-30T21:00) is assumed to be wall time in that zone, and the tool response says so ("assumed Pacific/Auckland wall time").An offset-qualified datetime (
…+12:00) is honoured as an instant and re-expressed in the zone — same wall clock when the offset matches, a correct conversion otherwise.A date-only value (
2026-06-30) is an all-day event.
Develop
uv sync # install deps + dev tools
uv run ruff check # lint
uv run pytest # unit tests (no server required)The unit tests cover the pure layers (timezone resolution, recurrence validation,
EXDATE/RECURRENCE-ID construction) and need no running CalDAV server. To exercise
the full stack end to end, point CALDAV_BASE_URL at a throwaway CalDAV account.
License
MIT © 2026 Robert Clark
Available Tools
11 toolscreate_calendarB
Create a new calendar by display name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits itself. It only says 'create a new calendar,' but fails to mention side effects (e.g., duplicate name handling), authentication requirements, or result output. This is minimal for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundancy. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, the description is incomplete. It doesn't specify return values, error behavior, or preconditions, which are needed for an agent to use the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides parameter name and type; the description adds that 'name' is the display name, which gives context beyond the schema. However, it doesn't clarify constraints like uniqueness or length, so coverage remains partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and the resource 'calendar', with the qualifier 'by display name' distinguishing it from sibling tools like list_calendars and create_event. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. It does not mention prerequisites (e.g., uniqueness of calendar name), potential conflicts, or typical use cases, leaving the agent to infer solely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_eventA
Create an event (single, or recurring if rrule is given).
`start`/`end` are ISO 8601 (see parameter docs for zone + default-duration
details — read those before writing). `rrule` is a raw RRULE body,
e.g. "FREQ=WEEKLY;COUNT=12". `calendar` is required in practice — there
is no default calendar. Pick deliberately; events are not validated
against calendar type.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ISO 8601 datetime. Omit for the default duration: 1 hour after `start` for timed events, 1 day after `start` for all-day. Must be after `start`. | |
| rrule | No | ||
| start | Yes | ISO 8601 datetime. A bare local time is interpreted as wall time in the configured zone (`Pacific/Auckland`); an offset-qualified time is honoured and stored in that zone. Use `resolve_datetime` to confirm before writing. With no `end`, the event defaults to 1 hour after this `start` (1 day for all-day). | |
| summary | Yes | ||
| calendar | No | ||
| location | No | ||
| description | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses important behavioral facts: recurrence via rrule, calendar requirement with no default, and lack of validation against calendar type. This goes beyond a bare statement, though it could mention permissions or return values. There is no contradiction with annotations (none provided).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences that front-load the purpose, then address the non-obvious parameters. No wasted words, and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations or output schema, the description covers the main behavioral pitfalls (recurrence, calendar requirement, validation, timezone/default-duration reference). It could be more explicit about when to use vs siblings, but it is a functional summary for a creation tool with seven parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 29% (start and end have descriptions). The description compensates by explaining rrule format with an example and clarifying that calendar is required in practice and not validated, which are key semantics. Other obvious fields (summary, location, description) need no elaboration, and it points to parameter docs for start/end details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates an event, explicitly distinguishes single vs recurring via rrule, and the verb+resource definition differentiates it from sibling tools like update_event or delete_event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides practical context: rrule for recurring events, calendar required in practice with no default, and events not validated against calendar type. It also advises reading parameter docs before writing. However, it does not explicitly name alternative tools or when-not-to-use scenarios, though the guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_calendarA
Delete a calendar and all of its events. Irreversible.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It explicitly discloses that the operation is irreversible and that all associated events are deleted, which is essential safety information for a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the core action and consequence. Every word adds value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete tool, the description sufficiently covers purpose, cascading event deletion, and irreversibility. No output schema is expected, and the description does not leave critical gaps for an agent to understand the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not elaborate on the 'name' parameter. With 0% schema coverage, the tool description needed to explain what name refers to (e.g., calendar display name vs. unique ID) and any expected format, but it remains ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete'), the resource ('a calendar'), and the scope ('and all of its events'). This distinguishes it from siblings like delete_event and create_calendar, providing unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear that this tool deletes the entire calendar plus all its events, offering strong context for when to use it. However, it does not explicitly name alternatives or state when not to use it (e.g., when only a single event should be removed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_eventA
Delete a whole event/series (and any of its overrides). Irreversible.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| calendar | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses irreversibility and that overrides are deleted, which is important destructive behavior. It lacks details on permissions or return values, but these are less critical for a simple delete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no fluff. It front-loads the action and includes essential caveats (irreversible, overrides) without wasting words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with two parameters and no output schema, the description covers the main behavioral aspects. It would be more complete with parameter semantics or usage alternatives, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain what 'uid' or 'calendar' mean. While 'uid' is inferable as the event identifier, no explicit guidance is provided, so the description fails to compensate for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and resource 'event/series', and specifies scope by including overrides. This distinguishes it from sibling tools like exclude_occurrence which handle single occurrences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'whole event/series' implies this is for full deletion, not individual occurrences, providing clear context. However, it does not explicitly name sibling alternatives for partial deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
exclude_occurrenceA
Drop a single occurrence of a recurring series (EXDATE).
`occurrence` is the instance's current start exactly as returned by
`list_events`, including the UTC offset (e.g. `2026-06-18T09:00:00+12:00`).
Bare local times may not match. The response includes `series_remaining`
(occurrences left in the series) and `overrides` (RECURRENCE-ID overrides
on the series) so the rest-of-series-unchanged claim is observable.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| calendar | No | ||
| occurrence | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It explains the effect (drops a single occurrence, rest of series unchanged) and reveals that the response includes series_remaining and overrides for observability. However, it does not state whether the operation is reversible, what permissions are needed, or error behavior, which are gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long and front-loaded with the main purpose. It includes a concrete example and explains the response fields efficiently. The final phrase 'so the rest-of-series-unchanged claim is observable' is slightly verbose but adds meaningful context. No redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, no output schema, and no annotations, the description is relatively complete in explaining the core behavior and the occurrence format. However, it omits details about uid and calendar, and does not address error scenarios or how to identify the target series. Given the complexity of a recurring-series mutation, some gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain all parameters. It thoroughly explains 'occurrence' (exact format with UTC offset, bare local times may not match) and mentions the response fields, but it does not explain 'uid' (presumably the event's unique ID) or 'calendar' (optional calendar context). Two of three parameters are undocumented, leaving significant ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Drop a single occurrence of a recurring series (EXDATE).' It uses a specific verb (drop) and resource (single occurrence of a recurring series), and distinguishes itself from sibling tools like move_occurrence or delete_event by focusing on exclusions rather than deletions or moves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (for dropping an occurrence from a recurring series) and gives specific instructions on how to format the occurrence parameter (must be the exact start as returned by list_events with UTC offset). It does not explicitly exclude alternative tools, but the usage scenario is well implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_calendarsA
List the calendars available on the account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The verb 'List' naturally conveys a non-destructive, read-only operation, which is a form of behavioral disclosure. However, the description does not mention what exactly is returned (e.g., calendar IDs, names, metadata) or any other behavioral traits like sorting or filtering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. Every word earns its place, and the structure is optimal for a simple list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list operation with no output schema, the description provides a sufficient understanding of the tool's basic purpose. It does not specify the return format or potential errors, but given the low complexity, this is not a critical gap. A richer description could mention that it returns calendar IDs for use in other operations, but the current description is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema confirms this with 100% coverage. According to the rubric, the baseline is 4 for zero-parameter tools, and the description does not need to add parameter semantics. No further elaboration is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('List') and the target resource ('calendars'), distinguishing it from list_events and other siblings. The verb-resource pairing is specific and unambiguous for a read-only inventory operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (retrieving available calendars), but does not explicitly state when this tool should be preferred over alternatives or mention any prerequisites or exclusions. Given the tool's simplicity, the implied context is sufficient but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_eventsA
List event occurrences in [start, end], expanding recurring series.
Dates are interpreted in the calendar's configured zone. Returns one entry per
occurrence (recurring instances are expanded), sorted by start.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | ||
| start | Yes | ||
| calendar | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses key behaviors: recurring series expansion, calendar timezone interpretation, per-occurrence output, and sorting by start. It does not mention read-only nature explicitly, but 'list' implies safe operation. Minor gaps remain about error handling or pagination, but the description is transparent about core behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the primary purpose and add necessary behavioral details. Every sentence adds value, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters, no output schema, and no annotations, yet the description covers scope, recurrence expansion, timezone handling, and sort order. It partially describes return shape ('one entry per occurrence') but lacks field-level details. Still, it is reasonably complete for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so the description must explain parameters. It clarifies start and end as a range, but does not explain the optional 'calendar' parameter or date format. Thus it adds some meaning but is incomplete for the calendar param.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('event occurrences') with a clear scope ('in [start, end]'), and distinguishes from sibling tools by focusing on occurrences and recurrence expansion. It clearly differentiates from list_calendars and mutation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing events in a date range, but does not explicitly state when to prefer it over alternatives or mention any exclusions. It provides clear context for what it does, but no when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mark_doneA
Mark an event (or one occurrence of a series) done at the current UTC moment.
`occurrence=None` marks the whole event / series; otherwise marks only that
occurrence (via a RECURRENCE-ID override). Idempotent: re-marking replaces
the prior timestamp. The response includes `series_remaining` and
`overrides` for parity with move_occurrence / exclude_occurrence.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| calendar | No | ||
| occurrence | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It discloses idempotency, timestamp at UTC, the RECURRENCE-ID override mechanism, and response fields (series_remaining, overrides), going well beyond basic expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the action and keep every detail meaningful. The format is efficient without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool without an output schema, the description sufficiently covers expected output, idempotency, and the complex occurrence handling, making it complete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It thoroughly explains the occurrence parameter, including None semantics and the override mechanism. Uid and calendar are not elaborated, but they are lower-complexity and the key parameter is well covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Mark an event (or one occurrence of a series) done at the current UTC moment.' It clearly differentiates from sibling tools like move_occurrence and exclude_occurrence by focusing on marking done, and even mentions parity with those tools to reinforce its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on when to use occurrence=None versus a specific occurrence, which is the main usage choice. It references sibling tools for parity but stops short of explicitly stating 'use this instead of X' for all alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
move_occurrenceA
Reschedule a single occurrence of a series (RECURRENCE-ID override).
`occurrence` is the instance's current start exactly as returned by
`list_events`, including the UTC offset (e.g. `2026-06-18T09:00:00+12:00`).
Bare local times may not match. `new_start`/`new_end` are where it moves to.
Omit `new_end` to keep the occurrence's existing duration. The rest of the
series is unchanged. The response includes `series_remaining` (occurrences
left in the series) and `overrides` (RECURRENCE-ID overrides on the series)
so the rest-of-series-unchanged claim is observable.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| new_end | No | ||
| calendar | No | ||
| new_start | Yes | ISO 8601 datetime. A bare local time is interpreted as wall time in the configured zone (`Pacific/Auckland`); an offset-qualified time is honoured and stored in that zone. Use `resolve_datetime` to confirm before writing. | |
| occurrence | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the key behavioral traits: the exact format required for occurrence, the effect of omitting new_end (duration preserved), and that the rest of the series is unchanged. It even mentions the response fields (series_remaining, overrides) to make the claim observable, providing significant transparency beyond the bare schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each adding value: purpose, critical format warning, the move semantics, and response observability. It is front-loaded with the primary verb and resource, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex (recurring series, timezone handling) and has no output schema or annotations, yet the description covers the essential context: how to reference the instance, how to specify the move, duration behavior, series impact, and what the response will reveal. This is enough to guide an agent toward correct invocation and interpretation of results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only new_start has a description), so the tool description compensates strongly. It explains the precise format for occurrence (including UTC offset and why bare local times may fail), the role of new_start/new_end, and the optional nature of new_end. This adds substantial meaning beyond the schema's field names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb+resource combination ('Reschedule a single occurrence of a series') and clarifies it as a RECURRENCE-ID override. This clearly distinguishes it from sibling tools like exclude_occurrence and update_event, making the unique purpose obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear contextual usage by explaining how to identify the occurrence (must match list_events output) and the meaning of new_start/new_end. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of full 'when/when-not' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
resolve_datetimeA
Show how a datetime string will be interpreted, without writing anything.
Use this to confirm a zone before committing an event.
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'without writing anything', which clearly communicates that this is a non-destructive, read-only operation. This is a valuable behavioral trait that goes beyond what the schema or name alone would convey, though it could have added more detail about the exact output format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise—two short sentences with no redundant information. It front-loads the primary action ('Show how a datetime string will be interpreted') and then gives a practical usage tip. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter, no output schema, and no annotations, the description covers the essential purpose and a concrete use case. However, it leaves the exact nature of the output ('how it will be interpreted') somewhat ambiguous, so it is not fully complete but is adequate for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a string parameter with no description (0% coverage), so the description must compensate. The description refers to 'a datetime string', which directly gives meaning to the 'value' parameter, clarifying that it expects a date-time representation. This adds essential semantic context beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Show') and resource ('datetime string'), and it distinguishes itself from sibling tools by focusing on interpretation rather than direct calendar or event operations. The phrase 'without writing anything' reinforces its read-only nature, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool: 'Use this to confirm a zone before committing an event.' This gives clear context for usage, though it does not name alternative tools or explicitly state when not to use it, which would push it to a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_eventA
Edit a whole event/series. Only the fields you pass change.
Preserves the UID and any single-occurrence exclusions/overrides. If you move
`start` without giving `end`, the duration is kept. Moving `start` re-anchors
the whole series — occurrences before the new start stop being generated (this
retimes an entire series; it does not split one at a date).
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ||
| uid | Yes | ||
| rrule | No | ||
| start | No | ISO 8601 datetime. A bare local time is interpreted as wall time in the configured zone (`Pacific/Auckland`); an offset-qualified time is honoured and stored in that zone. Use `resolve_datetime` to confirm before writing. If `end` is omitted, the existing duration is kept. | |
| summary | No | ||
| calendar | No | ||
| location | No | ||
| description | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does an excellent job. It discloses preservation of UID and single-occurrence exclusions/overrides, duration-keeping behavior when moving start without end, series re-anchoring, and the non-splitting nature. This is detailed and actionable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and information-dense, with line breaks that improve readability. Every sentence adds essential behavior or constraints—no filler. It earns its space given the complexity of series updates.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, series re-anchoring) and the absence of annotations and output schema, the description is remarkably complete. It covers key edge cases (duration preservation, exclusions, re-anchoring) and leaves no major ambiguity for selecting and invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 13%, so the description must compensate. It explains the interplay between start and end, and the general 'Only the fields you pass change' rule gives semantic meaning to all optional parameters. However, it does not individually describe rrule, summary, location, etc., beyond the general update rule.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with the specific verb 'Edit' and resource 'event/series', clearly distinguishing it from sibling tools that handle single occurrences. It also explicitly states it does not split a series at a date, which further differentiates it from occurrence-level operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (editing a whole event/series) and contrasts it with splitting behavior, but it does not explicitly name alternative tools like move_occurrence or exclude_occurrence. This is clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
11 tool updates
v1.1.1- First observed
create_calendar - First observed
create_event - First observed
delete_calendar - First observed
delete_event - First observed
exclude_occurrence - First observed
list_calendars - First observed
list_events - First observed
mark_done - First observed
move_occurrence - First observed
resolve_datetime - First observed
update_event
TDQS
Each tool targets a distinct resource and action: calendar CRUD, event CRUD, occurrence-level operations (exclude, move), done-status marking, and datetime resolution. Even update_event vs move_occurrence are unambiguous due to explicit scope differentiation (whole event/series vs single occurrence).
All tool names follow a consistent verb_noun snake_case pattern (list_calendars, create_event, exclude_occurrence). mark_done is a minor variation (verb+adverb) but still fits the naming style and does not disrupt the pattern.
11 tools is well-scoped for a calendar/scheduler server, covering calendar management, event management, and recurring-event operations without unnecessary redundancy. Each tool earns its place.
Core lifecycle for calendars (list/create/delete) and events (list/create/update/delete) is covered, along with advanced recurrence handling. Missing calendar update (e.g., rename) is a minor gap, but agents can work around it by recreate if needed.
Maintenance
Related MCP Connectors
MCP server for Cronofy — read calendars, events and free/busy, and create, update or delete events.
A MCP server that works with Google Calendar to manage event listing, reading, and updates.
Hosted Google Calendar MCP server for AI agents. No self-hosting or Google Cloud setup.
MCP server for Zooza — class scheduling, attendance, and booking for activity businesses.
Related MCP Servers
- AlicenseBqualityDmaintenanceA comprehensive MCP server for CalDAV calendar management, supporting multi-account CRUD operations, recurring events, tasks, journals, and advanced search.2729MIT
- AlicenseAqualityBmaintenanceMCP server for Apple Calendar and CalDAV providers. Enables listing, creating, updating, deleting events, and checking free/busy status with per-calendar write protection.6MIT
- FlicenseNot gradedqualityCmaintenanceMCP server that exposes Synology Calendar (CalDAV) operations as tools, enabling listing calendars and creating, querying, deleting events with timezone handling.-
- AlicenseBqualityAmaintenanceA reliable, cross-platform MCP server for Apple iCloud Calendar that provides guarded CalDAV CRUD operations, idempotent writes, ETag concurrency control, and recurrence expansion via stdio or HTTP.8279MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/limey/cal-scheduler-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server