← Back to Google Calendar docs
Google Calendar — Tool Reference
Read schedules, search events, create/update events, manage RSVPs, and find availability
Your AI assistant discovers and invokes these tools through the
MCP Server's meta tools —
it calls execute_tool with the tool name and arguments below.
# create_event write
Create a calendar event and return the created event details for timed or all-day events with attendees and location.
Full description
Create a new calendar event.
All-day events are detected by date format: YYYY-MM-DD triggers an all-day
event, RFC 3339 triggers a timed event.
Parameters:
calendar_id: Calendar ID (default 'primary')
summary: Event title (required)
start: RFC 3339 dateTime or YYYY-MM-DD for all-day (required)
end: RFC 3339 dateTime or YYYY-MM-DD, exclusive end for all-day (required)
description: Event description (optional)
location: Event location (optional)
attendees: List of attendee email addresses (optional)
send_updates: Notification preference - 'all', 'externalOnly', 'none' (default 'all')
recurrence: List of RRULE strings (optional, requires timezone)
reminders: Custom reminders object (optional)
timezone: IANA timezone (required for recurring events, optional otherwise)
conference: Auto-generate a Google Meet link (default false)
visibility: 'default', 'public', 'private', 'confidential' (default 'default')
transparency: 'opaque' (blocks time) or 'transparent' (default 'opaque')
color_id: Event color ID 1-11 from get_calendar_colors (optional)
Returns:
CreateEventResult with:
- event: Created event object with id, htmlLink, conference data, etc.
Notes:
- send_updates defaults to 'all' -- confirm with user before creating events with attendees
- When conference=true, creates a Google Meet conference and returns the join URI | Parameter | Type | Required | Description |
|---|---|---|---|
calendar_id | string | No | Calendar ID Default: "primary" |
summary | string | Yes | Event title |
start | string | Yes | RFC 3339 dateTime or YYYY-MM-DD for all-day |
end | string | Yes | RFC 3339 dateTime or YYYY-MM-DD (exclusive end for all-day) |
description | string | null | No | Event description |
location | string | null | No | Event location |
attendees | array<string> | null | No | List of attendee email addresses |
send_updates | string | No | Notification preference: 'all', 'externalOnly', 'none' Default: "all" |
recurrence | array<string> | null | No | List of RRULE strings (requires timezone) |
reminders | object | null | No | Custom reminders |
timezone | string | null | No | IANA timezone (e.g. 'America/New_York'). Required for recurring events |
conference | boolean | No | Auto-generate a Google Meet link Default: false |
visibility | string | No | 'default', 'public', 'private', 'confidential' Default: "default" |
transparency | string | No | 'opaque' (blocks time) or 'transparent' Default: "opaque" |
color_id | string | null | No | Event color ID (1-11) |
account | string | null | No | Optional Google account to create the event in (email). The event is created on, and invitations are sent FROM, this account. Omit to use the user's default Google account. Call list_accounts to see which accounts are connected. |
Parameter schema (JSON)
{
"description": "Parameters for create_event.",
"properties": {
"calendar_id": {
"default": "primary",
"description": "Calendar ID",
"title": "Calendar Id",
"type": "string"
},
"summary": {
"description": "Event title",
"title": "Summary",
"type": "string"
},
"start": {
"description": "RFC 3339 dateTime or YYYY-MM-DD for all-day",
"title": "Start",
"type": "string"
},
"end": {
"description": "RFC 3339 dateTime or YYYY-MM-DD (exclusive end for all-day)",
"title": "End",
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Event description",
"title": "Description"
},
"location": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Event location",
"title": "Location"
},
"attendees": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "List of attendee email addresses",
"title": "Attendees"
},
"send_updates": {
"default": "all",
"description": "Notification preference: 'all', 'externalOnly', 'none'",
"title": "Send Updates",
"type": "string"
},
"recurrence": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "List of RRULE strings (requires timezone)",
"title": "Recurrence"
},
"reminders": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Custom reminders",
"title": "Reminders"
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "IANA timezone (e.g. 'America/New_York'). Required for recurring events",
"title": "Timezone"
},
"conference": {
"default": false,
"description": "Auto-generate a Google Meet link",
"title": "Conference",
"type": "boolean"
},
"visibility": {
"default": "default",
"description": "'default', 'public', 'private', 'confidential'",
"title": "Visibility",
"type": "string"
},
"transparency": {
"default": "opaque",
"description": "'opaque' (blocks time) or 'transparent'",
"title": "Transparency",
"type": "string"
},
"color_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Event color ID (1-11)",
"title": "Color Id"
},
"account": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional Google account to create the event in (email). The event is created on, and invitations are sent FROM, this account. Omit to use the user's default Google account. Call list_accounts to see which accounts are connected.",
"title": "Account"
}
},
"required": [
"summary",
"start",
"end"
],
"title": "CreateEventParams",
"type": "object",
"additionalProperties": false
} Result schema (JSON)
{
"description": "Result of create_event.",
"properties": {
"event": {
"additionalProperties": true,
"title": "Event",
"type": "object"
}
},
"title": "CreateEventResult",
"type": "object"
} # delete_event write
Delete a calendar event by soft-cancelling it and return the cancellation result, optionally notifying attendees.
Full description
Delete (cancel) an event. This is a soft delete -- the event status is
set to 'cancelled', not permanently removed.
Parameters:
calendar_id: Calendar ID (default 'primary')
event_id: Event ID to delete (required)
send_updates: 'all', 'externalOnly', 'none' (default 'all')
Returns:
DeleteEventResult with:
- success: Whether the deletion succeeded
- event_id: The deleted event's ID
Notes:
- Soft delete only -- event is cancelled, not permanently removed
- No bulk delete is supported (intentional safety constraint)
- Cancellation notifications are sent to attendees by default | Parameter | Type | Required | Description |
|---|---|---|---|
calendar_id | string | No | Calendar ID Default: "primary" |
event_id | string | Yes | Event ID to delete |
send_updates | string | No | 'all', 'externalOnly', 'none' Default: "all" |
account | string | null | No | Optional Google account override (email). Pass the same account used to fetch this event_id from search_events — event and calendar IDs are scoped to the account they came from. |
Parameter schema (JSON)
{
"description": "Parameters for delete_event.",
"properties": {
"calendar_id": {
"default": "primary",
"description": "Calendar ID",
"title": "Calendar Id",
"type": "string"
},
"event_id": {
"description": "Event ID to delete",
"title": "Event Id",
"type": "string"
},
"send_updates": {
"default": "all",
"description": "'all', 'externalOnly', 'none'",
"title": "Send Updates",
"type": "string"
},
"account": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional Google account override (email). Pass the same account used to fetch this event_id from search_events — event and calendar IDs are scoped to the account they came from.",
"title": "Account"
}
},
"required": [
"event_id"
],
"title": "DeleteEventParams",
"type": "object",
"additionalProperties": false
} Result schema (JSON)
{
"description": "Result of delete_event.",
"properties": {
"success": {
"default": true,
"title": "Success",
"type": "boolean"
},
"event_id": {
"default": "",
"title": "Event Id",
"type": "string"
}
},
"title": "DeleteEventResult",
"type": "object"
} # find_free_busy read
Check availability across one or more Google calendars and return busy time blocks.
Full description
Check availability across one or more calendars.
Returns busy/free information only -- not event details (by design in
Google's API for privacy).
Parameters:
calendar_ids: List of calendar IDs to check (required)
time_min: Start of time range, RFC 3339 (required)
time_max: End of time range, RFC 3339 (required)
timezone: IANA timezone for display (optional)
Returns:
FindFreeBusyResult with:
- calendars: Dict mapping calendar IDs to their busy blocks
- timeMin: Start of the checked range
- timeMax: End of the checked range
Notes:
- For other people's calendars, shows time blocks as busy only
- Private events show as 'Busy' to others | Parameter | Type | Required | Description |
|---|---|---|---|
calendar_ids | array<string> | Yes | List of calendar IDs to check |
time_min | string | Yes | Start of time range (RFC 3339) |
time_max | string | Yes | End of time range (RFC 3339) |
timezone | string | null | No | IANA timezone for display |
account | string | null | No | Optional Google account override (email). The freeBusy query runs as this account; the calendar_ids must be visible to it. Omit to use the user's default Google account. Call list_accounts to see which accounts are connected. |
Parameter schema (JSON)
{
"description": "Parameters for find_free_busy.",
"properties": {
"calendar_ids": {
"description": "List of calendar IDs to check",
"items": {
"type": "string"
},
"title": "Calendar Ids",
"type": "array"
},
"time_min": {
"description": "Start of time range (RFC 3339)",
"title": "Time Min",
"type": "string"
},
"time_max": {
"description": "End of time range (RFC 3339)",
"title": "Time Max",
"type": "string"
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "IANA timezone for display",
"title": "Timezone"
},
"account": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional Google account override (email). The freeBusy query runs as this account; the calendar_ids must be visible to it. Omit to use the user's default Google account. Call list_accounts to see which accounts are connected.",
"title": "Account"
}
},
"required": [
"calendar_ids",
"time_min",
"time_max"
],
"title": "FindFreeBusyParams",
"type": "object",
"additionalProperties": false
} Result schema (JSON)
{
"description": "Result of find_free_busy.",
"properties": {
"calendars": {
"additionalProperties": true,
"title": "Calendars",
"type": "object"
},
"timeMin": {
"default": "",
"title": "Timemin",
"type": "string"
},
"timeMax": {
"default": "",
"title": "Timemax",
"type": "string"
}
},
"title": "FindFreeBusyResult",
"type": "object"
} # find_open_slots read
Find available meeting times that work for all participants.
Full description
Find available meeting times that work for all participants.
This is a Toolforest convenience tool (not a Google API endpoint). It calls
the freeBusy API, then computes gap intersection server-side to avoid
error-prone timezone math in the LLM.
Parameters:
calendar_ids: List of calendar IDs to check availability across (required)
time_min: Start of search range, RFC 3339 (required)
time_max: End of search range, RFC 3339 (required)
duration_minutes: Required meeting duration in minutes (required)
timezone: IANA timezone for display and working hours (optional)
working_hours_only: Restrict to 9am-5pm in the specified timezone (default true)
max_suggestions: Maximum number of time slots to suggest (default 5)
Returns:
FindOpenSlotsResult with:
- slots: List of available time slots with start/end
- calendarsChecked: List of calendar IDs that were checked
- searchRange: The time range that was searched
Notes:
- Working hours default to 9am-5pm in the specified timezone
- Returns empty slots array if no common availability exists | Parameter | Type | Required | Description |
|---|---|---|---|
calendar_ids | array<string> | Yes | List of calendar IDs to check availability across |
time_min | string | Yes | Start of search range (RFC 3339) |
time_max | string | Yes | End of search range (RFC 3339) |
duration_minutes | integer | Yes | Required meeting duration in minutes |
timezone | string | null | No | IANA timezone for display |
working_hours_only | boolean | No | Restrict suggestions to 9am-5pm Default: true |
max_suggestions | integer | No | Maximum number of time slots to suggest Default: 5 |
account | string | null | No | Optional Google account override (email). The freeBusy query runs as this account; the calendar_ids must be visible to it. Omit to use the user's default Google account. Call list_accounts to see which accounts are connected. |
Parameter schema (JSON)
{
"description": "Parameters for find_open_slots.",
"properties": {
"calendar_ids": {
"description": "List of calendar IDs to check availability across",
"items": {
"type": "string"
},
"title": "Calendar Ids",
"type": "array"
},
"time_min": {
"description": "Start of search range (RFC 3339)",
"title": "Time Min",
"type": "string"
},
"time_max": {
"description": "End of search range (RFC 3339)",
"title": "Time Max",
"type": "string"
},
"duration_minutes": {
"description": "Required meeting duration in minutes",
"title": "Duration Minutes",
"type": "integer"
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "IANA timezone for display",
"title": "Timezone"
},
"working_hours_only": {
"default": true,
"description": "Restrict suggestions to 9am-5pm",
"title": "Working Hours Only",
"type": "boolean"
},
"max_suggestions": {
"default": 5,
"description": "Maximum number of time slots to suggest",
"title": "Max Suggestions",
"type": "integer"
},
"account": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional Google account override (email). The freeBusy query runs as this account; the calendar_ids must be visible to it. Omit to use the user's default Google account. Call list_accounts to see which accounts are connected.",
"title": "Account"
}
},
"required": [
"calendar_ids",
"time_min",
"time_max",
"duration_minutes"
],
"title": "FindOpenSlotsParams",
"type": "object",
"additionalProperties": false
} Result schema (JSON)
{
"description": "Result of find_open_slots.",
"properties": {
"slots": {
"items": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"title": "Slots",
"type": "array"
},
"calendarsChecked": {
"items": {
"type": "string"
},
"title": "Calendarschecked",
"type": "array"
},
"searchRange": {
"additionalProperties": {
"type": "string"
},
"title": "Searchrange",
"type": "object"
}
},
"title": "FindOpenSlotsResult",
"type": "object"
} # get_calendar_colors read
Returns the color palette available for events and calendars.
Full description
Returns the color palette available for events and calendars.
Parameters:
None - This tool takes no parameters.
Returns:
GetCalendarColorsResult with:
- event: Dict mapping color IDs (1-11) to {background, foreground}
- calendar: Dict mapping calendar color IDs to {background, foreground}
Notes:
- Event color IDs are used with create_event and update_event color_id parameter
- Color values are stable and rarely change | Parameter | Type | Required | Description |
|---|---|---|---|
account | string | null | No | Optional Google account override (email). Omit to use the user's default Google account. Call list_accounts to see which accounts are connected. |
Parameter schema (JSON)
{
"description": "Parameters for get_calendar_colors.",
"properties": {
"account": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional Google account override (email). Omit to use the user's default Google account. Call list_accounts to see which accounts are connected.",
"title": "Account"
}
},
"title": "GetCalendarColorsParams",
"type": "object",
"additionalProperties": false
} Result schema (JSON)
{
"description": "Result of get_calendar_colors.",
"properties": {
"event": {
"additionalProperties": true,
"title": "Event",
"type": "object"
},
"calendar": {
"additionalProperties": true,
"title": "Calendar",
"type": "object"
}
},
"title": "GetCalendarColorsResult",
"type": "object"
} # get_event read
Read a specific event and return full event details, including description, recurrence, reminders, attachments, and conferencing.
Full description
Get full details of a specific event by ID.
Returns the complete event including full description (no truncation),
conference data, recurrence rules, reminders, and attachments.
Parameters:
calendar_id: Calendar ID (default 'primary')
event_id: Event ID from search_events response (required)
Returns:
GetEventResult with:
- event: Full event object with all fields
Notes:
- Returns full description (no truncation, unlike search_events)
- For recurring events, 'recurrence' contains RRULE strings on the master
- Instance events have 'recurringEventId' pointing to the master | Parameter | Type | Required | Description |
|---|---|---|---|
calendar_id | string | No | Calendar ID Default: "primary" |
event_id | string | Yes | Event ID |
account | string | null | No | Optional Google account override (email). Pass the same account used to fetch this event_id from search_events — event and calendar IDs are scoped to the account they came from, so calling get_event with the default account when the ID was obtained from a non-default account returns "not found". |
Parameter schema (JSON)
{
"description": "Parameters for get_event.",
"properties": {
"calendar_id": {
"default": "primary",
"description": "Calendar ID",
"title": "Calendar Id",
"type": "string"
},
"event_id": {
"description": "Event ID",
"title": "Event Id",
"type": "string"
},
"account": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional Google account override (email). Pass the same account used to fetch this event_id from search_events — event and calendar IDs are scoped to the account they came from, so calling get_event with the default account when the ID was obtained from a non-default account returns \"not found\".",
"title": "Account"
}
},
"required": [
"event_id"
],
"title": "GetEventParams",
"type": "object",
"additionalProperties": false
} Result schema (JSON)
{
"description": "Result of get_event.",
"properties": {
"event": {
"additionalProperties": true,
"title": "Event",
"type": "object"
}
},
"title": "GetEventResult",
"type": "object"
} # get_user_permissions read
Return OAuth scopes currently granted for this Google Calendar connection, plus authenticated email and timezone.
Full description
Return OAuth scopes currently granted for this Google Calendar connection,
the authenticated user's email address, and primary timezone.
Parameters:
None - This tool takes no parameters.
Returns:
GetUserPermissionsResult with:
- email: User's email address
- scopes: List of granted OAuth scope URLs
- primary_timezone: User's primary calendar timezone (e.g., 'America/Los_Angeles')
Common scopes:
- calendar.events: Create, update, delete events
- calendar.readonly: Read-only access to calendars and events
Errors:
ProviderError: User has not connected Google Calendar or token is invalid/expired | Parameter | Type | Required | Description |
|---|---|---|---|
account | string | null | No | Optional Google account override (email). Omit to use the user's default Google account. Call list_accounts to see which accounts are connected. |
Parameter schema (JSON)
{
"description": "Parameters for get_user_permissions.",
"properties": {
"account": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional Google account override (email). Omit to use the user's default Google account. Call list_accounts to see which accounts are connected.",
"title": "Account"
}
},
"title": "GetUserPermissionsParams",
"type": "object",
"additionalProperties": false
} Result schema (JSON)
{
"description": "Result of get_user_permissions.",
"properties": {
"email": {
"default": "",
"description": "User's email address",
"title": "Email",
"type": "string"
},
"scopes": {
"description": "Granted OAuth scopes",
"items": {
"type": "string"
},
"title": "Scopes",
"type": "array"
},
"primary_timezone": {
"default": "",
"description": "User's primary calendar timezone",
"title": "Primary Timezone",
"type": "string"
}
},
"title": "GetUserPermissionsResult",
"type": "object"
} # list_accounts read
List the Google accounts the user has connected for Google Calendar. Returns each account's email, name, and whether it's the current default for this MCP client. Use when the user mentions "my work calendar" / "my personal calendar" or asks which accounts are available — then pass `account=<email>` to target a non-default account on Calendar tools. `account=<email>` is supported on all Google Calendar tools.
Full description
Return the user's connected Google accounts for the current MCP client.
Returns:
ListAccountsResult with one entry per connected Google account, including the
account's email, display name (when available), and a boolean flag indicating
which account is the current default for this user + MCP client.
When the user has multiple Google accounts connected, this tool is the canonical
way to discover what's available before invoking other Google Calendar tools with
an explicit `account=...` override. No parameters.
Parameter schema (JSON)
{
"description": "Parameters for list_accounts.",
"properties": {},
"title": "ListAccountsParams",
"type": "object",
"additionalProperties": false
} Result schema (JSON)
{
"$defs": {
"ConnectedAccount": {
"description": "A single connected Google account.",
"properties": {
"email": {
"default": "",
"title": "Email",
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Name"
},
"is_default": {
"default": false,
"title": "Is Default",
"type": "boolean"
}
},
"title": "ConnectedAccount",
"type": "object"
}
},
"description": "Result of list_accounts.",
"properties": {
"accounts": {
"items": {
"$ref": "#/$defs/ConnectedAccount"
},
"title": "Accounts",
"type": "array"
}
},
"title": "ListAccountsResult",
"type": "object"
} # list_calendars read
List all Google calendars the user has access to (owned, subscribed, shared).
Full description
List all calendars the user has access to (owned, subscribed, shared).
Parameters:
show_hidden: Include hidden/minimized calendars (default false)
Returns:
ListCalendarsResult with:
- calendars: List of calendar entries with id, summary, timezone, accessRole, etc.
Notes:
- accessRole values: 'owner', 'writer', 'reader', 'freeBusyReader'
- 'primary' is true for exactly one calendar (the user's main calendar)
- Hidden calendars are excluded by default to reduce noise | Parameter | Type | Required | Description |
|---|---|---|---|
show_hidden | boolean | No | Include hidden/minimized calendars Default: false |
account | string | null | No | Optional Google account override (email, e.g. "alice.work@company.com"). Omit to use the user's default Google account. Call list_accounts to see which accounts are connected. |
Parameter schema (JSON)
{
"description": "Parameters for list_calendars.",
"properties": {
"show_hidden": {
"default": false,
"description": "Include hidden/minimized calendars",
"title": "Show Hidden",
"type": "boolean"
},
"account": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional Google account override (email, e.g. \"alice.work@company.com\"). Omit to use the user's default Google account. Call list_accounts to see which accounts are connected.",
"title": "Account"
}
},
"title": "ListCalendarsParams",
"type": "object",
"additionalProperties": false
} Result schema (JSON)
{
"$defs": {
"CalendarEntry": {
"description": "A single calendar entry.",
"properties": {
"id": {
"default": "",
"title": "Id",
"type": "string"
},
"summary": {
"default": "",
"title": "Summary",
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Description"
},
"timeZone": {
"default": "",
"title": "Timezone",
"type": "string"
},
"accessRole": {
"default": "",
"title": "Accessrole",
"type": "string"
},
"primary": {
"default": false,
"title": "Primary",
"type": "boolean"
},
"backgroundColor": {
"default": "",
"title": "Backgroundcolor",
"type": "string"
}
},
"title": "CalendarEntry",
"type": "object"
}
},
"description": "Result of list_calendars.",
"properties": {
"calendars": {
"items": {
"$ref": "#/$defs/CalendarEntry"
},
"title": "Calendars",
"type": "array"
}
},
"title": "ListCalendarsResult",
"type": "object"
} # list_event_instances read
List all instances of a recurring event within a time range.
Full description
List all instances of a recurring event within a time range.
Parameters:
calendar_id: Calendar ID (default 'primary')
event_id: Recurring event master ID (required)
time_min: Start of range, RFC 3339 (optional)
time_max: End of range, RFC 3339 (optional)
max_results: Maximum instances to return (default 25)
Returns:
ListEventInstancesResult with:
- instances: List of instance event objects
- recurringEventId: The master event ID
- summary: The master event's title
Notes:
- Instance IDs have the format {master_id}_{YYYYMMDDTHHMMSSZ}
- Modified instances (exceptions) include their overridden fields
- originalStartTime indicates when the instance was originally scheduled | Parameter | Type | Required | Description |
|---|---|---|---|
calendar_id | string | No | Calendar ID Default: "primary" |
event_id | string | Yes | Recurring event master ID |
time_min | string | null | No | Start of range (RFC 3339) |
time_max | string | null | No | End of range (RFC 3339) |
max_results | integer | No | Maximum instances to return Default: 25 |
account | string | null | No | Optional Google account override (email). Pass the same account used to fetch this event_id from search_events — event and calendar IDs are scoped to the account they came from. |
Parameter schema (JSON)
{
"description": "Parameters for list_event_instances.",
"properties": {
"calendar_id": {
"default": "primary",
"description": "Calendar ID",
"title": "Calendar Id",
"type": "string"
},
"event_id": {
"description": "Recurring event master ID",
"title": "Event Id",
"type": "string"
},
"time_min": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Start of range (RFC 3339)",
"title": "Time Min"
},
"time_max": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "End of range (RFC 3339)",
"title": "Time Max"
},
"max_results": {
"default": 25,
"description": "Maximum instances to return",
"title": "Max Results",
"type": "integer"
},
"account": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional Google account override (email). Pass the same account used to fetch this event_id from search_events — event and calendar IDs are scoped to the account they came from.",
"title": "Account"
}
},
"required": [
"event_id"
],
"title": "ListEventInstancesParams",
"type": "object",
"additionalProperties": false
} Result schema (JSON)
{
"description": "Result of list_event_instances.",
"properties": {
"instances": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Instances",
"type": "array"
},
"recurringEventId": {
"default": "",
"title": "Recurringeventid",
"type": "string"
},
"summary": {
"default": "",
"title": "Summary",
"type": "string"
}
},
"title": "ListEventInstancesResult",
"type": "object"
} # quick_add_event write
Create an event using natural language, leveraging Google Calendar's built-in NLP parsing.
Full description
Create an event using natural language, leveraging Google Calendar's
built-in NLP parsing.
Parameters:
calendar_id: Calendar ID (default 'primary')
text: Natural language event description (required)
e.g., 'Lunch with Nick at Canlis on Friday at noon'
Returns:
QuickAddEventResult with:
- event: Created event object
Notes:
- Uses Google Calendar's quickAdd API endpoint
- The parsed result may not always match user intent -- consider confirming | Parameter | Type | Required | Description |
|---|---|---|---|
calendar_id | string | No | Calendar ID Default: "primary" |
text | string | Yes | Natural language event description (e.g., 'Lunch with Nick at Canlis on Friday at noon') |
account | string | null | No | Optional Google account to create the event in (email). The event is created on this account. Omit to use the user's default Google account. Call list_accounts to see which accounts are connected. |
Parameter schema (JSON)
{
"description": "Parameters for quick_add_event.",
"properties": {
"calendar_id": {
"default": "primary",
"description": "Calendar ID",
"title": "Calendar Id",
"type": "string"
},
"text": {
"description": "Natural language event description (e.g., 'Lunch with Nick at Canlis on Friday at noon')",
"title": "Text",
"type": "string"
},
"account": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional Google account to create the event in (email). The event is created on this account. Omit to use the user's default Google account. Call list_accounts to see which accounts are connected.",
"title": "Account"
}
},
"required": [
"text"
],
"title": "QuickAddEventParams",
"type": "object",
"additionalProperties": false
} Result schema (JSON)
{
"description": "Result of quick_add_event.",
"properties": {
"event": {
"additionalProperties": true,
"title": "Event",
"type": "object"
}
},
"title": "QuickAddEventResult",
"type": "object"
} # rsvp_event write
Respond to an event invitation.
Full description
Respond to an event invitation.
Only modifies the current user's attendee entry. Internally implemented
as a PATCH that updates only the authenticated user's responseStatus.
Parameters:
calendar_id: Calendar ID (default 'primary')
event_id: Event ID to RSVP to (required)
response: 'accepted', 'declined', or 'tentative' (required)
send_updates: 'all', 'externalOnly', 'none' (default 'all')
Returns:
RsvpEventResult with:
- event_id: The event ID
- summary: Event title
- response: The submitted response status
- start: Event start time | Parameter | Type | Required | Description |
|---|---|---|---|
calendar_id | string | No | Calendar ID Default: "primary" |
event_id | string | Yes | Event ID to RSVP to |
response | string | Yes | 'accepted', 'declined', or 'tentative' |
send_updates | string | No | 'all', 'externalOnly', 'none' Default: "all" |
account | string | null | No | Optional Google account override (email). Pass the same account used to fetch this event_id from search_events — event and calendar IDs are scoped to the account they came from. The RSVP is recorded as this account. |
Parameter schema (JSON)
{
"description": "Parameters for rsvp_event.",
"properties": {
"calendar_id": {
"default": "primary",
"description": "Calendar ID",
"title": "Calendar Id",
"type": "string"
},
"event_id": {
"description": "Event ID to RSVP to",
"title": "Event Id",
"type": "string"
},
"response": {
"description": "'accepted', 'declined', or 'tentative'",
"title": "Response",
"type": "string"
},
"send_updates": {
"default": "all",
"description": "'all', 'externalOnly', 'none'",
"title": "Send Updates",
"type": "string"
},
"account": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional Google account override (email). Pass the same account used to fetch this event_id from search_events — event and calendar IDs are scoped to the account they came from. The RSVP is recorded as this account.",
"title": "Account"
}
},
"required": [
"event_id",
"response"
],
"title": "RsvpEventParams",
"type": "object",
"additionalProperties": false
} Result schema (JSON)
{
"description": "Result of rsvp_event.",
"properties": {
"event_id": {
"default": "",
"title": "Event Id",
"type": "string"
},
"summary": {
"default": "",
"title": "Summary",
"type": "string"
},
"response": {
"default": "",
"title": "Response",
"type": "string"
},
"start": {
"additionalProperties": true,
"title": "Start",
"type": "object"
}
},
"title": "RsvpEventResult",
"type": "object"
} # search_events read
Query Google Calendar events with time bounds and optional text search.
Full description
Query events with time bounds and optional text search.
The primary tool for finding calendar events. Supports free-text search
matching summary, description, location, attendee names/emails, and organizer.
Parameters:
calendar_id: Calendar ID to search (default 'primary')
query: Free-text search query (optional)
time_min: Lower bound inclusive, RFC 3339 with timezone offset (optional)
time_max: Upper bound exclusive, RFC 3339 with timezone offset (optional)
max_results: Maximum events to return, 1-250 (default 25)
page_token: Token for paginating through results (optional)
single_events: Expand recurring events into individual instances (default true)
show_deleted: Include cancelled events (default false)
updated_min: Only events modified after this timestamp (optional)
Returns:
SearchEventsResult with:
- events: List of event objects with truncated descriptions (~2000 chars)
- nextPageToken: Token for next page (if more results exist)
- resultCount: Number of events returned
Notes:
- Event descriptions are truncated to ~2000 chars; use get_event for full content
- At least one of query, time_min, or time_max should be provided
- All-day events use 'date' instead of 'dateTime' in start/end | Parameter | Type | Required | Description |
|---|---|---|---|
calendar_id | string | No | Calendar ID to search Default: "primary" |
query | string | null | No | Free-text search query |
time_min | string | null | No | Lower bound inclusive (RFC 3339 with timezone offset) |
time_max | string | null | No | Upper bound exclusive (RFC 3339 with timezone offset) |
max_results | integer | No | Maximum events to return (1-250) Default: 25 |
page_token | string | null | No | Token for paginating through results |
single_events | boolean | No | Expand recurring events into individual instances Default: true |
show_deleted | boolean | No | Include cancelled events Default: false |
updated_min | string | null | No | Only events modified after this timestamp (RFC 3339) |
account | string | null | No | Optional Google account override (email). Omit to use the user's default Google account. Call list_accounts to see which accounts are connected. |
Parameter schema (JSON)
{
"description": "Parameters for search_events.",
"properties": {
"calendar_id": {
"default": "primary",
"description": "Calendar ID to search",
"title": "Calendar Id",
"type": "string"
},
"query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Free-text search query",
"title": "Query"
},
"time_min": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Lower bound inclusive (RFC 3339 with timezone offset)",
"title": "Time Min"
},
"time_max": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Upper bound exclusive (RFC 3339 with timezone offset)",
"title": "Time Max"
},
"max_results": {
"default": 25,
"description": "Maximum events to return (1-250)",
"maximum": 250,
"minimum": 1,
"title": "Max Results",
"type": "integer"
},
"page_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Token for paginating through results",
"title": "Page Token"
},
"single_events": {
"default": true,
"description": "Expand recurring events into individual instances",
"title": "Single Events",
"type": "boolean"
},
"show_deleted": {
"default": false,
"description": "Include cancelled events",
"title": "Show Deleted",
"type": "boolean"
},
"updated_min": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Only events modified after this timestamp (RFC 3339)",
"title": "Updated Min"
},
"account": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional Google account override (email). Omit to use the user's default Google account. Call list_accounts to see which accounts are connected.",
"title": "Account"
}
},
"title": "SearchEventsParams",
"type": "object",
"additionalProperties": false
} Result schema (JSON)
{
"description": "Result of search_events.",
"properties": {
"events": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Events",
"type": "array"
},
"nextPageToken": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Nextpagetoken"
},
"resultCount": {
"default": 0,
"title": "Resultcount",
"type": "integer"
}
},
"title": "SearchEventsResult",
"type": "object"
} # update_event write
Update an existing Google Calendar event with patch semantics (only provided fields modified).
Full description
Update an existing event. Patch semantics -- only provided fields are modified.
For recurring events, this updates the master (all instances). Use
update_event_instance for single instances.
Parameters:
calendar_id: Calendar ID (default 'primary')
event_id: Event ID to update (required)
summary: New event title (optional)
start: New start time, RFC 3339 or YYYY-MM-DD (optional)
end: New end time, RFC 3339 or YYYY-MM-DD (optional)
description: New description (optional)
location: New location (optional)
attendees: Full replacement list of attendee emails (optional)
add_attendees: Emails to add to existing attendee list (optional)
remove_attendees: Emails to remove from existing attendee list (optional)
send_updates: 'all', 'externalOnly', 'none' (default 'all')
recurrence: Updated RRULE strings (optional)
reminders: Updated reminders (optional)
timezone: IANA timezone (optional)
conference: Add (true) or remove (false) Google Meet link (optional)
visibility: Updated visibility (optional)
transparency: Updated transparency (optional)
color_id: Updated color ID (optional)
Returns:
UpdateEventResult with the updated event object
Notes:
- 'attendees' is a full replacement. Prefer add_attendees/remove_attendees
for incremental changes.
- Only non-null fields are sent in the PATCH request | Parameter | Type | Required | Description |
|---|---|---|---|
calendar_id | string | No | Calendar ID Default: "primary" |
event_id | string | Yes | Event ID to update |
summary | string | null | No | New event title |
start | string | null | No | New start time (RFC 3339 or YYYY-MM-DD) |
end | string | null | No | New end time (RFC 3339 or YYYY-MM-DD) |
description | string | null | No | New description |
location | string | null | No | New location |
attendees | array<string> | null | No | Full replacement list of attendee emails |
add_attendees | array<string> | null | No | Emails to add to existing attendee list |
remove_attendees | array<string> | null | No | Emails to remove from existing attendee list |
send_updates | string | No | 'all', 'externalOnly', 'none' Default: "all" |
recurrence | array<string> | null | No | Updated RRULE strings (requires timezone) |
reminders | object | null | No | Updated reminders |
timezone | string | null | No | IANA timezone (e.g. 'America/New_York'). Required when updating recurrence |
conference | boolean | null | No | Add/remove Google Meet link |
visibility | string | null | No | Updated visibility |
transparency | string | null | No | Updated transparency |
color_id | string | null | No | Updated color ID |
account | string | null | No | Optional Google account override (email). Pass the same account used to fetch this event_id from search_events — event and calendar IDs are scoped to the account they came from. |
Parameter schema (JSON)
{
"description": "Parameters for update_event.",
"properties": {
"calendar_id": {
"default": "primary",
"description": "Calendar ID",
"title": "Calendar Id",
"type": "string"
},
"event_id": {
"description": "Event ID to update",
"title": "Event Id",
"type": "string"
},
"summary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New event title",
"title": "Summary"
},
"start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New start time (RFC 3339 or YYYY-MM-DD)",
"title": "Start"
},
"end": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New end time (RFC 3339 or YYYY-MM-DD)",
"title": "End"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New description",
"title": "Description"
},
"location": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New location",
"title": "Location"
},
"attendees": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Full replacement list of attendee emails",
"title": "Attendees"
},
"add_attendees": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Emails to add to existing attendee list",
"title": "Add Attendees"
},
"remove_attendees": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Emails to remove from existing attendee list",
"title": "Remove Attendees"
},
"send_updates": {
"default": "all",
"description": "'all', 'externalOnly', 'none'",
"title": "Send Updates",
"type": "string"
},
"recurrence": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Updated RRULE strings (requires timezone)",
"title": "Recurrence"
},
"reminders": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Updated reminders",
"title": "Reminders"
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "IANA timezone (e.g. 'America/New_York'). Required when updating recurrence",
"title": "Timezone"
},
"conference": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Add/remove Google Meet link",
"title": "Conference"
},
"visibility": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Updated visibility",
"title": "Visibility"
},
"transparency": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Updated transparency",
"title": "Transparency"
},
"color_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Updated color ID",
"title": "Color Id"
},
"account": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional Google account override (email). Pass the same account used to fetch this event_id from search_events — event and calendar IDs are scoped to the account they came from.",
"title": "Account"
}
},
"required": [
"event_id"
],
"title": "UpdateEventParams",
"type": "object",
"additionalProperties": false
} Result schema (JSON)
{
"description": "Result of update_event.",
"properties": {
"event": {
"additionalProperties": true,
"title": "Event",
"type": "object"
}
},
"title": "UpdateEventResult",
"type": "object"
} # update_event_instance write
Update a single instance of a recurring Google Calendar event.
Full description
Update a single instance of a recurring event.
Use this instead of update_event when you want to modify just one occurrence
(e.g., 'move just this week's standup to 3pm'). The master event remains unchanged.
Parameters:
Same as update_event. The event_id must be an instance ID
(format: {master_id}_{YYYYMMDDTHHMMSSZ}) from search_events with
single_events=true.
Returns:
UpdateEventInstanceResult with the updated instance event object
Notes:
- Instance IDs have the format {master_id}_{YYYYMMDDTHHMMSSZ}
- Modifying an instance creates an 'exception' in the recurring event | Parameter | Type | Required | Description |
|---|---|---|---|
calendar_id | string | No | Calendar ID Default: "primary" |
event_id | string | Yes | Instance ID (format: {master_id}_{YYYYMMDDTHHMMSSZ}) |
summary | string | null | No | New event title |
start | string | null | No | New start time (RFC 3339 or YYYY-MM-DD) |
end | string | null | No | New end time (RFC 3339 or YYYY-MM-DD) |
description | string | null | No | New description |
location | string | null | No | New location |
attendees | array<string> | null | No | Full replacement list of attendee emails |
add_attendees | array<string> | null | No | Emails to add to existing attendee list |
remove_attendees | array<string> | null | No | Emails to remove from existing attendee list |
send_updates | string | No | 'all', 'externalOnly', 'none' Default: "all" |
reminders | object | null | No | Updated reminders |
timezone | string | null | No | IANA timezone |
conference | boolean | null | No | Add/remove Google Meet link |
visibility | string | null | No | Updated visibility |
transparency | string | null | No | Updated transparency |
color_id | string | null | No | Updated color ID |
account | string | null | No | Optional Google account override (email). Pass the same account used to fetch this instance event_id from search_events — event and calendar IDs are scoped to the account they came from. |
Parameter schema (JSON)
{
"description": "Parameters for update_event_instance. Same as update_event but event_id must be an instance ID.",
"properties": {
"calendar_id": {
"default": "primary",
"description": "Calendar ID",
"title": "Calendar Id",
"type": "string"
},
"event_id": {
"description": "Instance ID (format: {master_id}_{YYYYMMDDTHHMMSSZ})",
"title": "Event Id",
"type": "string"
},
"summary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New event title",
"title": "Summary"
},
"start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New start time (RFC 3339 or YYYY-MM-DD)",
"title": "Start"
},
"end": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New end time (RFC 3339 or YYYY-MM-DD)",
"title": "End"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New description",
"title": "Description"
},
"location": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New location",
"title": "Location"
},
"attendees": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Full replacement list of attendee emails",
"title": "Attendees"
},
"add_attendees": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Emails to add to existing attendee list",
"title": "Add Attendees"
},
"remove_attendees": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Emails to remove from existing attendee list",
"title": "Remove Attendees"
},
"send_updates": {
"default": "all",
"description": "'all', 'externalOnly', 'none'",
"title": "Send Updates",
"type": "string"
},
"reminders": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Updated reminders",
"title": "Reminders"
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "IANA timezone",
"title": "Timezone"
},
"conference": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Add/remove Google Meet link",
"title": "Conference"
},
"visibility": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Updated visibility",
"title": "Visibility"
},
"transparency": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Updated transparency",
"title": "Transparency"
},
"color_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Updated color ID",
"title": "Color Id"
},
"account": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional Google account override (email). Pass the same account used to fetch this instance event_id from search_events — event and calendar IDs are scoped to the account they came from.",
"title": "Account"
}
},
"required": [
"event_id"
],
"title": "UpdateEventInstanceParams",
"type": "object",
"additionalProperties": false
} Result schema (JSON)
{
"description": "Result of update_event_instance.",
"properties": {
"event": {
"additionalProperties": true,
"title": "Event",
"type": "object"
}
},
"title": "UpdateEventInstanceResult",
"type": "object"
}