Data & Analytics
14 min read
A spreadsheet with a few hundred rows is easy to look at and surprisingly hard to ask questions of. 'How much did we spend on transport?' sounds like one question, but answering it means deciding which column holds the money, which rows count as transport, what to do about the rows where the amount is blank, and whether the number you end up with is the one you meant.
This is the section where an agent stops being something that talks and starts being something that computes. The rule that makes that work is short enough to remember: the model chooses, the code counts. The model reads the question and the column names and decides which operation would answer it; a tool written in ordinary JavaScript does the arithmetic over every row. The model never sees the data and never adds anything up.
That rule is worth understanding properly, because it is what separates an answer you can check from a number that merely sounds right. It also gives you a clean way to talk about the parts that go wrong: a wrong column name, a type that was guessed incorrectly, a blank cell, a question the table simply cannot answer. Each of those is a different failure with a different fix, and none of them is 'the model was bad at maths'.
The model should not be doing the arithmetic
Ask a language model to total a column of forty-six numbers and it will produce a plausible figure that is very close to right and occasionally wrong. That is the worst possible outcome: close enough to look correct, wrong enough to make a decision on. Language models predict text; a total is not a prediction, it is a calculation, and there is no reason to ask a text predictor to do one.
So the agent is built the other way round. The model is given the *shape* of the data - column names, types, how many values are missing - and a list of operations the tools can perform. It replies with a request: 'sum the amount column, grouped by category, sorted descending, top 5'. A tool validates that request against the schema and computes it over the whole table. The number in the final answer was produced by code that you can read, run again, and test.
This also fixes something subtler. When the model computes, the only thing anybody can check is whether the final number looks reasonable. When the tool computes, every step is visible: the request, the rows it matched, the values it skipped, the table it returned. An answer you can audit is worth more than an answer you merely trust.
A question becomes a request
The interesting step is the translation. The model is not asked to answer the question - it is asked to say which computation would answer it, in a shape the tool understands. Compare what a vague instruction produces with what a structured one does.
Asking for an answer instead of an operation
How much did we spend in total? Answer with the number.javascriptReply with JSON: { action: "tool", tool: "queryDataset", args: { metrics: [{ column: "amount", operation: "sum", as: "total" }] } }javascriptThe weak version invites the model to do the sum itself, from whatever rows it happens to have seen. The improved version names the operation and the column, and says nothing about the result - the model has nothing to invent, because it is not the one producing the number.
Naming a column before reading the schema
Sum the cost column.javascriptCall describeDataset first, then sum the column whose type is number and whose name matches the question.javascriptColumn names are guesses until you have looked. An agent that writes 'cost' when the column is called 'amount' gets a refusal from the tool - which is the correct behaviour, and also a wasted turn. One inspection call at the start is cheaper than a retry loop.
Answering a question the table cannot answer
Which student spent the most money?javascriptIf no column holds a person's name, ask which column was meant instead of answering.javascriptThe expenses table has a date, a category, a description and an amount. There is no student in it, and any name the model produces is invented. Asking a clarifying question is not a failure to answer - it is the correct answer to a question the data does not cover.
Missing, invalid and zero are three different things
Before any question can be answered, the data has to be read - and reading a CSV means making decisions. A blank cell is not a zero: nobody recorded that value, so it is *missing*. A cell that says 'n/a' in a money column is not missing either: something was recorded, and it cannot be read as a number, so it is *invalid*. Keeping those two apart matters, because 'we spent nothing here' and 'we do not know what we spent here' lead to different answers.
The platform reads the file, guesses each column's type, and shows you what it guessed. Guessing is a heuristic: a column of numbers is a number column until one value does not fit, and then it becomes text. That is the right default - refusing to quietly drop the odd value - but it is also the reason the amount column in the club expenses file arrives as text, because exactly one row says 'n/a'.
Correcting a type does not touch the values. The cells stay exactly as they were; only the reading changes. Once the amount column is read as a number, the 'n/a' row is counted as invalid rather than making the whole column unusable, and every calculation can say how many values it skipped. That is why the correction lives in a separate schema file next to the data: the data is evidence, and the schema is your interpretation of it.
What a tool call and its result actually look like
Walking through the club expenses file
The supplied dataset is a school club's spending: 46 rows, four columns - date, category, description and amount. One amount is blank, one says 'n/a', one is negative, and one description contains a comma inside quotes. The starter agent reads five rows and asks the model to answer from them, which is why its card says the answer was not computed.
1. Inspect before answering anything
The first tool call is describeDataset, with no arguments. It reports four columns and their counts: date as a date column with nothing missing, category and description as text with one blank each, and amount as text with one blank and one unreadable value. That last line is the finding that shapes everything else - a sum over a text column is refused, so the amount column has to be corrected first.
2. Correct the type, in the schema rather than the data
Setting amount to number in the schema panel changes how the column is read, not what it contains. The blank cell stays blank and becomes missing; the 'n/a' cell becomes invalid; the 44 readable values become numbers. The dataset card now says 44 values present, 1 missing, 1 invalid - and every result from here on reports how many values it skipped.
3. Ask the total, and get a table
The question 'What is the total spending?' turns into one queryDataset request: sum the amount column, no filters, no grouping. The tool returns 2828.03 with a note that it skipped one missing and one invalid value. The card shows the computed table next to the sentence, so the claim and the number are in the same place.
4. Group it, and read the ranking
The next question is 'Which category has the highest total spending?'. The request adds groupBy: ['category'] and a descending sort. The result is six groups - Transport 1120.60, Venue 535.00, Equipment 501.24, Refreshments 459.30, Printing 251.89, and a group labelled (missing) with -40.00 - and the answer names Transport. The sixth group is the interesting one: the row with no category is reported rather than dropped, and it is negative because one refund is recorded as a negative amount.
[
["Transport", 1120.6],
["Venue", 535],
["Equipment", 501.24],
["Refreshments", 459.3],
["Printing", 251.89],
["(missing)", -40]
]json5. Count, and notice what count means
'How many purchases were over 50?' is a filter plus a count: amount greater than 50, then count the rows. The answer is 21 - and it is a count of rows, not of values, which matters the moment a filter touches a column with gaps in it. The tool distinguishes the two: count() with no column counts rows, count(column) counts the values that are present.
6. Ask something the table cannot answer
'Which student spent the most?' has no answer here, because no column holds a person. The right outcome is a clarifying question, and the grader accepts only that: the agent asks which column was meant, the card is marked as a question rather than an answer, and nothing is invented. A plausible name would be the worst possible result, because it would look exactly like a real one.
7. Try your own file
Uploading a CSV replaces the active dataset and switches the exercise into its second mode. The tools still work - the schema is read the same way and the arithmetic is the same code - but the guided exercise's answer key describes the supplied file, so a custom run is never marked complete. That is deliberate: the platform can compute your numbers, and it cannot vouch for them. Say so in your answer, and the honesty is part of the work.
When a number is right and still misleading
Every figure in the walkthrough is correct, and several of them are easy to misuse. Transport has the highest total at 1120.60, but it also has the most rows of any category, so 'we spend most on transport' and 'transport is our most expensive line' are different claims. The average per purchase tells a different story again: 124.51 for Transport against 50.12 for Equipment, and Equipment's total is only slightly smaller than Venue's despite having nearly twice as many rows.
The group labelled (missing) is a small masterclass in reading a result carefully. It is one row, it totals -40.00, and it appears last in the ranking because a single refund is negative. Nothing is wrong with it - the filter did not drop it, the sort did not hide it, the sum did not ignore it - but a reader who only looks at the top line will never notice that 40 pounds of spending has no category attached. That is the difference between a computed answer and a good one: the computation gives you the table, and reading the table is still your job.
Averages deserve their own warning. The mean of the amount column is 64.27, computed over the 44 values that could be read - not over 46 rows. Had the two unreadable values been treated as zero, the same question would have returned 61.48, and nothing would have looked wrong. This is why the notes matter and why the card shows them: a number that silently decided how to handle a gap is a number you cannot fully trust, however carefully it was calculated.
Mistakes worth catching early
| What goes wrong | What it looks like | What to do instead |
|---|---|---|
| Letting the model do the arithmetic | A total that is almost right, with no table behind it to check. | Have the model name the operation and let the tool compute it. |
| Naming a column before inspecting | A refusal for a column that does not exist, and a wasted turn. | Call describeDataset first, every run, and answer from the schema. |
| Treating a blank as a zero | A total that is quietly too small, and no error anywhere. | Keep missing, invalid and zero separate, and report what was skipped. |
| Fixing the data instead of the reading | Values edited so the arithmetic works, and the evidence gone. | Correct the type in the schema; leave the cells alone. |
| Counting rows when the question meant values | A count that includes the blanks, because the filter was on another column. | Know whether you asked for count() or count(column), and say which. |
| Answering a question the columns cannot answer | A confident name, category or figure that no column contains. | Ask which column was meant. A clarifying question is a correct answer. |
| Presenting a mean as a total | A 'spending' figure that is really an average per purchase. | Label the operation, and keep it visible on the card. |
Debugging an analysis
- Read the tool call before the sentence. The request tells you what the agent thought the question meant, and most wrong answers are wrong there.
- If a number looks odd, read the notes first. 'Skipped 1 missing and 1 invalid value' explains most surprises before you look at the data.
- Check the row count against the question. A total over 46 rows and a total over 9 rows are different questions, and the tool reports both.
- When a result looks empty, look at the filter rather than the tool. An equality test against a value that is capitalised differently is the classic miss.
- When a column refuses an operation, read the error code: TYPE_MISMATCH means the reading is wrong, UNKNOWN_COLUMN means the name is. They have different fixes.
- Watch for a group labelled (missing). If it appears, part of your question was answered by rows that had no value there.
- If the answer disagrees with the table, trust the table. The numbers were computed; the sentence was not.
- Before you present anything, ask what a reader would assume from it - then check the table does not quietly contradict that.