How does it work? Im building a video editor and right now it has access to nearly 100 tools. Would be good to learn the techniques you used to make tool discovery more efficient.
I don’t think the Show Me section makes sense, the TOON variant clearly doesn’t have the same information. And the examples in the “How TOON works” section focuses on number of characters instead of tokens. I would think “null” is a single token anyway, why bother replacing it with an uncommon character?
I really doubt that null and \n make any sense to replace with non ascii symbols. They are both most likely already a token only and for other purposes at least \n becomes larger as a symbol.
I am not going to trust a single number thrown by these AI hustlers written in that salesman voice.
Leave alone 97%.
> Your agent calls 20 tools. Each returns 500-3,000 tokens wrapped in {"content":[{"type":"text","text":"..."}]}.
This is a problem with your tool design. Most MCPs are fully vibe coded without any thought about tool selection.
> On a 128K context window, that's 30-55% gone. Not on work. On syntax.
Tool output is not "syntax" you donkey clanker.
Again, use the code approach, let the LLM filter out the JSON using tools. This TOON thing is just vibes. Most of the time your tool output should not even be JSON. It should be well formatted markdown. In cases where it's large structured data, your LLM should have tools (code / jq) to dissect it. So TOON is pointless.
I made an MCP proxy with a similar idea in the past: replace a ton of tools that consume tokens with just two (get_tool_schema, invoke_tool) - https://github.com/ameshkov/mcp-compress-router
One thing that I noticed is that it’s often better to return tool names with argument names, i.e. return “search_web(query)” instead of just “search_web” when listing tools. Otherwise models often tend to hallucinate argument names and an extra turn is required to correct the mistake.
One additional advantage that such tools provide is that when you use different coding agents you don’t have to set up all the MCP servers in every agent, you just set up one (or point the agent to the cli like in this project).
Good point - Claude Code does defer tool loading when definitions exceed 10% of context. That helps a lot.
But they are solving different problems. Deferred loading is "don't load tools until you need them." mcptoon is "when you do load them, the listing is 5x smaller." They are complementary - you can defer loading AND compress what gets loaded.
The scenario where mcptoon helps most is when you actually need all your tools loaded (e.g., a coding session where the agent might call any of 96 tools). Claude Code's deferral would not kick in if you are actively using tools from all 5 servers.
I spent more than one week, as a side project, to add an MCP server to my Cheméo website. Only 4 tools.
It took me way more time than expected, I was thinking: "Just wrap the REST API, 2h, done".
The MCP payload has nothing to do with the REST API one. Because you need to make it interpretable and context efficient even so it is structured data.
It was really interesting work and I suppose very little people are taking the time to rethink what is sent over the wire while creating a MCP server. If so, we would not have MCPs with the minimal payload being 500kB of JSON soup.
If you send my MCP through your "save token filter", I can guarantee you, that you will have trash down the line.
Why is it replacing true/false with T/F? true/false is already 1 token in all tokenizer I've seen. Even worse is replacing null with ∅. ∅ is a special unicode symbol that takes up 2 tokens compared to the 1 token for null...
Agreed. This is what happens when you confuse token counts with byte counts.
A trivial test through tiktoken [1] (though technically you really have to match the tokenizer to the specific LLM) would have shown them that ∅ was a poor choice.
Even from the perspective of learned training data, you can probably just intuit that from a frequency standpoint alone the empty-set symbol ∅ can’t possibly have appeared that often outside of things like set theory and logic.
OP, I'm very interested in seeing an actual comparison ran through a common tokenizer of tool calls. I think you'll find different results than what you intended for this tool to be. You've mixed up tokens with characters on your screen.
Fair point. I used tiktoken (cl100k_base) for all measurements. The 2,034 token count is from the actual JSON tool listing returned by 5 MCP servers (filesystem, memory, sequential-thinking, sqlite, time). The benchmark script is in the repo under /benchmarks if anyone wants to verify.
You're just returning the name of the tool, the rest of the information (description/input schema) is definitely lost. Cut to the LLM making mistakes in calling the tool with incorrect schema or calling the wrong tools altogether, recovering, wasting tokens and cycles.
The format preserves all fields — name, description, and input schema are all there, just encoded with pipes instead of braces and quotes. It's lossless, not a truncation. I should have made that clearer in the post.
I like the idea, but this seems a little too aggressive, JSON (287 tokens) — what every other MCP client returns:
~~~
[
{"name": "search_web", "description": "Search the web for information",
"inputSchema": {"type": "object", "properties": {"query": {"type": "string", "description": "Search query"}, "num_results": {"type": "number", "default": 5}}, "required": ["query"]}},
{"name": "fetch_url", "description": "Fetch content from a URL",
"inputSchema": {"type": "object", "properties": {"url": {"type": "string"}}, "required": ["url"]}}
]
TOON (5 tokens) — what mcptoon returns:
Somewhat related to this project, I'm surprised that not all harnesses are using something like CodeMode for MCPs.
Been experimenting with it in the OpenCode V2 beta and it's pretty great. The combination of tool search, call chaining and field projections feels just right and saves a lot of context. LLMs are good at writing code, who would have thought that?
44 comments
[ 0.26 ms ] story [ 26.4 ms ] threadLeave alone 97%.
> Your agent calls 20 tools. Each returns 500-3,000 tokens wrapped in {"content":[{"type":"text","text":"..."}]}.
This is a problem with your tool design. Most MCPs are fully vibe coded without any thought about tool selection.
> On a 128K context window, that's 30-55% gone. Not on work. On syntax.
Tool output is not "syntax" you donkey clanker.
Again, use the code approach, let the LLM filter out the JSON using tools. This TOON thing is just vibes. Most of the time your tool output should not even be JSON. It should be well formatted markdown. In cases where it's large structured data, your LLM should have tools (code / jq) to dissect it. So TOON is pointless.
One thing that I noticed is that it’s often better to return tool names with argument names, i.e. return “search_web(query)” instead of just “search_web” when listing tools. Otherwise models often tend to hallucinate argument names and an extra turn is required to correct the mistake.
One additional advantage that such tools provide is that when you use different coding agents you don’t have to set up all the MCP servers in every agent, you just set up one (or point the agent to the cli like in this project).
But they are solving different problems. Deferred loading is "don't load tools until you need them." mcptoon is "when you do load them, the listing is 5x smaller." They are complementary - you can defer loading AND compress what gets loaded.
The scenario where mcptoon helps most is when you actually need all your tools loaded (e.g., a coding session where the agent might call any of 96 tools). Claude Code's deferral would not kick in if you are actively using tools from all 5 servers.
It took me way more time than expected, I was thinking: "Just wrap the REST API, 2h, done".
The MCP payload has nothing to do with the REST API one. Because you need to make it interpretable and context efficient even so it is structured data.
It was really interesting work and I suppose very little people are taking the time to rethink what is sent over the wire while creating a MCP server. If so, we would not have MCPs with the minimal payload being 500kB of JSON soup.
If you send my MCP through your "save token filter", I can guarantee you, that you will have trash down the line.
But, why not just use CLIs for each tool? That seems to be where things are going anyway
And using MCP as an internal communication method seems odd when you could use the APIs directly
A trivial test through tiktoken [1] (though technically you really have to match the tokenizer to the specific LLM) would have shown them that ∅ was a poor choice.
Even from the perspective of learned training data, you can probably just intuit that from a frequency standpoint alone the empty-set symbol ∅ can’t possibly have appeared that often outside of things like set theory and logic.
[1] - https://github.com/openai/tiktoken
Tokenization is not some black box, you can run tokenizers and check them.
You're just returning the name of the tool, the rest of the information (description/input schema) is definitely lost. Cut to the LLM making mistakes in calling the tool with incorrect schema or calling the wrong tools altogether, recovering, wasting tokens and cycles.
search_web fetch_url
~~~
Been experimenting with it in the OpenCode V2 beta and it's pretty great. The combination of tool search, call chaining and field projections feels just right and saves a lot of context. LLMs are good at writing code, who would have thought that?