A due diligence data room usually contains a few hundred PDFs and a few dozen workbooks. The PDFs tell the story. The workbooks hold the numbers behind it: the operating model, the cap table, the bookings tracker, the debt schedule. An analyst who gets a number wrong from one of those files loses the trust of everyone who reads the memo.
Language models are good at reading PDFs. Spreadsheets are harder for them, for two separate reasons. This post explains both, and what we built to handle them.
What you can ask it
Given a set of Excel files and a question in plain language, the agent works out where the answer lives and computes it. Here are three typical tasks, written for an imaginary company called Larkfield.
Pull figures from a wide, messy sheet
"Read the P&L tab in Larkfield's monthly management accounts. Give recognised revenue for 2023, 2024 and the first half of 2025, with the entity, currency and scale. Reconcile the 2024 figure against the monthly sales report. Cite each number."
One workbook. A monthly P&L thirty columns wide, where the year totals sit far to the right and are easy to miss.
Audit a model
"Audit Larkfield's customer ROI calculator. Read the exact inputs and formulas, reperform each economic claim, and report any place where a formula and its value disagree. Say which inputs are documented and which are the user's assumptions."
One workbook, two calculator tabs. The agent has to recompute the outputs itself and compare them with what the sheet shows.
Reconcile across files
"Read every tab of Larkfield's board pack, the budget workbook and the five-year revenue plan. Extract revenue by segment and period, separate actuals from forecast, state the scale and currency, and flag any discrepancy between the three."
Three workbooks built by different people, with different period labels and units for the same business.
In each case the answer comes back as tables and a short note, with a citation on every figure. The agent reads workbooks and does not change them.
Why spreadsheets defeat standard retrieval
The standard way to give a language model access to documents is retrieval. You split each document into chunks, index them, and pull the relevant ones into the model's context when a question comes in. That works because prose is one-dimensional: a paragraph carries its meaning with it wherever it goes.
A spreadsheet's meaning lives in its two-dimensional layout, and almost none of that survives being flattened into text. Here is a small but representative sheet. Any analyst can read it in a few seconds.
| A | B | C | D | E | F | |
|---|---|---|---|---|---|---|
| 1 | Regional Sales Summary (USD '000)1 | |||||
| 2 | ||||||
| 3 | 20242 | |||||
| 4 | Region | Product | Q1 | Q2 | Q3 | Q4 |
| 5 | North | Widgets | 120 | 135 | 150 | 160 |
| 6 | Gadgets | 80 | 85 | 90 | 95 | |
| 7 | North subtotal3 | 200 | 220 | 240 | 255 | |
| 8 | South5 | Widgets | 100 | 110 | 115 | 130 |
| 9 | Gadgets | 60 | 62 | 70 | 75 | |
| 10 | South subtotal | 160 | 172 | 185 | 205 | |
| 11 | ||||||
| 12 | Headcount4 | |||||
| 13 | Site | FTE | ||||
| 14 | Pune | 42 | ||||
| 15 | Austin | 17 | ||||
- 1a banner, not data
- 2a year merged over its quarters
- 3a subtotal hiding in the data
- 4a second table, same sheet
- 5one merged label covering two rows
What a text parser hands the model
Regional Sales Summary (USD '000) Region Product 2024 Q1 Q2 Q3 Q4 North Widgets 120 135 150 160 Gadgets 80 85 90 95 North subtotal 200 220 240 255 South Widgets 100 110 115 130 Gadgets 60 62 70 75 South subtotal 160 172 185 205 Headcount Site FTE Pune 42 Austin 17
Ask the flattened version for total Q4 sales and a common answer is 920. The right answer is 460. The subtotal rows were added in a second time.
The flattened version
- North · Widgets160
- North · Gadgets95
- North subtotaladded a second time255
- South · Widgets130
- South · Gadgets75
- South subtotaladded a second time205
Total Q4 sales920
The right answer
- North · Widgets160
- North · Gadgets95
- South · Widgets130
- South · Gadgets75
Total Q4 sales460
The Q4 column of the sheet above, USD '000
That is the first failure: layout carries meaning, and flattening destroys it. Real workbooks are worse than this one. Tables do not start at A1. Layouts are pivot-style. Notes sit under the data. A model has forty sheets.
The second failure is independent of the first. Even when a model can see the right cells, it is unreliable at arithmetic over them. Summing thirty numbers from a rendered table is the kind of task where a model gives a confident, plausible, wrong answer. In finance a wrong number is worse than no answer.
Answers with cell-level citations
You ask a question in plain language, in chat or as part of a generated report. You get the figure, and next to it a citation that opens the sheet and says how the figure was arrived at.
North was 55.4% of Q4 sales
Q4 2024 by region, subtotals recomputed
EvidenceSourced from 1 file
Sales analysis
How this was found
North sold $255K in Q4 2024, 55.4% of the $460K total, calculated as $255K divided by $460K. The subtotal rows were left out and the total recomputed.
Sales.xlsx
Totals use the four product rows under Q4, not the subtotal rows
| A | B | … | F | |
|---|---|---|---|---|
| 4 | Region | Product | … | Q4 |
| 5 | North | Widgets | … | 160 |
| 6 | Gadgets | … | 95 | |
| 7 | North subtotal | … | 255 | |
| 8 | South | Widgets | … | 130 |
| 9 | Gadgets | … | 75 | |
| 10 | South subtotal | … | 205 | |
North Q4 255 = F5 + F6Total Q4 460 = F5 + F6 + F8 + F9Share = 255 ÷ 460 = 55.4%
A made-up example on the sheet above, drawn the way the product shows it: the figure, its evidence and the four cells it rests on.
This matters most in the places our customers use it: due diligence, credit analysis and marketing attribution. In all three, someone senior will pick a number from the page and ask where it came from. The answer has to be one click away.
Design principles
- Structure is observed, never assumed. The agent looks at each workbook's layout before it touches the data.
- The model never does the math. Every reported figure comes from code or a computation the agent ran, and can be traced back to source cells.
So the model's job is to behave like a careful analyst. It plans, looks, writes the code that cleans up a messy region, and writes the answer. The numbers themselves only ever come from code that ran.
Architecture and workflow
The spreadsheet agent is a specialist that other agents call. A chat agent or a report pipeline hands it one task and gets back an answer with citations. It works in a private workspace that holds the workbook files and a small embedded database (DuckDB) of the tables it has extracted.
workspace, one per conversation
Inside that workspace, the agent follows the same five steps every time.
- 1 · Listevery file and its sheets
- 2 · Inspectmerges · table regions · a preview of each
- 3 · Extractone messy region into one clean table
- 4 · Verifyrow count · types · first row
- 5 · Answerread-only SQL · cited figures
wrong shape or type? fix and extract again before moving on
Inspect uses plain rules, and that is deliberate. Each table region it finds comes back with a preview of its first rows and the merged cells inside it. The result is a hint for a reasoning model. Because the rules are simple, we can explain every mistake they make, and the preview is what lets the agent catch one.
Extract follows a short playbook of rules, each added after we watched an extraction go wrong without it. Subtotal rows, for example, stay out of the table and totals are recomputed in SQL, so nothing is counted twice.
Verify is built into the tool. Registering a table prints what was stored and flags a number column that contains text, which usually means a header row leaked into the data. The agent reads output it already has, so the check costs no extra round trip.
A coding tool in place of fixed functions
Most of the agent's tools are narrow: list the files, map a workbook, read a block of cells, run a query. One is open-ended. The agent can write and run Python.
We made that choice because no fixed set of functions covers every layout people build in Excel. A "fill merged headers" function handles one case. The next workbook has three header rows, or units in a side column, or two tables sharing a header. With a coding tool the model writes the dozen lines that fit the sheet in front of it, using pandas the way an analyst would.
The environment is set up so that the easy path is also the safe one:
- Helpers are already loaded. One reads a block of cells through the streaming reader described below. One registers a clean table in the workspace database and records which cells it came from. One audits a workbook's formulas.
- Each run is a fresh process. Nothing carries over between runs except the tables and files in the workspace, so a run that goes wrong cannot quietly affect the next one.
- The code runs in a sandbox. It is influenced by the contents of uploaded files, so we treat it as untrusted. It has no network access, and limits on memory and running time. If the sandbox cannot be set up, the agent refuses to run code at all.
- Code prepares the data, queries produce the figures. The agent uses Python to clean and reshape, then answers from the registered tables with read-only SQL. That split is what makes every figure traceable.
A worked example
Here is the whole loop on a small workbook. The task: "What were FY2025 Q4 bookings, and what share came from Subscriptions?" Step through it to see which cells the agent looks at, what it decides, and what it runs.
| A | B | C | D | E | F | |
|---|---|---|---|---|---|---|
| 1 | Larkfield Software: bookings by product line (USD '000) | |||||
| 2 | FY2025 | |||||
| 3 | Segment | Product | Q1 | Q2 | Q3 | Q4 |
| 4 | Subscriptions | Platform | 410 | 455 | 480 | 520 |
| 5 | Analytics add-on | 190 | 210 | 235 | 260 | |
| 6 | Subscriptions subtotal | 600 | 665 | 715 | 780 | |
| 7 | Services | Implementation | 80 | 85 | 90 | 110 |
| 8 | Support plans | 120 | 130 | 140 | 150 | |
| 9 | Services subtotal | 200 | 215 | 230 | 260 | |
| 10 | Total bookings | 800 | 880 | 945 | 1,040 | |
| 11 | ||||||
| 12 | Headcount | |||||
| 13 | Site | FTE | ||||
| 14 | Pune | 42 | ||||
| 15 | Austin | 17 | ||||
Nothing has been read yet.
Two table regions found: bookings in green, headcount in blue. They are separated by a blank row.
Amber: title row. Blue: two-level header. Dashed green: a label that covers two rows. Red: subtotal and total rows to leave out.
Green cells go into the table. Red rows are dropped. The table remembers that it came from A2:F10 of this sheet.
The check is printed by the registration call itself, so it costs no extra round trip.
Solid green: the four cells the query summed. Dashed amber: the sheet's own total, which agrees.
Clicking citation 1 opens the Bookings sheet at the region the table was built from.
A task arrives from the calling agent
The task names one workbook. I should not assume anything about its layout. First I will list the files and map the workbook, both in the same turn.
List the files and map the workbook
list_workbook_files() inspect_excel_workbook()
Larkfield_Operating_Model.xlsx sheet "Bookings" 6 columns x 15 rows merged A1:F1, C2:F2, A4:A5, A7:A8, B12:C12 region 1 A1:F10 preview: title row, FY2025 over Q1..Q4, ... region 2 B12:C15 preview: Headcount, Site | FTE, ...
Read the layout before touching the data
Region 1 is the one I need. Row 1 is a title, not data. Rows 2 and 3 are a two-level header: FY2025 sits over Q1 to Q4. Subscriptions and Services are each written once for two rows. Rows 6, 9 and 10 are subtotals and a total. If I keep them, every sum doubles. Region 2 is headcount and is not needed.
Turn the region into one clean table
raw = read_sheet(F, "Bookings", "A2:F10")
quarters = [f"FY2025 {q}" for q in raw.iloc[1, 2:]]
df = raw.iloc[2:].copy()
df.columns = ["segment", "product", *quarters]
df["segment"] = df["segment"].ffill() # fill the merged label down
df = df[~df["segment"].str.contains("total", case=False)]
tidy = df.melt(["segment", "product"],
var_name="quarter", value_name="usd_k")
register_table("bookings_fy2025", tidy,
source=(F, "Bookings", "A2:F10"))Check what was stored
16 rows is 4 products times 4 quarters, which is what I expect. The number column holds only numbers, so no header row leaked in.
bookings_fy2025: 16 rows segment VARCHAR, product VARCHAR, quarter VARCHAR, usd_k BIGINT first row: Subscriptions | Platform | FY2025 Q1 | 410
Compute the answer with SQL
780 + 260 = 1,040. That matches the sheet's own Total bookings row, which I left out of the table. 780 / 1,040 = 75.0%.
SELECT segment, SUM(usd_k) AS "q4_usd_k" FROM bookings_fy2025 WHERE quarter = 'FY2025 Q4' GROUP BY segment
segment q4_usd_k Subscriptions 780 Services 260 source_refs: bookings_fy2025 -> [1]
Report the figures with their sources
Step through with the numbered steps, Back and Next, or the arrow keys
Reading large workbooks efficiently
The questions the agent asks of a file are small: what do the first rows of this region look like, what is in this block of cells. The files are not small. openpyxl, the standard Python library for Excel files, is excellent at what it is designed for. But its default loader reads the whole workbook and builds an object for every cell before you can read the first one. On one 44 MB export that took 4.9 GB of memory and 96 seconds, which crashed the process.
An .xlsx file is a zip archive of XML documents, so we wrote a reader that streams. It parses rows one at a time, frees each row once it has been used, and stops at the last row of the window the agent asked for. Memory now depends on the size of the question, and the size of the file hardly matters.
openpyxl, default loaderload everything, then read
an object in memory for every cell
memory grows with the file
streaming readerparse only as far as the range asked for
rows parsed,then freedstops early
shared strings and date styles read once, then cached
memory grows with the question
One detail we like. The list of merged cells sits at the end of a sheet's XML, after all the cell data. Reaching it with a parser means walking every row first. We scan the raw bytes for the merge list instead. This is safe because angle brackets inside cell values are always escaped in XML, so those bytes can only be the real element.
Citations and data lineage
The agent's most natural path is also the hardest one to cite. When it loads a sheet into the database and answers with SQL, it never reads a passage the way a search agent reads a PDF. A normal citation system has nothing to attach to. The answer would be right and impossible to check.
Our fix is to record where data came from at the moment it is extracted, not when the answer is written.
So every figure carries the file, the sheet and the cell range it came from, however many steps it passes through on the way to the answer, and citing it is a matter of copying, not reconstruction. For a computed figure, the citation pane adds one sentence with the formula and where each input sits, in the sheet's own labels.
Stale formula values and safe recalculation
Excel files store two things for each formula: the formula, and the value from the last time someone calculated it. Workbooks exported by other tools often carry stale values, sometimes an error marker for a formula that is perfectly valid. Excel recalculates when you open the file, so a person never sees the problem. Code that reads the file gets the stale value. Our agent was reporting errors where Excel showed real numbers, and it was correct about what the file contained.
So we recalculate. When a workbook shows the symptoms, its formulas are recomputed once before the agent reads it. On real files this resolved about 97% of the affected cells. The rest were real errors that Excel shows too.
We keep two lessons from this work. The accuracy ceiling of an AI system is often set by a file format quirk and not by the model. And a fix that can damage its input, as recalculation can, needs a check that it did not.
Precomputing at index time
The layout map and the recalculation are properties of the workbook. They do not depend on the question. A workbook used by twenty sections of a report was being scanned twenty times.
Both now happen once, when the document is indexed. The agent looks up the stored map and the recalculated copy when it starts work. If the lookup fails or is slow, the agent does the scan itself, exactly as before. The new layer can make things faster. It cannot make an answer wrong.
Before
A workbook used by twenty sections of a report, scanned twenty times
Now
once, when the document is indexedlayout map · recalculated copy
the agent looks up the stored mapwhen it starts work
if the lookup fails or is slow, the agent does the scan itself
Tool messages as guidance for the model
In a normal program, an error message is read by a developer, later. In an agent, every error is read immediately by a model that is deciding what to do next. The wording of the error decides how many more round trips the task takes.
Take a read that is too large. The grid tool shows a limited number of cells at a time, and the agent asks for far more.
error names the violation
agentrange read
- read 25,000 cells
- ✗ too big
- read 12,000 cells
- ✗ too big
- read 6,000 cells…
three round trips, still guessing
error names the next move
agentrange read
- read 25,000 cells
- too big: read A1:AZ61 first,then page down 61 rows at a time
- read A1:AZ61
- ✓ grid
one corrective round trip
no error (what we ship)
agentrange read
- read 25,000 cells
- ✓ first window of the grid+ note: the next window, andthe columns left over
data on the first call
We applied the same thinking to every failure message. When extraction code is stopped at the time limit, the message says what kind of code tends to run long, how to restructure it, and that tables registered before the stop may still exist. Each of these messages replaced a loop we had watched the agent get stuck in.
Cost per question
The unit of cost for an agent is the round trip: one full call to the model with the whole conversation sent again. Tool calls are cheap by comparison. So we treat the number of round trips as a design metric. Discovery calls go out together, and independent reads are batched into one turn.
We ran the same agent, with the same tools, on the same two questions over a 27,000-cell financial model, and changed only the model underneath. Every configuration got both answers right. The cost differed by about thirty times.
| Model behind the agent | Round trips | Time | Relative cost |
|---|---|---|---|
| Model A | 8 to 10 | 103 to 118 s | 1× |
| Model B | 26 | 127 s | 4.5 to 7× |
| Model C | 32 | 239 s | 22 to 33× |
A reusable component and its applications
We built the spreadsheet agent as a building block. It takes one task in plain language plus a set of files, and returns an answer with citations. It knows nothing about who is asking. Any other agent, report pipeline or workflow can call it the same way, so every product that needs a number from a workbook gets the same care.
Today it sits behind chat, behind report generation, and behind customer-specific agents. Three kinds of work use it most:
- Due diligence. Does the bookings figure in the management deck tie to the operating model? Which months does the cash forecast run out in? Dozens of report sections can call the agent in parallel, each with its own workspace and a shared download cache so a workbook is fetched once.
- Credit analysis and rating. Pull leverage and coverage ratios from a debt schedule, compare them with the covenant levels, and cite both sheets.
- Marketing attribution. Campaign and channel data usually arrives as spreadsheet exports. Analysts ask which channels drove revenue against spend, across several files, and need the arithmetic to be right.
The same pattern fits anywhere the source of truth is a workbook: finance operations, budget reviews, audit sampling, portfolio monitoring.
It reads .xlsx and .csv files, and it reads formulas when a question is about them, such as finding hard-coded numbers or links to other workbooks. What we are building next: formulas read alongside values on every question, so an answer can show how a figure is built as well as what it is.
Why not upload the workbook to a chat assistant?
A general assistant with code execution can open an uploaded workbook and run pandas on it. Due diligence asks for more than that:
- The whole data room. The agent is handed the workbooks a question needs from a private data room of hundreds of documents. Nobody downloads or uploads a file.
- Your own cloud. Needl.ai can run in the customer's own AWS or Azure account, so the files never leave it.
- A whole report at once. Dozens of report sections work on the same workbooks in parallel, each in its own workspace.
- Cell-level sources. Every figure opens the sheet and cell range it came from, with one sentence on how it was computed.
Lessons learned
- Make the model look before it acts. Almost every wrong answer we traced came from the agent acting on a layout it had not looked at.
- Send every number through a deterministic engine. The rule "extract and query, never read a figure off the grid" did more for accuracy than any amount of prompting the model to be careful.
- Record sources where the data moves. By the time the answer is written, the link to the source cells is gone. Capture it at extraction and make citing a copy operation.
- Write tool messages for the model that reads them. Name the next legal move, or better, return the part of the result you can.
None of the parts here is exotic. Streaming parsers, sandboxes and lineage records are old ideas. The model gets the attention, and the system around it is what makes the numbers right.


