# Calendar tools

> Every calendar tool in the developer API, with arguments and examples: list events, find free time, book and change events.

**Needs:** Google, Outlook or iCloud Calendar. 7 tools.

These tools appear in `GET /v1/tools` only when the API key's MCP server includes a connection of this kind. Call each one with `POST /v1/tools/\<name>`, sending its arguments as a JSON object. See [Calling tools](https://docs.plugsight.app/developers/calling-tools.md) for the request and response format.

| Tool                                                  | What it does            | Kind   |
| ----------------------------------------------------- | ----------------------- | ------ |
| [`calendar_list_calendars`](#calendar_list_calendars) | List calendars          | Read   |
| [`calendar_list_events`](#calendar_list_events)       | List calendar events    | Read   |
| [`calendar_get_event`](#calendar_get_event)           | Read a calendar event   | Read   |
| [`calendar_find_free_time`](#calendar_find_free_time) | Find free time          | Read   |
| [`calendar_create_event`](#calendar_create_event)     | Book a calendar event   | Change |
| [`calendar_update_event`](#calendar_update_event)     | Change a calendar event | Change |
| [`calendar_cancel_event`](#calendar_cancel_event)     | Cancel a calendar event | Change |

Change tools in this group: `calendar_create_event`, `calendar_update_event`, `calendar_cancel_event`. Check each tool's notes below for what it needs before it runs.

The example requests fill in only the required arguments, with placeholder values.

## calendar_list_calendars

**List calendars** · Read

Calendars this connection can read (Google, Outlook or iCloud), with their ids, time zones and whether events can be added.

| Argument  | Type   | Required | What it is                                                                     |
| --------- | ------ | -------- | ------------------------------------------------------------------------------ |
| `account` | string | No       | Connection id from list_accounts (optional when there's only one of this type) |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/calendar_list_calendars \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## calendar_list_events

**List calendar events** · Read

Events between two times, across all visible calendars or one, optionally matching text. Times are ISO 8601 (e.g. "2026-11-20T09:00:00+04:00") or dates (YYYY-MM-DD), which cover whole days in the calendar's time zone. Recurring events are expanded. Long descriptions are shortened (description_truncated: true); calendar_get_event returns an event in full. When more events match than `limit`, the result says truncated: true and gives next_from to continue from.

| Argument      | Type    | Required | What it is                                                                                                    |
| ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `from`        | string  | Yes      | Start: ISO date-time or YYYY-MM-DD                                                                            |
| `to`          | string  | Yes      | End: ISO date-time or YYYY-MM-DD (inclusive for dates)                                                        |
| `query`       | string  | No       | Text to match in title, description, location or attendees                                                    |
| `calendar_id` | string  | No       | One calendar id from calendar_list_calendars; default all visible                                             |
| `time_zone`   | string  | No       | IANA time zone for dates and times given without an offset, e.g. "Europe/London". Default: the calendar's own |
| `limit`       | integer | No       | Most events to return. Default `100`.                                                                         |
| `account`     | string  | No       | Connection id from list_accounts (optional when there's only one of this type)                                |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/calendar_list_events \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "2026-11-01", "to": "2026-11-15"}'
```

## calendar_get_event

**Read a calendar event** · Read

One event in full: the whole description, every guest and their reply, video-call and dial-in links, location and attached files (names and links). Use an event id (and calendar_id) from calendar_list_events.

| Argument      | Type   | Required | What it is                                                                                |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------------- |
| `event_id`    | string | Yes      | Event id from calendar_list_events                                                        |
| `calendar_id` | string | No       | The event's calendar_id from calendar_list_events; default: look in each visible calendar |
| `account`     | string | No       | Connection id from list_accounts (optional when there's only one of this type)            |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/calendar_get_event \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id": "…"}'
```

## calendar_find_free_time

**Find free time** · Read

Busy times across visible calendars between two times, and free gaps of at least min_minutes. Dates (YYYY-MM-DD) cover whole days in the calendar's time zone. Events marked free don't block time; all-day events marked busy or out of office do. Use it to suggest meeting slots; check notes for calendars that couldn't be read.

| Argument      | Type    | Required | What it is                                                                                                    |
| ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `from`        | string  | Yes      | Start: ISO date-time or YYYY-MM-DD                                                                            |
| `to`          | string  | Yes      | End: ISO date-time or YYYY-MM-DD (inclusive for dates)                                                        |
| `time_zone`   | string  | No       | IANA time zone for dates and times given without an offset, e.g. "Europe/London". Default: the calendar's own |
| `min_minutes` | integer | No       | Shortest free gap worth listing, in minutes. Default `30`.                                                    |
| `account`     | string  | No       | Connection id from list_accounts (optional when there's only one of this type)                                |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/calendar_find_free_time \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "2026-11-01", "to": "2026-11-15"}'
```

## calendar_create_event

**Book a calendar event** · Change

Creates an event, optionally inviting guests (and, on Google calendars, adding a Google Meet link). Check calendar_find_free_time first. Times are ISO 8601 with offset (e.g. "2026-11-20T15:00:00+04:00"), or YYYY-MM-DD for all-day events (end is the day after).

> [!IMPORTANT]
> This tool makes a change, so the request must include `"confirm": true`, and changes must be allowed. See [Making changes](https://docs.plugsight.app/developers/calling-tools.md#making-changes).

| Argument        | Type            | Required | What it is                                                                     |
| --------------- | --------------- | -------- | ------------------------------------------------------------------------------ |
| `title`         | string          | Yes      | Event title                                                                    |
| `start`         | string          | Yes      | ISO date-time with offset, or YYYY-MM-DD for all day                           |
| `end`           | string          | Yes      | ISO date-time with offset, or YYYY-MM-DD (exclusive) for all day               |
| `time_zone`     | string          | No       | IANA zone, e.g. "Europe/London"; default the calendar's                        |
| `description`   | string          | No       | Description                                                                    |
| `location`      | string          | No       | Location                                                                       |
| `guests`        | array of string | No       | Email addresses to invite                                                      |
| `google_meet`   | boolean         | No       | Add a Google Meet video link (Google calendars only) Default `false`.          |
| `notify_guests` | boolean         | No       | Email the guests (invitations, updates or cancellation) Default `true`.        |
| `calendar_id`   | string          | No       | Default: the primary calendar                                                  |
| `account`       | string          | No       | Connection id from list_accounts (optional when there's only one of this type) |
| `confirm`       | boolean         | Yes      | Must be true: the user approved these exact details                            |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/calendar_create_event \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "…", "start": "2026-11-20T15:00:00+00:00", "end": "2026-11-20T15:30:00+00:00", "confirm": true}'
```

## calendar_update_event

**Change a calendar event** · Change

Moves or edits an event: new time, title, description, location, or more guests. Only the fields given change. Use the event id from calendar_list_events.

> [!IMPORTANT]
> This tool makes a change, so the request must include `"confirm": true`, and changes must be allowed. See [Making changes](https://docs.plugsight.app/developers/calling-tools.md#making-changes).

| Argument        | Type            | Required | What it is                                                                     |
| --------------- | --------------- | -------- | ------------------------------------------------------------------------------ |
| `event_id`      | string          | Yes      | Event id from calendar_list_events                                             |
| `calendar_id`   | string          | No       | The event's calendar; default the primary calendar                             |
| `title`         | string          | No       | New title                                                                      |
| `start`         | string          | No       | New start, ISO 8601 date-time                                                  |
| `end`           | string          | No       | New end, ISO 8601 date-time                                                    |
| `time_zone`     | string          | No       | IANA time zone, e.g. Europe/London                                             |
| `description`   | string          | No       | Description                                                                    |
| `location`      | string          | No       | Location                                                                       |
| `add_guests`    | array of string | No       | Guest email addresses to invite                                                |
| `notify_guests` | boolean         | No       | Email the guests (invitations, updates or cancellation) Default `true`.        |
| `account`       | string          | No       | Connection id from list_accounts (optional when there's only one of this type) |
| `confirm`       | boolean         | Yes      | Must be true: the user approved these exact details                            |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/calendar_update_event \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id": "…", "confirm": true}'
```

## calendar_cancel_event

**Cancel a calendar event** · Change

Deletes an event and, by default, emails guests a cancellation. For a repeating event, Google cancels only the given occurrence; iCloud cancels the whole series.

> [!IMPORTANT]
> This tool makes a change, so the request must include `"confirm": true`, and changes must be allowed. See [Making changes](https://docs.plugsight.app/developers/calling-tools.md#making-changes).

| Argument        | Type    | Required | What it is                                                                     |
| --------------- | ------- | -------- | ------------------------------------------------------------------------------ |
| `event_id`      | string  | Yes      | Event id from calendar_list_events                                             |
| `calendar_id`   | string  | No       | Calendar id from calendar_list_calendars (default: the main calendar)          |
| `notify_guests` | boolean | No       | Email the guests (invitations, updates or cancellation) Default `true`.        |
| `account`       | string  | No       | Connection id from list_accounts (optional when there's only one of this type) |
| `confirm`       | boolean | Yes      | Must be true: the user approved these exact details                            |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/calendar_cancel_event \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id": "…", "confirm": true}'
```

## Related articles

- [Calling tools](https://docs.plugsight.app/developers/calling-tools.md)
- [Errors](https://docs.plugsight.app/developers/errors.md)
- [Authentication](https://docs.plugsight.app/developers/authentication.md)

---

Web version: https://docs.plugsight.app/developers/calendar-tools
