What Is the Toon Format? A Practical Guide

Over the past few months, you've probably noticed a new term showing up across GitHub, Twitter/X, and tech blogs: Toon format (or Toon notation). People describe it as:

"JSON for LLMs"
"A data format designed to save tokens for AI models"

So what's the deal? In this post, I'll break down Toon piece by piece: what problem it actually solves, what it looks like, when you should care about it, and how to integrate it into your projects.

1. Why Does Toon Even Exist? JSON's Problem with LLMs

1.1 JSON Wasn't Built for Large Language Models

Here's the thing: JSON was designed for program-to-program communication, not for human-to-LLM interaction. That creates some friction:

1. Token overhead gets expensive fast

   • Keys like "name", "id", "value" repeat constantly
   • Braces, quotes, commas—they all count as tokens
   • For the LLM, a lot of these structural characters don't add much semantic value

2. The structure isn't particularly intuitive for models

   • Take a list of users—usually it's nested as arrays of objects
   • The model has to traverse this tree to figure out what matters

3. Your context window fills up way too quickly

   • In RAG systems, agents, multi-tool workflows, JSON alone can eat up your 8K or 32K context
   • Hit that limit and you're stuck cutting content or dropping fields

So naturally you start asking:

Can we represent the same structured data with fewer tokens in a way that's friendlier to LLMs?

That's basically what Toon is trying to do.

1.2 Toon's Goal: Reshape Data for Tokens and Models

Toon stands for Token-Oriented Object Notation. The core idea is pretty straightforward:

Express the same structured data with fewer tokens, without making it unreadable for humans.

How? Toon does a few things:

• Cuts down repeated keys by declaring them once and reusing them
• Uses a more tabular layout for list-like data
• Designs its syntax around how tokenizers actually work, so each token carries more weight

Basically, Toon asks:

If the consumer is a large language model, what would an ideal data layout actually look like?

1.3 Why Is Everyone Suddenly Talking About It?

Since late 2025, Toon went from obscure side project to mainstream pretty fast:

• The official Toon repo started gaining stars rapidly
• Implementations popped up in multiple languages: TypeScript, Python, Go, R, Elixir, PHP, Scala, and more
• Blogs from freeCodeCamp, Towards AI, and enterprise engineering teams started sharing experiments and cost savings

That's a strong signal. Toon has moved from "interesting GitHub project" into serious technical evaluation territory for a lot of teams.

2. Toon Format Basics: What It Actually Looks Like

Let me show you some examples—once you see it, Toon makes a lot more sense.

2.1 Simple Example: Toon vs JSON Side by Side

Here's a basic JSON array of users:

[
  {
    "id": 1,
    "name": "Alice",
    "role": "admin"
  },
  {
    "id": 2,
    "name": "Bob",
    "role": "user"
  }
]

The Toon representation of the same data might look like this (simplified):

users:
  id  name   role
  1   Alice  admin
  2   Bob    user

What changed?

• Column names id, name, role are written once
• Each row represents a single user
• The alignment is tabular—closer to what models have seen in training: CSV, tables, spreadsheets

For list/record data like this, Toon can pack the same information into way fewer tokens while staying easy to scan.

2.2 What Can Toon Actually Represent?

From the official spec and various implementations, Toon supports:

• Scalars: strings, numbers, booleans, null
• Objects: key-value pairs
• Arrays/lists
• Tabular sections: multi-row, multi-column, uniform structures (this is where Toon really shines)

A useful mental model:

• Flat objects + lists + table-like data → Toon shines
• Deeply nested, irregular structures → benchmark first; JSON might be fine or even better if you've already optimized it

2.3 Toon Spec and Validation

There's a formal Toon specification (currently v2.x) that defines:

• Syntax and layout rules
• Type mapping and escaping
• Error conditions and edge cases

There's also a spec package on npm that tools and editors can use as a single source of truth.

What this means for you:

• You don't need to guess at the syntax
• If you're building editors, linters, formatters, or validation tools, you've got a stable spec to work from

3. Toon vs JSON: Token Cost, Readability, Model Performance

3.1 Token Cost: When Does Toon Actually Save 30–60%?

Based on community benchmarks and various blog posts, here's what people are seeing:

• For uniform list/table data, Toon often cuts tokens by 30–60% compared to JSON
• For RAG outputs and report-style data, Toon can significantly reduce context usage and API bills
• For deeply nested, complex JSON, Toon might still help, but the gap is smaller—especially if you've already shortened keys and cleaned up your JSON

Rule of thumb:

The more your data looks like a table, the more Toon helps.

3.2 Model Understanding and Answer Quality

Fewer tokens don't automatically mean better answers, right? So what actually happens?

Early experiments suggest:

• In many tasks, Toon maintains or slightly improves accuracy while using far fewer tokens
• Column-based, table-like layouts often align better with how models represent structured information internally
• If your data isn't very structured, or if it's tiny, Toon might not make much difference

The smart approach:

1. Pick 1–2 real endpoints (not toy examples)
2. Prepare two versions of your prompt:
   • JSON version
   • Toon version
3. Compare:
   • Token usage
   • Quality of outputs
   • Latency and overall cost

Let your own benchmarks guide you, not just what people say on Twitter.

3.3 Readability and Developer Experience

From a human perspective:

• For developers writing code

  • You typically still work with JSON objects in your application
  • Toon conversion happens at the boundary right before you call the LLM
  • You don't manually write Toon text for most use cases

• For developers reading logs

  • Table-like Toon is actually pretty easy to scan
  • For complex nested structures, JSON might remain more familiar and easier to debug
  • A lot of teams log both JSON and Toon during early adoption

Good pattern:

Use Toon at the LLM protocol layer, not as your primary storage or logging format.

4. How to Actually Use Toon: SDKs and Tools

Alright, let's get practical. How do you actually integrate Toon into your codebase?

4.1 Using the Official TypeScript SDK

The official npm package @toon-format/toon works in both Node.js and browsers.

Install it:

npm install @toon-format/toon
# or
pnpm add @toon-format/toon
# or
yarn add @toon-format/toon

Basic usage in Node:

import { decode, encode } from "@toon-format/toon"

const users = [
  { id: 1, name: "Alice", role: "admin" },
  { id: 2, name: "Bob", role: "user" },
]

// JSON object -> Toon string
const toonText = encode(users)

// Toon string -> JSON object
const parsed = decode(toonText)

console.log("Toon representation:")
console.log(toonText)

Integrating it into an LLM call:

import { encode } from "@toon-format/toon"

import { openai } from "./openai-client" // your LLM client

const contextData = [
  /* your structured data */
]

const toonContext = encode(contextData)

const prompt = `
You are a data analyst. The following context is in Toon format.

${toonContext}

Please summarize the number of admins and users.
`

const response = await openai.chat.completions.create({
  model: "gpt-4.1",
  messages: [{ role: "user", content: prompt }],
})

console.log(response.choices[0].message.content)

Key idea: keep your business logic in JSON, treat Toon as the final "wire format" for the LLM.

4.2 Multi-language Support: You Don't Need to Switch Stacks

If your backend isn't JavaScript/TypeScript, no problem. Toon has implementations for:

• Python
• Go
• R
• Elixir
• PHP
• Scala/JVM
• And more popping up regularly

The pattern is usually the same across languages:

1. Work with native data structures (dicts, structs, lists)
2. Call encode() to get Toon text
3. Optionally call decode() to parse Toon back into objects

This makes Toon an implementation detail at your LLM gateway, not a disruptive change to your entire architecture.

4.3 No Code Yet? Try Online JSON → Toon Tools

Before you write any code, it's smart to play around with Toon using online converters. These tools usually let you:

• Paste JSON into a text box
• Convert to Toon with one click
• Compare token counts and visual layout
• Sometimes cross-convert between JSON/CSV/YAML/XML and Toon

Recommended workflow for evaluation:

1. Copy real JSON samples from your system (RAG results, reports, logs)
2. Paste them into a Toon converter
3. Look at:
   • How much shorter the Toon version is
   • How easy it is for you to scan
4. Decide if it's worth doing a PoC

4.4 Using Toon in Workflow Tools and Agent Frameworks

If you're using tools like n8n, LangChain, LlamaIndex, or a custom agent framework, think of Toon as just another transformation step:

• Upstream: Database query / third-party API → gives you JSON
• Middle: Code node or transformation step JSON → Toon
• Downstream: LLM node consumes Toon-formatted context

This approach:

• Minimizes intrusion into the rest of your system
• Makes Toon adoption reversible
• Works well for PoC or low-risk experiments

5. When Should You Actually Use Toon? When Should You Stick with JSON?

5.1 Toon's Sweet Spot

Toon tends to work really well in these scenarios:

1. RAG search results

   • Multiple document snippets with metadata (score, title, source)
   • Uniform, row-based data that maps nicely to Toon tables

2. Recommendations, feeds, rankings

   • Product lists, content feeds, recommended items
   • Repeated fields, consistent structure

3. Reports and metrics

   • Monthly KPIs, funnel breakdowns, channel performance
   • Naturally tabular—Toon keeps that shape but cuts the overhead

4. Agent tool calls and logs

   • Tool schemas, call history, result summaries
   • Makes it easier for the LLM to compare or reason over multiple rows

Bottom line: anywhere you're feeding the model list-style or tabular data.

5.2 When JSON Is Probably Still Better

You don't need to force Toon everywhere. JSON is still great in plenty of situations:

• Highly dynamic schemas tightly coupled to JSON

  • Event buses, log pipelines, third-party APIs that expect JSON
  • Swapping in Toon might cause more integration headaches than it's worth

• Deeply nested, configuration-heavy data

  • Complex trees with many optional fields, custom structures
  • Well-formatted JSON might be more readable, and token savings could be minimal

• Tiny payloads in ultra-latency-sensitive paths

  • If your payload is very small, encoding/decoding overhead might outweigh token savings
  • Toon shines when context size is actually a problem

Pragmatic takeaway:

Treat Toon as an optional optimization layer, not a religion.

5.3 Quick Toon Evaluation Checklist

Ask yourself:

• Is my data more like a table than a deeply nested tree?
• Is my LLM context often close to its token limit?
• Do I have a central LLM gateway where I can add a Toon encoding step?
• Is my team willing to maintain an extra protocol layer?

If you answered "yes" to most of these, Toon is worth exploring with a PoC.

6. Real-world Examples and Best Practices

6.1 Example: Using Toon in a RAG Pipeline

Picture a typical RAG flow:

1. User asks a question
2. You retrieve the top 10 relevant documents from a vector store
3. You assemble those into a JSON structure: each item has title, score, snippet, url
4. You send that JSON into your model with instructions

To try Toon:

1. Keep your internal data as an array of JSON objects
2. Right before calling the LLM, call encode() to get Toon
3. Update your prompt template to say:

   "The following context is provided in Toon format. Each row is one document."

Then run A/B tests:

• JSON vs Toon for the same questions and documents
• Measure:
  • Context tokens per request
  • Response quality (accuracy, missing info)
  • Overall cost and latency

A lot of early adopters report 30–40% lower response token usage in RAG scenarios, with comparable or better answer quality.

6.2 Example: Optimizing an Internal Agent's Tool-Call Protocol

Say you've got an internal agent platform where tools are called via LLM instructions:

• Each tool has a schema, input parameters, output
• Calls and results are logged or passed back into the model

You could:

1. Agree on a Toon-based format for tool invocations and results
2. Introduce a Gateway Layer that:
   • Receives JSON from tools
   • Encodes it to Toon before passing to the model
   • Decodes back into JSON when needed

Benefits:

• Keeps the model-facing protocol lightweight
• Provides a structured way to reason about tool calls as "rows" in a Toon table
• Makes cross-tool analysis and summarization easier for the LLM

6.3 Toon Best Practices

Based on what early adopters are saying:

1. Start small

   • Don't reformat your entire system on day one
   • Pick one or two endpoints where context is actually a bottleneck

2. Benchmark everything

   • Token savings, model performance, latency
   • Use your own data and models, not just published numbers

3. Encapsulate Toon in a central layer

   • Avoid sprinkling encode() calls all over your codebase
   • Wrap Toon usage in an "LLM client" or "context builder" module

4. Tell the model what Toon is

   • Add a short explanation and a tiny Toon example in your system prompt
   • Don't assume the model will figure out the format perfectly

5. Plan for fallback

   • If encoding/decoding fails, have a safe path back to JSON
   • Log Toon errors explicitly during early rollout

7. Wrapping Up: FAQ and Next Steps

7.1 Quick Summary

• What is Toon format?
  Toon is a structured text format designed with LLMs in mind, trying to express the same data as JSON using fewer tokens while staying human-readable.

• How does it compare to JSON?
  It works really well for list/table-like data, often cutting token usage by 30–60% while keeping or improving answer quality in many tasks.

• Where does Toon make the most sense?
  RAG results, recommendations, reports, agent tool calls—anywhere you're feeding structured batches of similar records to models.

• How do you integrate it?
  Treat it as a protocol layer: keep JSON in your code, convert to Toon just before calling the LLM using official SDKs or tools.

• Do you need to replace JSON everywhere?
  Nope. Think of Toon as a targeted optimization, not a universal replacement.

7.2 What You Can Do Next

If you're curious about Toon and want to test it with minimal effort:

1. Copy real JSON samples from your system (RAG results, analytics, logs)
2. Paste them into an online Toon converter and compare:
   • Length and layout
   • Token counts, if the tool supports it
3. If it looks promising, create a small PoC:
   • Add Toon encoding to one LLM endpoint
   • Measure token savings and answer quality
4. Share findings with your team or the community

7.3 FAQ: Common Questions

Q1. Will Toon become an industry standard?
Too early to say. Interest and adoption are climbing fast, but JSON is deeply entrenched. In the near term, expect Toon to coexist with JSON as an optimization option rather than a replacement.

Q2. If I've already optimized my JSON, do I still need Toon?
If your payloads are small or heavily optimized, Toon might offer limited benefits. For large, repetitive datasets, Toon can still provide substantial gains. Always validate with real-world benchmarks.

Q3. Can all models understand Toon?
Yeah, in the sense that Toon is just text. Any general LLM (GPT, Claude, Llama, DeepSeek, etc.) can parse it as long as you explain the format and provide a small example in your prompt.

Q4. What if Toon encoding or decoding fails?
You should always have a fallback path: log the error, skip Toon for that request, and send JSON directly instead. Don't let Toon become a single point of failure.

Q5. Does Toon make debugging harder?
Not really. For tabular data, Toon can actually be easier to inspect than deeply nested JSON. For complex structures, you might want to log both JSON and Toon during rollout until your team gets comfortable.

Look, Toon isn't magic—but it's a genuinely useful new tool for anyone building serious LLM applications.

If you're working on RAG systems, agents, or analytics-heavy AI products and you're hitting token limits or cost ceilings, Toon is absolutely worth a weekend PoC. And if you need help designing that PoC or integrating Toon into your existing stack, you can take the patterns in this guide and adapt them to your specific setup.