DocumentationGoogle Calendar
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 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_connectionsto confirmgoogle-calendaris connected and get the exact tool names. - Read —
google_calendar_list_events(what's next) orgoogle_calendar_search_events(by text). Usegoogle_calendar_list_calendarsto target a non-primary calendar. - Write —
google_calendar_create_eventto add an event, orgoogle_calendar_update_eventto change one (pass itseventId). - 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 requiresconnectors: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.