cd /news/ai-agents/code-mode-a-new-way-to-call-tools-an… · home › topics › ai-agents › article
[ARTICLE · art-173312] src=pub.towardsai.net ↗ pub= topic=ai-agents verified=true sentiment=↑ positive

Code Mode: A New Way to Call Tools and do Data Tasks With 10% of the Tokens

A blog post published on the toolkernel GitHub repository argues that agents should replace multi-tool JSON calling with a single "run this code" tool, citing an Anthropic example in which presenting MCP tools as code files cut an agent's usage from about 150,000 tokens to about 2,000. In the post's worked example, 24,000 spreadsheet rows (about 8.5 MB) stay in a Python variable and only the computed EMEA revenue figure, 15960536.65, returns to the model — 149 bytes of context. The post traces the approach to CodeAct (2024), Hugging Face smolagents' CodeAgent, Cloudflare's 2025 "Code Mode" for TypeScript in Workers isolates, and Anthropic's "Code execution with MCP" and programmatic tool calling.

recommendation

Replace per-tool JSON calls with a single sandboxed run_python tool whose namespace holds your functions, keeping large results in variables and returning only printed output plus the last line, capped at 2,000 characters.

more in playbook: Designing agent systems
by read8 min views4 publishedNov 20, 2026

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.

── more in #ai-agents 4 stories · sorted by recency
── more on @anthropic 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/code-mode-a-new-way-…] indexed:0 read:8min 2026-11-20 · —