<!-- Generated by `just docs` from catalog/toolkits/google_calendar.yaml, catalog/expansions/google_calendar.yaml, catalog/evals/scorecard.json. Edit the source, not this file. -->

# Google Calendar

Calendars. Create, find, and change events and meetings, check when people are free, and manage calendars and their sharing.

| Property | Value |
| --- | --- |
| Slug | `google_calendar` |
| Definition version | `0.1.0` |
| Base URL | `https://www.googleapis.com/calendar/v3` |
| Auth schemes | `oauth2` |
| Action tools | 26 |
| By class | 10 read, 12 write, 4 destructive |
| Triggers | 1 |
| Provider rate limit | not declared, so outbound calls are unpaced |

## Measured routing accuracy

40 golden cases replayed through the router over the whole index: measured over corpus `ea4f12ad2948` (65 toolkits, 2283 tools indexed and 13 declared uncallable), 16 cases written by hand and 22 cases from the paraphrase pass, plus 2 context cases whose intent names no app and is decided by the session. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all.

| Measure | Cases | Share |
| --- | --- | --- |
| top-1 | 13/40 | 32.5% |
| top-8 | 29/40 | 72.5% |

The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. `just eval-live` measures the same cases through the live reranker.

## Authentication

Connect an entity with `ConnectionsService.InitiateConnection`, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only.

### `oauth2`

| Property | Value |
| --- | --- |
| Authorization URL | `https://accounts.google.com/o/oauth2/v2/auth` |
| Token URL | `https://oauth2.googleapis.com/token` |
| Default scopes | `https://www.googleapis.com/auth/calendar` |
| Refresh tokens | yes, the refresh daemon renews ahead of expiry |

## Tools

26 action tools. The catalog-wide slug is `google_calendar.<tool>`, which is what `search_tools` returns and `call_tool` takes.

### `google_calendar.list_events`

List or search events on a calendar within a time window, with free-text query support. Use when the user asks what's on their calendar, what meetings they have, or wants to find an event by name. Recurring events expand to one entry per occurrence when single_events is true. For one known event use get_event.

Class `read` (reads only). Scopes `https://www.googleapis.com/auth/calendar.events.readonly`. Calls `GET /calendars/{{params.calendar_id}}/events`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar id, or "primary" for the user's main calendar. |
| `max_results` | integer | no | Page size, default 250. |
| `order_by` | string, one of startTime, updated | no | Sort order. startTime requires single_events true. |
| `page_token` | string | no | Token from a previous page's nextPageToken. |
| `query` | string | no | Free-text search over summary, description, and attendees. |
| `single_events` | boolean | no | Expand recurring events into individual instances. Default false, which returns the recurring series as one entry. |
| `time_max` | string | no | RFC 3339 timestamp; excludes events starting after this. |
| `time_min` | string | no | RFC 3339 timestamp; excludes events ending before this. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `items` | array of object |  |
| `items[].attendees` | array of object |  |
| `items[].attendees[].email` | string |  |
| `items[].attendees[].responseStatus` | string |  |
| `items[].end` | object |  |
| `items[].end.date` | string |  |
| `items[].end.dateTime` | string |  |
| `items[].end.timeZone` | string |  |
| `items[].htmlLink` | string |  |
| `items[].id` | string |  |
| `items[].location` | string |  |
| `items[].start` | object |  |
| `items[].start.date` | string |  |
| `items[].start.dateTime` | string |  |
| `items[].start.timeZone` | string |  |
| `items[].status` | string |  |
| `items[].summary` | string |  |
| `nextPageToken` | string |  |

Also retrieved by: "what's on my calendar this week", "show me my meetings for tomorrow", "what do I have going on today", "pull up everything scheduled between these two dates", "find that meeting about the budget", "what's my agenda look like this week", "check my schedule for any meetings today".

### `google_calendar.get_event`

Get one event's full details by event id: time, location, description, attendees and their RSVP status, recurrence, and video conference link. Use after list_events to read a specific meeting. For every occurrence of a recurring event use list_event_instances.

Class `read` (reads only). Scopes `https://www.googleapis.com/auth/calendar.events.readonly`. Calls `GET /calendars/{{params.calendar_id}}/events/{{params.event_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar id, or "primary" for the user's main calendar. |
| `event_id` | string | **yes** | Event id from list_events or create_event. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `attendees` | array of object |  |
| `attendees[].displayName` | string |  |
| `attendees[].email` | string |  |
| `attendees[].optional` | boolean |  |
| `attendees[].responseStatus` | string |  |
| `creator` | object |  |
| `creator.email` | string |  |
| `description` | string |  |
| `end` | object |  |
| `end.date` | string |  |
| `end.dateTime` | string |  |
| `end.timeZone` | string |  |
| `hangoutLink` | string |  |
| `htmlLink` | string |  |
| `id` | string |  |
| `location` | string |  |
| `organizer` | object |  |
| `organizer.email` | string |  |
| `recurrence` | array of string |  |
| `recurringEventId` | string |  |
| `start` | object |  |
| `start.date` | string |  |
| `start.dateTime` | string |  |
| `start.timeZone` | string |  |
| `status` | string |  |
| `summary` | string |  |

Also retrieved by: "pull up the details for that meeting", "show me everything about this appointment", "what time and where is that thing again", "open up that calendar entry", "who else is on that meeting and when is it", "what's the location for the 2pm meeting".

### `google_calendar.create_event`

Create a calendar event or meeting. Use when the user wants to schedule, book, or set up a meeting, appointment, or reminder at a specific time. Give an all-day event with start_date and end_date, or a timed event with start_time and end_time. Invited attendees get an email unless send_updates is "none". For a plain-English one-liner like "lunch with Sam Friday at noon" use quick_add_event.

Class `write` (writes, no confirmation needed). Scopes `https://www.googleapis.com/auth/calendar.events`. Calls `POST /calendars/{{params.calendar_id}}/events`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `attendees` | array of object | no | People to invite. |
| `attendees[].email` | string | **yes** |  |
| `attendees[].optional` | boolean | no | Marks the attendee as optional rather than required. |
| `calendar_id` | string | **yes** | Calendar id, or "primary" for the user's main calendar. |
| `color_id` | string | no | Event color id from list_calendar_colors. |
| `description` | string | no | Longer free-text notes for the event. |
| `end_date` | string | no | All-day event end (exclusive), "YYYY-MM-DD". |
| `end_time` | string | no | Timed event end, RFC 3339. |
| `location` | string | no | Free-text location or meeting address. |
| `recurrence` | array of string | no | RFC 5545 recurrence lines, e.g. ["RRULE:FREQ=WEEKLY;COUNT=5"]. |
| `send_updates` | string, one of all, externalOnly, none | no | Who gets the invite email. Default none. |
| `start_date` | string | no | All-day event start, "YYYY-MM-DD". Omit for a timed event. |
| `start_time` | string | no | Timed event start, RFC 3339. Omit for an all-day event. |
| `summary` | string | **yes** | Event title. |
| `time_zone` | string | no | IANA time zone for start_time/end_time, e.g. "America/Chicago". Required alongside start_time. |
| `visibility` | string, one of default, public, private | no |  |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `attendees` | array of object |  |
| `attendees[].email` | string |  |
| `attendees[].responseStatus` | string |  |
| `end` | object |  |
| `end.date` | string |  |
| `end.dateTime` | string |  |
| `hangoutLink` | string |  |
| `htmlLink` | string |  |
| `id` | string |  |
| `start` | object |  |
| `start.date` | string |  |
| `start.dateTime` | string |  |
| `status` | string |  |
| `summary` | string |  |

Also retrieved by: "put a meeting on my calendar", "book time with the design team next Tuesday", "set up an appointment for Thursday afternoon", "get something on the calendar for next week", "schedule a call with the client", "block off time for a meeting Friday morning", "put a meeting on the calendar with a few people invited".

### `google_calendar.quick_add_event`

Create an event from one plain-English line, e.g. "Dinner with Sam Tuesday at 7pm at Luigi's". Google parses the date, time, and title; use when the user phrases a booking casually rather than giving separate fields. For explicit start and end times, invitee objects, or recurrence, use create_event instead.

Class `write` (writes, no confirmation needed). Scopes `https://www.googleapis.com/auth/calendar.events`. Calls `POST /calendars/{{params.calendar_id}}/events/quickAdd`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar id, or "primary" for the user's main calendar. |
| `send_updates` | string, one of all, externalOnly, none | no | Who gets the invite email. Default none. |
| `text` | string | **yes** | The event described in one sentence, e.g. "Appointment at Somewhere on June 3rd 10am-10:25am". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `end` | object |  |
| `end.date` | string |  |
| `end.dateTime` | string |  |
| `htmlLink` | string |  |
| `id` | string |  |
| `start` | object |  |
| `start.date` | string |  |
| `start.dateTime` | string |  |
| `summary` | string |  |

Also retrieved by: "jot down dinner with Sam Friday at 7", "just throw coffee with Alex on Monday morning on the calendar", "add "standup at 9am" real quick", "drop a one-line reminder on my calendar for Monday".

### `google_calendar.update_event`

Change an existing event's title, time, location, description, recurrence, or visibility by event id. Use when the user wants to reschedule, rename, move, or edit a meeting. Only the fields given are changed; the rest stay as they are. To change who is invited use update_event_attendees; to cancel it entirely use delete_event.

Class `write` (writes, no confirmation needed). Scopes `https://www.googleapis.com/auth/calendar.events`. Calls `PATCH /calendars/{{params.calendar_id}}/events/{{params.event_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar id, or "primary" for the user's main calendar. |
| `description` | string | no | New free-text notes. |
| `end_date` | string | no | New all-day end (exclusive), "YYYY-MM-DD". |
| `end_time` | string | no | New timed end, RFC 3339. |
| `event_id` | string | **yes** | Event to update. |
| `location` | string | no | New location. |
| `recurrence` | array of string | no | Replacement RFC 5545 recurrence lines. |
| `send_updates` | string, one of all, externalOnly, none | no | Who gets the change notification email. Default none. |
| `start_date` | string | no | New all-day start, "YYYY-MM-DD". |
| `start_time` | string | no | New timed start, RFC 3339. |
| `summary` | string | no | New event title. |
| `time_zone` | string | no | IANA time zone, required alongside start_time or end_time. |
| `visibility` | string, one of default, public, private | no |  |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `end` | object |  |
| `end.date` | string |  |
| `end.dateTime` | string |  |
| `htmlLink` | string |  |
| `id` | string |  |
| `start` | object |  |
| `start.date` | string |  |
| `start.dateTime` | string |  |
| `status` | string |  |
| `summary` | string |  |

Also retrieved by: "push that meeting back an hour", "change the location for tomorrow's appointment", "rename that calendar entry", "move the client call to a different day", "reschedule tomorrow's meeting to the afternoon".

### `google_calendar.delete_event`

Permanently cancel and remove an event from a calendar by event id. Use when the user wants to cancel, delete, or remove a meeting or appointment. Unrecoverable; other attendees are notified by default. Verify the event id first, e.g. with get_event.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `https://www.googleapis.com/auth/calendar.events`. Calls `DELETE /calendars/{{params.calendar_id}}/events/{{params.event_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar id, or "primary" for the user's main calendar. |
| `event_id` | string | **yes** | Event to cancel and remove. |
| `send_updates` | string, one of all, externalOnly, none | no | Who gets the cancellation email. Default all. |

Also retrieved by: "cancel that meeting", "get rid of tomorrow's appointment", "clear that thing off my calendar", "I don't need that call anymore, take it off", "cancel the meeting and let everyone know it's off".

### `google_calendar.move_event`

Move an event from one calendar to another, e.g. from a personal calendar to a shared team calendar. Use when the user wants an event put on a different calendar, not just rescheduled in time. For a time or detail change on the same calendar use update_event.

Class `write` (writes, no confirmation needed). Scopes `https://www.googleapis.com/auth/calendar.events`. Calls `POST /calendars/{{params.calendar_id}}/events/{{params.event_id}}/move`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar the event currently lives on. |
| `destination_calendar_id` | string | **yes** | Calendar id to move the event onto. |
| `event_id` | string | **yes** | Event to move. |
| `send_updates` | string, one of all, externalOnly, none | no | Who gets the change notification email. Default none. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `htmlLink` | string |  |
| `id` | string |  |
| `organizer` | object |  |
| `organizer.email` | string |  |

Also retrieved by: "put that meeting on the team calendar instead", "shift this appointment onto my work calendar", "this belongs on a different calendar, move it over".

### `google_calendar.list_event_instances`

List every occurrence of a recurring event within a time window, each with its own id, start, and end. Use when the user asks about a specific occurrence of a repeating meeting, or wants every date in a series. For the series definition itself use get_event.

Class `read` (reads only). Scopes `https://www.googleapis.com/auth/calendar.events.readonly`. Calls `GET /calendars/{{params.calendar_id}}/events/{{params.event_id}}/instances`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar id, or "primary" for the user's main calendar. |
| `event_id` | string | **yes** | Recurring event id from list_events or get_event. |
| `max_results` | integer | no | Page size, default 250. |
| `page_token` | string | no | Token from a previous page's nextPageToken. |
| `time_max` | string | no | RFC 3339 timestamp; excludes instances starting after this. |
| `time_min` | string | no | RFC 3339 timestamp; excludes instances ending before this. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `items` | array of object |  |
| `items[].end` | object |  |
| `items[].end.date` | string |  |
| `items[].end.dateTime` | string |  |
| `items[].id` | string |  |
| `items[].start` | object |  |
| `items[].start.date` | string |  |
| `items[].start.dateTime` | string |  |
| `items[].status` | string |  |
| `items[].summary` | string |  |
| `nextPageToken` | string |  |

Also retrieved by: "show me every date in that recurring series", "what are all the occurrences of the weekly standup", "list out each instance of that repeating meeting".

### `google_calendar.update_event_attendees`

Replace the complete guest list on an event: add someone, remove someone, or change your own or another guest's RSVP status. Use when the user wants to invite, uninvite, add, remove, or respond to a meeting (accept, decline, or mark tentative). Google replaces the whole attendee list, so include everyone who should stay invited, not just the one being changed; read the current list with get_event first.

Class `write` (writes, no confirmation needed). Scopes `https://www.googleapis.com/auth/calendar.events`. Calls `PATCH /calendars/{{params.calendar_id}}/events/{{params.event_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `attendees` | array of object | **yes** | The complete new guest list. Include every attendee who should remain invited, with their current or intended responseStatus. |
| `attendees[].email` | string | **yes** |  |
| `attendees[].optional` | boolean | no | Marks the attendee as optional rather than required. |
| `attendees[].responseStatus` | string, one of needsAction, declined, tentative, accepted | no |  |
| `calendar_id` | string | **yes** | Calendar id, or "primary" for the user's main calendar. |
| `event_id` | string | **yes** | Event whose guest list is being replaced. |
| `send_updates` | string, one of all, externalOnly, none | no | Who gets the change notification email. Default none. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `attendees` | array of object |  |
| `attendees[].email` | string |  |
| `attendees[].optional` | boolean |  |
| `attendees[].responseStatus` | string |  |
| `id` | string |  |

Also retrieved by: "add Priya to the guest list for that meeting", "take Jordan off the guest list", "accept that meeting invite", "decline the invitation to that call", "mark myself as tentative for that one", "RSVP yes to the planning meeting", "put another person on the invite for Thursday's meeting".

### `google_calendar.get_calendar`

Get a calendar's own metadata by id: title, description, location, and time zone. Use to check a calendar's display name or time zone. For the user's list of calendars and per-calendar view settings (color, visibility) use list_calendars instead.

Class `read` (reads only). Scopes `https://www.googleapis.com/auth/calendar.readonly`. Calls `GET /calendars/{{params.calendar_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar id, or "primary" for the user's main calendar. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `description` | string |  |
| `id` | string |  |
| `location` | string |  |
| `summary` | string |  |
| `timeZone` | string |  |

Also retrieved by: "what time zone is that calendar set to", "look up the details on this calendar", "what's this calendar named".

### `google_calendar.create_calendar`

Create a new secondary calendar, separate from the user's primary calendar. Use when the user wants a new calendar for a project, team, or area of life, distinct from a shared calendar someone else already owns. To use an existing calendar someone shared with you, use add_calendar_to_list instead.

Class `write` (writes, no confirmation needed). Scopes `https://www.googleapis.com/auth/calendar.calendars`. Calls `POST /calendars`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `description` | string | no | Longer free-text notes for the calendar. |
| `location` | string | no | Free-text geographic location. |
| `summary` | string | **yes** | Calendar title. |
| `time_zone` | string | no | IANA time zone, e.g. "America/Chicago". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `summary` | string |  |
| `timeZone` | string |  |

Also retrieved by: "set up a new calendar for the project", "make a separate calendar for the marketing team", "start a fresh calendar just for travel plans", "I want a brand new calendar just for this, not on my main one", "spin up a calendar for the onboarding project".

### `google_calendar.update_calendar`

Rename a calendar or change its description, location, or time zone by calendar id. Use when the user wants to rename or edit a calendar itself, not an event on it. Only affects calendars the user owns or can manage.

Class `write` (writes, no confirmation needed). Scopes `https://www.googleapis.com/auth/calendar.calendars`. Calls `PATCH /calendars/{{params.calendar_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar to update. |
| `description` | string | no | New free-text notes. |
| `location` | string | no | New free-text location. |
| `summary` | string | no | New calendar title. |
| `time_zone` | string | no | New IANA time zone. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `description` | string |  |
| `id` | string |  |
| `location` | string |  |
| `summary` | string |  |
| `timeZone` | string |  |

Also retrieved by: "rename that calendar", "change the time zone on this calendar", "give this calendar a new description".

### `google_calendar.delete_calendar`

Permanently delete a secondary calendar and every event on it, by calendar id. Unrecoverable. Use only when the user explicitly wants a whole calendar gone, not just emptied; to keep the calendar but remove its events use clear_calendar, and to just stop seeing a shared calendar use remove_calendar_from_list.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `https://www.googleapis.com/auth/calendar.calendars`. Calls `DELETE /calendars/{{params.calendar_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar to delete permanently. |

Also retrieved by: "get rid of that whole calendar for good", "delete the project calendar entirely", "remove this calendar and everything on it", "that calendar isn't needed anymore, delete it completely", "permanently delete this calendar, not just clear it out".

### `google_calendar.clear_calendar`

Permanently delete every event on the primary calendar, keeping the calendar itself. Use when the user wants to wipe, empty, or start their calendar over from scratch. Unrecoverable and only works on the primary calendar; for a secondary calendar use delete_calendar instead.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `https://www.googleapis.com/auth/calendar.calendars`. Calls `POST /calendars/{{params.calendar_id}}/clear`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Must be "primary"; the API only clears the primary calendar. |

Also retrieved by: "wipe every event off my calendar", "empty out my calendar completely", "start my calendar over from scratch".

### `google_calendar.list_calendars`

List every calendar the user has access to: their own, shared ones, and subscribed public calendars, with each one's display color and access role. Use when the user asks what calendars they have, or to resolve a calendar's display name to its id.

Class `read` (reads only). Scopes `https://www.googleapis.com/auth/calendar.calendarlist.readonly`. Calls `GET /users/me/calendarList`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `max_results` | integer | no | Page size, default 100. |
| `page_token` | string | no | Token from a previous page's nextPageToken. |
| `show_hidden` | boolean | no | Include calendars the user has hidden. Default false. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `items` | array of object |  |
| `items[].accessRole` | string |  |
| `items[].colorId` | string |  |
| `items[].hidden` | boolean |  |
| `items[].id` | string |  |
| `items[].primary` | boolean |  |
| `items[].selected` | boolean |  |
| `items[].summary` | string |  |
| `items[].timeZone` | string |  |
| `nextPageToken` | string |  |

Also retrieved by: "what calendars do I have", "show me every calendar in my account", "list out all my calendars", "which calendar is that team's stuff on", "what calendars can I pick from when I make an event".

### `google_calendar.get_calendar_list_entry`

Get one calendar's entry in the user's own calendar list: its display color, whether it is selected or hidden, default reminders, and access role. Use for the user's personal view settings on a calendar. For the calendar's own title and time zone use get_calendar instead.

Class `read` (reads only). Scopes `https://www.googleapis.com/auth/calendar.calendarlist.readonly`. Calls `GET /users/me/calendarList/{{params.calendar_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar id, or "primary" for the user's main calendar. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `accessRole` | string |  |
| `colorId` | string |  |
| `hidden` | boolean |  |
| `id` | string |  |
| `primary` | boolean |  |
| `selected` | boolean |  |
| `summary` | string |  |

Also retrieved by: "what color is that calendar set to in my view", "is this calendar hidden from my view", "check my personal settings for that calendar".

### `google_calendar.add_calendar_to_list`

Subscribe to an existing calendar someone shared, or a public calendar, adding it to the user's own calendar list by its id. Use when the user wants to add, follow, or subscribe to a calendar they don't own. To create a brand-new calendar use create_calendar.

Class `write` (writes, no confirmation needed). Scopes `https://www.googleapis.com/auth/calendar.calendarlist`. Calls `POST /users/me/calendarList`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Id of the calendar to subscribe to, usually its owner's email or a public calendar id. |
| `color_id` | string | no | Display color id from list_calendar_colors. |
| `hidden` | boolean | no | Add it hidden from the calendar view. Default false. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `accessRole` | string |  |
| `id` | string |  |
| `summary` | string |  |

Also retrieved by: "subscribe to the team's shared calendar", "add that calendar someone shared with me", "follow the company holidays calendar".

### `google_calendar.update_calendar_list_entry`

Change how a subscribed calendar appears for the user: its display color, whether it is selected (shown) or hidden. Use when the user wants to recolor, show, or hide a calendar in their own view. Does not affect the calendar for anyone else.

Class `write` (writes, no confirmation needed). Scopes `https://www.googleapis.com/auth/calendar.calendarlist`. Calls `PATCH /users/me/calendarList/{{params.calendar_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar entry to update. |
| `color_id` | string | no | New display color id from list_calendar_colors. |
| `hidden` | boolean | no | Whether the calendar is hidden from the calendar view. |
| `selected` | boolean | no | Whether the calendar is shown in the calendar view. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `colorId` | string |  |
| `hidden` | boolean |  |
| `id` | string |  |
| `selected` | boolean |  |

Also retrieved by: "change the color on that calendar", "hide this calendar from my view", "show that calendar again in my view".

### `google_calendar.remove_calendar_from_list`

Unsubscribe from a calendar, removing it from the user's own calendar list. Use when the user wants to stop seeing, hide for good, or remove a shared or public calendar from their view. The calendar itself and its events are untouched; to delete a calendar the user owns, use delete_calendar.

Class `write` (writes, no confirmation needed). Scopes `https://www.googleapis.com/auth/calendar.calendarlist`. Calls `DELETE /users/me/calendarList/{{params.calendar_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar entry to remove from the user's list. |

Also retrieved by: "stop showing me that calendar", "take that shared calendar out of my view", "unsubscribe from the old team calendar".

### `google_calendar.list_acl_rules`

List who has access to a calendar and their role: owner, writer, reader, or free/busy only. Use when the user asks who can see or edit a calendar, or who it's shared with.

Class `read` (reads only). Scopes `https://www.googleapis.com/auth/calendar.acls.readonly`. Calls `GET /calendars/{{params.calendar_id}}/acl`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar id, or "primary" for the user's main calendar. |
| `page_token` | string | no | Token from a previous page's nextPageToken. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `items` | array of object |  |
| `items[].id` | string |  |
| `items[].role` | string |  |
| `items[].scope` | object |  |
| `items[].scope.type` | string |  |
| `items[].scope.value` | string |  |
| `nextPageToken` | string |  |

Also retrieved by: "who can see this calendar", "who has access to edit this calendar", "show me everyone this calendar is shared with".

### `google_calendar.share_calendar`

Grant a person, group, or the whole domain access to a calendar. Use when the user wants to share, invite, or give someone access to a calendar. role controls what they can do: freeBusyReader (just availability), reader, writer, or owner. To change an existing person's role use update_acl_rule.

Class `write` (writes, no confirmation needed). Scopes `https://www.googleapis.com/auth/calendar.acls`. Calls `POST /calendars/{{params.calendar_id}}/acl`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar id, or "primary" for the user's main calendar. |
| `role` | string, one of freeBusyReader, reader, writer, owner | **yes** | Access level to grant. |
| `scope_type` | string, one of user, group, domain, default | no | Who scope_value identifies. Default "user" (an individual email address). |
| `scope_value` | string | **yes** | Email address for a user or group, or a domain name for scope_type domain. |
| `send_notifications` | boolean | no | Email the person that they now have access. Default true. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `role` | string |  |
| `scope` | object |  |
| `scope.type` | string |  |
| `scope.value` | string |  |

Also retrieved by: "give Priya access to my calendar", "share this calendar with the whole team", "let Jordan see when I'm free on this calendar", "invite someone new to view or edit my calendar", "grant a coworker access to this calendar for the first time".

### `google_calendar.update_acl_rule`

Change an existing sharing rule's access level on a calendar by rule id. Use when the user wants to upgrade or downgrade what someone who already has access can do, e.g. from reader to writer. Rule ids come from list_acl_rules. To grant access to someone new use share_calendar.

Class `write` (writes, no confirmation needed). Scopes `https://www.googleapis.com/auth/calendar.acls`. Calls `PATCH /calendars/{{params.calendar_id}}/acl/{{params.rule_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar id, or "primary" for the user's main calendar. |
| `role` | string, one of freeBusyReader, reader, writer, owner | **yes** | New access level. |
| `rule_id` | string | **yes** | Sharing rule id from list_acl_rules. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `role` | string |  |
| `scope` | object |  |
| `scope.type` | string |  |
| `scope.value` | string |  |

Also retrieved by: "upgrade Priya to be able to edit the calendar", "change what access Jordan has on this calendar", "make Sam an editor instead of just a viewer".

### `google_calendar.remove_acl_rule`

Revoke a person, group, or domain's access to a calendar entirely, by rule id. Use when the user wants to unshare, revoke, or remove someone's access to a calendar. Rule ids come from list_acl_rules. They lose access immediately with no notice.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `https://www.googleapis.com/auth/calendar.acls`. Calls `DELETE /calendars/{{params.calendar_id}}/acl/{{params.rule_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendar_id` | string | **yes** | Calendar id, or "primary" for the user's main calendar. |
| `rule_id` | string | **yes** | Sharing rule to revoke. |

Also retrieved by: "take away Jordan's access to this calendar", "revoke that person's access entirely", "unshare this calendar with them".

### `google_calendar.check_availability`

Check when one or more calendars are busy within a time window, without seeing the events themselves. Use when the user asks if someone is free, wants to find a meeting time, or asks about a scheduling conflict. Returns only busy intervals; read the actual events with list_events if titles or details are needed.

Class `read` (reads only). Scopes `https://www.googleapis.com/auth/calendar.freebusy`. Calls `POST /freeBusy`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `calendars` | array of object | **yes** | Calendars to check, each as an object with an id: primary for the user's own calendar, or another person's email. |
| `calendars[].id` | string | **yes** |  |
| `time_max` | string | **yes** | RFC 3339 timestamp for the end of the window. |
| `time_min` | string | **yes** | RFC 3339 timestamp for the start of the window. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `calendars` | object | Keyed by calendar id, each holding a busy array of {start, end} intervals. |
| `timeMax` | string |  |
| `timeMin` | string |  |

Also retrieved by: "is Sam free Thursday afternoon", "find a time that works for everyone", "when is there a scheduling conflict this week", "check if anyone's busy during that window".

### `google_calendar.list_calendar_colors`

List the color ids available for calendars and for events, with their background and foreground hex values. Use before setting a color_id on a calendar or event, or when the user asks what colors are available.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /colors`.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `calendar` | object | Keyed by color id, each holding {background, foreground} hex colors. |
| `event` | object | Keyed by color id, each holding {background, foreground} hex colors. |

Also retrieved by: "what colors can I use for events", "show me the color options for calendars", "what color ids are available".

### `google_calendar.list_settings`

List the user's own Calendar settings: default time zone, week start day, and time format. Use when the user asks what time zone or format their calendar is set to, not an individual event's time zone.

Class `read` (reads only). Scopes `https://www.googleapis.com/auth/calendar.settings.readonly`. Calls `GET /users/me/settings`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `page_token` | string | no | Token from a previous page's nextPageToken. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `items` | array of object |  |
| `items[].id` | string |  |
| `items[].value` | string |  |
| `nextPageToken` | string |  |

Also retrieved by: "what time zone is my calendar set to", "check my calendar preferences", "what format does my calendar use for time".

## Triggers

Triggers are app-initiated. They are not retrievable as tools and cannot be called; subscribe with `TriggersService.CreateSubscription` and events arrive as signed deliveries.

### `calendar_changed`

Fires when a watched calendar's events change: created, updated, or deleted. Carries no details of what changed, only the channel and resource ids; call list_events with a sync token afterward to read what's new.

Payload fields (anything the schema does not declare never reaches a subscriber):

| Field | Type | Notes |
| --- | --- | --- |
| `channelId` | string |  |
| `resourceId` | string |  |
| `resourceState` | string |  |

## Inbound webhooks

Providers post to `/webhooks/google_calendar`. Posts that fail verification are rejected before anything is stored, and the ingest path refuses every post while the secret variable is unset.

| Property | Value |
| --- | --- |
| Verification scheme | `token_query` |
| Shared secret | `AUTOMATON_GOOGLE_CALENDAR_WEBHOOK_TOKEN` (deployment environment) |
| Token query parameter | `token` |

Mappings are tried in order and the first match wins.

| Trigger | Matches when | Entity resolved from |
| --- | --- | --- |
| `calendar_changed` | header `X-Goog-Resource-State` = `exists` |  |