list_events

This reference is generated from the published tool contract.

Behavior and boundaries

Lists events from selected Google, Microsoft or CalDAV calendars in a UTC interval of at most 744 elapsed hours (31 times 24 hours), filtered by the detail level chosen for this assistant (busy only, title and time, or full details). CalDAV series are read including exceptions; CalDAV RSVP and CalDAV series creation are not supported. canEdit and canRespond include this assistant’s current permissions as well as provider and calendar restrictions. When canEdit is false, editBlockedReason explains the verified restriction or reports unknown; do not infer a read-only calendar from canEdit alone. Each event includes the connected user’s current RSVP status when known. Events that overlap the interval are returned with their real start and duration, even if they began earlier. If a calendar or part of the interval cannot be read, the remaining events are still returned and warnings names each affected calendarId with the missing UTC ranges or skipped events; tell the user the result does not cover them. Actions recheck permissions and provider state before writing.

Permissions

Granted scopes, accounts, calendars and visibility rules limit access. Workspace administrators do not automatically gain access to other users’ accounts.

calendar:read

Consent and boundaries

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "calendarIds": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "start": {
      "type": "string",
      "description": "Inclusive ISO 8601 date-time."
    },
    "end": {
      "type": "string",
      "description": "Exclusive ISO 8601 date-time, at most 744 elapsed hours after start. Split longer periods into consecutive windows; daylight-saving changes affect elapsed duration."
    },
    "timeZone": {
      "description": "User-confirmed IANA timezone for CalDAV all-day and floating times, e.g. Europe/Berlin. Supply it for CalDAV; ask the user if unknown. Does not change absolute event timestamps.",
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "calendarIds",
    "start",
    "end"
  ],
  "additionalProperties": false
}

Output

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "termine": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "eventId": {
            "type": "string"
          },
          "calendarId": {
            "type": "string"
          },
          "occurrenceId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "locations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "coordinates": {
                  "type": "string"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            }
          },
          "virtualLocations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "uri": {
                  "type": "string"
                }
              },
              "required": [
                "uri"
              ],
              "additionalProperties": false
            }
          },
          "links": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "href": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "rel": {
                  "type": "string"
                }
              },
              "required": [
                "href"
              ],
              "additionalProperties": false
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "color": {
            "type": "string"
          },
          "start": {
            "type": "string"
          },
          "timeZone": {
            "type": "string"
          },
          "duration": {
            "type": "string"
          },
          "showWithoutTime": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "confirmed",
              "tentative",
              "cancelled"
            ]
          },
          "freeBusyStatus": {
            "type": "string",
            "enum": [
              "free",
              "busy"
            ]
          },
          "canRespond": {
            "type": "boolean",
            "description": "Whether this assistant may respond, subject to a fresh provider check."
          },
          "editBlockedReason": {
            "description": "Why editing is unavailable. Only calendar_read_only means the calendar is read-only; unknown means no verified reason.",
            "type": "string",
            "enum": [
              "calendar_read_only",
              "access_denied",
              "recurring_event",
              "not_organizer",
              "guests_or_scheduling",
              "conference",
              "managed_copy",
              "version_unavailable",
              "unknown"
            ]
          },
          "canEdit": {
            "type": "boolean",
            "description": "Whether this assistant may edit or delete, subject to a fresh provider check."
          },
          "responseStatus": {
            "type": "string",
            "enum": [
              "needs-action",
              "accepted",
              "declined",
              "tentative"
            ]
          },
          "privacy": {
            "type": "string",
            "enum": [
              "public",
              "private",
              "secret"
            ]
          },
          "alerts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "offset": {
                  "type": "string"
                },
                "action": {
                  "type": "string",
                  "enum": [
                    "display",
                    "email"
                  ]
                }
              },
              "required": [
                "offset"
              ],
              "additionalProperties": false
            }
          },
          "workingLocation": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "home",
                  "office",
                  "custom"
                ]
              },
              "label": {
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "eventId",
          "calendarId",
          "occurrenceId",
          "title",
          "start",
          "duration",
          "showWithoutTime",
          "status",
          "freeBusyStatus",
          "canRespond",
          "canEdit"
        ],
        "additionalProperties": false
      }
    },
    "warnings": {
      "description": "Present only when the result is incomplete: names each calendar and UTC range whose events are missing. Tell the user the result does not cover them.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "calendarId": {
            "type": "string"
          },
          "reason": {
            "type": "string",
            "enum": [
              "calendar_unavailable",
              "time_range_incomplete",
              "events_skipped"
            ]
          },
          "ranges": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "start": {
                  "type": "string"
                },
                "end": {
                  "type": "string"
                }
              },
              "required": [
                "start",
                "end"
              ],
              "additionalProperties": false
            }
          },
          "skippedEvents": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "calendarId",
          "reason",
          "message"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "ok",
    "termine"
  ],
  "additionalProperties": false
}

Errors and retries

Check the tool result for errors. Do not blindly retry writes after a timeout. Check the current resource or send status first.

Error handling