Google Drive and Sheets

​

Overview

The Google Drive integration gives configured agents access to Drive files and shared drives. The same durable OAuth connection also authorizes native Google Sheets tools for spreadsheet metadata, bounded ranges, cell edits, and creation. There is no separate Google Sheets connection or token store. Choose one authorization mode:

• Each member connects: tools use the acting member’s Google account and inherit that person’s Drive and spreadsheet permissions.
• Org service account: an administrator connects one intentionally shared Google account whose access is used by the organization’s configured agents.

Both modes store refresh tokens server-side and refresh access tokens when needed. If Google revokes a grant, reconnect Google Drive in Control Hub. Choose an access level independently of the authorization mode:

• Read only (recommended): uses Google’s drive.readonly grant. Agents can search, list, inspect, read, export, and download Drive files and Google Docs, and can read Google Sheets metadata and bounded ranges. Server-side policy rejects create, upload, copy, move, edit, append, and clear operations.
• Read and write: uses Google’s full drive grant and enables those mutation workflows for agents that are also configured with mutation tools.

The runtime applies the stricter of the organization policy and the actual OAuth token scope. Downgrading the policy blocks writes immediately; reconnect to replace the previously broad Google grant with a read-only refresh token. Upgrading also requires reconnecting before writes become available. In per-user mode, each member reconnects their own account after an access-level change.

​

Setup

​

Native Google Sheets tools

All three tools require the Google Drive integration (google_drive). They do not add a Sheets OAuth card, alter Clerk login, delete spreadsheets, or delete tabs. In read-only mode, google_sheets_read is available while google_sheets_edit and google_sheets_create fail before sending a mutation to Google. Tool selection still provides a second layer of control: omit mutation tools from agents that should never request them, even in an organization with read-and-write Drive access.

​

Read behavior and limits

Omit ranges from google_sheets_read to inspect only the spreadsheet and tab metadata. With ranges, use bounded A1 notation such as 'Revenue 2026'!A1:F100. Whole-row and whole-column ranges are rejected so a call cannot accidentally load an arbitrarily large workbook.

• A request accepts at most 20 ranges covering at most 50,000 addressable cells.
• Output defaults to at most 10,000 non-empty cells and 100,000 text characters.
• Results report whether they were truncated and how many returned cells were omitted. Read smaller ranges to continue.
• formatted returns the display value and is the default. raw returns the underlying unformatted value. formula returns formula expressions where present. Date/time output can be serial numbers or formatted strings for raw/formula reads; Google ignores that choice for formatted reads.
• Empty ranges return an empty values array with empty: true.

For a whole-workbook copy, google_drive_download_file exports XLSX. The Drive text reader can export the first tab as CSV. These remain better fits for file download workflows; Sheets-native reads are designed for selected tabs and ranges.

​

Edit safety and concurrency

Every google_sheets_edit call requires a spreadsheet ID and an operations array. Every operation requires a bounded, tab-qualified range. The tool validates operation shapes, tab names, grid bounds, row/column/cell counts, and serialized payload size before the first mutation.

• write stores a two-dimensional value matrix inside the exact range.
• append uses the explicit range to locate a table and inserts supplied rows after it.
• clear removes values only; formatting and data validation remain.
• Input defaults to raw, which stores strings literally. Select user_entered only when Sheets should interpret formulas, dates, or numbers as if a person typed them.

Compatible consecutive writes or clears use Google batch APIs. Operations still run in the supplied order, but a call that mixes write, append, and clear API endpoints is not fully transactional: an earlier group remains applied if a later group fails. Every operation receives a success, error, or not-executed result. For best-effort optimistic concurrency, pass expected_modified_time from a prior read. The edit is rejected before mutations if the Drive modification time has already changed. This preflight comparison is not an atomic spreadsheet lock; collaborators can still edit after the check.

​

OAuth scopes

Aster does not request a Sheets- or Docs-specific scope. Google’s Sheets scope table and official values.get and values.update method references document the Drive scopes used by this integration:

• https://www.googleapis.com/auth/drive.readonly authorizes spreadsheet metadata and value reads, as well as Drive file reads.
• https://www.googleapis.com/auth/drive authorizes spreadsheet creation and value writes, appends, and clears, plus Drive mutation workflows.

The optional drive.readonly scope is introduced solely to offer a genuinely read-only Drive connection. It does not change Clerk’s Google login scopes and does not create another OAuth client, connection card, or token store.

​

Troubleshooting