toon-formatlisted

# TOON Format ## What TOON Is TOON (Token-Oriented Object Notation) is a compact, human-readable encoding of the JSON data model optimized for LLM context windows. It uses YAML-style indentation for objects and CSV-style tabular rows for uniform arrays. It achieves ~40% fewer tokens than JSON on mixed-structure data. TOON is a **wire format between harness and model** — not a replacement for JSON in code. ## When to Use TOON Use TOON when injecting structured data into context and the data has repeated structure: - Tool call results that return arrays of objects (database rows, search results, file listings). - RAG document metadata and chunks (maximize documents per context window). - Few-shot examples with uniform shape. - API response payloads with tabular data. Do **not** use TOON when: - Data is deeply nested and irregular (≤40% tabular eligibility) — JSON compact is smaller. - Data is flat homogeneous rows with no LLM parsing needed — CSV is 5–10% smaller. - The model or downstream consumer expects JSON explicitly. **Decision rule**: if the data contains arrays of objects with mostly the same keys, use TOON. Otherwise, use JSON. ## How to Encode Data as TOON ### Encoding Tool Results When a tool returns structured JSON, encode it as TOON before injecting into the conversation. Use the TypeScript SDK: ```typescript import { encode } from '@toon-format/toon' const toon = encode(toolResult) ``` Wrap in a `toon` code fence when embedding in a message: ```` ```to