MCP structuredContent vs Text Content: Where TOON Fits
MCP tools return structuredContent JSON plus a text block the model reads. Keep JSON for clients and put TOON in the text block. Spec rules, examples, caveats.
An MCP tool result can carry the same data twice: as JSON in structuredContent for programs, and as a text block for the model and older clients. The spec says that text SHOULD be the serialized JSON. For large uniform arrays, you can keep JSON in structuredContent and put TOON in the text block, if you accept the compatibility trade-off.
What is structuredContent in an MCP tool result?
The MCP 2026-07-28 tools specification defines two kinds of tool output. Unstructured content goes in the content array and can contain text, images, audio, resource links and embedded resources. Structured content is "returned as a JSON value in the structuredContent field", and it can be any JSON value: an object, array, string, number, boolean or null.
Three rules from the spec shape how you use it:
- If a tool declares an
outputSchema, "Servers MUST provide structured results that conform to this schema," and clients SHOULD validate them. - "For backwards compatibility, a tool that returns structured content SHOULD also return the serialized JSON in a TextContent block."
structuredContent"is unrelated to LLM 'structured outputs'". It is data produced by the server, not schema-constrained text generated by the model.
Schemas default to JSON Schema 2020-12 when no $schema is given.
Which part does the model actually read?
The spec does not say, and that is the key point. It defines what a server returns, not what the host application puts into the model's context. Some clients forward the text block, some can use structuredContent, and older clients only know about content. That is why the spec asks for the JSON mirror in text: it is the channel every client understands.
The text block also does not have to be a verbatim copy in practice. The spec's own list_users example returns the user array in structuredContent and a one-line prose summary in the text block: "Found 2 users: Alice (alice@example.com) and Bob (bob@example.com)." The text block is for whoever consumes it, and you choose its format.
What does a tool result look like with JSON vs TOON text?
Here is the spec-default shape, with the serialized JSON mirrored into the text block:
{
"resultType": "complete",
"content": [
{
"type": "text",
"text": "{\"items\":[{\"sku\":\"KB-201\",\"name\":\"Mechanical keyboard\",\"stock\":42,\"warehouse\":\"AMS\"},{\"sku\":\"MS-110\",\"name\":\"Wireless mouse\",\"stock\":0,\"warehouse\":\"AMS\"},{\"sku\":\"HD-330\",\"name\":\"USB-C hub, 7-port\",\"stock\":15,\"warehouse\":\"BER\"}]}"
}
],
"structuredContent": {
"items": [
{ "sku": "KB-201", "name": "Mechanical keyboard", "stock": 42, "warehouse": "AMS" },
{ "sku": "MS-110", "name": "Wireless mouse", "stock": 0, "warehouse": "AMS" },
{ "sku": "HD-330", "name": "USB-C hub, 7-port", "stock": 15, "warehouse": "BER" }
]
}
}And the same result with TOON in the text block. structuredContent is unchanged:
{
"resultType": "complete",
"content": [
{
"type": "text",
"text": "items[3]{sku,name,stock,warehouse}:\n KB-201,Mechanical keyboard,42,AMS\n MS-110,Wireless mouse,0,AMS\n HD-330,\"USB-C hub, 7-port\",15,BER"
}
],
"structuredContent": {
"items": [
{ "sku": "KB-201", "name": "Mechanical keyboard", "stock": 42, "warehouse": "AMS" },
{ "sku": "MS-110", "name": "Wireless mouse", "stock": 0, "warehouse": "AMS" },
{ "sku": "HD-330", "name": "USB-C hub, 7-port", "stock": 15, "warehouse": "BER" }
]
}
}Decoded, the TOON text reads:
items[3]{sku,name,stock,warehouse}:
KB-201,Mechanical keyboard,42,AMS
MS-110,Wireless mouse,0,AMS
HD-330,"USB-C hub, 7-port",15,BERThe encoder (@toon-format/toon 4.1.1) quoted USB-C hub, 7-port because it contains the comma delimiter. That is required for the row to decode correctly. With three rows the saving is small, but on a 500-row result the header is written once and every repeated key disappears.
Which text-block strategy should you choose?
| Text block contains | Spec status | Best for | Risk |
|---|---|---|---|
| Serialized JSON | Recommended (SHOULD) | Small or nested results; unknown clients | Repeats every key; most tokens |
| TOON | Allowed deviation | Large uniform arrays the model only reads | Clients that parse text as JSON will fail |
| Prose summary | Used in the spec's own example | Few records; human-facing hosts | Model loses exact field values |
| TOON, no structuredContent | Valid only without an outputSchema | Model-only tools | No typed data for programs; no validation |
The second row is the usual compromise. Programs get schema-validated JSON in structuredContent, and the model gets the compact version. Say so in the tool description, for example "Text output is TOON: one header line, then one row per item", so the model knows what it is reading.
How do you implement it in a server?
Whatever SDK you use, the handler ends by building the result object. The format choice is a few lines:
import { encode } from "@toon-format/toon";
const TOON_MIN_ROWS = 20; // below this, plain JSON is simpler and nearly as small
export async function listInventory(args: { warehouse?: string }) {
const items = await db.inventory.findMany({
where: { warehouse: args.warehouse },
orderBy: { sku: "asc" }, // stable order keeps the output cacheable
});
const structured = { items };
const text = items.length >= TOON_MIN_ROWS
? encode(structured)
: JSON.stringify(structured);
return {
content: [{ type: "text", text }],
structuredContent: structured, // must match outputSchema
};
}The row threshold is a judgment call, not a spec value. Pick it from your own measurements. Our MCP server with TOON tutorial walks through a full server, and our hosted TOON MCP server exposes json_to_toon and toon_to_json tools you can try from any MCP client.
What about proxies like Tooner?
If you do not control the server, Tooner is an MCP proxy listed in the TOON README. It launches the real server as a subprocess and converts JSON responses to TOON on the way through. Its README claims about 40% fewer tokens on JSON-heavy outputs. It does not document how it treats structuredContent, so test it with your client before you rely on it.
Does TOON in tool results actually help?
For reading data, the evidence is good. The current official benchmark (spec v4.1, 5,856 calls) found TOON used 42.6% fewer tokens than JSON with 72.2% accuracy versus 71.4%. For agents, it is mixed. arXiv 2605.29676 ran MCP benchmarks on open-weight models and found up to 18% fewer tokens at about a 9-point accuracy cost, concluding TOON is "not safe as a default in multi-turn agentic systems." See our summary of that study.
The practical answer is to use TOON per tool, not globally: for large uniform results the model reads once, and not for small, nested or multi-turn outputs. The spec background is in MCP 2026-07-28 spec changes. To check a real tool response, paste it into the JSON to TOON converter.
Frequently Asked Questions
What is structuredContent in MCP?
structuredContent is an optional field on an MCP tool result that holds a JSON value. If the tool declares an outputSchema, the server must return structured content that matches it, and clients should validate it. It is server data, unrelated to LLM structured outputs.
Can I put TOON in the text block of an MCP tool result?
Yes, but it is a deliberate deviation. The spec says a tool returning structured content SHOULD also return the serialized JSON in a text block. SHOULD is not MUST, so TOON is allowed, but you lose compatibility with clients that parse that text as JSON.
Does the model read structuredContent or the text content?
The spec does not say. Each MCP client decides what it puts in the model's context. The text block is the backwards-compatible channel every client understands, so check what your host forwards before optimizing either one.
When should I keep JSON in the text block?
Keep JSON for small results, deeply nested or irregular data, clients that parse the text block as JSON, and long multi-turn agents where research found TOON less reliable. Use TOON for large uniform arrays that the model only needs to read.
Recommended Reading
MCP 2026-07-28 Spec: Stateless Servers and Your Data
The MCP 2026-07-28 spec drops sessions and the initialize handshake, adds cacheable lists and header routing. What changed and how to format tool results.
Is TOON Safe for AI Agents? What the 2026 Research Says
A 2026 arXiv study found TOON saves up to 18% of tokens in agent loops but costs about 9 accuracy points on open models. Where it helps and where it breaks.
Building an MCP Server That Returns TOON
Building an MCP server that returns TOON instead of JSON. Tool results dominate agent token budgets; the input/output format split keeps it reliable.