What is programmatic tool calling?

Programmatic tool calling lets an AI model write code that invokes tools and processes their results inside an execution environment. The program handles loops, branching, and intermediate data before returning a result to the model. Anthropic offers this pattern through its code execution tool.

Support agents may need to find open incidents, group them by service, and identify the responsible teams. Once the required operations are known, a program can perform those lookups and build the report without asking the model to interpret every intermediate response.

Copy link to headingHow does it differ from ordinary tool calling?

With ordinary function or tool calling, the model selects a tool and supplies structured arguments. The application validates and executes the request, then makes the result available for the model's next decision.

Programmatic tool calling moves some of that decision-making into generated code. The model can express "fetch these records, keep the urgent ones, group them by service, and look up each owner" as a program. The runtime executes the program and connects its tool calls to the application's implementations.

Direct tool calling can already request multiple independent operations in one model response. Programmatic calling adds the ability to use their results in further computation and tool calls without requiring a new model decision for every step. Its benefit depends on how much of the workflow can be expressed ahead of time.

Copy link to headingWhat does a programmatic tool call look like?

Consider a report that counts urgent incidents by service and names the responsible team. Suppose your application exposes two read-only tools:

• listIncidents returns authorized incident records and sets hasMore to true when more pages remain.

• getServiceOwner returns the team responsible for an authorized service.

The JavaScript below is the body of an illustrative generated program, intended for a runtime that supports top-level await and return. The runtime supplies the asynchronous tools methods defined by your application; they are not built-in Sandbox SDK methods. Here, severity: 1 marks an urgent incident.

const page = await tools.listIncidents({ status: 'open' });
if (page.hasMore) {
  throw new Error('Fetch all incident pages before building the report');
}

const counts = new Map();
for (const incident of page.items) {
  if (incident.severity === 1) {
    counts.set(incident.serviceId, (counts.get(incident.serviceId) ?? 0) + 1);
  }
}

const services = [];
for (const [serviceId, urgentIncidents] of counts) {
  try {
    const owner = await tools.getServiceOwner({ serviceId });
    services.push({ serviceId, urgentIncidents, team: owner.team });
  } catch {
    services.push({ serviceId, urgentIncidents, ownerLookupFailed: true });
  }
}

return { services };

The program filters records and counts incidents before looking up owners. If several incidents affect the same service, it asks for that service's owner once. The model receives a compact report rather than the full incident collection.

For an illustrative input with two urgent incidents in checkout, one in search, and a non-urgent incident in checkout, successful owner lookups would produce:

{
  "services": [
    { "serviceId": "checkout", "urgentIncidents": 2, "team": "payments" },
    { "serviceId": "search", "urgentIncidents": 1, "team": "discovery" }
  ]
}

The example looks up owners sequentially, although a runtime with concurrent tool support could overlap those requests within its call limits. It rejects an incident page when hasMore is true and marks failed owner lookups, so an incomplete report does not silently appear complete.

The tool service must enforce access on every request. It should determine the tenant from authenticated context, regardless of what service identifiers appear in the generated program. Tool names and argument schemas describe how to call operations; they do not establish the caller's authority.

Copy link to headingWhy can this reduce model context and latency?

Tools can return hundreds of records even when a user needs only a count or comparison. Processing those records in code can reduce how much intermediate data reaches the model.

Those tool requests still reach the underlying services. Checking ten services may mean ten API calls even if the model sees only a summary. Reducing model-mediated steps and intermediate context leaves the backend's rate limits and per-operation costs in place.

Context savings depend on what the program returns. Sending an entire dataset back to the model restores that context load; returning too little can omit necessary evidence. Counts and owners may support incident routing, while an investigation also needs incident identifiers and details.

Code execution adds runtime overhead and software to operate. For one small lookup, a direct call may be a better fit. Compare task latency with failures and retries included before assuming fewer model turns will improve it.

Copy link to headingWhich implementations can you use?

The architecture appears in several products, but their runtime contracts differ.

Anthropic's programmatic tool calling runs orchestration code in its hosted code execution container. Eligible custom tools opt into code calling through allowed_callers. When the program invokes one of your tools, your application handles the tool request and returns its result so execution can continue. Check the current model and tool-version requirements when integrating it.

OpenAI's programmatic tool calling runs generated JavaScript in an isolated hosted V8 runtime. In the Responses API, your application selects which eligible tools the program may call and continues to execute client-owned tools. The runtime has no Node.js or direct network access, so external operations use enabled tools.

The AI SDK's experimental Code Mode runs generated JavaScript or TypeScript in an isolated QuickJS environment. It exposes selected AI SDK tools to the program and returns a JSON-serializable value. Code Mode requires Node.js 22 or newer.

QuickJS provides language-level isolation; it does not create a Vercel Sandbox Linux microVM. Nested calls cannot pause for AI SDK tool approvals, so keep approval-dependent tools directly callable.

Cloudflare Code Mode also exposes tools as methods that generated code can compose. Its experimental status and integration-specific behavior mean that a program written for another tool runtime isn't automatically interchangeable.

Choose the implementation according to the code and tools you need to run. Transforming returned JSON has different requirements from a Python script that installs a scientific package or invokes a native binary.

Copy link to headingWhere does Vercel Sandbox fit?

Vercel Sandbox provides a Linux environment for custom implementations that need commands, files, or dependencies. To run generated orchestration there, your application must also connect it to authorized tools. Sandbox creation does not expose your backend functions to the generated code.

One design exposes a narrow tool service outside the sandbox. Generated code calls that service through a controlled connection. The service verifies the execution's identity, checks the requested operation, and returns only the permitted data. Your application chooses the network policy and keeps service credentials outside the generated program wherever possible.

Anthropic's hosted code-execution feature runs in Anthropic's environment. Selecting it does not redirect execution to Vercel Sandbox, and the AI SDK's QuickJS Code Mode uses its own runtime.

For data-heavy tasks, run data queries in Sandbox through MCP tools. For programs that need an approval pause, Run SDK and Workflow SDK can suspend execution and resume after a decision.

Copy link to headingWhat is the relationship to MCP?

The Model Context Protocol defines how applications connect to servers that expose tools and other capabilities. Its architecture covers the communication between hosts, clients, and servers. Programmatic tool calling governs how a model-generated program composes the operations available to it.

Code runtimes can expose MCP tools or application-defined tools without MCP. With code execution over MCP tools, the program can discover operations and process intermediate data before returning selected information to the model.

MCP doesn't supply a universal Python or JavaScript function namespace inside every sandbox. The integration still needs to map tool definitions into callable methods and route requests to the right server with the right identity.

Copy link to headingWhat still needs application-level control?

Generated programs can call the wrong tool or repeat an operation. Set execution budgets and enforce tool-call limits outside the generated source. The model may include a limit in its own loop, but it can also omit or change that limit.

Writes require particular care. If a program updates a ticket and loses the response, retrying the whole program can repeat the update. Use idempotent operations or explicit operation identifiers where the downstream service supports them, and keep an audit record that distinguishes a requested action from a confirmed result.

Code also changes when the model gets an opportunity to reconsider. If the next step requires judgment about an ambiguous result, return the relevant information to the model instead of forcing the program to guess. Keep human approval at a point the chosen runtime can enforce before the consequential operation occurs.

Copy link to headingFrequently asked questions

Copy link to headingIs programmatic tool calling the same as function calling?

Function calling lets a model request an operation with structured arguments. Programmatic tool calling lets the model compose operations in executable code and process their intermediate results there. Both rely on the application to implement tools and enforce permissions.

Copy link to headingIs programmatic tool calling the same as parallel tool calling?

No. Parallel tool calling lets a model request several tools in one response; the application decides whether to execute them concurrently. Programmatic calling also lets code use earlier results to branch, transform data, or choose further calls before the model resumes.

Copy link to headingDoes programmatic tool calling require MCP?

No. Programmatic tool calling can use application-defined tools or tools exposed through MCP. MCP supplies the connection protocol; your integration must expose callable methods, route requests, and enforce authorization.

Copy link to headingWhen should I keep direct tool calls?

Keep direct calls for small lookups and for steps that need the model to interpret an intermediate result. They also suit operations whose approval flow the code runtime cannot support. Programmatic execution helps when code can coordinate calls or reduce data between model decisions.

Copy link to headingDoes running tool calls in a sandbox make them authorized?

No. Sandboxing limits code execution, while the application or tool service decides whether a caller may perform an operation. Each request still needs authorization against the caller's identity and permitted scope.

Copy link to headingRelated resources

• Programmatic tool calling in the Claude API

• AI SDK Code Mode

• Large-scale data analysis with Sandbox and MCP

• Run dynamic code in a durable workflow