List Calendars

Get all calendars the user has access to, including owned calendars, shared calendars, and subscribed calendars.

Overview

The List Calendars tool retrieves all Google Calendars associated with your account. This includes:

• Your primary calendar
• Calendars you created
• Calendars shared with you
• Subscribed calendars (holidays, sports, etc.)

For each calendar, you'll get the calendar ID, name, timezone, color, and your access level (owner, writer, or reader).

Prerequisites

• A connected Google Account with OAuth authentication
• Google Calendar API enabled in your Google Cloud project
• Setup Guide

Usage

Basic Usage

{
  "tool": "google_calendar_List_Calendars",
  "arguments": {}
}

No input arguments needed - the tool automatically lists all calendars for the authenticated account.

Response Format

Success Response

{
  "success": true,
  "calendars": [
    {
      "id": "primary",
      "summary": "My Calendar",
      "description": "",
      "location": "",
      "timezone": "America/Los_Angeles",
      "color_id": "1",
      "background_color": "#9fc6e7",
      "foreground_color": "#000000",
      "access_role": "owner",
      "is_primary": true,
      "is_selected": true,
      "is_hidden": false
    },
    {
      "id": "xyz123@group.calendar.google.com",
      "summary": "Team Calendar",
      "description": "Shared team calendar",
      "location": "",
      "timezone": "America/New_York",
      "color_id": "5",
      "background_color": "#ff887c",
      "foreground_color": "#000000",
      "access_role": "writer",
      "is_primary": false,
      "is_selected": true,
      "is_hidden": false
    }
  ],
  "total_count": 2,
  "primary_calendar_id": "primary",
  "summary": {
    "total": 2,
    "owned": 1,
    "writable": 2,
    "read_only": 0
  }
}

Response Fields

Calendar Object

Field	Type	Description
id	string	Unique calendar identifier (use this for other calendar operations)
summary	string	Calendar name/title
description	string	Calendar description (may be empty)
location	string	Geographic location of the calendar
timezone	string	Calendar's timezone (e.g., "America/Los_Angeles")
color_id	string	Calendar color ID (1-11)
background_color	string	Hex color for calendar background
foreground_color	string	Hex color for calendar text
access_role	string	Your permission level: owner, writer, reader, or freeBusyReader
is_primary	boolean	Whether this is the user's primary calendar
is_selected	boolean	Whether calendar is shown in user's calendar list
is_hidden	boolean	Whether calendar is hidden from list

Summary Object

Field	Type	Description
total	number	Total number of calendars
owned	number	Number of calendars you own
writable	number	Number of calendars you can edit (owner + writer)
read_only	number	Number of calendars you can only read

Access Roles Explained

• owner: Full control - edit events, manage sharing, delete calendar
• writer: Can create and edit events, but cannot manage calendar settings or sharing
• reader: Can only view events, cannot make changes
• freeBusyReader: Can only see if times are busy or free (no event details)

Use Cases

1. Display User's Calendars in UI

{
  "tool": "google_calendar_List_Calendars",
  "arguments": {}
}

Use the response to populate a calendar selector dropdown, showing calendar names and colors.

2. Find Primary Calendar ID

// Response includes primary_calendar_id
{
  "primary_calendar_id": "primary",
  ...
}

Use "primary" as the calendar_id for other tools when you want to use the user's main calendar.

3. Identify Writable Calendars

Filter calendars where access_role is "owner" or "writer" to show only calendars where the user can create events.

4. Get Calendar Timezone

Each calendar includes its timezone, which is important for creating events with correct times.

Error Handling

Calendar API Not Enabled

Error:

{
  "error": "Google Calendar API is not enabled in your Google Cloud project.\n\nTo fix this:\n1. Go to: https://console.cloud.google.com/apis/library/calendar-json.googleapis.com\n2. Select your project (the one with your OAuth credentials)\n3. Click the 'Enable' button\n4. Wait a few seconds for it to activate\n5. Try this tool again..."
}

Solution:

1. Click the link in the error message
2. Select your Google Cloud project
3. Click "Enable" button
4. Wait 10-30 seconds for activation
5. Retry the tool

See Setup Guide for detailed instructions.

Authentication Failed

Error:

{
  "error": "Authentication failed. Your access token may have expired or been revoked..."
}

Solution:

• Disconnect and reconnect your Google Account in Reeva
• Ensure you granted Calendar permissions during OAuth flow

No Google Account Connected

Error:

{
  "error": "Google Calendar requires OAuth authentication. Please connect a Google Account."
}

Solution:

Connect a Google Account with OAuth following the Setup Guide.

Tips

1. Save Calendar IDs - The id field is what you'll use for creating/updating events
2. Check Access Role - Always verify access_role before attempting to create/edit events
3. Use Primary Calendar - "primary" is a special ID that always refers to the user's main calendar
4. Timezone Awareness - Note each calendar's timezone when creating events to avoid confusion
5. Hidden Calendars - Calendars with is_hidden: true are not shown in the user's calendar UI
6. Use with Get Events - After getting calendar IDs, use them with the Get Events tool to retrieve events from specific calendars

Limitations

1. OAuth Only - This tool requires OAuth authentication. App Password accounts cannot access Calendar API.
2. Rate Limits - Google Calendar API has rate limits (typically 1,000,000 requests/day on free tier)
3. Deleted Calendars - Deleted calendars are not included in the response

Related Tools

• Get Events - List or search events in a calendar
• Create Event (coming soon)
• Update Event (coming soon)
• Delete Event (coming soon)

Billing

Cost: 1 credit per execution

This tool has a fixed cost of 1 credit regardless of the number of calendars returned.