# ADR-0004: TOON Transformer — Token-Oriented Output Compression

**Status:** Accepted
**Date:** 2026-05-13
**Extension:** `extensions/toon-transformer/index.ts` (315 lines)

## Problem

JSON is verbose for LLM tokenization: every `{`, `}`, `"`, `:`, `,` is a separate token. A 50-entry result = 2000-4000 tokens. Across dozens of tool calls, this eats context window.

## Decision

Intercept structured tool output and encode to [TOON](https://github.com/toon-format/spec):

- Objects → YAML-style indentation (no braces/quotes)
- Uniform arrays → CSV-style tabular layout
- Tracks KB savings per transform

Savings: 40-60% on structured data per [TOON benchmarks](https://toonformat.dev/guide/benchmarks.html).

## Alternatives

| Approach                 | Why Rejected                             |
| ------------------------ | ---------------------------------------- |
| Keep JSON                | Baseline — too verbose                   |
| Compact JSON (no spaces) | Only ~10% improvement; still quote-heavy |
| YAML-only                | No tabular array optimization            |
| CSV-only                 | No nested object support                 |

## Trade-offs

One conversion step per structured response. TOON is newer (2025 spec) but [arXiv 2603.03306](https://arxiv.org/abs/2603.03306) confirms solid LLM comprehension via one-shot in-context learning, even though TOON was never in training data.

## References

- [TOON spec](https://github.com/toon-format/spec) — ABNF grammar, encoding rules
- [TOON benchmarks](https://toonformat.dev/guide/benchmarks.html) — 209 questions, 4 models, accuracy/1K tokens ranking
- [arXiv 2603.03306](https://arxiv.org/abs/2603.03306) — TOON vs JSON comprehension + generation benchmark
- [Byte-level efficiency model](https://toonformat.dev/reference/efficiency-formalization) — formal mathematical comparison
