# Use Google Sheets Tools

Google Sheets Tools let an Agent search rows or add exactly one row in a spreadsheet that a workspace owner or admin selected from My Drive. The integration is dashboard-only in V1: there is no customer API-key automation, CLI, SDK, Shared Drive support, or way for the model to choose a spreadsheet ID, tab, range, or column mapping at runtime.

## Connect a spreadsheet

1. Ask a workspace owner or admin to open **Settings → Integrations → Google Sheets**.
2. Select **Connect Google account** and review the disclosure. Operade requests `drive.file`, which limits the integration to files explicitly selected for the app. Pick one Google Sheet from My Drive.
3. Return to Integrations and confirm the connection and spreadsheet are active. Use **Add spreadsheet** to select another file from the same Google account. If the account is different, Operade rejects the selection.

The consent disclosure explains that a configured read can send selected cell data to the AI model and store the bounded result in conversation history. Revoke removes Operade's stored access and refresh tokens, but it does not erase past conversation history or published Agent versions.

## Configure Search rows

Open **Tools**, add a Google Sheets Tool, and choose **Search rows**. Select the connection, spreadsheet, tab, fixed range, search columns, and return columns. The default match is **Exact** with a maximum of one row. Choose **Contains** or a higher limit only when the Agent genuinely needs a broader result because more cell data may reach the model and conversation history.

For a sheet headed `customer_id,name,status,note`, a narrow configuration can search `customer_id` and return `name,status`. During a run, the model supplies only the search query. Operade supplies the saved target and bounds, labels returned cells as untrusted spreadsheet data, and caps the result before it enters model context.

## Configure Add one row

Choose **Add one row**, then map each allowed Tool parameter to one selected column. Operade accepts scalar strings, numbers, or booleans, uses `RAW`, verifies the saved header snapshot, and adds one real row per append call. It does not offer a fake dry-run or automatic retry after an uncertain write.

Select **Validate & save** to verify access, target, headers, and mapping without running the action. In **Agent Test**, an append requires explicit confirmation that the test will add exactly one real row. Repeated tests may add multiple rows, so use synthetic values and check the Sheet afterward.

## Attach, test, and publish

1. Save the Tool and run Agent Test with a narrow read or synthetic append.
2. Attach the Tool to the intended Agent draft, Procedure, or Workflow node.
3. Test the complete draft path, including no-match, unavailable-file, and quota behavior.
4. Publish a new Agent version only after the Activity record and spreadsheet result match the intended action.

A webhook Tool remains a mutable shared resource; editing it changes future runtime resolution. By contrast, a Google Sheets Tool becomes **Locked after publish** when an immutable Agent version captures it. Use **Clone to change**, attach the clone to the draft, run Agent Test, and publish a new version. Keep that lifecycle difference in mind when reviewing changes.

Continue with [Google Sheets troubleshooting](/docs/tools/google-sheets-troubleshooting) for reconnect, schema drift, quota, and uncertain append recovery, or use the [Google Sheets error reference](/docs/reference/google-sheets-errors) to look up an exact code.