grr

Overview Schema Source Related Servers Discussions Admin

calendar.calendarList.list

Retrieve calendars from a user's calendar list with filters for access role, hidden or deleted entries, and paginated results.

Instructions

Returns the calendars on the user's calendar list [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, insert, patch, 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.
`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.
`syncToken`	No	[query parameter] 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 contai
`maxResults`	No	[query parameter] 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.
`showHidden`	No	[query parameter] Whether to show hidden entries. Optional. The default is False.
`showDeleted`	No	[query parameter] Whether to include deleted calendar list entries in the result. Optional. The default is False.
`minAccessRole`	No	[query parameter] The minimum access role for the user in the returned entries. Optional. The default is no restriction. Values: `freeBusyReader` = The user can read free/busy information.; `owner` = The user can read and modify events and access control lists.; `reader` = The user can read events that are not private.; `writer` = The user can read and modify events.; `writerWithoutPrivateAccess` = The user can read and modify events that aren't private. The user can read free/busy information about private events. The user can't modify private events..
`showOwnOrganizationOnly`	No	[query parameter] Whether to show only entries for calendars from the organization. This parameter is only applicable to Google Workspace users. Optional. The default is False.

Output Schema

Name	Required	Description	Default
`etag`	No
`kind`	No
`items`	No
`nextPageToken`	No
`nextSyncToken`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedOct 26, 2026

changedInput schema / properties / maxResults / description

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

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

changedInput schema / properties / minAccessRole / description

Previous value: -"The minimum access role for the user in the returned entries. Optional. The default is no restriction."New value: +"[query parameter] The minimum access role for the user in the returned entries. Optional. The default is no restriction. Values: `freeBusyReader` = The user can read free/busy information.; `owner` = The user can read and modify events and access control lists.; `reader` = The user can read events that are not private.; `writer` = The user can read and modify events.; `writerWithoutPrivateAccess` = The user can read and modify events that aren't private. The user can read free/busy information about private events. The user can't modify private events.."

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 calendar list entries in the result. Optional. The default is False."New value: +"[query parameter] Whether to include deleted calendar list entries in the result. Optional. The default is False."

changedInput schema / properties / showHidden / description

Previous value: -"Whether to show hidden entries. Optional. The default is False."New value: +"[query parameter] Whether to show hidden entries. Optional. The default is False."

changedInput schema / properties / showOwnOrganizationOnly / description

Previous value: -"Whether to show only entries for calendars from the organization. This parameter is only applicable to Google Workspace users. Optional. The default is False."New value: +"[query parameter] Whether to show only entries for calendars from the organization. This parameter is only applicable to Google Workspace users. Optional. The default is False."

changedInput schema / properties / syncToken / description

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

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "etag": {
+      "type": "string"
+    },
+    "items": {
+      "items": {
+        "properties": {
+          "accessRole": {
+            "type": "string"
+          },
+          "autoAcceptInvitations": {
+            "type": "boolean"
+          },
+          "backgroundColor": {
+            "type": "string"
+          },
+          "colorId": {
+            "type": "string"
+          },
+          "conferenceProperties": {
+            "properties": {
+              "allowedConferenceSolutionTypes": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              }
+            },
+            "type": "object"
+          },
+          "dataOwner": {
+            "type": "string"
+          },
+          "defaultReminders": {
+            "items": {
+              "properties": {
+                "method": {
+                  "type": "string"
+                },
+                "minutes": {
+                  "type": "integer"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "deleted": {
+            "type": "boolean"
+          },
+          "description": {
+            "type": "string"
+          },
+          "etag": {
+            "type": "string"
+          },
+          "foregroundColor": {
+            "type": "string"
+          },
+          "hidden": {
+            "type": "boolean"
+          },
+          "id": {
+            "type": "string"
+          },
+          "kind": {
+            "type": "string"
+          },
+          "location": {
+            "type": "string"
+          },
+          "notificationSettings": {
+            "properties": {
+              "notifications": {
+                "items": {
+                  "properties": {
+                    "method": {
+                      "type": "string"
+                    },
+                    "type": {
+                      "type": "string"
+                    }
+                  },
+                  "type": "object"
+                },
+                "type": "array"
+              }
+            },
+            "type": "object"
+          },
+          "primary": {
+            "type": "boolean"
+          },
+          "selected": {
+            "type": "boolean"
+          },
+          "summary": {
+            "type": "string"
+          },
+          "summaryOverride": {
+            "type": "string"
+          },
+          "timeZone": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "kind": {
+      "type": "string"
+    },
+    "nextPageToken": {
+      "type": "string"
+    },
+    "nextSyncToken": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

First observedOct 26, 2026

TDQS

B3.3/5.0

Behavior3/5

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

With no annotations, the description does disclose that this is an HTTP GET returning JSON, which establishes the read-only safety profile. However, it omits pagination behavior, auth/scope requirements, the meaning of sync tokens, and instead spends its second sentence on body-building mechanics that are irrelevant to a GET.

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

Conciseness3/5

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

The purpose and sibling list are front-loaded and useful, but the middle sentence about request bodies and `body_file` is generic wrapper boilerplate that cannot apply to a GET/list and dilutes the signal.

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

Completeness3/5

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

The tool has an output schema and full parameter documentation, so the description needn't explain return values or filters. What's still missing is the one thing structured fields can't cover: guidance on choosing this over calendar.calendars.list and other list siblings.

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 description coverage is 100%, so all 11 parameters (pageToken, syncToken, maxResults, showHidden, showDeleted, minAccessRole, showOwnOrganizationOnly, plus wrapper params) are already documented. The description only restates that typed flags win over the `params` map, which the schema also says, so it adds nothing beyond the baseline.

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?

The first clause states a specific verb and resource ('Returns the calendars on the user's calendar list [HTTP GET]') and the sibling line names the operations over the same resource, so an agent can distinguish list from get/insert/delete. The remaining gap is that it doesn't contrast with the closely-named sibling calendar.calendars.list.

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?

Listing siblings over the same resource ('delete, get, insert, patch, update, watch') implies the alternative set, but there is no explicit when-to-use guidance and no distinction from calendar.calendars.list, which is the tool an agent is most likely to confuse with this one.

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

Deploy Server