> For the complete documentation index, see [llms.txt](https://help.botpenguin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.botpenguin.com/ai-agents/prompts-and-tools/google-sheets.md).

# Google Sheets

Learn how to use Google Sheets tool with BotPenguin

The Google Sheets tool lets your AI agent read from and write to a Google Sheets spreadsheet. You add it on the Prompt & Tools page, choose which actions the agent may use, and tell the agent when to use it.

### Prerequisites

* An AI agent. See Create your first AI Agent.
* A Google account and a spreadsheet.
* Edit access to AI Agents.

### Key definitions

| Term               | Meaning                                                                              |
| ------------------ | ------------------------------------------------------------------------------------ |
| Tool               | Something your agent can use to take an action.                                      |
| Action             | One thing a tool can do. You turn each action on or off with Allowed.                |
| Usage instructions | Your words that tell the agent when to use the tool and what to do.                  |
| Connected account  | The account of the other service. You connect it once and reuse it for other agents. |

### What the Google Sheets tool can do

| Action       | What it does                 |
| ------------ | ---------------------------- |
| Create sheet | Creates a new sheet.         |
| Read rows    | Looks up rows.               |
| Add row      | Adds a new row.              |
| Update sheet | Changes values in the sheet. |
| Delete row   | Removes a row.               |

You fill in these fields when you set up the tool:

* Connection (your Google account)
* Spreadsheet
* Sheet tab

### Steps

1. Open **Prompt & Tools** under Setup in the AI Agent sidebar. Click **Add tool**. In the Add tools window, find **Google Sheets**. You can search for it, or look under External tools. Click it.

![Find Google Sheets in the Add tools window](https://content.gitbook.com/content/APDb8cKQtGlIAfgHjcsQ/blobs/hO8Ck75cvRxN3fEDJ5eg/images/google-sheets-step-1.png)

2. On the Connect step, choose the account you want. If you have none, click **Connect another account** and sign in without leaving the page. Click **Continue**.

![Choose the account for Google Sheets](https://content.gitbook.com/content/APDb8cKQtGlIAfgHjcsQ/blobs/Ul7nxtW0eJEQV8vDutpS/images/google-sheets-step-2.png)

3. On the Configure step, fill in: Spreadsheet; Sheet tab. Turn on the actions you want the agent to use. Under "How should the agent use Google Sheets?", write when the agent should use the tool and what it should do. This is required.
4. Click **Add tool**. The button stays grey until the required fields are filled. The tool now shows under Connected tools with an Active label. Click **Done**, then click **Update** to save the page.

### Example usage instructions

> Use Google Sheets to manage table bookings. Columns: Name, Phone, Date, Time, Party Size, Status.
>
> Add row: When a customer wants to book, ask for any missing detail (name, phone, date, time, party size). Add the row only when you have all five, with Status "Confirmed". Then repeat the details back.
>
> Read rows: When a customer asks about a booking, look it up by phone number. If nothing is found, say so and offer a new booking.
>
> Update sheet: When a customer wants to change a booking, read the row first and confirm it with them. Change only what they asked.
>
> Delete row: Only when the customer clearly says cancel. Ask "Do you want me to cancel this booking?" and delete only after they say yes.
>
> Create sheet: Only when staff ask for a new sheet. Never for customer requests.
>
> Rules: Never share other customers' details. If the tool gives an error, say "I could not update the sheet right now" and offer to connect them with the team. Never say a booking is confirmed before the row is added.

Write your own in the same way: say when to use the tool, then what to do.

***

### Change or remove the tool

Under Connected tools, click the gear icon to open the tool's settings again. Click the delete icon to remove it. You are asked to confirm. Deleting removes the tool and its usage instructions from the agent. The connected account stays, so other agents can still use it.

***

### Common errors

<details>

<summary>The agent does not use the tool</summary>

Check that the tool shows Active under Connected tools. Check that the action you need is allowed. Make your usage instructions clearer about when to use the tool.

</details>

<details>

<summary>I cannot save the tool</summary>

The usage instructions are required. Fill them in. Also fill in the other required fields.

</details>

<details>

<summary>I do not see Google Sheets in the Add tools window</summary>

Your partner may not have turned this integration on. Ask your partner or account owner.

</details>

<details>

<summary>The Continue button is grey</summary>

Choose an account first. If you have none, click Connect another account.

</details>

<details>

<summary>Can I use the same account for more than one agent?</summary>

Yes. Connected accounts belong to your account, so other agents can use them.

</details>

<details>

<summary>What happens if I delete the tool?</summary>

The agent can no longer use it, and its usage instructions are removed. Text about the tool in your prompt stays, so remove it too.

</details>

### Support

Still not working? Write to us at <support@botpenguin.com>. We will reach out to you within 24 hours.
