Skip to main content
The 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-DD or YYYY-MM-DDTHH:mm:ssZ).
    • dateTo (string, required): Range end date in ISO 8601 format. Maximum window is 92 days after dateFrom.
    • coachId (string, optional): Filter occurrences assigned to a specific coach (see list_staff).
    • locationId (string, optional): Filter occurrences held at a specific location (see list_locations).
    • page (integer, optional): Page number, starting at 1.
    • limit (integer, optional): Items per page, default 10, maximum 100.
  • Returns: page, limit, total and events[], ordered by start time. Request the next page while page * limit < total. total counts every occurrence in the range.
  • Limits: A range that is too large to expand completely returns COMPANY_MCP_CALENDAR_QUERY_TOO_COMPLEX with details.action (narrow_date_range_or_filters or retry_later) instead of a partial list. truncated is always false.
Fixed-clock recurring events keep their local clock in the event time zone across offset changes. Returned occurrence timestamps are UTC; date range bounds apply inclusively to the resolved start.

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 by list_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, Manager or Admin.
    • 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: true and 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?”

JSON-RPC Call Example (list_calendar_events)