What is TOON? A Token-Efficient Format for AI Agent Data

Every tool call in an MCP conversation consumes tokens. Calendar data is particularly verbose — event titles, timestamps, timezone metadata, attendee lists. When an agent queries a week of events across three calendars, the response can easily hit 2,000-3,000 tokens in JSON.

TOON (Token-Optimized Object Notation) is a structured data format designed to reduce this cost. All Temporal Cortex data tools return TOON by default, and it typically produces ~40% fewer tokens than equivalent JSON.

How TOON differs from JSON

TOON keeps data machine-parseable while eliminating the structural overhead that inflates token counts. Three key techniques:

1. Indentation replaces braces and commas

JSON wraps every object in {} and every array in [], with commas between elements. TOON uses indentation (like Python or YAML) to convey structure.

{
  "event": {
    "summary": "Team Standup",
    "start": "2026-03-16T09:00:00-04:00",
    "end": "2026-03-16T09:30:00-04:00"
  }
}

event
  summary: Team Standup
  start: 2026-03-16T09:00:00-04:00
  end: 2026-03-16T09:30:00-04:00

The TOON version has zero braces, zero commas, and zero quotes around keys or simple values. Every character serves the data, not the format.

2. Tabular arrays for uniform objects

When an array contains objects with the same keys (common in calendar responses — a list of events all have summary, start, end), TOON uses a tabular format:

[
  { "summary": "Standup", "start": "09:00", "end": "09:30" },
  { "summary": "1:1 with Alice", "start": "10:00", "end": "10:30" },
  { "summary": "Design Review", "start": "14:00", "end": "15:00" }
]

| summary         | start | end   |
| Standup          | 09:00 | 09:30 |
| 1:1 with Alice   | 10:00 | 10:30 |
| Design Review    | 14:00 | 15:00 |

The tabular form eliminates repeated key names entirely. For a 10-event response, that’s 30 fewer key-name tokens.

3. Context-dependent quoting

JSON requires quotes around all strings, even when unambiguous. TOON only quotes strings when necessary — when the value is empty, looks like a boolean or number, or contains special characters (colons, brackets, backslashes).

{ "name": "Alice", "available": true, "slots": 3 }

name: Alice
available: true
slots: 3

Alice doesn’t need quotes — it’s clearly a string. true and 3 don’t need quotes either — the parser knows their types from context.

Token comparison: a real calendar response

Here’s a realistic find_free_slots response for a workday — 5 free slots found:

JSON (87 tokens):

{
  "slots": [
    { "start": "2026-03-16T08:00:00-04:00", "end": "2026-03-16T09:00:00-04:00", "duration_minutes": 60 },
    { "start": "2026-03-16T10:30:00-04:00", "end": "2026-03-16T12:00:00-04:00", "duration_minutes": 90 },
    { "start": "2026-03-16T13:00:00-04:00", "end": "2026-03-16T14:00:00-04:00", "duration_minutes": 60 },
    { "start": "2026-03-16T15:30:00-04:00", "end": "2026-03-16T16:30:00-04:00", "duration_minutes": 60 },
    { "start": "2026-03-16T17:00:00-04:00", "end": "2026-03-16T18:00:00-04:00", "duration_minutes": 60 }
  ],
  "count": 5
}

TOON (52 tokens):

slots
  | start                          | end                            | duration_minutes |
  | 2026-03-16T08:00:00-04:00      | 2026-03-16T09:00:00-04:00      | 60               |
  | 2026-03-16T10:30:00-04:00      | 2026-03-16T12:00:00-04:00      | 90               |
  | 2026-03-16T13:00:00-04:00      | 2026-03-16T14:00:00-04:00      | 60               |
  | 2026-03-16T15:30:00-04:00      | 2026-03-16T16:30:00-04:00      | 60               |
  | 2026-03-16T17:00:00-04:00      | 2026-03-16T18:00:00-04:00      | 60               |
count: 5

40% fewer tokens. Same data. Perfect roundtrip fidelity — you can convert TOON back to JSON and get the identical structure.

When to use JSON instead

TOON is the default output for all Temporal Cortex data tools, but every tool accepts a format: "json" parameter to get standard JSON instead. Use JSON when:

• Programmatic parsing: Your code consumes the tool response directly and you already have a JSON parser
• Debugging: JSON is more familiar for most developers inspecting raw responses
• Interop: Other tools in your pipeline expect JSON

For AI agent conversations — where the response flows into an LLM’s context window — TOON is almost always the better choice. The LLM reads it just as easily, and the token savings compound across a multi-turn scheduling conversation.

TOON specification

TOON has precise rules for when to quote, how to handle special characters, and what constitutes valid output. The key rules:

• No trailing whitespace or newlines
• Numbers: No exponents, no leading zeros, no trailing fractional zeros
• Strings: Quote if empty, or if the value looks like a boolean/null/number, or contains colons, backslashes, brackets, or control characters
• Keys: Unquoted if they match ^[A-Za-z_][A-Za-z0-9_.]*$
• Arrays: Inline form for short arrays, tabular form for uniform objects, mixed form for heterogeneous data

The full specification and a CLI tool (toon encode / toon decode / toon stats) are available in the Temporal Cortex Core repository. TOON is one of several components we open-sourced as part of our core time engine — read more about that decision in Why We Open-Sourced Our Time Engine. You can try the interactive TOON/JSON toggle on the Architecture page.