Ask an AI agent “What was our EMEA revenue last quarter?” and look at what actually happens.
The agent calls a tool like read_table("sales_2025.xlsx"). The tool returns 24,000 rows. All 24,000 rows go into the model's context, about 8.5 MB of text. The model then reads all of it, as tokens, to add up one column.
That’s how tool calling works in most agents today, MCP included: the tool’s result goes straight into the conversation. That’s fine for “what’s the weather?”. For spreadsheets, CSV exports, log files, long web pages and API responses with thousands of records, it costs a lot of money, runs slowly, and is often wrong. Models are bad at adding up 2,000 numbers by reading them.
This post covers:
The fix is simple to state. Instead of giving the model 20 tools and putting each result into its context, give it one tool: “run this code”. The other tools become functions the code can call.
rows = read_table(path="sales/sales_2025.xlsx", sheet="Orders")["rows"] # 24,000 rows stay in Pythonsum(r["revenue"] for r in rows if r["region"] == "EMEA" and r["order_date"][5:7] in ("07", "08", "09"))
The 24,000 rows land in a Python variable. Only the last line’s value goes back to the model: 15960536.65. 8.5 MB of data, 149 bytes for the model to read. The arithmetic is done by Python, which is good at it, instead of by the model, which isn't.
This is not my idea, and it’s not new. A short history:
Who What How it works------------------------------------------------- --------------------------------------------------------------------- -------------------------------------------------------------------------------------CodeAct (research paper, 2024) Agents that act by writing Python instead of emitting JSON tool calls Showed that code as the action format works better than JSON on many agent benchmarksHugging Face smolagents CodeAgent An open-source agent framework where the model writes Python that calls toolsCloudflare "Code Mode" (2025) Turns MCP tools into a TypeScript API The model writes TypeScript, which runs in a sandboxed Workers isolateAnthropic, "Code execution with MCP" (2025) Presents MCP tools as code files the agent can browse Their example cut an agent's usage from about 150,000 tokens to about 2,000Anthropic, programmatic tool calling (Claude API) Claude calls your tools from code it runs in a sandbox Intermediate results stay out of the context
They all rest on the same insight: models are trained on huge amounts of code, and code can keep data out of the context. Code can filter, join, loop and add up, and only the result needs to come back.
(Links are at the end. Things move fast here, so check them for the latest.)
You don’t need a framework to try this. Here’s a complete, working version. The full file is examples/tiny_code_mode.py.
Step 1: the tools are plain Python functions, placed in a dictionary that will be the code’s namespace:
def read_csv(path: str) -> list[dict]: with open(DATA / path, newline="") as f: return list(csv.DictReader(f))
php
def read_jsonl(path: str) -> list[dict]: return [json.loads(line) for line in open(DATA / path)]
namespace = {"read_csv": read_csv, "read_jsonl": read_jsonl, "list_files": list_files}
Step 2: one tool for the model, run_python. It runs the code in that same namespace, so variables survive from one step to the next. It returns what the code printed plus the value of the last line, cut to 2,000 characters:
def run_python(code: str) -> str: out = io.StringIO() try: tree = ast.parse(code) last = tree.body.pop() if tree.body and isinstance(tree.body[-1], ast.Expr) else None with contextlib.redirect_stdout(out): exec(compile(tree, "<agent>", "exec"), namespace) if last is not None: value = eval(compile(ast.Expression(last.value), "<agent>", "eval"), namespace) if value is not None: print(repr(value)) except Exception as e: print(f"{type(e).__name__}: {e}", file=out) text = out.getvalue() or "(no output)" if len(text) > MAX_RESULT: text = text[:MAX_RESULT] + f"\n[cut: {len(text) - MAX_RESULT:,} more characters. Print less.]" return text
That character cap matters more than it looks. Without it, one careless print(rows) from the model puts the whole file back into its context, and you're back where you started.
Step 3: an ordinary agent loop, with one tool:
for _ in range(15): r = client.chat.completions.create(model=model, messages=messages, tools=[TOOL]) msg = r.choices[0].message messages.append(msg.model_dump(exclude_none=True)) if not msg.tool_calls: print("Answer:", msg.content); break for call in msg.tool_calls: result = run_python(json.loads(call.function.arguments)["code"]) messages.append({"role": "tool", "tool_call_id": call.id, "content": result})
I asked it “Which region has the slowest average resolution time for urgent support tickets?” That means reading 9,000 tickets from a JSONL file, joining them to 4,000 customers in a CSV, and averaging. With gpt-5-mini, the model wrote a loop that joined and averaged in Python, and saw only this:
[('APAC', 30.46), ('NA', 28.09), ('LATAM', 28.03), ('EMEA', 27.85)]
It answered APAC, 30.46 hours, which is correct, using 15,927 tokens in total.
This toy is enough to understand the idea, and it’s also where the hard parts begin:
Filling these gaps is what I wanted to learn about, so I built ToolKernel.
ToolKernel is a self-hosted gateway that sits between an AI agent and its MCP servers. To the agent, it looks like a single MCP server. Behind it, it connects to all your real ones.
AI agent (Claude Code, Cursor, your own agent) │ one MCP server, 7 tools (execute_code, search_tools, describe_tool, ...) ▼ToolKernel ── persistent Python runtime per session │ └─ typed Python packages generated from each tool's schema: servers.github, servers.files, ... │ └─ output guard, policies and approvals, web UI ▼Your MCP servers: GitHub · Slack · files · databases · anything
[Image: docs/images/tour.gif or docs/images/home.png from the repo]
What it adds on top of the 80-line version:
[result] 15960536.65 [state] orders: list[24000] [meta] exec 2747ms · tool calls 1 (files.read_table ×1) · data via tools 8.5 MB · returned 149 B
To test it end to end, I wrote examples/agent_demo.py. It runs one agent loop on one question, twice:
The only difference between the two runs is which MCP server the agent connects to:
if mode == "direct": read, write = await stack.enter_async_context(stdio_client(files_server_params))else: read, write, *_ = await stack.enter_async_context(streamable_http_client("http://localhost:7300/mcp"))
I used three questions, each with an answer I checked independently, and two cheap models: gpt-5-mini and DeepSeek’s deepseek-flash. The data is synthetic.
Question Data it needs Correct answer-------------------------------------------------------------- ----------------------------------------------------- --------------Q1: total EMEA revenue in Q3 2025 Excel, 24,000 rows 15,960,536.65Q2: customer segment with the most high-priority tickets in Q3 JSONL (9,000 tickets) joined to CSV (4,000 customers) SMB, 201Q3: region with the slowest urgent-ticket resolution Same join, then an average APAC, 30.46 h
Question Model Direct ToolKernel-------- -------------- ----------------------------------------------- -------------------------------Q1 deepseek-flash ✅ 180k tokens, 133 s ✅ 34k tokens, 13 sQ1 gpt-5-mini ❌ gave up, 628k tokens ❌ ran out of turns, 78k tokensQ2 deepseek-flash ❌ "SMB, 200" (off by one), 1.33M tokens, 373 s ✅ SMB, 201 · 37k tokens, 13 sQ2 gpt-5-mini ❌ "SMB, 612", 925k tokens ✅ SMB, 201 · 73k tokensQ3 deepseek-flash ✅ 465k tokens, 200 s ✅ 63k tokens, 20 sQ3 gpt-5-mini ❌ "EMEA, 38.6 h", 202k tokens ✅ APAC, 30.46 h · 33k tokens
Totals
Direct ToolKernel--------------- ------------ --------------------------Correct answers 2 of 6 5 of 6Tokens 3.73 million 317 thousand (11.8× fewer)Cost $0.505 $0.029 (about 18× less)Time 17.5 min 2.9 min
The direct runs didn’t fail in one way. They failed in four:
DeepSeek did get Q1 and Q3 right in direct mode, so direct can work. It just takes 5–10× more tokens and time to get there.
On Q1, gpt-5-mini went in circles in ToolKernel mode. It kept calling read_output and search_tools instead of the table, and hit the 25-turn limit. My earlier, larger benchmark found the same weakness with this model. Code mode moves the problem: the model no longer has to read the data, but it has to write good code against an API it's never seen. Smaller models sometimes struggle with that, and how the tools are described matters a lot.
Building the benchmark also found six bugs in ToolKernel itself. One example: an empty folder in the runtime misled agents into looking there for data instead of using the tools. The fixes are listed in the repo.
This is a small experiment: 3 questions, 2 models, 1 run each, on synthetic data that’s heavy by design. On questions whose tool results are small (“what’s the weather?”), code mode adds overhead and won’t help. The repo has a larger benchmark (7 task types, 3 models, 4 configurations) with the same pattern: 8/21 correct with tools wired in directly against 20/21 through ToolKernel, with about 10× fewer tokens. It’s still small. Please rerun it, and tell me where it breaks.
Use it when your agent:
Skip it when results are small and tasks are one-shot, or when you can’t run model-written code safely.
To try it:
The lesson I’d take from this: the agent doesn’t need to see the data. It needs to see the answer.
ToolKernel is a learning project, not production software.
Code Mode: A New Way to Call Tools and do Data Tasks With 10% of the Tokens was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.