Knowledge & tools

Google Calendar & Sheets tools

Two Google tools that share one setup. Google Calendar books, checks and manages events - the natural companion to a voice receptionist. Google Sheets reads and writes spreadsheet data - lead logs, order lists, small reports. Both connect through a single Google Cloud OAuth setup you do once, so if you're using both tools you only go through the steps below one time.

Publish your OAuth consent screen to production, or the connection dies after 7 days. This is the one setting that catches people out. The connection uses a permanent refresh token you mint once. But a token minted while the Google Cloud project's consent screen is still in "Testing" mode stops working after exactly 7 days - everything runs fine for a week, then quietly breaks. Set the consent screen to "In production" before you mint the token (step 3). The "unverified app" warning Google shows is expected and fine for your own account.

Google Calendar - what it does

Eight actions. The calendar_id defaults to the account's primary calendar.

list_calendars - the calendars on the account.
list_events - events in a time window (time_min / time_max), with an optional text filter; recurring events are expanded.
get_event - a single event's details.
create_event - summary, start_time and end_time (RFC3339) are required; optional description, location, attendee emails and IANA timezone. Set notify_attendees to email invitations.
update_event - change any field (partial update).
delete_event - remove an event; notify_attendees emails a cancellation.
check_availability - free/busy across one or more calendars.
quick_add - create an event from a natural-language phrase.

Google Sheets - what it does

Nine actions. Ranges use A1 notation (Sheet1!A1:C10). Cell values are parsed the way typed input is - "42" becomes a number, "2026-07-19" a date, "=SUM(A1:A5)" a formula.

create_spreadsheet - make a new spreadsheet (returns its id and URL).
get_spreadsheet - the tabs and their sizes.
read_range - read a range of cells.
append_rows - add rows at the bottom of a table.
update_range - overwrite specific cells.
clear_range - empty a range.
add_sheet - add a new tab.
find_replace - find and replace across the whole spreadsheet.
delete_spreadsheet - delete a spreadsheet the tool created (see the limitation below).

Before you start

You need:

The Google account whose calendar and spreadsheets the agent will use.
Access to the Google Cloud Console (console.cloud.google.com) for that account.

One-time Google Cloud setup

This single setup serves both tools. Do it once, then paste the same three values into each tool you use.

Create a project at console.cloud.google.com.
Enable the APIs under APIs & Services → Library: Google Calendar API, Google Sheets API, and Google Drive API (Drive is required for deleting spreadsheets). Enabling an API is a separate switch from granting its scope - skip it and calls fail with a "has not been used or is disabled" 403.
Publish the OAuth consent screen. OAuth consent screen → External → Publish to Production. Add the scopes .../auth/calendar, .../auth/spreadsheets and .../auth/drive.file. See the callout at the top - this is the step that makes the token permanent.
Create an OAuth Client ID. Credentials → Create OAuth Client ID → type Web application, and add the redirect URI https://developers.google.com/oauthplayground.
Mint the refresh token at the OAuth Playground: open the gear icon (top right), tick "Use your own OAuth credentials" and paste the Client ID and Secret; in Step 1 authorize the three scopes as the target Google account; in Step 2 exchange the authorization code for tokens; copy the refresh token.
Paste Client ID + Client Secret + Refresh Token into the Hania tool form and save.

Google updates the Cloud Console and Playground from time to time, so treat the section names above as authoritative and the exact labels as approximate - find the named screen if a label has moved.

Connecting both tools

Because Calendar and Sheets share one Google account setup, connecting both is easy: do the Google Cloud steps once, then create a configuration for each tool and paste the same three values (Client ID, Client Secret, Refresh Token) into each. The refresh token you minted authorized all three scopes, so it works for both. Behind the scenes Hania shares the minted access token between the tools.

Field reference

Both tools use the same three fields, all required:

Client ID (required) - the OAuth Client ID from your Google Cloud project (APIs & Services → Credentials).
Client Secret (required, secret) - the OAuth client's secret. Stored encrypted and never returned.
Refresh Token (required, secret) - a permanent refresh token for the Google account. The consent screen must be published "In production" - a token minted in "Testing" mode expires after 7 days. Access tokens are minted from it automatically.

Sheets deletion limitation

The Sheets tool can only delete spreadsheets it created itself. This is a safety boundary of the drive.file scope, which grants access only to files the app made - not your whole Drive. Ask the agent to delete a spreadsheet it didn't create and the call comes back "not found". So don't expect the agent to tidy up files it never touched; it can only remove ones it made.

Working with the agents

Two blueprints give you a configured agent in one click - you supply only the credentials from this guide:

Scheduling Assistant (Calendar) - checks availability before booking, confirms with you before it changes anything on your calendar, and can email invitations to attendees.
Spreadsheet Assistant (Sheets) - reads the data before writing, and confirms with you before it overwrites or clears cells.

Both are built for the write-carefully habits that matter when an agent is touching a real calendar or a live spreadsheet.

Troubleshooting

Works, then breaks after about a week - the consent screen was still in "Testing" when the token was minted. Publish it to Production (step 3) and mint a fresh refresh token.
"unauthorized_client" error - the token was minted without ticking "Use your own OAuth credentials" in the Playground. Re-mint with your own credentials pasted in.
A "Drive / Calendar / Sheets API has not been used… or is disabled" 403 - that API isn't enabled in the Cloud project. Enable it (step 2) and wait a minute before retrying.
PERMISSION_DENIED / NOT_FOUND / INVALID_ARGUMENT - Google's own error, surfaced verbatim in the trace. NOT_FOUND on a spreadsheet delete usually means the tool didn't create that file (see the limitation).
Validation errors (a missing required field, an empty update) - the agent self-corrects these, so they may flash through a trace before the call succeeds.

Safety in autonomous runs

Like any tool, these carry a safety classification (read-only / destructive / sends-data-externally) that governs scheduled or triggered (autonomous) runs. Because both tools change real data - events that email people, spreadsheet cells that get overwritten or cleared - a new configuration of either is created with Read-only switched off, Destructive switched on, and Sends data externally on. Destructive actions are then gated in autonomous runs unless the bot's "Allow destructive actions in autonomous runs" is enabled. Keep those defaults, and let the blueprints' confirmation prompts do their job. Interactive chat is never gated by these flags.

Security

The Client Secret and Refresh Token are stored AES-encrypted at rest and are never returned by the API - the console shows only whether each is set. Editing a configuration without retyping a secret preserves the stored one, so you must retype it to replace it. To revoke access, remove the app's access in your Google account's security settings or delete the OAuth client in the Cloud Console.