Do I need to tell the model what TOON is?

Usually not for reading — the tabular layout with a field header is self-explanatory, and current models parse it well. If you want to be explicit, one line like 'the data below is in TOON, a compact tabular format' is plenty.

Should my API return TOON instead of JSON?

No. TOON is a prompt-side optimization. Keep your APIs and storage on JSON and convert to TOON only at the point where data enters a prompt.

Which data should I convert?

Uniform arrays of objects — rows from a database, a product list, API records. Nested or one-off objects save little, so leave those as-is.

TOON for LLM prompts

When you put structured data into a prompt, you are trading two things against each other: how many tokens it costs and how reliably the model reads it. Raw JSON is expensive on the first and only middling on the second. TOON was designed for exactly this job — feeding a table of data into a model as input.

Why raw JSON is a poor prompt format

JSON repeats field names on every object and surrounds every value with punctuation, so a large array burns tokens on structure the model does not need twice. It also gives the model no explicit contract: no declared field list, no row count to check itself against. The model usually copes, but you are paying more for a weaker signal.

How to use TOON in a prompt

The workflow is three steps and takes seconds:

Convert your data with the JSON to TOON (or CSV/YAML) converter.
Paste the TOON block into your prompt where the data belongs.
Ask your question as usual — the model reads the table directly.

A TOON block looks like this, and reads like a spreadsheet with a typed header:

users[2]{id,name,role}:
  1,Ada,admin
  2,Alan,user

Why models read it reliably

The declared field header and explicit row count give the model structure to validate against — it knows how many rows to expect and which column is which. Independent benchmarks find models parse tabular TOON at least as accurately as JSON, while spending far fewer tokens. The cheat sheet covers the full syntax if you want to hand-write or tweak a block.

Keep JSON everywhere else

TOON earns its place at one point in your stack: the moment data enters a prompt. Your databases, APIs and function-calling schemas should stay on JSON, where the tooling lives. Convert in, not out. For the head-to-head, see TOON vs JSON.

Measure it first

Before you rewrite a prompt template, drop the data into the converter and check the token receipt. If it is a uniform table you will usually see a 30–60% reduction — proof, on your own payload, that the change is worth making.