calendar_events module provides access to scheduled calendar entries and event occurrences.
The write tools create and update lessons, appointments and recurring series.
They require individual tool grants and the approving coach’s current calendar
permissions. create_calendar_task creates a separate coach task; it does not
create a bookable calendar event.
Available Tools
create_calendar_event Write
Create a lesson or appointment from an existing event template. Look up resource
IDs with list_event_templates, list_locations and list_staff first. Show
the coach the proposed dates, local clock, location, trainers and recurrence
before setting confirm: true.
Required fields: templateId, coachIds (1–20 distinct active company trainers),
startAt, endAt, timeZone and confirm: true. Optional fields: locationId,
name (up to 200 characters), and recurrence. If no name is supplied, the
template name is used. Locations and templates must belong to the company.
The selected location’s configured time zone must match timeZone.
Times are UTC ISO-8601 strings ending in Z, with seconds equal to zero. Event
duration must be positive and no longer than 24 hours. Supply the IANA time
zone separately so recurring events keep their local clock across daylight
saving changes.
recurrence accepts frequency (DAILY, WEEKLY or MONTHLY), optional
interval (1–12, default 1), and exactly one of count (including the first
event) or until (inclusive UTC occurrence-start cutoff). A series is limited
to 366 occurrences within three years. Monthly dates that do not exist are
skipped according to the recurrence rule.
The connection needs the calendar_events module, write access and an explicit
create_calendar_event grant. The coach must have current
calendar.events.create permission under the company’s authorization policy.
Normal trainer, location, overlap and recurring-conflict checks apply. This
tool cannot override conflicts, create templates, or book members.
update_calendar_event Write
Required fields: eventId, scope, reason (1–500 characters) and
confirm: true. Review the exact affected occurrences with the coach first.
For recurring updates, use the master
eventId and the occurrence start returned
by list_calendar_events as occurrenceStartAt. When a listed occurrence has
an exception ID, call get_calendar_event first and use its event.masterId.
Direct updates using an exception ID are rejected. Read the changed series again after a following update, which
can return a new master ID.
Provide at least one changed field: templateId, locationId, coachIds,
startAt and endAt together, timeZone, name, or recurrence.
Recurrence changes are supported only for following and series scopes.
Omitted fields are preserved. Recurrence cannot be removed through this tool.
Optional notifyClients and notifyCoach booleans default to false.
Existing bookings and external calendar synchronization follow normal agenda
rescheduling behavior. Enabling notifications can notify affected members and
coaches. Member booking and billing actions are not accepted as tool inputs.
The connection needs an explicit update_calendar_event write grant. Current
staff authorization checks calendar.events.update for a single event, or
calendar.recurring_events.update for a recurring update, including the target
event and destination location scope.
Both tools require a unique idempotencyKey per intended change. Reuse it only
for a retry of the identical request; changing the payload with the same key
is rejected. Current staff access is checked again before cached results are
returned. No existing connection receives the new write grants automatically.
Both return event with eventId, masterId, name, startAt, endAt,
isRecurring, timeZone, templateId, locationId, coaches (each with
coachId and name), plus the applied scope. Coach names may be empty; resolve
them with list_staff. Raw documents, member records and internal notes are
not returned. Invalid input, inaccessible resources, missing permissions and
calendar conflicts reject the request without bypassing the agenda checks.
list_calendar_events
Retrieve calendar event occurrences within a required date range (max 92 days). Recurring events are expanded into individual occurrences.
- Type: Read-only
- Important Input Fields:
dateFrom(string, required): Range start date in ISO 8601 format (YYYY-MM-DDorYYYY-MM-DDTHH:mm:ssZ).dateTo(string, required): Range end date in ISO 8601 format. Maximum window is 92 days afterdateFrom.coachId(string, optional): Filter occurrences assigned to a specific coach (seelist_staff).locationId(string, optional): Filter occurrences held at a specific location (seelist_locations).page(integer, optional): Page number, starting at 1.limit(integer, optional): Items per page, default 10, maximum 100.
- Returns:
page,limit,totalandevents[], ordered by start time. Request the next page whilepage * limit < total.totalcounts every occurrence in the range. - Limits: A range that is too large to expand completely returns
COMPANY_MCP_CALENDAR_QUERY_TOO_COMPLEXwithdetails.action(narrow_date_range_or_filtersorretry_later) instead of a partial list.truncatedis alwaysfalse.
get_calendar_event
Retrieve full details of a specific calendar event.
- Type: Read-only
- Important Input Fields:
eventId(string, required): Unique identifier of the calendar event.startAt(string, optional): UTC occurrence start returned bylist_calendar_events. Supply it to retrieve a recurring occurrence and its occupancy. Cancelled occurrences are unavailable.
get_location_availability
Retrieve configured availability per location: the weekly pattern
(dayOfWeek 0 = Sunday), time slots and open hours per day,
totalWeeklyHours, exceptions for the next 60 days, and booking settings.
- Type: Read-only
- Important Input Fields:
locationId(string, optional): Return one location. Omit for all locations.
list_staff
List active coaches and staff of the company: name, email, role,
trainerStatus, weeklyHours, calendarColor, locationAccess
(mode plus locationIds) and lastActiveAt. Use it to find coachId
values for the coach filters of other tools. Date of birth, image and sex are
not exposed.
- Type: Read-only
- Important Input Fields:
search(string, optional): Match on first name, last name or email.role(string, optional):Coach,ManagerorAdmin.page,limit(integer, optional): Pagination (max 50 per page).
list_locations
List company locations with name, status, time zone, address and opening
hours (mode, weekly pattern with slots and hours per day, totalWeeklyHours,
and opening-hours exceptions for the next 60 days). Opening hours describe when
a location is open; for bookable availability windows use
get_location_availability.
- Type: Read-only
- Important Input Fields: none (returns up to 50 locations).
cancel_calendar_event Write
Cancel one event, one recurring occurrence, this and following occurrences, or the whole series, like the dashboard cancel action. All bookings in scope are cancelled with the company cancellation policy (financialAction followPolicy by default; refund, retain or charge override it). For a recurring event pass the master eventId plus occurrenceStartAt from list_calendar_events. notifyClient defaults to false. Show the coach the scope, number of booked members and financial effect, and get explicit confirmation first.
- Type: Write (requires
userConfirmed: trueand the write-tool grant) - Input Fields:
eventId(string, required)scope(string:occurrence,following,series, optional)occurrenceStartAt(string, optional)financialAction(string:followPolicy,refund,retain,charge, optional)cancellationReasonCode(string, optional)cancellationReasonText(string, optional)coachNote(string, optional)notifyClient(boolean, optional)idempotencyKey(string, optional)
Natural Language Examples
- “List all calendar events scheduled for next week.”
- “Retrieve details for the workout event with ID event_abc123.”
- “How many hours per week is each location available?”
- “Which coaches work here, and what are the opening hours of each location?”