grr

Overview Schema Source Related Servers Discussions Admin

calendar.events.instances

Retrieve instances of a specified recurring calendar event, filtered by time range, timezone, attendees, or pagination, to inspect each occurrence.

Instructions

Returns instances of the specified recurring event [HTTP GET]. Returns the requested resource as JSON — request bodies are built from the typed parameters (typed flags win over the params map), or read whole from body_file Siblings over the same resource: delete, get, import, insert, list, move, patch, quickAdd, update, watch.

Input Schema

Name	Required	Description
`query`	No	Extra KEY=VALUE query pairs for endpoints whose parameters Discovery does not describe.
`params`	No	Parameter map merged into the request; typed parameters win.
`dry_run`	No	Return the request that would be sent, without sending it.
`eventId`	Yes	[URL path segment] Recurring event identifier.
`timeMax`	No	[query parameter] 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 mandator
`timeMin`	No	[query parameter] 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 ti
`timeZone`	No	[query parameter] Time zone used in the response. Optional. The default is the time zone of the calendar.
`body_file`	No	Read the request body from this file ('-' for stdin) instead of building one from the parameters.
`pageToken`	No	[query parameter] Token specifying which result page to return. Optional.
`calendarId`	Yes	[URL path segment] 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
`maxResults`	No	[query parameter] 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`	No	[query parameter] Whether to include deleted events (with status equals "cancelled") in the result. Cancelled instances of recurring events will still be included if singleEvents
`maxAttendees`	No	[query parameter] 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`	No	[query parameter] The original start time of the instance in the result. Optional.
`alwaysIncludeEmail`	No	[query parameter] Deprecated and ignored. A value will always be returned in the email field for the organizer, creator and attendees, even if no real email address is available

Output Schema

Name	Required	Description	Default
`etag`	No
`kind`	No
`items`	No
`summary`	No
`updated`	No
`timeZone`	No
`accessRole`	No
`description`	No
`nextPageToken`	No
`nextSyncToken`	No
`defaultReminders`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed18 schema fields changedOct 26, 2026

changedInput schema / properties / alwaysIncludeEmail / description

Previous value: -"Deprecated and ignored. A value will always be returned in the email field for the organizer, creator and attendees, even if no real email address is available "New value: +"[query parameter] Deprecated and ignored. A value will always be returned in the email field for the organizer, creator and attendees, even if no real email address is available "

changedInput schema / properties / calendarId / description

Previous value: -"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"New value: +"[URL path segment] 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"

changedInput schema / properties / eventId / description

Previous value: -"Recurring event identifier."New value: +"[URL path segment] Recurring event identifier."

changedInput schema / properties / maxAttendees / description

Previous value: -"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"New value: +"[query parameter] 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"

addedInput schema / properties / maxAttendees / format
```
Added value: +"int32"
```
addedInput schema / properties / maxAttendees / minimum
```
Added value: +1
```

changedInput schema / properties / maxResults / description

Previous value: -"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."New value: +"[query parameter] 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."

addedInput schema / properties / maxResults / format
```
Added value: +"int32"
```
addedInput schema / properties / maxResults / minimum
```
Added value: +1
```

changedInput schema / properties / originalStart / description

Previous value: -"The original start time of the instance in the result. Optional."New value: +"[query parameter] The original start time of the instance in the result. Optional."

changedInput schema / properties / pageToken / description

Previous value: -"Token specifying which result page to return. Optional."New value: +"[query parameter] Token specifying which result page to return. Optional."

changedInput schema / properties / showDeleted / description

Previous value: -"Whether to include deleted events (with status equals \"cancelled\") in the result. Cancelled instances of recurring events will still be included if singleEvents"New value: +"[query parameter] Whether to include deleted events (with status equals \"cancelled\") in the result. Cancelled instances of recurring events will still be included if singleEvents"

changedInput schema / properties / timeMax / description

Previous value: -"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 mandator"New value: +"[query parameter] 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 mandator"

addedInput schema / properties / timeMax / format
```
Added value: +"date-time"
```

changedInput schema / properties / timeMin / description

Previous value: -"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 ti"New value: +"[query parameter] 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 ti"

addedInput schema / properties / timeMin / format
```
Added value: +"date-time"
```

changedInput schema / properties / timeZone / description

Previous value: -"Time zone used in the response. Optional. The default is the time zone of the calendar."New value: +"[query parameter] Time zone used in the response. Optional. The default is the time zone of the calendar."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "accessRole": {
+      "type": "string"
+    },
+    "defaultReminders": {
+      "items": {
+        "properties": {
+          "method": {
+            "type": "string"
+          },
+          "minutes": {
+            "type": "integer"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "description": {
+      "type": "string"
+    },
+    "etag": {
+      "type": "string"
+    },
+    "items": {
+      "items": {
+        "properties": {
+          "anyoneCanAddSelf": {
+            "type": "boolean"
+          },
+          "attachments": {
+            "items": {
+              "properties": {
+                "fileId": {
+                  "type": "string"
+                },
+                "fileUrl": {
+                  "type": "string"
+                },
+                "iconLink": {
+                  "type": "string"
+                },
+                "mimeType": {
+                  "type": "string"
+                },
+                "title": {
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "attendees": {
+            "items": {
+              "properties": {
+                "additionalGuests": {
+                  "type": "integer"
+                },
+                "asyncOperation": {
+                  "type": "string"
+                },
+                "comment": {
+                  "type": "string"
+                },
+                "displayName": {
+                  "type": "string"
+                },
+                "email": {
+                  "type": "string"
+                },
+                "id": {
+                  "type": "string"
+                },
+                "optional": {
+                  "type": "boolean"
+                },
+                "organizer": {
+                  "type": "boolean"
+                },
+                "resource": {
+                  "type": "boolean"
+                },
+                "responseStatus": {
+                  "type": "string"
+                },
+                "self": {
+                  "type": "boolean"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "attendeesOmitted": {
+            "type": "boolean"
+          },
+          "birthdayProperties": {
+            "properties": {
+              "contact": {
+                "type": "string"
+              },
+              "customTypeName": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "colorId": {
+            "type": "string"
+          },
+          "conferenceData": {
+            "properties": {
+              "conferenceId": {
+                "type": "string"
+              },
+              "conferenceSolution": {
+                "properties": {
+                  "iconUri": {
+                    "type": "string"
+                  },
+                  "key": {
+                    "type": "object"
+                  },
+                  "name": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "createRequest": {
+                "properties": {
+                  "conferenceSolutionKey": {
+                    "type": "object"
+                  },
+                  "requestId": {
+                    "type": "string"
+                  },
+                  "status": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              },
+              "entryPoints": {
+                "items": {
+                  "properties": {
+                    "accessCode": {
+                      "type": "string"
+                    },
+                    "entryPointFeatures": {
+                      "items": {
+                        "type": "string"
+                      },
+                      "type": "array"
+                    },
+                    "entryPointType": {
+                      "type": "string"
+                    },
+                    "label": {
+                      "type": "string"
+                    },
+                    "meetingCode": {
+                      "type": "string"
+                    },
+                    "passcode": {
+                      "type": "string"
+                    },
+                    "password": {
+                      "type": "string"
+                    },
+                    "pin": {
+                      "type": "string"
+                    },
+                    "regionCode": {
+                      "type": "string"
+                    },
+                    "uri": {
+                      "type": "string"
+                    }
+                  },
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "notes": {
+                "type": "string"
+              },
+              "parameters": {
+                "properties": {
+                  "addOnParameters": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              },
+              "signature": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "created": {
+            "type": "string"
+          },
+          "creator": {
+            "properties": {
+              "displayName": {
+                "type": "string"
+              },
+              "email": {
+                "type": "string"
+              },
+              "id": {
+                "type": "string"
+              },
+              "self": {
+                "type": "boolean"
+              }
+            },
+            "type": "object"
+          },
+          "description": {
+            "type": "string"
+          },
+          "end": {
+            "properties": {
+              "date": {
+                "type": "string"
+              },
+              "dateTime": {
+                "type": "string"
+              },
+              "timeZone": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "endTimeUnspecified": {
+            "type": "boolean"
+          },
+          "etag": {
+            "type": "string"
+          },
+          "eventLabelId": {
+            "type": "string"
+          },
+          "eventType": {
+            "type": "string"
+          },
+          "extendedProperties": {
+            "properties": {
+              "private": {
+                "type": "object"
+              },
+              "shared": {
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "focusTimeProperties": {
+            "properties": {
+              "autoDeclineMode": {
+                "type": "string"
+              },
+              "chatStatus": {
+                "type": "string"
+              },
+              "declineMessage": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "gadget": {
+            "properties": {
+              "display": {
+                "type": "string"
+              },
+              "height": {
+                "type": "integer"
+              },
+              "iconLink": {
+                "type": "string"
+              },
+              "link": {
+                "type": "string"
+              },
+              "preferences": {
+                "type": "object"
+              },
+              "title": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string"
+              },
+              "width": {
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          },
+          "guestsCanInviteOthers": {
+            "type": "boolean"
+          },
+          "guestsCanModify": {
+            "type": "boolean"
+          },
+          "guestsCanSeeOtherGuests": {
+            "type": "boolean"
+          },
+          "hangoutLink": {
+            "type": "string"
+          },
+          "htmlLink": {
+            "type": "string"
+          },
+          "iCalUID": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string"
+          },
+          "kind": {
+            "type": "string"
+          },
+          "location": {
+            "type": "string"
+          },
+          "locked": {
+            "type": "boolean"
+          },
+          "organizer": {
+            "properties": {
+              "displayName": {
+                "type": "string"
+              },
+              "email": {
+                "type": "string"
+              },
+              "id": {
+                "type": "string"
+              },
+              "self": {
+                "type": "boolean"
+              }
+            },
+            "type": "object"
+          },
+          "originalStartTime": {
+            "properties": {
+              "date": {
+                "type": "string"
+              },
+              "dateTime": {
+                "type": "string"
+              },
+              "timeZone": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "outOfOfficeProperties": {
+            "properties": {
+              "autoDeclineMode": {
+                "type": "string"
+              },
+              "declineMessage": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "privateCopy": {
+            "type": "boolean"
+          },
+          "recurrence": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "recurringEventId": {
+            "type": "string"
+          },
+          "reminders": {
+            "properties": {
+              "overrides": {
+                "items": {
+                  "properties": {
+                    "method": {
+                      "type": "string"
+                    },
+                    "minutes": {
+                      "type": "integer"
+                    }
+                  },
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "useDefault": {
+                "type": "boolean"
+              }
+            },
+            "type": "object"
+          },
+          "sequence": {
+            "type": "integer"
+          },
+          "source": {
+            "properties": {
+              "title": {
+                "type": "string"
+              },
+              "url": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "start": {
+            "properties": {
+              "date": {
+                "type": "string"
+              },
+              "dateTime": {
+                "type": "string"
+              },
+              "timeZone": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "status": {
+            "type": "string"
+          },
+          "summary": {
+            "type": "string"
+          },
+          "transparency": {
+            "type": "string"
+          },
+          "updated": {
+            "type": "string"
+          },
+          "visibility": {
+            "type": "string"
+          },
+          "workingLocationProperties": {
+            "properties": {
+              "customLocation": {
+                "properties": {
+                  "label": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "homeOffice": {
+                "type": "any"
+              },
+              "officeLocation": {
+                "properties": {
+                  "buildingId": {
+                    "type": "string"
+                  },
+                  "deskId": {
+                    "type": "string"
+                  },
+                  "floorId": {
+                    "type": "string"
+                  },
+                  "floorSectionId": {
+                    "type": "string"
+                  },
+                  "label": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "type": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "kind": {
+      "type": "string"
+    },
+    "nextPageToken": {
+      "type": "string"
+    },
+    "nextSyncToken": {
+      "type": "string"
+    },
+    "summary": {
+      "type": "string"
+    },
+    "timeZone": {
+      "type": "string"
+    },
+    "updated": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

First observedOct 26, 2026

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does disclose that this is an HTTP GET returning JSON and explains request-body construction precedence, but it omits key behavior: what happens when eventId refers to a non-recurring event, how pagination (pageToken/maxResults) behaves across pages, and any auth/permission requirements for reading a calendar's events.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first clause and the transport mechanics follow compactly. The trailing sibling enumeration is a low-value name dump that lengthens the definition without helping selection, keeping it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and 15 parameters are fully covered by the schema. Given a read operation of moderate complexity, the description supplies purpose, method, and body-construction mechanics — enough for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline of 3 applies and the schema already documents path segments, query params, and body_file/dry_run. The description's one added rule — 'typed flags win over the `params` map' — restates what the params schema already says, adding no new parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Returns instances of the specified recurring event', which is genuinely distinct from calendar.events.get (one event) and calendar.events.list (all events). The sibling line is a bare name dump with no differentiation guidance, so the tool's own identity is clear but the sibling contrast is left implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied — the agent must infer that this is the right tool when it has a recurring event ID and wants its individual occurrences. The sibling list nominally provides alternatives (get, list, instances) but never says which condition selects which, and no prerequisites or exclusions are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server