How to build a Spreadsheet Lookup tool

A Spreadsheet Lookup Tool is a custom tool that reads rows from a spreadsheet you point it at. The AI agent calls the tool with a filter, and the tool returns the matching rows. Use it when a workflow needs to look something up in reference data that already lives in a spreadsheet — a price list, a routing table, a mapping of codes to descriptions, an approved-vendor list — without you writing any code.

A Spreadsheet Lookup tool is a good fit when the answer is in the sheet and the task is finding the right rows. If the task instead needs judgment over unstructured text, use a Custom AI Tool; if it is a fixed rule or calculation, use a Custom Code Tool. Those two, along with document-template tools, are covered in Custom Tools.

Before you start

The tool reads the spreadsheet through your thunk's connections, so make sure the source is reachable:

Google Sheets and OneDrive / SharePoint workbooks require the matching connection on the thunk. See Connect business applications.
An .xlsx, .xls, or .csv file can be uploaded directly instead.

Create the tool

In the thunk's Custom-built tools, open Add New Tool and choose Spreadsheet Lookup Tool.
A Create new Spreadsheet Lookup tool dialog opens. Give the tool a clear snake_case name and a description that says what it looks up — the AI agent reads both to decide when to call it. The same naming guidance as every custom tool applies; see the style guide in Custom Tools.
Save the tool. You point it at a spreadsheet and read its columns from the tool's editor, which is available once the tool is saved and reopened from the tools list.

Point the tool at a spreadsheet

In the tool's editor, set the Spreadsheet URL. You can:

Paste the URL of a Google Sheet or a OneDrive / SharePoint workbook, or
Use the file picker to choose a Google Sheet, a SharePoint file, or upload a local .xlsx / .xls / .csv.

If a workbook has more than one tab, append ?tab=TabName to the URL to pin the tab the tool should read. Use the open-in-new-tab button beside the field to confirm you have the right sheet.

Changing the spreadsheet URL clears the columns already read from the old sheet, because everything the tool knows about its shape came from that sheet.

Read the columns

After the URL is set, choose Read spreadsheet columns. The tool reads the sheet's header row and lists each column with the type it detected (for example text, number, or a small set of recurring values). The tab the columns came from is shown above the list.

Re-read the columns whenever the sheet's structure changes — a renamed or added column is only picked up on the next read.

Choose which columns callers can filter on

Each column has a switch. Turn on the columns you want the AI agent to be able to filter by — for example the key column a lookup searches on.

Filterable columns and returned columns are separate concerns:

The agent may filter only on the columns switched on here.
The agent may retrieve any column in the sheet, regardless of the switches.

Keeping the filter set small keeps the tool focused: the agent is guided toward the searches the tool is meant to serve.

How the AI agent calls the tool

The agent calls the tool with a filter and gets back the rows that match. It builds the call from three parts:

Filter — one or more column = value conditions. When there is more than one, all must match. Each condition can be:
- an exact value,
- a list of values (matches a row whose column value is any one of them), or
- a "contains" substring match.
- An empty value matches rows where that column is empty (the equivalent of is blank).
Columns to return — an optional list narrowing which columns come back in each row. Leave it empty to return every column.
First match only — when the filter identifies a single row, the agent can ask for just the first match instead of the full set.

You do not configure these per call — they are how the agent uses the tool at run time. Your job is to point the tool at the right sheet and choose sensible filterable columns.

What the tool returns

Each lookup returns:

Match count — how many rows matched the filter. This is the total even when first match only limited the rows returned, so the agent can tell whether a filter was ambiguous.
Rows — the matching rows, one property per column read from the sheet (or per the columns the caller asked for).

Keeping the tool in sync with the sheet

The tool advertises the columns it read, so it depends on those columns still being there:

If a filterable column is removed or renamed in the sheet, the tool cannot run and reports that its columns no longer match. Re-read the spreadsheet's columns in the tool's editor to bring it back in sync.
If a column's values drift — new entries the tool had not seen when its columns were read — the lookup still returns correct rows. Re-reading the columns refreshes the detected types when you want the tool's description to reflect the current data.

Data entry in the sheet is expected and does not break the tool; only a change to which columns exist does.

Trying it out

Like every custom tool, a Spreadsheet Lookup tool has a Try it! action so you can run it with a test filter and confirm it returns what you expect before the workflow relies on it.