# Google Calendar connector

When a user connects their Google Calendar, your agent gets tools to list and search their events, list their calendars, and create or update events on their behalf. Read is separate from write, gated by distinct scopes.

## Overview

The Google Calendar connector lets your agent read and manage a user's schedule. The user authorizes ONBF **once** with Google's Calendar scopes; ONBF vaults and refreshes the OAuth token and exposes the tools on the run's session token. You never register a Google app, request scopes or handle a callback — see **[Connectors](/docs/connectors)** for the zero-setup model.

> **Read + create/update events:** Calendar uses `calendar.readonly` (list/search events, list calendars) and `calendar.events` (create/update events). The narrower `calendar.events` scope is used deliberately — it can create and edit events but never delete a whole calendar.

## Tools

These tools are exposed when the builder selects Google Calendar under Required connectors. Read calls require `connectors:use`; writes also require `connectors:write`. User connection status is checked when a tool runs.

| Tool | Access | What it does | Key arguments |
| --- | --- | --- | --- |
| `google_calendar_list_events` | Read | List upcoming events (defaults to the primary calendar, from now, ordered by start). Recurring events are expanded into instances. | `calendarId`, `timeMin`, `timeMax`, `maxResults`, `pageToken` (all optional). |
| `google_calendar_search_events` | Read | Search events by free-text query within an optional time window. | `query`; `calendarId`, `timeMin`, `timeMax`, `maxResults`, `pageToken` (optional). |
| `google_calendar_list_calendars` | Read | List the user's calendars — `id`, `summary`, whether it's `primary`, and access role. | — |
| `google_calendar_create_event` | Write | Create an event (defaults to the primary calendar). Returns the created event with its id and web link. | `summary`, `start`, `end` (ISO-8601); `description`, `location`, `attendees`, `calendarId` (optional). |
| `google_calendar_update_event` | Write | Patch an existing event by id — only the fields you pass change; omitted fields are preserved. | `eventId`; any of `summary`, `start`, `end`, `description`, `location`, `attendees`, `calendarId`. |

## Typical flow

- **Discover** — call `list_connections` to confirm `google-calendar` is connected and get the exact tool names.
- **Read** — `google_calendar_list_events` (what's next) or `google_calendar_search_events` (by text). Use `google_calendar_list_calendars` to target a non-primary calendar.
- **Write** — `google_calendar_create_event` to add an event, or `google_calendar_update_event` to change one (pass its `eventId`).
- **Confirm back** — the write tools return the resulting event (with its `htmlLink`); relay it to the user.

## Access & consent

- **Read vs write are separate** — reading requires `connectors:use`; creating/updating requires `connectors:write`. A read-only grant can never modify the calendar.
- **Per-user & revocable** — each user connects their own account and can disconnect it anytime from their ONBF dashboard under **Connectors**.
- **Allowlisted by the builder** — tools appear when Calendar is selected under Required connectors and the credential has the needed scope. If this user has not connected Calendar, calls return `{ connected: false, message }` — prompt them to connect, then retry.

> **Google verification:** `calendar.readonly` and `calendar.events` are Google 'sensitive' scopes. Test users work immediately; a public launch requires Google app verification for these scopes.