On this article, you’ll study what instrument calling and code execution are as agent motion primitives, how they differ mechanically, and when to decide on one over the opposite.
Matters we are going to cowl embody:
- How instrument calling works beneath the hood, and why it stays the precise alternative for single, time-sensitive lookups.
- How code execution through Programmatic Device Calling differs from normal instrument calling, and what measurable advantages it presents for fan-out and aggregation duties.
- A sensible resolution framework for selecting between the 2 primitives primarily based on name depend, information sensitivity, latency, infrastructure, and auditability wants.
Image an agent asking one simple-sounding query: which of twenty workers went over their Q3 journey finances. To reply it, the agent wants every individual’s expense line objects, each flight, lodge, and meal receipt, in contrast towards a finances restrict tied to their stage. Constructed the apparent method, with the mannequin calling a instrument for every individual’s bills one by one, that’s twenty separate instrument calls, every returning fifty to 100 line objects, and each single a type of objects has to move by way of the mannequin’s context simply so it may be added up. That’s over 2,000 line objects and greater than 50KB of uncooked information the mannequin by no means truly wanted to learn — it wanted a sum.
That’s the true price hiding behind a design resolution most agent tutorials skip previous fully: how does an agent truly take motion on the earth. There are two actual solutions, instrument calling and code execution, and which one you attain for isn’t a method choice — it’s an architectural alternative with measurable penalties for price, latency, and accuracy. This text breaks down each motion primitives for AI brokers intimately, builds an actual, runnable instance of every utilizing the identical underlying instrument, and closes with an sincere, numbers-backed framework for selecting between them. If you happen to haven’t constructed a fundamental tool-calling agent but, try this text, Straightforward Agentic Device Calling with Gemma 4 — it’s the pure place to begin earlier than this one.
What Is an Motion Primitive, and Why Does the Alternative Matter?
An motion primitive is the elemental mechanism by which a language mannequin turns a choice into an actual impact on the earth — a database write, an API name, a file learn. Each agent framework, no matter else it does, is constructed on high of considered one of these primitives at its core.
Device calling is the primitive most individuals study first: the mannequin produces one structured request at a time, a number software executes it, and the consequence comes again into the dialog earlier than the mannequin decides what to do subsequent. Code execution is the newer various: as a substitute of requesting one motion and ready, the mannequin writes an precise program — in Python or TypeScript — that performs a number of actions in sequence or in parallel, and solely this system’s closing output returns to the mannequin.
Neither one is a wrapper across the different, and neither has quietly changed the opposite. They’re genuinely completely different mechanisms with completely different failure modes, completely different infrastructure necessities, and completely different price profiles, and the remainder of this text is about understanding each nicely sufficient to select accurately.
Device Calling
It’s price understanding what’s truly taking place beneath a instrument name, as a result of the mechanics clarify each its strengths and its actual limitations. In accordance with Cloudflare’s detailed breakdown of the method, a mannequin producing a instrument name doesn’t produce odd textual content. It’s been particularly educated to output a pair of particular tokens — one signaling “the next is a instrument name” and one other marking its finish — with a JSON payload describing the instrument identify and arguments sitting between them. The applying operating the mannequin watches for these tokens, pauses technology the second it sees the closing one, parses the JSON towards a schema you outlined, truly executes the decision, and feeds the consequence again into the dialog as if it have been the following factor the consumer stated.
That’s a clear, auditable, one-step-at-a-time loop, and it’s precisely why instrument calling turned the default. Each motion is a discrete, loggable occasion. Each result’s one thing the mannequin instantly sees and may cause about in pure language earlier than deciding what occurs subsequent.
Code Execution
Code execution takes a unique beginning place fully: as a substitute of asking the mannequin to explain an motion in a constrained JSON format, you let it write precise code that performs the motion, operating in a sandboxed setting separate from the mannequin itself. Anthropic’s authentic code-execution-with-MCP sample frames this exactly as presenting your instruments as a code API slightly than a set of instantly callable features, so the mannequin can write a script that imports precisely the instruments it wants and calls them the best way it might name every other operate.
The mechanism that makes this genuinely completely different — not only a relabeled instrument name — is what Anthropic now calls Programmatic Device Calling, launched alongside two companion options in November 2025. Reasonably than every instrument consequence flowing again by way of the mannequin one by one, you mark particular instruments as callable from code by including an allowed_callers subject to their definition, and add a code_execution instrument to the request. When the mannequin needs to behave, it writes a full script — loops, conditionals, error dealing with, and all — that calls these instruments instantly inside a sandboxed execution setting. Every particular person instrument name the script makes nonetheless executes precisely the best way it might in odd instrument calling; you continue to obtain a request and return a consequence, however that result’s intercepted and processed by the operating script slightly than being pushed into the mannequin’s context. Solely when the script finishes does its closing output — and nothing else — return to the mannequin.
That’s the whole distinction in a single sentence: instrument calling places each intermediate end in entrance of the mannequin; code execution lets the mannequin determine, by way of the code it writes, precisely what makes it again.
A side-by-side movement diagram of Device Calling and Code Execution (click on to enlarge)
Device Calling for a Single, Time-Delicate Lookup
Idea is less complicated to belief as soon as it’s operating towards an actual API, so each examples on this article use the identical instrument — a get_weather operate backed by Open-Meteo, a free climate API that wants no API key in any respect, solely an Anthropic API key to run the agent itself.
Begin with the case instrument calling is clearly proper for: a single query that wants one lookup and a natural-language reply — “what’s the climate like in London proper now.”
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 |
import json import requests from anthropic import Anthropic
consumer = Anthropic() # reads ANTHROPIC_API_KEY from the setting
def get_weather(metropolis: str) -> dict: “”“Search for a metropolis’s coordinates, then fetch its present temperature and this week’s every day highs from Open-Meteo’s free, keyless API.”“” geo = requests.get( “https://geocoding-api.open-meteo.com/v1/search”, params={“identify”: metropolis, “depend”: 1}, ).json() if not geo.get(“outcomes”): return {“error”: f“Couldn’t discover a location named ‘{metropolis}'”} lat = geo[“results”][0][“latitude”] lon = geo[“results”][0][“longitude”]
forecast = requests.get( “https://api.open-meteo.com/v1/forecast”, params={ “latitude”: lat, “longitude”: lon, “present”: “temperature_2m”, “every day”: “temperature_2m_max”, “timezone”: “auto”, }, ).json()
return { “metropolis”: metropolis, “current_temp_c”: forecast[“current”][“temperature_2m”], “week_high_temps_c”: forecast[“daily”][“temperature_2m_max”], “unit”: “celsius”, }
weather_tool = { “identify”: “get_weather”, “description”: ( “Get the present temperature and this week’s every day excessive “ “temperatures for a metropolis. Returns JSON with metropolis, “ “current_temp_c, week_high_temps_c (7 every day highs), and unit.” ), “input_schema”: { “kind”: “object”, “properties”: { “metropolis”: {“kind”: “string”, “description”: “Metropolis identify, e.g. ‘Lagos'”} }, “required”: [“city”], }, }
messages = [{“role”: “user”, “content”: “What’s the weather like in London right now?”}]
response = consumer.messages.create( mannequin=“claude-sonnet-5”, max_tokens=1024, instruments=[weather_tool], messages=messages, )
# Maintain resolving instrument calls till Claude produces a closing textual content reply whereas response.stop_reason == “tool_use”: messages.append({“position”: “assistant”, “content material”: response.content material}) tool_results = []
for block in response.content material: if block.kind == “tool_use” and block.identify == “get_weather”: consequence = get_weather(**block.enter) tool_results.append({ “kind”: “tool_result”, “tool_use_id”: block.id, “content material”: json.dumps(consequence), })
messages.append({“position”: “consumer”, “content material”: tool_results}) response = consumer.messages.create( mannequin=“claude-sonnet-5”, max_tokens=1024, instruments=[weather_tool], messages=messages, )
for block in response.content material: if block.kind == “textual content”: print(block.textual content) |
Strolling by way of what issues right here: get_weather itself is odd Python — nothing agent-specific about it — it geocodes a metropolis identify and pulls each the present temperature and the week’s every day highs in a single request. The weather_tool dictionary is the schema Claude truly sees, and the outline issues greater than it seems — a obscure description is likely one of the most typical causes of a mannequin calling a instrument with the improper arguments. The whereas response.stop_reason == “tool_use” loop is the true mechanical coronary heart of ordinary instrument calling: each time Claude requests the instrument, your code has to truly run it, wrap the consequence as a tool_result block, append it to the dialog, and name the API once more — and this repeats for as many instrument calls as the duty wants. For a single lookup like this one, that’s one move by way of the loop and executed, which is precisely why instrument calling matches this case nicely: one name, one consequence, and a consequence small and related sufficient that Claude genuinely advantages from seeing it instantly earlier than writing a natural-language reply.
Code Execution for Fan-Out and Aggregation
Now change the query, utilizing the very same get_weather operate — fully unchanged: “given these fifteen cities, which one can have the coldest excessive temperature this week, and what’s the common weekly excessive throughout all of them?”
Run that by way of the tool-calling loop above and also you’d get fifteen separate instrument calls, fifteen full JSON payloads of every day temperatures pushed into Claude’s context, and Claude would then must manually evaluate and common them in pure language — gradual, token-expensive, and precisely the type of arithmetic a mannequin is extra error-prone at than a for-loop is. That is exactly the case Programmatic Device Calling was constructed for.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 |
import json from anthropic import Anthropic
consumer = Anthropic()
# Identical get_weather operate from the earlier instance, unchanged
weather_tool = { “identify”: “get_weather”, “description”: ( “Get the present temperature and this week’s every day excessive “ “temperatures for a metropolis. Returns JSON with metropolis, “ “current_temp_c, week_high_temps_c (7 every day highs), and unit.” ), “input_schema”: { “kind”: “object”, “properties”: { “metropolis”: {“kind”: “string”, “description”: “Metropolis identify, e.g. ‘Lagos'”} }, “required”: [“city”], }, # That is the one line that modifications the primitive: it opts the instrument # into being known as from inside generated code, not solely instantly # by the mannequin “allowed_callers”: [“code_execution_20250825”], }
code_execution_tool = {“kind”: “code_execution_20250825”, “identify”: “code_execution”}
cities = [ “Lagos”, “Nairobi”, “Cairo”, “Accra”, “Kigali”, “Casablanca”, “Addis Ababa”, “Dakar”, “Tunis”, “Kampala”, “Harare”, “Lusaka”, “Maputo”, “Windhoek”, “Gaborone”, ]
messages = [{ “role”: “user”, “content”: ( f“Given these cities: {‘, ‘.join(cities)}, which one will have “ “the coldest high temperature this week, and what’s the average “ “weekly high across all of them? Use the get_weather tool.” ), }]
response = consumer.beta.messages.create( betas=[“advanced-tool-use-2025-11-20”], mannequin=“claude-sonnet-5”, max_tokens=2048, instruments=[code_execution_tool, weather_tool], messages=messages, )
# The loop seems much like normal instrument calling, however now some # tool_use blocks carry a “caller” subject, which means the request got here # from inside Claude’s generated script slightly than from Claude instantly whereas response.stop_reason == “tool_use”: messages.append({“position”: “assistant”, “content material”: response.content material}) tool_results = []
for block in response.content material: if block.kind == “tool_use” and block.identify == “get_weather”: consequence = get_weather(**block.enter) tool_results.append({ “kind”: “tool_result”, “tool_use_id”: block.id, “content material”: json.dumps(consequence), })
if tool_results: messages.append({“position”: “consumer”, “content material”: tool_results})
response = consumer.beta.messages.create( betas=[“advanced-tool-use-2025-11-20”], mannequin=“claude-sonnet-5”, max_tokens=2048, instruments=[code_execution_tool, weather_tool], messages=messages, )
for block in response.content material: if block.kind == “textual content”: print(block.textual content) |
The only most essential line on this complete script is “allowed_callers”: [“code_execution_20250825”]. With out it, the instrument behaves precisely because it did within the earlier instance — callable solely instantly by the mannequin. With it added, Claude positive aspects the choice to jot down a script that calls get_weather fifteen instances itself, doubtless in parallel utilizing asyncio.collect, sum and type the outcomes, and print solely the ultimate reply — the coldest metropolis and the common — to plain output. Your Python code doesn’t change the way it responds to particular person instrument calls in any respect; that a part of the loop seems practically equivalent to the tool-calling instance. What modifications is invisible out of your aspect of the API: fourteen of these fifteen climate lookups, and each intermediate comparability between them, by no means contact Claude’s context.
Claude solely ever sees the 2 numbers it truly requested for. Since this makes use of a beta characteristic, it’s price double-checking the precise beta header string and block-handling particulars towards Anthropic’s present documentation earlier than counting on it in manufacturing, as beta APIs are the a part of any platform almost certainly to shift.
Why Code Execution Wins at Scale
The climate instance makes the mechanism seen, however it’s price backing this up with actual, revealed figures slightly than instinct alone. Anthropic’s authentic code-execution-with-MCP sample took an actual Google Drive-to-Salesforce workflow from 150,000 tokens right down to 2,000 — a 98.7% discount — just by maintaining a full assembly transcript contained in the execution setting as a substitute of routing it by way of the mannequin twice.
Programmatic Device Calling’s personal inside benchmarking, reported instantly by Anthropic, discovered common token utilization on advanced analysis duties dropped from 43,588 to 27,297 — a 37% discount — whereas accuracy on the GAIA benchmark truly improved, rising from 46.5% to 51.2%, and inside data retrieval accuracy rose from 25.6% to twenty-eight.5%. That final element issues greater than the token financial savings alone: this isn’t purely a price optimization. Offloading orchestration logic to precise code slightly than asking a mannequin to trace it by way of pure language measurably reduces the type of errors that come from a mannequin shedding observe of a dozen intermediate values it’s attempting to match in its head.
The educational consequence beneath all of this predates Anthropic’s personal tooling. The unique CodeAct paper from Wang and colleagues in 2024 discovered that brokers taking motion by way of executable code, slightly than JSON-formatted instrument calls, succeeded as much as 20% extra typically on advanced, multi-step duties. Code execution isn’t a current product characteristic bolted onto an present concept — it’s a research-backed sample that the most important labs have spent the previous two years turning into manufacturing infrastructure.
The place Device Calling Nonetheless Wins
The numbers above could make code execution appear to be an unconditional improve, and it isn’t one. There’s an actual, sincere case for sticking with plain instrument calling in a significant set of conditions.
Single-call duties are the clearest case. The Lagos climate instance earlier on this article positive aspects nothing from a sandbox — one name, one small consequence, and the overhead of spinning up a code execution setting provides latency with out including any actual profit. Duties the place the mannequin genuinely must cause over an intermediate end in pure language are the second case: if the precise level of a step is for the mannequin to note one thing refined in a doc or a dataset and reply to it conversationally, filtering that information away in a sandbox defeats the aim. Easier infrastructure is an actual, sensible issue too — a group with out an present safe sandboxing setup takes on actual operational price standing one up, and that price must be weighed towards the financial savings, not assumed away. And auditability issues greater than it will get credit score for: a instrument name is one clear, loggable occasion with a reputation and a set of arguments, whereas reasoning about precisely what a generated script did internally — particularly after the actual fact, throughout an incident — is a genuinely tougher debugging downside.
Resolution Framework: Selecting the Proper Primitive
Pulling all the pieces above into one sensible reference:
| Issue | Favors instrument calling | Favors code execution |
|---|---|---|
| Variety of calls wanted | One, or a small, fastened few | A number of, particularly with fan-out or aggregation |
| What occurs to outcomes | The mannequin must learn and cause over them instantly | They only should be filtered, summed, or in contrast |
| Knowledge sensitivity | Low — nothing problematic concerning the mannequin seeing it | Excessive — PII or giant payloads higher stored out of context |
| Latency tolerance | Tight — sandbox startup isn’t price paying for | Workflow already includes a number of round-trips anyway |
| Workforce infrastructure | No present sandboxing setup | Sandbox or code-execution tooling already in place |
| Auditability wants | Each discrete motion should be individually logged | Mixture consequence issues greater than every inside step |
The Hybrid Actuality: Most Manufacturing Brokers Use Each
It’s price closing this out by pushing again gently on the framing of the article’s personal title. In apply, this isn’t a everlasting, once-and-for-all architectural resolution — it’s a per-task judgment name, and Anthropic’s personal steerage treats it precisely that method. Their superior instrument use launch shipped Programmatic Device Calling alongside two companion options particularly meant to be layered collectively as wanted: a Device Search Device for locating the precise instrument out of a giant library with out loading each definition upfront, and Device Use Examples for educating a mannequin the conventions a schema alone can’t categorical. Their very own advice is to begin with whichever bottleneck is definitely limiting a given agent — context bloat from too many instrument definitions, giant intermediate outcomes polluting context, or parameter errors — and add the matching characteristic, slightly than reaching for each functionality on day one.
A single well-built agent, in apply, tends to make use of plain instrument calling for its easy, single-shot lookups and swap to code execution the second a process requires fan-out, aggregation, or dealing with information too giant or delicate to place in entrance of the mannequin instantly. The precise ability price constructing isn’t choosing a primitive as soon as — it’s recognizing, process by process, which one the work in entrance of you truly wants.
Conclusion
An motion primitive is infrastructure, not a choice, and the 2 examples constructed on this article show it with the identical fifteen strains of instrument definition beneath each. Get it proper and an agent handles a fan-out process throughout fifteen cities — or two thousand expense line objects — in a single clear move. Get it improper — attain for instrument calling on a process that wants code execution — and nothing crashes. The agent nonetheless solutions. It simply does it slower, extra expensively, and with a context window quietly crammed with information no person truly wanted to learn.
