When not to use TOON

TOON has exactly one trick. It declares field names once and streams records underneath as rows, the way CSV does, instead of repeating every key in every object the way JSON does. That is where the savings come from, and it is the only place they come from.

So the question “does TOON save tokens?” is really the question “does my data let TOON use its tabular form?” — and for a lot of real payloads the answer is no.

Payload	TOON	JSON	CSV	Difference	Cheapest
API response	210	353	—	−41%	TOON
Plain table	195	338	163	−42%	CSV
Nested config	81	67	—	+21%	JSON
Records with a list	290	218	—	+33%	JSON

1. Deeply nested data with nothing repeating

Configuration files, deeply structured domain objects, anything shaped like a tree rather than a table. There is no repeated key set for a header to amortise, so TOON falls back to a YAML-style indented form — and that form spends characters on indentation that minified JSON spends on braces, with the braces winning.

The nested config row above is a small, ordinary server configuration. TOON costs more tokens than minified JSON for it, not fewer.

This is the case most often missed, because the announcement benchmarks are run on record arrays. If your prompt carries settings, a deeply nested domain object or an arbitrary tree, measure before you switch.

2. Records that contain an array or an object

This is the sharpest edge, and the least obvious. Take a perfectly uniform array of records — same keys, same order, every one of them — and give each record a single field holding a list:

[
  { "id": 1001, "name": "user_0", "tags": ["beta", "eu"] },
  { "id": 1002, "name": "user_1", "tags": ["beta", "eu"] }
]

The tabular form requires every field to be a primitive. One array field is enough to disable it, and the encoder drops back to a list that repeats id, name and tags for every single record:

[2]:
  - id: 1001
    name: user_0
    tags[2]: beta,eu
  - id: 1002
    name: user_1
    tags[2]: beta,eu

Compare that to the tabular form the same data would have taken without the tags field:

[2]{id,name}:
  1001,user_0
  1002,user_1

The data is still uniform. The records still share a key set. The savings are gone anyway, and TOON now costs about a third more than minified JSON — see the “Records with a list” row above.

The practical rule: if your records carry nested values, either flatten them before encoding or do not use TOON for that payload. A tags array that you flatten into a delimited string restores the tabular form; one you leave alone removes it.

3. Flat tables, where CSV is simply better

If your payload is a flat array of records and every field is a primitive, you have the ideal TOON case — and CSV is still cheaper, because CSV spends nothing at all on structure. The official benchmarks put TOON a few percent above CSV on flat data, and the “Plain table” row above shows the same.

TOON earns its place when CSV cannot represent the payload:

• there is an envelope around the records (status, pagination, totals)
• there are several arrays in one document
• values have types that matter, and you do not want the model guessing whether 007 is a string or a number

If none of those apply, send CSV.

4. Short prompts

Every figure on this page measures the payload alone. None of them include the tokens you spend explaining TOON’s syntax to the model — and unless you are using a model that already knows the format well, you will spend some.

A few hundred tokens of format explanation is nothing across a million calls carrying large payloads. Against a 200-token payload sent occasionally, it exceeds everything the format saves. The break-even is a function of payload size times call volume, not a property of the format.

How to decide in one minute

1. Is your payload a uniform array of records? If not, stop — use minified JSON.
2. Is every field in those records a primitive? If not, either flatten or stop.
3. Does anything outside the record array need to survive — an envelope, a second array, type information? If not, use CSV.
4. Is the payload large enough, or sent often enough, that a few hundred tokens of syntax explanation amortise away?

Four yeses mean TOON is the right call. Anything else and it is not.

Or paste the payload into the converter and let it answer the same four questions for you.