# Google Calendar

Google Calendar is a time management tool providing scheduling features, event reminders, and integration with email and other apps for streamlined organization

- **Category:** scheduling & booking
- **Auth:** OAUTH2
- **Composio Managed App Available?** Yes
- **Tools:** 46
- **Triggers:** 7
- **Slug:** `GOOGLECALENDAR`
- **Version:** 20260323_00

## Frequently Asked Questions

### How do I set up custom Google OAuth credentials for Google Calendar?

For a step-by-step guide on creating and configuring your own Google OAuth credentials with Composio, see [How to create OAuth2 credentials for Google Apps](https://composio.dev/auth/googleapps).

### Why am I seeing "App is blocked" when connecting Google Calendar?

The OAuth client is requesting scopes that Google hasn't verified for that client. This usually happens when you add extra scopes beyond the defaults.

Remove the additional scopes from your auth config, or create your own OAuth app and submit the scopes for verification. See [How to create OAuth2 credentials for Google Apps](https://composio.dev/auth/googleapps).

### Why am I getting "Google Calendar API has not been used in project" error?

When using custom OAuth credentials, the Google Calendar API must be enabled in the Google Cloud project that owns those credentials. Enable it in Google Cloud Console under APIs & Services, wait a few minutes, and retry.

### Why am I getting "Error 400: invalid_scope"?

The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/auth-configuration/programmatic-auth-configs).

### Why does the OAuth consent screen show "Composio" instead of my app?

By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).

### Why am I getting 401 errors on tool calls?

The user's access token is no longer valid. Common causes: the user revoked access, changed their password or 2FA, a Workspace admin policy changed, or Google's refresh token limit (~50 per account) was exceeded. Re-authenticating the user typically resolves this.

---

## Tools

### Delete ACL Rule

**Slug:** `GOOGLECALENDAR_ACL_DELETE`

Deletes an access control rule from a Google Calendar. Use when you need to remove sharing permissions for a user, group, or domain.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `rule_id` | string | Yes | ACL rule identifier. |
| `calendar_id` | string | Yes | Calendar identifier. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get ACL Rule

**Slug:** `GOOGLECALENDAR_ACL_GET`

Retrieves a specific access control rule for a calendar. Use when you need to check permissions for a specific user, group, or domain.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `rule_id` | string | Yes | ACL rule identifier. Format: 'scope_type:scope_value' or 'default'. Valid scope types: 'user' (email), 'group' (group email), 'domain' (domain name), 'default' (public access). Examples: 'user:john@example.com', 'group:team@example.com', 'domain:example.com', 'default'. Note: 'me' is NOT valid; use actual email/domain. The rule must exist - use GOOGLECALENDAR_LIST_ACL_RULES to find valid IDs. |
| `calendar_id` | string | Yes | Calendar identifier. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create ACL Rule

**Slug:** `GOOGLECALENDAR_ACL_INSERT`

Creates an access control rule for a calendar. Use when you need to grant sharing permissions to a user, group, or domain.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `role` | string ("none" | "freeBusyReader" | "reader" | "writer" | "owner") | Yes | The role assigned to the scope. Possible values: "none" - Provides no access; "freeBusyReader" - Provides read access to free/busy information; "reader" - Provides read access to the calendar; "writer" - Provides read and write access to the calendar; "owner" - Provides ownership of the calendar. |
| `scope` | object | Yes | The extent to which calendar access is granted by this ACL rule. Specifies who gets the access (user, group, domain, or default). |
| `calendar_id` | string | Yes | Calendar identifier. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword. |
| `send_notifications` | boolean | No | Whether to send notifications about the calendar sharing change. Optional. The default is true. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List ACL Rules

**Slug:** `GOOGLECALENDAR_ACL_LIST`

Retrieves the list of access control rules (ACLs) for a specified calendar, providing the necessary 'rule_id' values required for updating specific ACL rules.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pageToken` | string | No | Token specifying which result page to return. Optional. |
| `syncToken` | string | No | Token obtained from the nextSyncToken field returned on the last page of a previous list operation. It makes the result of this list operation contain only entries that have changed since then. Optional. The default is to retrieve all entries. |
| `calendarId` | string | Yes | Calendar identifier. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword. |
| `maxResults` | integer | No | Maximum number of entries returned on one result page. Optional. The default is 100. |
| `showDeleted` | boolean | No | Whether to include deleted ACLs in the result. Optional. The default is False. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Patch ACL Rule

**Slug:** `GOOGLECALENDAR_ACL_PATCH`

Updates an existing access control rule for a calendar using patch semantics (partial update). This allows modifying specific fields without affecting other properties. IMPORTANT: The ACL rule must already exist on the calendar. This action cannot create new rules. If you receive a 404 Not Found error, the rule does not exist - use ACL insert to create it first, or use ACL list to verify available rules. Each patch request consumes three quota units. For domain-type ACL rules, if PATCH fails with 500 error, this action will automatically fallback to UPDATE method.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `role` | string | No | The role assigned to the scope. Possible values are: "none" - Provides no access; "freeBusyReader" - Provides read access to free/busy information; "reader" - Provides read access to the calendar (private events appear but details are hidden); "writer" - Provides read and write access to the calendar (private events and details are visible); "owner" - Provides ownership of the calendar (all permissions of writer plus ability to see and manipulate ACLs). |
| `scope` | object | No | The extent to which calendar access is granted by this ACL rule. Optional for patch operations. Must include `type` (one of: 'user', 'group', 'domain', 'default') and `value` (email address or domain name) for all types except 'default'. |
| `rule_id` | string | Yes | ACL rule identifier of an existing rule. IMPORTANT: The rule must already exist on the calendar - this action cannot create new rules, only modify existing ones. Use the ACL list action to find existing rule IDs, or use the ACL insert action to create a new rule first. Format: 'type:value', such as 'user:email@example.com' or 'group:group@example.com'. |
| `calendar_id` | string | Yes | Calendar identifier. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword. |
| `send_notifications` | boolean | No | Whether to send notifications about the calendar sharing change. Note that there are no notifications on access removal. Optional. The default is True. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update ACL Rule

**Slug:** `GOOGLECALENDAR_ACL_UPDATE`

Updates an access control rule for the specified calendar.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `role` | string | Yes | The role assigned to the scope. Possible values are:  - "none" - Provides no access.  - "freeBusyReader" - Provides read access to free/busy information.  - "reader" - Provides read access to the calendar. Private events will appear to users with reader access, but event details will be hidden.  - "writer" - Provides read and write access to the calendar. Private events will appear to users with writer access, and event details will be visible.  - "owner" - Provides ownership of the calendar. This role has all of the permissions of the writer role with the additional ability to see and manipulate ACLs. |
| `rule_id` | string | Yes | ACL rule identifier. |
| `calendar_id` | string | Yes | Calendar identifier. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword. |
| `send_notifications` | boolean | No | Whether to send notifications about the calendar sharing change. Note that there are no notifications on access removal. Optional. The default is True. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Watch ACL Changes

**Slug:** `GOOGLECALENDAR_ACL_WATCH`

Tool to watch for changes to ACL resources. Use when you need to set up real-time notifications for access control list modifications on a calendar.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | A UUID or similar unique string that identifies this channel. |
| `type` | string | No | The type of delivery mechanism used for this channel. Valid values are "web_hook" or "webhook". |
| `token` | string | No | An arbitrary string delivered to the target address with each notification delivered over this channel. Optional. |
| `params` | object | No | Additional parameters controlling delivery channel behavior. Optional. |
| `address` | string | Yes | The address where notifications are delivered for this channel. |
| `pageToken` | string | No | Token specifying which result page to return. Optional. |
| `syncToken` | string | No | Token obtained from the nextSyncToken field returned on the last page of results from the previous list request. It makes the result of this list request contain only entries that have changed since then. All entries deleted since the previous list request will always be in the result set and it is not allowed to set showDeleted to False. Optional. |
| `calendarId` | string | Yes | Calendar identifier. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword. |
| `maxResults` | integer | No | Maximum number of entries returned on one result page. By default the value is 100 entries. The page size can never be larger than 250 entries. Optional. |
| `showDeleted` | boolean | No | Whether to include deleted ACLs in the result. Deleted ACLs are represented by role equal to 'none'. Deleted ACLs will always be included if syncToken is provided. Optional. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Batch Events

**Slug:** `GOOGLECALENDAR_BATCH_EVENTS`

Execute up to 1000 event mutations (create/patch/delete) in one Google Calendar HTTP batch request with per-item status/results. Use this to materially reduce round-trips for bulk operations like migrations, cleanup, or large-scale updates.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fail_fast` | boolean | No | If true, stop processing after the first batch containing any 4xx error (except 404 on DELETE). Default is false. |
| `operations` | array | Yes | List of batch operations to execute. Maximum 1000 operations per request. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Remove Calendar from List

**Slug:** `GOOGLECALENDAR_CALENDAR_LIST_DELETE`

Tool to remove a calendar from the user's calendar list. Use when you need to unsubscribe from or hide a calendar from the user's list.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `calendar_id` | string | Yes | Calendar identifier. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the 'primary' keyword. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Single Calendar by ID

**Slug:** `GOOGLECALENDAR_CALENDAR_LIST_GET`

Retrieves metadata for a SINGLE specific calendar from the user's calendar list by its calendar ID. This action requires a calendarId parameter and returns details about that one calendar only. NOTE: This does NOT list all calendars. To list all calendars in the user's calendar list, use GOOGLECALENDAR_CALENDAR_LIST_LIST instead.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `calendarId` | string | Yes | Required. The calendar identifier for the single calendar to retrieve. Use 'primary' for the primary calendar of the authenticated user, or provide a specific calendar ID (e.g., an email address or group calendar ID). To find calendar IDs, first use GOOGLECALENDAR_CALENDAR_LIST_LIST to list all calendars. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Insert Calendar into List

**Slug:** `GOOGLECALENDAR_CALENDAR_LIST_INSERT`

Inserts an existing calendar into the user's calendar list, making it visible in the UI. Calendars (e.g., newly created ones) won't appear in the list or UI until explicitly inserted.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The identifier of the calendar to insert. Must be a valid calendar ID in email format (e.g., ‘user@example.com’ for a user’s calendar or ‘calendarid@group.calendar.google.com’ for a shared calendar). Note: The ‘primary’ keyword is not supported for this operation - use the actual email address of the primary calendar instead. The calendar must exist and you must have appropriate access permissions. |
| `hidden` | boolean | No | Whether the calendar has been hidden from the list. Accepts only boolean values: true or false. If not specified, the API defaults to false. |
| `colorId` | string | No | The color of the calendar. This is an ID referring to an entry in the calendarCore color palette. |
| `selected` | boolean | No | Whether the calendar is selected and visible in the calendar list. Accepts only boolean values: true or false. If not specified, the API defaults to false. |
| `backgroundColor` | string | No | The background color of the calendar in the Web UI. (Hexadecimal color code) |
| `foregroundColor` | string | No | The foreground color of the calendar in the Web UI. (Hexadecimal color code) |
| `summaryOverride` | string | No | The summary that the authenticated user has set for this calendar. |
| `color_rgb_format` | boolean | No | Whether to use the foregroundColor and backgroundColor fields to write the calendar colors (RGB). If this feature is used, the index-based colorId field will be set to the best matching option automatically. Optional. The default is False. |
| `defaultReminders` | array | No | The default reminders that the authenticated user has for this calendar. |
| `notificationSettings` | object | No | The notifications that the authenticated user is receiving for this calendar. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Patch Calendar List Entry

**Slug:** `GOOGLECALENDAR_CALENDAR_LIST_PATCH`

Updates an existing calendar on the user's calendar list using patch semantics. This method allows partial updates, modifying only the specified fields.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `hidden` | boolean | No | Whether calendar is hidden. |
| `colorId` | string | No | ID for calendar color from colors endpoint. |
| `selected` | boolean | No | Whether calendar content shows in UI. |
| `calendar_id` | string | Yes | Calendar identifier. To retrieve calendar IDs call the calendarList.list method. Use "primary" keyword for the currently logged in user's primary calendar. |
| `colorRgbFormat` | boolean | No | Whether to use RGB for foreground/background colors. |
| `backgroundColor` | string | No | Hex color for calendar background. |
| `foregroundColor` | string | No | Hex color for calendar foreground. |
| `summaryOverride` | string | No | User-set summary for the calendar. |
| `defaultReminders` | array | No | List of default reminders. |
| `notificationSettings` | object | No | Notification settings for the calendar. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Calendar List Entry

**Slug:** `GOOGLECALENDAR_CALENDAR_LIST_UPDATE`

Updates a calendar list entry's display/subscription settings (color, visibility, reminders, selection) for the authenticated user — does not modify the underlying calendar resource (title, timezone, etc.). To modify the calendar itself, use GOOGLECALENDAR_CALENDARS_UPDATE.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `hidden` | boolean | No | Whether calendar is hidden. |
| `colorId` | string | No | ID for calendar color from colors endpoint. |
| `selected` | boolean | No | Whether calendar content shows in UI. |
| `calendar_id` | string | Yes | Calendar identifier. Must be an actual calendar ID (e.g., "examplecalendar@group.calendar.google.com" or "c_abc123...@group.calendar.google.com"). To retrieve valid calendar IDs, use the GOOGLECALENDAR_LIST_CALENDARS action first. The "primary" alias is not valid for calendarList.update. |
| `colorRgbFormat` | boolean | No | Whether to use RGB for foreground/background colors. |
| `backgroundColor` | string | No | Hex color for calendar background. |
| `foregroundColor` | string | No | Hex color for calendar foreground. |
| `summaryOverride` | string | No | User-set summary for the calendar. |
| `defaultReminders` | array | No | List of default reminders. |
| `notificationSettings` | object | No | Notification settings for the calendar. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Watch Calendar List

**Slug:** `GOOGLECALENDAR_CALENDAR_LIST_WATCH`

Watch for changes to CalendarList resources using push notifications. Use this to receive real-time updates when calendar list entries are modified.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | A UUID or similar unique string that identifies this channel. Maximum 64 characters. |
| `type` | string | Yes | The type of delivery mechanism used for this channel. Must be "web_hook" or "webhook". |
| `token` | string | No | An arbitrary string delivered to the target address with each notification. Maximum 256 characters. Used for channel verification and message routing. |
| `params` | object | No | Additional parameters controlling delivery channel behavior. |
| `address` | string | Yes | The HTTPS URL where notifications are delivered for this channel. Must have a valid SSL certificate. |
| `expiration` | integer | No | Unix timestamp in milliseconds indicating when the API should stop sending notifications. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Calendar

**Slug:** `GOOGLECALENDAR_CALENDARS_DELETE`

Deletes a secondary calendar that you own or have delete permissions on. Deletion is permanent and irreversible — verify the correct calendar_id before calling. You cannot delete your primary calendar or calendars you only have read/write access to. Use calendarList.list to find calendars with owner accessRole. For primary calendars, use calendars.clear instead. Parallel calls may trigger userRateLimitExceeded; sequence bulk deletions.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `calendar_id` | string | Yes | Calendar identifier for a secondary calendar you own or have delete permissions on. Use calendarList.list to find deletable calendar IDs (look for accessRole "owner"). Primary calendars cannot be deleted; use the Clear Calendar action instead. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Calendar

**Slug:** `GOOGLECALENDAR_CALENDARS_UPDATE`

Full PUT-style update that overwrites all calendar metadata fields; unspecified optional fields are cleared. Use GOOGLECALENDAR_PATCH_CALENDAR to update only a subset of fields. Mutates the underlying calendar resource (title, description, timeZone, etc.); use GOOGLECALENDAR_CALENDAR_LIST_UPDATE to change per-user display properties like color.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `summary` | string | Yes | Title of the calendar. Must be a non-empty string; passing an empty string clears the calendar title. |
| `location` | string | No | Geographic location of the calendar as free-form text. Optional. |
| `timeZone` | string | No | The time zone of the calendar. (Formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich".) Optional. |
| `calendarId` | string | Yes | Calendar identifier. Use 'primary' to update the primary calendar of the currently logged in user, or provide a specific calendar ID (typically in email format like 'abc123@group.calendar.google.com'). To retrieve calendar IDs call the calendarList.list method. IMPORTANT: This is NOT the calendar's display name/title. NOTE: For better performance, prefer providing the actual calendar ID instead of 'primary', as the 'primary' alias requires an additional API call to resolve. |
| `description` | string | No | Description of the calendar. Optional. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Stop Channel

**Slug:** `GOOGLECALENDAR_CHANNELS_STOP`

Tool to stop watching resources through a notification channel. Use when you need to discontinue push notifications for a specific channel subscription.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | A UUID or similar unique string that identifies this channel. |
| `token` | string | No | An arbitrary string delivered to the target address with each notification delivered over this channel. Optional. |
| `resourceId` | string | Yes | An opaque ID that identifies the resource being watched on this channel. Stable across different API versions. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Clear Calendar

**Slug:** `GOOGLECALENDAR_CLEAR_CALENDAR`

Clears a primary calendar by deleting all events from it. The calendar itself is preserved; only its events are removed. Primary calendars cannot be deleted entirely.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `calendar_id` | string | Yes | Calendar identifier. To retrieve calendar IDs call the `calendarList.list` method. If you want to access the primary calendar of the currently logged in user, use the "`primary`" keyword. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Color Definitions

**Slug:** `GOOGLECALENDAR_COLORS_GET`

Returns the color definitions for calendars and events. Use when you need to retrieve the available color palette for styling calendars or events.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Event

**Slug:** `GOOGLECALENDAR_CREATE_EVENT`

Create a Google Calendar event using start_datetime plus duration fields. The organizer is added as an attendee unless exclude_organizer is True. By default adds Google Meet link (works for Workspace, gracefully falls back for personal Gmail). Attendees can be email strings (required) or objects with email and optional fields. No conflict checking is performed; use GOOGLECALENDAR_FREE_BUSY_QUERY to detect overlaps before creating. Returns event id and htmlLink nested under data.response_data. Example: { "start_datetime": "2025-01-16T13:00:00", "timezone": "America/New_York", "event_duration_hour": 1, "event_duration_minutes": 30, "summary": "Client sync", "attendees": ["required@example.com", {"email": "optional@example.com", "optional": true}] }

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `summary` | string | No | Summary (title) of the event. |
| `location` | string | No | Geographic location of the event as free-form text. |
| `timezone` | string | No | IANA timezone name from the timezone database (e.g., 'America/New_York', 'Europe/London', 'Asia/Jerusalem', 'UTC'). Required if datetime is naive. For recurring events, start and end must include a timeZone. If not provided, UTC is used. If datetime includes timezone info (Z or offset), this field is optional and defaults to UTC. IMPORTANT: Must be a valid IANA timezone identifier. Values like 'EST', 'PST', 'ISRAEL TIME', or other abbreviations are NOT valid IANA timezone names. |
| `attendees` | array | No | List of attendees. Each attendee can be either: (1) A string email address (e.g., 'user@example.com'), or (2) An object with 'email' (required), 'optional' (boolean, default false), 'displayName' (string), 'comment' (string), 'additionalGuests' (integer), and 'resource' (boolean). To mark an attendee as optional (not required), use object format: {'email': 'user@example.com', 'optional': true}. IMPORTANT: Only valid email addresses are accepted. Plain names cannot be used. |
| `eventType` | string ("birthday" | "default" | "focusTime" | "outOfOffice" | "workingLocation") | No | Type of the event, immutable post-creation. 'workingLocation' (REQUIRES Google Workspace Enterprise). Note: 'fromGmail' events cannot be created via API. |
| `recurrence` | array | No | List of RRULE, EXRULE, RDATE, EXDATE lines for recurring events. Supported frequencies: DAILY, WEEKLY, MONTHLY, YEARLY. For recurring events, start.timeZone and end.timeZone must be present. UNTIL values follow RFC 5545: date-only (YYYYMMDD) for all-day events, or UTC datetime with Z suffix (YYYYMMDDTHHMMSSZ) for timed events. UNTIL values with time but missing Z suffix are auto-corrected. Provide an empty list to remove recurrence so the event becomes non-recurring. |
| `visibility` | string ("default" | "public" | "private" | "confidential") | No | Event visibility: 'default', 'public', 'private', or 'confidential'. |
| `calendar_id` | string | No | Calendar identifier. Use 'primary' (recommended) for the user's main calendar. Alternatively, use a calendar ID from the user's accessible calendar list. Calendar IDs look like email addresses (e.g., 'xyz@group.calendar.google.com' for shared calendars). Important: Arbitrary email addresses will NOT work - the calendar must exist in the user's calendar list with appropriate access permissions. Use GOOGLECALENDAR_LIST_CALENDARS to retrieve valid calendar IDs. |
| `description` | string | No | Description of the event. Can contain HTML. Optional. Must be omitted for 'birthday' event type. |
| `end_datetime` | string | No | Event end time in ISO 8601 format: YYYY-MM-DDTHH:MM:SS. When provided, this parameter takes precedence over event_duration_hour and event_duration_minutes. If not provided, the end time is calculated using start_datetime + duration. Must be after start_datetime. Fractional seconds and timezone info will be automatically stripped if provided. Examples: '2025-01-16T14:30:00', '2025-01-16T14:30'. |
| `send_updates` | boolean | No | Defaults to True. Whether to send updates to the attendees. |
| `transparency` | string ("opaque" | "transparent") | No | 'opaque' (busy) or 'transparent' (available). |
| `start_datetime` | string | Yes | REQUIRED. Event start time in ISO 8601 format: YYYY-MM-DDTHH:MM:SS. IMPORTANT: Natural language expressions like 'tomorrow', 'next Monday', '2pm tomorrow' are NOT supported and will be rejected. You must provide the exact date and time in ISO format. Fractional seconds (e.g., .000) and timezone info (Z, +, -) will be automatically stripped if provided. Examples: '2025-01-16T13:00:00', '2025-01-16T13:00'. |
| `guestsCanModify` | boolean | No | If True, guests can modify the event. |
| `exclude_organizer` | boolean | No | If True, the organizer will NOT be added as an attendee. Default is False (organizer is included). |
| `birthdayProperties` | object | No | Properties for birthday events. |
| `create_meeting_room` | boolean | No | Defaults to True. When True, for CREATE operations creates a Google Meet link; for UPDATE operations preserves existing conference data if present, or adds a new Meet link if none exists. Google Workspace accounts will successfully receive a Meet link. Personal Gmail accounts and other unsupported accounts will gracefully fallback to creating an event without a Meet link when conference creation fails. Set to False to skip Meet link operations (won't create new or modify existing conference data). The fallback ensures event creation succeeds even when conference features are unavailable due to account limitations. |
| `event_duration_hour` | integer | No | Number of hours for the event duration. Supports multi-day events (e.g., 240 hours = 10 days). For durations under 1 hour, use event_duration_minutes instead. Ignored if end_datetime is provided. |
| `extended_properties` | object | No | Extended properties of the event for storing custom metadata. Contains 'private' (visible only on this calendar) and/or 'shared' (visible to all attendees) dictionaries mapping string keys to string values. Example: {'private': {'key1': 'value1'}, 'shared': {'key2': 'value2'}} |
| `focusTimeProperties` | object | No | Properties for focusTime events. REQUIRES Google Workspace Enterprise account with Focus Time feature enabled. |
| `guestsCanInviteOthers` | boolean | No | Whether attendees other than the organizer can invite others to the event. |
| `outOfOfficeProperties` | object | No | Properties for outOfOffice events. |
| `event_duration_minutes` | integer | No | Duration in minutes (0-59 ONLY). NEVER use 60+ minutes - use event_duration_hour=1 instead. Maximum value is 59. Combined duration (hours + minutes) must be greater than 0. Ignored if end_datetime is provided. |
| `guestsCanSeeOtherGuests` | boolean | No | Whether attendees other than the organizer can see who the event's attendees are. |
| `workingLocationProperties` | object | No | Properties for workingLocation events. REQUIRES Google Workspace Enterprise.  Constraints discovered from testing: - Must set transparency='transparent' and visibility='public' - Description must be omitted - Depending on 'type', include one of 'homeOffice', 'officeLocation', or 'customLocation' |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete event

**Slug:** `GOOGLECALENDAR_DELETE_EVENT`

Deletes a specified event by `event_id` from a Google Calendar (`calendar_id`); idempotent — a 404 for an already-deleted event is a no-op. Bulk deletions may trigger `rateLimitExceeded` or `userRateLimitExceeded`; cap concurrency to 5–10 requests and apply exponential backoff.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `event_id` | string | Yes | Unique identifier of the event to delete. For standalone events, use the base event ID (e.g., 'abc123def456'). For recurring event instances, use the instance ID format 'baseEventId_YYYYMMDDTHHMMSSZ' (e.g., 'abc123def456_20260522T093000Z') where the timestamp suffix represents the instance's original start time in UTC. Instance IDs can be obtained from the EVENTS_INSTANCES action. To delete ALL occurrences of a recurring event, use the base event ID without the timestamp suffix. Must be the internal API identifier from a prior API response — UI-visible identifiers, URL-encoded variants, or shortened IDs are invalid and cause 404/validation errors. |
| `calendar_id` | string | No | Identifier of the Google Calendar (e.g., email address, specific ID, or 'primary' for the authenticated user's main calendar) from which the event will be deleted. Read-only or subscribed calendars (calendars not owned by the authenticated user) return 403 on deletion attempts. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create a calendar

**Slug:** `GOOGLECALENDAR_DUPLICATE_CALENDAR`

Creates a new, empty Google Calendar with the specified title (summary). Newly created calendars default to UTC timezone; use GOOGLECALENDAR_PATCH_CALENDAR afterward to set the desired timeZone if needed.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `summary` | string | Yes | Title for the new Google Calendar to be created. Required and must be a non-empty string. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Event

**Slug:** `GOOGLECALENDAR_EVENTS_GET`

Retrieves a SINGLE event by its unique event_id (REQUIRED). This action does NOT list or search events - it fetches ONE specific event when you already know its ID. If you want to list events within a time range, search for events, or filter by criteria like time_min/time_max, use GOOGLECALENDAR_EVENTS_LIST instead.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `event_id` | string | Yes | REQUIRED. The unique identifier of the specific event to retrieve. You must already know this ID (e.g., from a previous EVENTS_LIST call or event creation response). This action fetches ONE event by ID - it cannot list or search events. To find events by time range or search criteria, use GOOGLECALENDAR_EVENTS_LIST instead. |
| `time_zone` | string | No | Time zone used in the response. If not specified, the calendar's time zone is used. |
| `calendar_id` | string | No | Identifier of the Google Calendar (e.g., email address, specific ID, or 'primary' for the authenticated user's main calendar) from which to retrieve the event. |
| `max_attendees` | integer | No | Maximum number of attendees to include in the response. If there are more than the specified number, only the participant is returned. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Import Event

**Slug:** `GOOGLECALENDAR_EVENTS_IMPORT`

Tool to import an event as a private copy to a calendar. Use when you need to add an existing event to a calendar using its iCalUID. Only events with eventType='default' can be imported.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end` | object | Yes | The (exclusive) end time of the event. For all-day events, use 'date' field; for timed events, use 'dateTime' and 'timeZone' fields. |
| `start` | object | Yes | The (inclusive) start time of the event. For all-day events, use 'date' field; for timed events, use 'dateTime' and 'timeZone' fields. `dateTime` must be ISO 8601 format (e.g., `'2024-01-15T10:00:00'`); `timeZone` should match the calendar's timezone to avoid shifted times. |
| `source` | object | No | Source from which the event was created. |
| `status` | string | No | Status of the event. Possible values: 'confirmed', 'tentative', 'cancelled'. |
| `colorId` | string | No | The color of the event. This is an ID referring to an entry in the event colors definition. |
| `iCalUID` | string | Yes | Event unique identifier as defined in RFC5545. This is required to identify the event being imported. |
| `summary` | string | No | Title of the event. |
| `location` | string | No | Geographic location of the event as free-form text. |
| `sequence` | integer | No | Sequence number as per iCalendar. |
| `attendees` | array | No | The attendees of the event. |
| `reminders` | object | No | Information about the event's reminders for the authenticated user. |
| `recurrence` | array | No | List of RRULE, EXRULE, RDATE and EXDATE lines for a recurring event, as specified in RFC5545. Each string must include the full prefix (e.g., `'RRULE:FREQ=WEEKLY;BYDAY=MO'`); omitting the prefix causes a 400 error. |
| `visibility` | string | No | Visibility of the event. Possible values: 'default', 'public', 'private', 'confidential'. Default: 'default'. |
| `attachments` | array | No | File attachments for the event. |
| `calendar_id` | string | No | Calendar identifier. Use 'primary' for the logged-in user's primary calendar or the calendar's email address. |
| `description` | string | No | Description of the event. Can contain HTML. |
| `transparency` | string | No | Whether the event blocks time on the calendar. Possible values: 'opaque' (blocks time), 'transparent' (does not block time). Default: 'opaque'. |
| `guestsCanModify` | boolean | No | Whether attendees other than the organizer can modify the event. Default: False. |
| `extendedProperties` | object | No | Extended properties of the event. |
| `supportsAttachments` | boolean | No | Whether API client performing operation supports event attachments. Default: False. |
| `conferenceDataVersion` | integer | No | Version number of conference data supported by the API client. Version 0 assumes no conference data support and ignores conference data in the event's body. Version 1 enables copying of ConferenceData as well as for creating new conferences using the createRequest field of conferenceData. Default: 0. |
| `guestsCanInviteOthers` | boolean | No | Whether attendees other than the organizer can invite others to the event. Default: True. |
| `guestsCanSeeOtherGuests` | boolean | No | Whether attendees other than the organizer can see who the event's attendees are. Default: True. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Event Instances

**Slug:** `GOOGLECALENDAR_EVENTS_INSTANCES`

Returns instances of the specified recurring event. Use timeMin/timeMax to constrain the window; omitting bounds can return large result sets and is quota-heavy. On high-volume calls, 403 rateLimitExceeded or 429 too_many_requests may occur; apply exponential backoff (1s, 2s, 4s) before retrying.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `eventId` | string | Yes | REQUIRED. The ID of the recurring event whose instances you want to retrieve. You must first use GOOGLECALENDAR_FIND_EVENT or GOOGLECALENDAR_EVENTS_LIST to find recurring events and get their IDs. This action only works with recurring events that have a recurrence rule. |
| `timeMax` | string | No | Upper bound (exclusive) for an event's start time to filter by. Optional. The default is not to filter by start time. Must be an RFC3339 timestamp with mandatory time zone offset. |
| `timeMin` | string | No | Lower bound (inclusive) for an event's end time to filter by. Optional. The default is not to filter by end time. Must be an RFC3339 timestamp with mandatory time zone offset. |
| `timeZone` | string | No | Time zone used in the response. Optional. The default is the time zone of the calendar. |
| `pageToken` | string | No | Token specifying which result page to return. Optional. |
| `calendarId` | string | Yes | Calendar identifier. To retrieve calendar IDs call the `calendarList.list` method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword. |
| `maxResults` | integer | No | Maximum number of events returned on one result page. By default the value is 250 events. The page size can never be larger than 2500 events. Optional. |
| `showDeleted` | boolean | No | Whether to include deleted events (with status equals "cancelled") in the result. Cancelled instances of recurring events will still be included if `singleEvents` is False. Optional. The default is False. |
| `maxAttendees` | integer | No | The maximum number of attendees to include in the response. If there are more than the specified number of attendees, only the participant is returned. Optional. |
| `originalStart` | string | No | The original start time of the instance in the result. Optional. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Events

**Slug:** `GOOGLECALENDAR_EVENTS_LIST`

Returns events on the specified calendar. TIMEZONE WARNING: When using timeMin/timeMax with UTC timestamps (ending in 'Z'), the time window is interpreted in UTC regardless of the calendar's timezone. For example, querying '2026-01-19T00:00:00Z' to '2026-01-20T00:00:00Z' on a calendar in America/Los_Angeles (UTC-8) covers 2026-01-18 4pm to 2026-01-19 4pm local time, potentially missing events on the intended local date. To query for a specific local date, use timestamps with the appropriate timezone offset in timeMin/timeMax (e.g., '2026-01-19T00:00:00-08:00' for PST).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | No | Free text search terms to find events that match these terms in various fields. Optional. |
| `iCalUID` | string | No | Specifies an event ID in the iCalendar format to be provided in the response. Optional. Use this if you want to search for an event by its iCalendar ID. |
| `orderBy` | string | No | The order of the events returned in the result. Optional. The default is an unspecified, stable order. Acceptable values are: "startTime", "updated". When set to "startTime", singleEvents must be true. The action automatically sets singleEvents=true when orderBy='startTime'. |
| `timeMax` | string | No | Upper bound (exclusive) for an event's start time to filter by. Optional. If unset, no start-time upper bound is applied. Must be an RFC3339 timestamp with mandatory time zone offset (e.g., 2011-06-03T10:00:00-07:00 or 2011-06-03T10:00:00Z). Milliseconds may be provided but are ignored. If timeMin is set, timeMax must be greater than timeMin. TIMEZONE WARNING: If using UTC times (ending in 'Z') but the calendar is in a different timezone, the time window may not align with local calendar dates. For example, '2026-01-19T00:00:00Z' to '2026-01-20T00:00:00Z' covers 2026-01-18 4pm to 2026-01-19 4pm in America/Los_Angeles (UTC-8). To query a specific local date, use timestamps with the appropriate local timezone offset (e.g., '2026-01-19T00:00:00-08:00' for PST). NOTE: Natural language expressions like 'today', 'tomorrow', 'next week' are NOT supported. |
| `timeMin` | string | No | Lower bound (exclusive) for an event's end time to filter by. Optional. If unset, no end-time lower bound is applied. Must be an RFC3339 timestamp with mandatory time zone offset (e.g., 2011-06-03T10:00:00-07:00 or 2011-06-03T10:00:00Z). Milliseconds may be provided but are ignored. If timeMax is set, timeMin must be smaller than timeMax. TIMEZONE WARNING: If using UTC times (ending in 'Z') but the calendar is in a different timezone, the time window may not align with local calendar dates. For example, '2026-01-19T00:00:00Z' to '2026-01-20T00:00:00Z' covers 2026-01-18 4pm to 2026-01-19 4pm in America/Los_Angeles (UTC-8). To query a specific local date, use timestamps with the appropriate local timezone offset (e.g., '2026-01-19T00:00:00-08:00' for PST). NOTE: Natural language expressions like 'today', 'tomorrow', 'next week' are NOT supported. |
| `timeZone` | string | No | Time zone used in the response for formatting event times. Optional. Use an IANA time zone identifier (e.g., America/Los_Angeles). Defaults to the user's primary time zone. Offsets (e.g., '-03:00', 'UTC+0') and abbreviations (e.g., 'IST', 'PST') are invalid. NOTE: This parameter only affects how event times are displayed in the response. It does NOT change how timeMin/timeMax filtering is interpreted. To query a specific local date, use timestamps with the appropriate timezone offset directly in timeMin/timeMax (e.g., '2026-01-19T00:00:00-08:00'). |
| `pageToken` | string | No | Opaque pagination token from a previous response's nextPageToken field. Must be the exact string returned by the API - do not use placeholder values like 'NEXT', 'next', '1', '2', etc. Omit this parameter entirely for the first page of results. Optional. |
| `syncToken` | string | No | Token from nextSyncToken to return only entries changed since the last list. Cannot be combined with iCalUID, orderBy, privateExtendedProperty, q, sharedExtendedProperty, timeMin, timeMax, or updatedMin. Deletions since the previous list are always included; showDeleted cannot be false in this mode. The action automatically removes conflicting parameters when syncToken is provided. |
| `calendarId` | string | No | Calendar identifier. Use "primary" for the user's main calendar, or a calendar ID from the user's accessible calendar list. Arbitrary email addresses will NOT work - the calendar must exist in the user's calendar list. Use GOOGLECALENDAR_LIST_CALENDARS to retrieve valid calendar IDs. Defaults to "primary". Empty strings will be treated as "primary". Do NOT use Composio internal IDs like connectedAccountId (which start with "ca_") - these will be automatically replaced with "primary". |
| `eventTypes` | string | No | Event types to return. Optional. Pass a single value only. If unset, returns all event types. Acceptable values are: "birthday", "default", "focusTime", "fromGmail", "outOfOffice", "workingLocation". |
| `maxResults` | integer | No | Maximum number of events returned on one result page. The number of events in the resulting page may be less than this value, or none at all, even if there are more events matching the query. Incomplete pages can be detected by a non-empty nextPageToken field in the response. By default the value is 250 events. The page size can never be larger than 2500 events. Optional. Must be >= 1 if provided. |
| `updatedMin` | string | No | Lower bound for an event's last modification time (RFC3339). When specified, entries deleted since this time are always included regardless of showDeleted. Optional. |
| `showDeleted` | boolean | No | Include cancelled events (status="cancelled"). Optional; default is false. This surfaces cancelled (soft-deleted) events, not items in the Trash. When syncToken or updatedMin is used, deletions since those markers are included regardless of showDeleted. Recurring interaction: if singleEvents=false and showDeleted=false, cancelled instances of a recurring series may still be included; if showDeleted=true and singleEvents=true, only single deleted instances (not parent series) are returned. |
| `maxAttendees` | integer | No | The maximum number of attendees to include in the response. If there are more than the specified number of attendees, only the participant is returned. Optional. Must be >= 1 if provided. |
| `singleEvents` | boolean | No | Whether to expand recurring events into instances and only return single one-off events and instances of recurring events. Optional. The default is False. |
| `alwaysIncludeEmail` | boolean | No | Deprecated and ignored. |
| `showHiddenInvitations` | boolean | No | Whether to include hidden invitations in the result. Optional. The default is False. Hidden invitations are events where your attendee entry has responseStatus='needsAction' and attendees[].self==true. When true, such invitations are included. |
| `sharedExtendedProperty` | string | No | Extended properties constraint specified as propertyName=value. Matches only shared properties. This parameter might be repeated multiple times to return events that match all given constraints. |
| `privateExtendedProperty` | string | No | Extended properties constraint specified as propertyName=value. Matches only private properties. This parameter might be repeated multiple times to return events that match all given constraints. |
| `composio_replaced_calendar_id` | string | No | Internal field to track if calendarId was replaced |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Events from All Calendars

**Slug:** `GOOGLECALENDAR_EVENTS_LIST_ALL_CALENDARS`

Return a unified event list across all calendars in the user's calendar list for a given time range. Use when you need a single view of all events across multiple calendars. An inverted or incorrect time range silently returns empty results rather than an error. An empty `items` list means no events matched the filters—adjust `time_min`, `time_max`, or `q` before concluding no events exist.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | No | Free text search terms to find events that match these terms in any field, except for extended properties. Optional. |
| `time_max` | string | Yes | Upper bound (exclusive) for an event's start time to filter by. Must be an RFC3339 timestamp with mandatory time zone offset (e.g., 2011-06-03T10:00:00-07:00 or 2011-06-03T10:00:00Z). If timezone offset is missing, UTC (Z) will be automatically appended. Required. |
| `time_min` | string | Yes | Lower bound (inclusive) for an event's end time to filter by. Must be an RFC3339 timestamp with mandatory time zone offset (e.g., 2011-06-03T10:00:00-07:00 or 2011-06-03T10:00:00Z). If timezone offset is missing, UTC (Z) will be automatically appended. Required. |
| `event_types` | array | No | Event types to return. Optional. |
| `calendar_ids` | array | No | Optional list of specific calendar IDs to query. If not provided, all calendars from the user's calendar list will be queried. |
| `show_deleted` | boolean | No | Whether to include deleted events (with status equals 'cancelled') in the result. Optional. The default is False. |
| `summary_only` | boolean | No | When True (default), returns only the compact summary_view suitable for agent consumption, omitting the large events array to reduce token usage. When False, returns both summary_view and the full detailed events array. Recommended to keep True unless full event details are explicitly needed. |
| `single_events` | boolean | No | Whether to expand recurring events into instances and only return single one-off events and instances of recurring events. Optional. The default is True. |
| `max_results_per_calendar` | integer | No | Maximum number of events returned per calendar. Optional. If not provided, defaults to the API's default (250). Results may be paginated; follow `nextPageToken` in the response until absent to retrieve the complete event list. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Move Event

**Slug:** `GOOGLECALENDAR_EVENTS_MOVE`

Moves an event to another calendar, i.e., changes an event's organizer.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `event_id` | string | Yes | Event identifier. To retrieve event identifiers call the events.list method. |
| `calendar_id` | string | Yes | Calendar identifier of the source calendar. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword. |
| `destination` | string | Yes | Calendar identifier of the destination calendar. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword. |
| `send_updates` | string ("all" | "externalOnly" | "none") | No | Options for who should receive notifications about event changes. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Watch Events

**Slug:** `GOOGLECALENDAR_EVENTS_WATCH`

Watch for changes to Events resources. Watch channels expire; persist the channel `id` per `calendarId` to re-establish watches after expiration or restarts.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | A UUID or similar unique string that identifies this channel. |
| `type` | string | No | The type of delivery mechanism used for this channel. |
| `token` | string | No | An arbitrary string delivered to the target address with each notification delivered over this channel. Optional. |
| `params` | object | No | Additional parameters controlling delivery channel behavior. Optional. |
| `address` | string | Yes | The address where notifications are delivered for this channel. Must be a publicly accessible HTTPS URL; http:// or localhost URLs will not receive notifications. |
| `payload` | boolean | No | A Boolean value to indicate whether payload is wanted. Optional. |
| `calendarId` | string | Yes | Calendar identifier. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Find event

**Slug:** `GOOGLECALENDAR_FIND_EVENT`

Finds events in a specified Google Calendar using text query, time ranges (event start/end, last modification), and event types. Ensure `timeMin` is not chronologically after `timeMax` if both are provided. Results may span multiple pages; always follow `nextPageToken` until absent to avoid silently missing events. Validate the correct match from results by checking summary, start.dateTime, and organizer.email before using event_id for mutations. An empty `items` array means no events matched — widen filters rather than treating it as an error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | No | Free-text search terms to find events. This query is matched against various event fields including summary, description, location, attendees' details (displayName, email), and organizer's details. Cannot search by event_id. Performs full-text match (not exact); broad terms may return unrelated events. For person-based matching, prefer attendees[].email over display names. If results appear incomplete, use GOOGLECALENDAR_EVENTS_LIST with client-side filtering. |
| `timeMax` | string | No | Upper bound (exclusive) for an event's start time to filter by. Only events starting before this time are included. Accepts multiple formats: 1. RFC3339 timestamp (e.g., '2024-12-06T13:00:00Z') 2. Comma-separated date/time parts (e.g., '2024,12,06,13,00,00') 3. Simple datetime string (e.g., '2024-12-06 13:00:00') Set to the first instant after the desired period to avoid missing boundary events, especially all-day events (date-only fields). Overly wide ranges expand many recurring instances, causing large payloads and high latency — constrain to the minimum required window. |
| `timeMin` | string | No | Lower bound (exclusive) for an event's end time to filter by. Only events ending after this time are included. Accepts multiple formats: 1. RFC3339 timestamp (e.g., '2024-12-06T13:00:00Z') 2. Comma-separated date/time parts (e.g., '2024,12,06,13,00,00') 3. Simple datetime string (e.g., '2024-12-06 13:00:00') RFC3339 timestamps must include explicit timezone offsets; missing or mismatched offsets can silently exclude matching events. To align with the calendar's timezone, retrieve it via GOOGLECALENDAR_GET_CALENDAR. |
| `order_by` | string | No | Order of events: 'startTime' (ascending by start time) or 'updated' (ascending by last modification time). Note: 'startTime' requires single_events=true. Use 'updated' if you need to include recurring masters (e.g., cancelled series). |
| `page_token` | string | No | Token from a previous response's `nextPageToken` to fetch the subsequent page of results. Always follow every `nextPageToken` until absent; skipping pagination silently omits events on busy calendars. |
| `calendar_id` | string | No | Identifier of the Google Calendar to query. IMPORTANT: This must be a valid calendar identifier, NOT a calendar name/title. Valid formats are: 'primary' (the authenticated user's primary calendar), an email address (e.g., 'user@example.com'), or a calendar ID (e.g., 'abc123xyz@group.calendar.google.com'). To find the calendar ID for a named calendar, first use the List Calendars action (GOOGLECALENDAR_LIST_CALENDARS) to retrieve all available calendars with their IDs. 'primary' searches only the authenticated user's primary calendar; to search all calendars, retrieve each ID via GOOGLECALENDAR_LIST_CALENDARS and query separately. |
| `event_types` | array | No | Event types to include. Supported values: 'birthday', 'default', 'focusTime', 'outOfOffice', 'workingLocation'. |
| `max_results` | integer | No | Maximum number of events per page (1-2500). |
| `updated_min` | string | No | Lower bound (exclusive) for an event's last modification time to filter by. Only events updated after this time are included. When specified, events deleted since this time are also included, regardless of the `show_deleted` parameter. Accepts multiple formats: 1. RFC3339 timestamp (e.g., '2024-12-06T13:00:00Z') 2. Comma-separated date/time parts (e.g., '2024,12,06,13,00,00') 3. Simple datetime string (e.g., '2024-12-06 13:00:00') |
| `show_deleted` | boolean | No | Include events whose status is 'cancelled'. This surfaces cancelled/deleted events, not a separate 'trash' view. Behavior with recurring events: when single_events=true, only individual cancelled instances are returned (the recurring master is omitted); to include cancelled recurring masters, set single_events=false. If updated_min is provided, events deleted since that time are included regardless of this flag. |
| `single_events` | boolean | No | When true, recurring event series are expanded into their individual instances. When false, only the recurring master events are returned. Note: Ordering by 'startTime' requires singleEvents=true. For large calendars, it is strongly recommended to specify both timeMin and timeMax to limit the expansion window and improve performance. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Find free slots

**Slug:** `GOOGLECALENDAR_FIND_FREE_SLOTS`

Finds both free and busy time slots in Google Calendars for specified calendars within a defined time range. If `time_min` is not provided, defaults to the current timestamp in the specified timezone. If `time_max` is not provided, defaults to 23:59:59 of the day specified in `time_min` (if provided), otherwise defaults to 23:59:59 of the current day in the specified timezone. Returns busy intervals and calculates free slots by finding gaps between busy periods; `time_min` must precede `time_max` if both are provided. This action retrieves free and busy time slots for the specified calendars over a given time period. It analyzes the busy intervals from the calendars and provides calculated free slots based on the gaps in the busy periods. Returned free slots are unfiltered by duration; callers must filter intervals to those fully containing the required meeting length. No event metadata (titles, descriptions, links) is returned; use GOOGLECALENDAR_EVENTS_LIST for event details.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `items` | array | No | List of calendar identifiers to query for free/busy information. Pass as a simple list of strings, e.g., ['primary'] or ['primary', 'user@example.com']. Valid values include: 'primary' (authenticated user's main calendar), calendar IDs from the user's calendar list (typically ending in @group.calendar.google.com), or email addresses of users whose free/busy information you want to query. The FreeBusy API will return error information for any calendars that are not accessible or invalid in the response under the 'errors' key for each calendar. Calendars omitted from `items` or inaccessible are treated as free (not unknown), which can silently produce incorrect availability results. |
| `time_max` | string | No | End datetime for the query interval. Accepts ISO, comma-separated, or simple datetime formats. If provided without an explicit timezone, it is interpreted in the specified `timezone`. If not provided, defaults to 23:59:59 of the day specified in `time_min` (if provided), otherwise defaults to 23:59:59 of the current day in the specified `timezone`. Maximum span between time_min and time_max is approximately 90 days per Google Calendar freeBusy API limit. `time_max` is exclusive; to cover a full day, set `time_max` to 00:00:00 of the following day in the target timezone rather than 23:59:59. |
| `time_min` | string | No | Start datetime for the query interval. Accepts ISO, comma-separated, or simple datetime formats. If provided without an explicit timezone, it is interpreted in the specified `timezone`. If not provided, defaults to the current timestamp in the specified `timezone` to ensure only future/bookable slots are returned. Maximum span between time_min and time_max is approximately 90 days per Google Calendar freeBusy API limit. |
| `timezone` | string | No | IANA timezone identifier (e.g., 'America/New_York', 'Europe/London', 'Asia/Tokyo'). Determines how naive `time_min`/`time_max` are interpreted and the timezone used in the response for `timeMin`, `timeMax`, busy periods, and calculated free slots. Note: 'local' is not supported; use a specific IANA timezone name. |
| `group_expansion_max` | integer | No | Maximum calendar identifiers to return for a single group. Must be between 1 and 100 (inclusive). Values exceeding 100 will be rejected. |
| `calendar_expansion_max` | integer | No | Maximum calendars for which FreeBusy information is provided. Must be between 1 and 50 (inclusive). Values exceeding 50 will be rejected. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Query Free/Busy Information (Deprecated)

**Slug:** `GOOGLECALENDAR_FREE_BUSY_QUERY`

DEPRECATED: Use GOOGLECALENDAR_FIND_FREE_SLOTS instead (though this tool provides wider secondary/shared calendar coverage). Returns opaque busy intervals only—no event titles or details; use GOOGLECALENDAR_EVENTS_LIST when event details are needed.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `items` | array | Yes | List of calendars and/or groups to query. Accepts either strings (e.g., ['primary', 'user@example.com']) or objects with an 'id' field (e.g., [{'id': 'primary'}]). String values are automatically converted to the proper format. Only calendars with at least freeBusyReader-level access are queried; omitting shared/secondary calendars can hide real conflicts. Batch all attendees into one call to avoid 403 rateLimitExceeded or 429 tooManyRequests errors. |
| `timeMax` | string | Yes | The end of the interval for the query formatted as per RFC3339. Exclusive bound; must be greater than timeMin. Keep the timeMin–timeMax window within ~90 days; larger spans may return empty or degraded results. |
| `timeMin` | string | Yes | The start of the interval for the query formatted as per RFC3339. Must be strictly less than timeMax. For full-day windows, use local 00:00 in the target timezone to avoid DST/off-by-one errors. |
| `timeZone` | string | No | Time zone used in the response. Optional. The default is UTC. Defaults to UTC, which skews working-hours analysis for users in other timezones; always supply a valid IANA timezone (e.g., 'America/New_York'). |
| `groupExpansionMax` | integer | No | Maximal number of calendar identifiers to be provided for a single group. Optional. An error is returned for a group with more members than this value. Maximum value is 100. |
| `calendarExpansionMax` | integer | No | Maximal number of calendars for which FreeBusy information is to be provided. Optional. Maximum value is 50. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Google Calendar

**Slug:** `GOOGLECALENDAR_GET_CALENDAR`

Retrieves a specific Google Calendar, identified by `calendar_id`, to which the authenticated user has access. Response includes `timeZone` (IANA format, e.g., 'America/Los_Angeles') — use it directly when constructing `timeMin`/`timeMax` in other tools to avoid DST errors. An empty `defaultReminders` list is valid (no defaults configured). Insufficient `accessRole` may omit fields like `defaultReminders` and `colorId`.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `calendar_id` | string | No | Identifier of the Google Calendar to retrieve. Must be 'primary' (the default) for the user's main calendar, or an email-like identifier (e.g., 'user@example.com' or 'en.usa#holiday@group.v.calendar.google.com'). IMPORTANT: Calendar display names/titles (e.g., 'Work', 'Vacation') are NOT valid identifiers and will result in errors. To find a calendar's ID, use the LIST_CALENDARS action which returns the 'id' field for each calendar. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Calendar Profile (Deprecated)

**Slug:** `GOOGLECALENDAR_GET_CALENDAR_PROFILE`

DEPRECATED: Use CalendarListGet instead. Tool to retrieve the authenticated user's primary calendar profile. Use when you need to get information about the user's main calendar, including timezone, settings, and preferences.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get current date and time

**Slug:** `GOOGLECALENDAR_GET_CURRENT_DATE_TIME`

Gets the current date and time, allowing for a specific timezone offset. Call this tool first before computing relative dates (e.g., 'tomorrow', 'next Monday') to avoid off-by-one-day errors across timezones.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `timezone` | string | No | Timezone specification. Accepts: (1) IANA timezone identifier (e.g., 'America/New_York', 'Asia/Kolkata', 'Europe/London') - RECOMMENDED, (2) Common timezone abbreviations (e.g., 'PST', 'EST', 'CST', 'GMT', 'UTC') - will be auto-converted to IANA, or (3) Numeric UTC offset in hours (e.g., -5, 5.5). Use positive values for east of UTC, negative for west. Default 0 is UTC. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Google Calendars

**Slug:** `GOOGLECALENDAR_LIST_CALENDARS`

Retrieves calendars from the user's Google Calendar list, with options for pagination and filtering. Loop through all pages using nextPageToken until absent to avoid missing calendars. Use the primary flag and accessRole field from the response to identify calendars — display names are not valid calendar_id values. Read access (listing) does not imply write OAuth scopes.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page_token` | string | No | Token for the page of results to return, from a previous response. |
| `sync_token` | string | No | Sync token from a previous list request to get only changed entries; showDeleted, showHidden, and pageToken are ignored if provided. Also ignores minAccessRole. An HTTP 410 Gone response means the token has expired; perform a full resync by omitting sync_token. |
| `max_results` | integer | No | Maximum number of calendars to return per page. Max 250. |
| `show_hidden` | boolean | No | Include calendars not typically shown in the UI. |
| `show_deleted` | boolean | No | Include deleted calendars in the result. |
| `min_access_role` | string | No | Minimum access role for calendars returned. Valid values are 'freeBusyReader', 'owner', 'reader', 'writer'. freeBusyReader calendars expose only free/busy slots — no event details and writes fail with 403. Omit this filter to include read-only calendars. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Calendar Settings (Deprecated)

**Slug:** `GOOGLECALENDAR_LIST_SETTINGS`

DEPRECATED: Use GOOGLECALENDAR_SETTINGS_LIST instead. Tool to return all user settings for the authenticated user. Use when you need to retrieve calendar settings.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pageToken` | string | No | Token for pagination to retrieve subsequent result pages |
| `maxResults` | integer | No | Maximum number of settings to return |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Patch Calendar

**Slug:** `GOOGLECALENDAR_PATCH_CALENDAR`

Partially updates (PATCHes) an existing Google Calendar, modifying only the fields provided. At least one of summary, description, location, or timezone must be provided. Empty strings for `description` or `location` clear them.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `summary` | string | No | New title for the calendar; cannot be an empty string when provided. At least one of summary, description, location, or timezone must be provided. |
| `location` | string | No | New geographic location of the calendar (e.g., 'Paris, France'). |
| `timezone` | string | No | New IANA Time Zone Database name for the calendar (e.g., 'Europe/Zurich', 'America/New_York'). Calendars duplicated via GOOGLECALENDAR_DUPLICATE_CALENDAR may default to UTC; set the correct timezone explicitly after duplication. |
| `calendar_id` | string | Yes | The unique identifier of the Google Calendar to update. Use 'primary' for the main calendar, or a calendar's unique ID (typically in email format like 'abc123@group.calendar.google.com'). IMPORTANT: This is NOT the calendar's display name/title - use GOOGLECALENDAR_LIST_CALENDARS to find the 'id' field for a calendar. |
| `description` | string | No | New description for the calendar. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Patch Event

**Slug:** `GOOGLECALENDAR_PATCH_EVENT`

Update specified fields of an existing event in a Google Calendar using patch semantics (array fields like `attendees` are fully replaced if provided); ensure the `calendar_id` and `event_id` are valid and the user has write access to the calendar.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `summary` | string | No | New title for the event. |
| `end_time` | string | No | New end time (RFC3339 timestamp, e.g., '2024-07-01T11:00:00-07:00'). Uses `timezone` if provided, otherwise UTC. For all-day events, use YYYY-MM-DD format (exclusive end date). Optional when updating start_time - the original event duration will be preserved if end_time is not specified. Must be strictly after `start_time`; mismatched or mixed formats cause HTTP 400 `timeRangeEmpty`. |
| `event_id` | string | Yes | The unique technical identifier of the event to update. IMPORTANT: This is NOT the event title/name. Event IDs are opaque strings typically base32hex encoded (5-1024 characters using lowercase a-v and digits 0-9). For recurring event instances, the ID format is 'baseEventId_YYYYMMDDTHHMMSSZ' with an underscore separator (e.g., 'abc123def456_20260115T100000Z'). To get an event ID, first use GOOGLECALENDAR_FIND_EVENT or GOOGLECALENDAR_EVENTS_LIST to search for events and retrieve their IDs. Use master event ID to update the entire recurring series; use instance ID to update only that occurrence — confirm scope before patching. |
| `location` | string | No | New geographic location (physical address or virtual meeting link). |
| `timezone` | string | No | IANA Time Zone Database name for start/end times (e.g., 'America/Los_Angeles'). Used if `start_time` and `end_time` are provided and not all-day dates; defaults to UTC if unset. Mismatched or missing timezone with offset timestamps silently shifts event to unintended wall-clock time. |
| `attendees` | array | No | List of valid email addresses for attendees (e.g., 'user@example.com'). Replaces existing attendees. Provide an empty list to remove all. |
| `start_time` | string | No | New start time (RFC3339 timestamp, e.g., '2024-07-01T10:00:00-07:00'). Uses `timezone` if provided, otherwise UTC. For all-day events, use YYYY-MM-DD format. When only start_time is provided without end_time, the event's original duration is preserved automatically. |
| `calendar_id` | string | Yes | Identifier of the calendar. Use 'primary' for the primary calendar of the logged-in user. To find other calendar IDs, use the `calendarList.list` method. Must be provided in snake_case format. |
| `description` | string | No | New description for the event; can include HTML. |
| `send_updates` | string ("all" | "externalOnly" | "none") | No | Whether to send update notifications to attendees. Uses default user behavior if unspecified. Set explicitly to avoid unintended notifications when removing attendees or making bulk updates. |
| `max_attendees` | integer | No | Maximum attendees in response; does not affect invited count. If more, response includes organizer only. Must be positive. |
| `rsvp_response` | string ("needsAction" | "declined" | "tentative" | "accepted") | No | RSVP response status for the authenticated user. Updates only the current user's response status without affecting other attendees. Note: RSVP is only supported for regular calendar events (eventType='default'); attempting to RSVP to focusTime, outOfOffice, birthday, or workingLocation events will result in an error. |
| `supports_attachments` | boolean | No | Client application supports event attachments. Set to `True` if so. |
| `conference_data_version` | integer | No | API client's conference data support version. Set to 1 to manage conference details (e.g., Google Meet links); 0 (default) ignores conference data. Setting to 1 enables reading/preserving conference data but does not generate a new Meet link — use GOOGLECALENDAR_UPDATE_EVENT with `create_meeting_room=true` to create one. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Quick Add Event

**Slug:** `GOOGLECALENDAR_QUICK_ADD`

Parses natural language text to quickly create a basic Google Calendar event with its title, date, and time, suitable for simple scheduling; does not support direct attendee addition or recurring events, and `calendar_id` must be valid if not 'primary'.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | string | No | Natural language input describing the event; Google Calendar parses this for event details like title, date, and time. |
| `calendar_id` | string | No | Identifier of the calendar for the event. Use 'primary' for the main calendar, or provide a specific calendar ID (e.g., email address). |
| `send_updates` | string ("all" | "externalOnly" | "none") | No | Controls whether email notifications about the event creation are sent to attendees. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Remove attendee from event

**Slug:** `GOOGLECALENDAR_REMOVE_ATTENDEE`

Removes an attendee from a specified event in a Google Calendar; the calendar and event must exist. Concurrent calls on the same event can overwrite attendee lists — apply changes sequentially per event.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `event_id` | string | Yes | Unique identifier of the event. For recurring events, target the master series ID or a specific instance ID; removing an attendee from one instance does not affect other instances in the series. |
| `calendar_id` | string | No | Identifier of the Google Calendar to which the event belongs; 'primary' signifies the user's main calendar. |
| `attendee_email` | string | Yes | Email address of the attendee to remove. Must match an attendee email present on the event. If no match is found, the attendee was already removed or was never on the event. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Calendar Setting

**Slug:** `GOOGLECALENDAR_SETTINGS_GET`

Tool to return a single user setting for the authenticated user. Use when you need to retrieve a specific calendar setting value.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `setting` | string | Yes | The identifier of the user setting to retrieve. Valid values include: autoAddHangouts, dateFieldOrder, defaultEventLength, format24HourTime, hideInvitations, hideWeekends, locale, remindOnRespondedEventsOnly, showDeclinedEvents, timezone, useKeyboardShortcuts, weekStart |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Settings

**Slug:** `GOOGLECALENDAR_SETTINGS_LIST`

Returns all user settings for the authenticated user. Results include multiple settings keyed by id (e.g., `timeZone`); locate a specific setting by its `id` field. `timeZone` values are IANA identifiers (e.g., `America/New_York`) — use directly in datetime and event logic; align with `timeZone` from GOOGLECALENDAR_GET_CALENDAR for consistent notification times.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pageToken` | string | No | Token specifying which result page to return. |
| `syncToken` | string | No | Token obtained from the nextSyncToken field returned on the last page of results from the previous list request. It makes the result of this list request contain only entries that have changed since then. If the syncToken expires, the server will respond with a 410 GONE response code and the client should clear its storage and perform a full synchronization without any syncToken. |
| `maxResults` | integer | No | Maximum number of entries returned on one result page. By default the value is 100 entries. The page size can never be larger than 250 entries. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Watch Settings

**Slug:** `GOOGLECALENDAR_SETTINGS_WATCH`

Watch for changes to Settings resources.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | A UUID or similar unique string that identifies this channel. |
| `type` | string | Yes | The type of delivery mechanism used for this channel. Must be "web_hook". |
| `token` | string | No | An arbitrary string delivered to the target address with each notification delivered over this channel. |
| `params` | object | No | Additional parameters controlling delivery channel behavior. |
| `address` | string | Yes | The address where notifications are delivered for this channel. |
| `expiration` | integer | No | Unix timestamp in milliseconds specifying when the API should stop sending notifications for this channel. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Sync Events (Deprecated)

**Slug:** `GOOGLECALENDAR_SYNC_EVENTS`

DEPRECATED: Use GOOGLECALENDAR_EVENTS_LIST instead. EventsList already handles syncToken with automatic param stripping. Synchronizes Google Calendar events, performing a full sync if no `sync_token` is provided or if a 410 GONE error (due to an expired token) necessitates it, otherwise performs an incremental sync for events changed since the `sync_token` was issued.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pageToken` | string | No | Token for paginating results, from a previous response's `nextPageToken`. Repeat with each returned `nextPageToken` until no `nextPageToken` is returned; stopping early silently omits remaining events. |
| `sync_token` | string | No | Token for incremental sync, retrieving only changes since issued. A 410 GONE response indicates an expired token, requiring a full sync. Cannot be combined with `timeMin`, `timeMax`, `orderBy`, `query`, or `updatedMin`; mixing these causes the request to fail. |
| `calendar_id` | string | No | Google Calendar identifier; 'primary' refers to the authenticated user's main calendar. |
| `event_types` | array | No | Filters events by specified types (e.g., 'default', 'focusTime', 'outOfOffice', 'workingLocation'). All types returned if omitted. |
| `max_results` | integer | No | Max events per page (max 2500); Google Calendar's default is used if unspecified. |
| `single_events` | boolean | No | If True, expands recurring events into individual instances (excluding master event); otherwise, Google's default handling applies. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Google event

**Slug:** `GOOGLECALENDAR_UPDATE_EVENT`

Updates an existing event in Google Calendar. REQUIRES event_id - you MUST first search for the event using GOOGLECALENDAR_FIND_EVENT or GOOGLECALENDAR_EVENTS_LIST to obtain the event_id. This is a full PUT replacement: omitted fields (including attendees, reminders, recurrence, conferencing) are cleared. Always provide the complete desired event state. Use GOOGLECALENDAR_PATCH_EVENT instead for partial edits.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `summary` | string | No | Summary (title) of the event. |
| `event_id` | string | Yes | REQUIRED. The unique identifier of the event to update. This parameter is MANDATORY - events cannot be updated by title, date, or other criteria. You MUST first retrieve the event_id by using GOOGLECALENDAR_FIND_EVENT or GOOGLECALENDAR_EVENTS_LIST to search for the event, then use the returned 'id' field here. |
| `location` | string | No | Geographic location of the event as free-form text. |
| `timezone` | string | No | IANA timezone name from the timezone database (e.g., 'America/New_York', 'Europe/London', 'Asia/Jerusalem', 'UTC'). Required if datetime is naive. For recurring events, start and end must include a timeZone. If not provided, UTC is used. If datetime includes timezone info (Z or offset), this field is optional and defaults to UTC. IMPORTANT: Must be a valid IANA timezone identifier. Values like 'EST', 'PST', 'ISRAEL TIME', or other abbreviations are NOT valid IANA timezone names. |
| `attendees` | array | No | List of attendees. Each attendee can be either: (1) A string email address (e.g., 'user@example.com'), or (2) An object with 'email' (required), 'optional' (boolean, default false), 'displayName' (string), 'comment' (string), 'additionalGuests' (integer), and 'resource' (boolean). To mark an attendee as optional (not required), use object format: {'email': 'user@example.com', 'optional': true}. IMPORTANT: Only valid email addresses are accepted. Plain names cannot be used. |
| `eventType` | string ("birthday" | "default" | "focusTime" | "outOfOffice" | "workingLocation") | No | Type of the event, immutable post-creation. 'workingLocation' (REQUIRES Google Workspace Enterprise). Note: 'fromGmail' events cannot be created via API. |
| `recurrence` | array | No | List of RRULE, EXRULE, RDATE, EXDATE lines for recurring events. Supported frequencies: DAILY, WEEKLY, MONTHLY, YEARLY. For recurring events, start.timeZone and end.timeZone must be present. UNTIL values follow RFC 5545: date-only (YYYYMMDD) for all-day events, or UTC datetime with Z suffix (YYYYMMDDTHHMMSSZ) for timed events. UNTIL values with time but missing Z suffix are auto-corrected. Provide an empty list to remove recurrence so the event becomes non-recurring. |
| `visibility` | string ("default" | "public" | "private" | "confidential") | No | Event visibility: 'default', 'public', 'private', or 'confidential'. |
| `calendar_id` | string | No | Identifier of the Google Calendar where the event resides. The value 'primary' targets the user's primary calendar. |
| `description` | string | No | Description of the event. Can contain HTML. Optional. Must be omitted for 'birthday' event type. |
| `end_datetime` | string | No | Event end time in ISO 8601 format: YYYY-MM-DDTHH:MM:SS. When provided, this parameter takes precedence over event_duration_hour and event_duration_minutes. If not provided, the end time is calculated using start_datetime + duration. Must be after start_datetime. Fractional seconds and timezone info will be automatically stripped if provided. Examples: '2025-01-16T14:30:00', '2025-01-16T14:30'. |
| `send_updates` | boolean | No | Defaults to True. Whether to send updates to the attendees. |
| `transparency` | string ("opaque" | "transparent") | No | 'opaque' (busy) or 'transparent' (available). |
| `start_datetime` | string | Yes | REQUIRED. Event start time in ISO 8601 format: YYYY-MM-DDTHH:MM:SS. IMPORTANT: Natural language expressions like 'tomorrow', 'next Monday', '2pm tomorrow' are NOT supported and will be rejected. You must provide the exact date and time in ISO format. Fractional seconds (e.g., .000) and timezone info (Z, +, -) will be automatically stripped if provided. Examples: '2025-01-16T13:00:00', '2025-01-16T13:00'. |
| `guestsCanModify` | boolean | No | If True, guests can modify the event. |
| `birthdayProperties` | object | No | Properties for birthday events. |
| `create_meeting_room` | boolean | No | Defaults to True. When True, for CREATE operations creates a Google Meet link; for UPDATE operations preserves existing conference data if present, or adds a new Meet link if none exists. Google Workspace accounts will successfully receive a Meet link. Personal Gmail accounts and other unsupported accounts will gracefully fallback to creating an event without a Meet link when conference creation fails. Set to False to skip Meet link operations (won't create new or modify existing conference data). The fallback ensures event creation succeeds even when conference features are unavailable due to account limitations. |
| `event_duration_hour` | integer | No | Number of hours for the event duration. Supports multi-day events (e.g., 240 hours = 10 days). For durations under 1 hour, use event_duration_minutes instead. Ignored if end_datetime is provided. |
| `extended_properties` | object | No | Extended properties of the event for storing custom metadata. Contains 'private' (visible only on this calendar) and/or 'shared' (visible to all attendees) dictionaries mapping string keys to string values. Example: {'private': {'key1': 'value1'}, 'shared': {'key2': 'value2'}} |
| `focusTimeProperties` | object | No | Properties for focusTime events. REQUIRES Google Workspace Enterprise account with Focus Time feature enabled. |
| `guestsCanInviteOthers` | boolean | No | Whether attendees other than the organizer can invite others to the event. |
| `outOfOfficeProperties` | object | No | Properties for outOfOffice events. |
| `event_duration_minutes` | integer | No | Duration in minutes (0-59 ONLY). NEVER use 60+ minutes - use event_duration_hour=1 instead. Maximum value is 59. Combined duration (hours + minutes) must be greater than 0. Ignored if end_datetime is provided. |
| `guestsCanSeeOtherGuests` | boolean | No | Whether attendees other than the organizer can see who the event's attendees are. |
| `workingLocationProperties` | object | No | Properties for workingLocation events. REQUIRES Google Workspace Enterprise.  Constraints discovered from testing: - Must set transparency='transparent' and visibility='public' - Description must be omitted - Depending on 'type', include one of 'homeOffice', 'officeLocation', or 'customLocation' |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |


## Triggers

### Attendee Response Changed

**Slug:** `GOOGLECALENDAR_ATTENDEE_RESPONSE_CHANGED_TRIGGER`

**Type:** poll

Polling trigger that fires when any attendee's RSVP changes to
    accepted, declined, or tentative. Returns attendee info and current status.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `calendarId` | string | No | The unique identifier for the calendar |
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `showDeleted` | boolean | No | Whether to include deleted events in the results |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `attendee_email` | string | No | Email of the attendee whose RSVP changed |
| `attendee_name` | string | No | Display name of the attendee |
| `calendar_id` | string | Yes | The calendar identifier |
| `event_html_link` | string | No | Link to the event in Google Calendar |
| `event_id` | string | Yes | The unique identifier of the event |
| `event_summary` | string | No | Event title/summary |
| `previous_response_status` | string | No | Previous RSVP status |
| `response_status` | string | Yes | Current RSVP status (accepted, declined, tentative) |

### Event Canceled or Deleted

**Slug:** `GOOGLECALENDAR_EVENT_CANCELED_DELETED_TRIGGER`

**Type:** poll

Triggers when a Google Calendar event is cancelled or deleted.
    Returns minimal data: event_id, summary (if available), and cancellation timestamp.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `calendarId` | string | No | The unique identifier for the calendar to monitor |
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cancelled_at` | string | No | Cancellation timestamp (from event.updated) |
| `event_id` | string | Yes | The unique identifier of the event |
| `summary` | string | No | Event title/summary (may be missing for cancelled events) |

### Event Starting Soon

**Slug:** `GOOGLECALENDAR_EVENT_STARTING_SOON_TRIGGER`

**Type:** poll

Triggers when a calendar event is within a configured number of minutes from starting.
    Includes countdown window, start time, and event metadata.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `calendarId` | string | No | The unique identifier for the calendar to monitor |
| `countdown_window_minutes` | integer | No | Look-ahead window (in minutes) for upcoming events to evaluate |
| `include_all_day` | boolean | No | Whether to consider all-day events (default False) |
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `minutes_before_start` | integer | No | Trigger when an event is within this many minutes from starting |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `attendees` | array | No | List of attendees |
| `calendar_id` | string | Yes | The calendar identifier |
| `countdown_window_minutes` | integer | Yes | Countdown window used for this trigger |
| `creator_email` | string | No | Email of the event creator |
| `description` | string | No | Event description |
| `event_id` | string | Yes | The unique identifier of the event |
| `hangout_link` | string | No | Google Meet link for the conference, if available |
| `html_link` | string | No | Link to the event in Google Calendar |
| `location` | string | No | Event location |
| `minutes_until_start` | number | No | Minutes remaining until event starts (>= 0) |
| `organizer_email` | string | No | Email of the event organizer |
| `start_time` | string | No | Event start time in ISO format |
| `start_timestamp` | number | No | Event start time as UNIX epoch timestamp (UTC) |
| `summary` | string | No | Event title/summary |

### Calendar Event Changes

**Slug:** `GOOGLECALENDAR_GOOGLE_CALENDAR_EVENT_CHANGE_TRIGGER`

**Type:** webhook

**SOON TO BE DEPRECATED** - Use Calendar Event Sync (polling trigger) instead.
    Real-time webhook trigger for calendar event changes. Returns event metadata only.
    For full event data, use Calendar Event Sync (polling trigger).

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `calendar_id` | string | No | The unique identifier for the calendar |
| `ttl` | integer | No | The time-to-live in seconds for the notification channel |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `channel_id` | string | Yes | The unique identifier passed to identify this channel |
| `resource_id` | string | Yes | The unique identifier of the resource |
| `resource_state` | string | Yes | The state of the resource |
| `resource_url` | string | Yes | The url for the resource |

### Event Created

**Slug:** `GOOGLECALENDAR_GOOGLE_CALENDAR_EVENT_CREATED_TRIGGER`

**Type:** poll

Polling trigger that fires when a new calendar event is created.
    Returns event ID, summary, start/end times, and organizer info.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `calendarId` | string | No | The unique identifier for the calendar |
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `showDeleted` | boolean | No | Whether to include deleted events in the results |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `calendar_id` | string | Yes | The calendar identifier |
| `end_time` | string | No | Event end time in ISO format |
| `event_id` | string | Yes | The unique identifier of the event |
| `organizer_email` | string | No | Email of the event organizer |
| `organizer_name` | string | No | Name of the event organizer |
| `start_time` | string | No | Event start time in ISO format |
| `summary` | string | No | Event title/summary |

### Calendar Event Sync

**Slug:** `GOOGLECALENDAR_GOOGLE_CALENDAR_EVENT_SYNC_TRIGGER`

**Type:** poll

Polling trigger that returns full event data including details, attendees, and metadata.
    For real-time notifications with basic info, use Calendar Event Changes (webhook).

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `calendarId` | string | No | The unique identifier for the calendar |
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `showDeleted` | boolean | No | Whether to include deleted events in the results |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `attendees` | array | No | List of attendees |
| `calendar_id` | string | Yes | The calendar identifier |
| `conference_data` | object | No | Conference data structure containing details about the meeting |
| `created_at` | string | No | When the event was created |
| `creator_email` | string | No | Email of the event creator |
| `creator_name` | string | No | Name of the event creator |
| `description` | string | No | Event description |
| `end_time` | string | No | Event end time in ISO format |
| `event_id` | string | Yes | The unique identifier of the event |
| `event_type` | string | Yes | Type of change: created, updated, or deleted |
| `hangout_link` | string | No | Google Meet link for the conference, if available |
| `html_link` | string | No | Link to the event in Google Calendar |
| `location` | string | No | Event location |
| `organizer_email` | string | No | Email of the event organizer |
| `organizer_name` | string | No | Name of the event organizer |
| `recurring_event_id` | string | No | ID of recurring event if applicable |
| `start_time` | string | No | Event start time in ISO format |
| `status` | string | No | Event status (confirmed, tentative, cancelled) |
| `summary` | string | No | Event title/summary |
| `updated_at` | string | No | When the event was last updated |
| `visibility` | string | No | Event visibility |

### Event Updated

**Slug:** `GOOGLECALENDAR_GOOGLE_CALENDAR_EVENT_UPDATED_TRIGGER`

**Type:** poll

Triggers when an existing Google Calendar event is modified. Returns the event ID,
    change type, and the specific fields that changed with their previous and new values.

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `calendarId` | string | No | The unique identifier for the calendar |
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `showDeleted` | boolean | No | Whether to include deleted (cancelled) events in the results |
| `tracked_fields` | array | No | List of event fields to track for changes. start and end are compared as RFC3339 strings (preferring dateTime over date). Attendees are compared by email, displayName, responseStatus, and optional flag. |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `calendar_id` | string | Yes | The calendar identifier |
| `change_type` | string | No | Type of change. Always 'updated' for this trigger |
| `event_id` | string | Yes | The unique identifier of the event |
| `updated_at` | string | No | When the event was last updated (RFC3339) |
| `updated_fields` | object | Yes | Dictionary of changed fields with old and new values |