> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Sheets

> Connect Google Sheets to your agents for reading, writing, and managing spreadsheet data in real time.

# Google Sheets Integration

Let your agents read from and write to Google Sheets. This turns any spreadsheet into a live data source or a place to log information — leads, orders, survey responses, and more.

## Connecting Google Sheets

### Step 1: Start the OAuth Flow

1. Navigate to **Agents** and select your agent.
2. Go to the **Tools** section and click **Add Tool**.
3. Select **Google Sheets**.
4. Click **Connect Google Account**.

### Step 2: Authorize Access

1. Sign in with the Google account that has access to your spreadsheets.
2. Review and approve the permissions:
   * **View your Google Sheets** — read spreadsheet data
   * **Edit your Google Sheets** — write and update data
3. Click **Allow**.

### Step 3: Configure the Tool

| Setting                   | Description                                                                        |
| ------------------------- | ---------------------------------------------------------------------------------- |
| **Spreadsheet URL or ID** | The Google Sheets URL or spreadsheet ID to connect                                 |
| **Sheet Name**            | Specific sheet/tab within the spreadsheet (optional — defaults to the first sheet) |
| **Allowed Actions**       | Read, write, or both                                                               |

## Available Actions

| Action           | Description                                            |
| ---------------- | ------------------------------------------------------ |
| **Read Data**    | Retrieve rows, columns, or ranges from the spreadsheet |
| **Write Data**   | Add new rows or update existing cells                  |
| **Search**       | Find rows matching specific criteria                   |
| **Get Metadata** | Retrieve sheet names, column headers, and row counts   |

## Reading Spreadsheet Data

The agent can read data from your spreadsheet and use it to answer questions:

```
User:   "How many leads came in this week?"
Agent:  [Reads the Leads sheet, filters by date column]
        "You had 23 new leads this week. 15 from the website form,
         5 from LinkedIn, and 3 from referrals."
```

The agent understands column headers and can filter, sort, and aggregate data conversationally.

## Writing to Spreadsheets

The agent can also write data back to your sheets:

```
User:   "Log a new lead: John Smith, john@example.com, interested in
         the Enterprise plan."
Agent:  [Appends a new row to the Leads sheet]
        "Done! I've added John Smith to the leads spreadsheet with
         his email and interest in the Enterprise plan."
```

## Using Sheets as a Data Source

Google Sheets is a powerful way to give your agent structured knowledge without building a database:

### Common Use Cases

| Use Case               | Sheet Structure                              |
| ---------------------- | -------------------------------------------- |
| **Product catalog**    | Product Name, SKU, Price, Description, Stock |
| **FAQ database**       | Question, Answer, Category                   |
| **Pricing table**      | Plan, Monthly Price, Annual Price, Features  |
| **Employee directory** | Name, Department, Email, Phone, Location     |
| **Lead tracking**      | Name, Email, Source, Status, Date, Notes     |

### Setting Up a Data Sheet

1. Create a Google Sheet with clear column headers in the first row.
2. Fill in your data starting from row 2.
3. Connect the sheet to your agent using the steps above.
4. In your agent instructions, describe the data:

```
You have access to our product catalog via Google Sheets.
The sheet contains columns: Product Name, SKU, Price, Category, Description.
When users ask about products, look up the information in the sheet.
Always include the price and SKU in your response.
```

## Example: Lead Tracking Agent

Build an agent that captures and manages leads in a Google Sheet.

### Sheet Setup

Create a Google Sheet called "Leads" with these columns:

| Name | Email | Phone | Source | Interest | Status | Date | Notes |
| ---- | ----- | ----- | ------ | -------- | ------ | ---- | ----- |

### Agent Instructions

```
You are a lead capture assistant. When someone expresses interest:

1. Collect their name, email, and phone number
2. Ask what they're interested in (Basic, Pro, or Enterprise plan)
3. Log the lead in the Google Sheet with:
   - Name, Email, Phone
   - Source: "Chat Widget"
   - Interest: the plan they mentioned
   - Status: "New"
   - Date: today's date
   - Notes: any additional context

4. Confirm the information was saved
5. Let them know a sales rep will follow up within 24 hours

Before adding a lead, check if their email already exists in the sheet.
If it does, update the existing row instead of creating a duplicate.
```

### Sample Conversation

```
User:   "I'm interested in learning more about your Enterprise plan."

Agent:  "I'd be happy to help with the Enterprise plan! Let me get your
         details so our team can follow up. What's your name?"

User:   "Maria Garcia."

Agent:  "Thanks, Maria! And your email address?"

User:   "maria@company.com"

Agent:  "Got it. And a phone number where our team can reach you?"

User:   "555-0142"

Agent:  [Writes to Google Sheet: Maria Garcia, maria@company.com,
         555-0142, Chat Widget, Enterprise, New, 2026-03-05]
        "All set, Maria! I've captured your information. A member of
         our sales team will reach out within 24 hours to discuss the
         Enterprise plan. Is there anything specific you'd like them
         to address?"
```

## Tips

* **Column headers matter** — Use clear, descriptive headers. The agent reads them to understand the data structure.
* **Keep data clean** — Consistent formatting helps the agent parse data accurately.
* **Use named ranges** — If your sheet is complex, named ranges make it easier for the agent to find the right data.
* **Multiple sheets** — You can connect multiple sheets to the same agent, each serving a different purpose (e.g., one for products, one for leads).
* **Formulas are respected** — The agent reads computed values from formulas, not the formula text itself.

## Troubleshooting

| Issue                   | Solution                                                                                                   |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
| "Spreadsheet not found" | Verify the spreadsheet URL/ID is correct and the connected Google account has access.                      |
| Can't write data        | Ensure "Write" is enabled in Allowed Actions and the Google account has edit permission on the sheet.      |
| Wrong sheet tab         | Specify the exact sheet/tab name in the tool configuration.                                                |
| Stale data              | The agent reads live data on each request — if data looks stale, check if someone else modified the sheet. |

## Next Steps

* **[Gmail](/docs/tools/gmail)** — Send follow-up emails after capturing leads.
* **[Google Calendar](/docs/tools/google-calendar)** — Book appointments from sheet data.
* **[Custom Tools](/docs/tools/custom-tools)** — Push sheet data to your CRM via API.