Page history
Process results programmatically
agents-and-tools/tool-use/programmatic-tool-calling
History
agents-and-tools/tool-use/programmatic-tool-calling Changed · +1 / -0 lines
from line 1367
The following tools cannot be called programmatically: * Tools provided by an [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) +* The [computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) and [browser use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool) toolsets (`computer_toolset_20260801` and `browser_toolset_20260801`), whose `allowed_callers` field accepts only `"direct"` ### Message formatting restrictions
agents-and-tools/tool-use/programmatic-tool-calling Changed · +3 / -3 lines
from line 249
if err != nil { log.Fatal(err) } - fmt.Println(response) + fmt.Println(response.RawJSON()) ``` ```java Java
from line 874
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5, MaxTokens: 4096, - Container: anthropic.MessageNewParamsContainerUnion{ + Container: anthropic.MessageCreateParamsContainerUnion{ OfString: anthropic.String("container_xyz789"), }, Messages: []anthropic.MessageParam{
from line 936
if err != nil { log.Fatal(err) } - fmt.Println(response) + fmt.Println(response.RawJSON()) ``` ```java Java
agents-and-tools/tool-use/programmatic-tool-calling First recorded · 1585 lines, first recorded
## Model compatibility ## Quick start ## How programmatic tool calling works ## Core concepts ### The `allowed_callers` field ### The `caller` field in responses ### Container lifecycle ## Example workflow ### Step 1: Initial request ### Step 2: API response with tool call ### Step 3: Provide tool result ### Step 4: Next tool call or completion ### Step 5: Final response ## Advanced patterns ### Batch processing with loops ### Early termination ### Conditional tool selection ### Data filtering ## Response format ### Programmatic tool call ### Tool result handling ### Code execution completion ## Error handling ### Common errors ### Container expiration during tool call ### Tool execution errors ## Constraints and limitations ### Feature incompatibilities ### Input schema limitations ### Tool restrictions ### Message formatting restrictions ### Rate limits ### Validate tool results before use ## Token efficiency ## Usage and pricing ## Best practices ### Tool design ### When to use programmatic calling ### Performance optimization ## Troubleshooting ### Common issues ### Debugging tips ## Why programmatic tool calling works ## Alternative implementations ### Client-side direct execution ### Self-managed sandboxed execution ### Anthropic-managed execution ## Data retention ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: Programmatic tool calling
url: https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling
description: Let Claude call your tools from code in the code execution container, cutting model round trips and token use in multi-tool workflows.
---
Programmatic tool calling allows Claude to write code that calls your tools programmatically within a [code execution](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) container, rather than requiring round trips through the model for each tool invocation. This reduces latency for multi-tool workflows and decreases token consumption by allowing Claude to filter or process data before it reaches the model's context window. On agentic search benchmarks like [BrowseComp](https://arxiv.org/abs/2504.12516) and [DeepSearchQA](https://github.com/google-deepmind/deepsearchqa), which test multistep web research and complex information retrieval, adding programmatic tool calling on top of basic search tools improved performance by an average of 11% while using 24% fewer input tokens (see [Improved web search with dynamic filtering](https://claude.com/blog/improved-web-search-with-dynamic-filtering)).
Consider checking budget compliance across 20 employees: the traditional approach requires 20 separate model round-trips, pulling thousands of expense line items into the context along the way. With programmatic tool calling, a single script runs all 20 lookups, filters the results, and returns only the employees who exceeded their limits, shrinking what Claude needs to reason over from hundreds of kilobytes down to a handful of lines.
<Tip>
For a deeper look at the inference and context costs that programmatic tool calling addresses, see [Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use).
</Tip>
<Note>
This feature requires the code execution tool to be enabled.
</Note>
<Note>
For how zero data retention (ZDR) applies to this feature, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).
</Note>
## Model compatibility
Programmatic tool calling requires `code_execution_20260120` or later, which is supported on the following models:
| Model |
| ---------------------------------------------- |
| Claude Fable 5 (claude-fable-5) |
| Claude Mythos 5 (claude-mythos-5) |
| Claude Opus 5 (claude-opus-5) |
| Claude Opus 4.8 (claude-opus-4-8) |
| Claude Opus 4.7 (claude-opus-4-7) |
| Claude Opus 4.6 (claude-opus-4-6) |
| Claude Sonnet 5 (claude-sonnet-5) |
| Claude Sonnet 4.6 (claude-sonnet-4-6) |
| Claude Opus 4.5 (claude-opus-4-5-20251101) |
| Claude Sonnet 4.5 (claude-sonnet-4-5-20250929) |
For the full code execution tool version matrix, see the [code execution tool model compatibility table](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#model-compatibility). Programmatic tool calling is available on the Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry). On Microsoft Foundry, programmatic tool calling requires a [Hosted on Anthropic deployment](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure). It is not currently available on Amazon Bedrock or Google Cloud.
## Quick start
Here's an example where Claude programmatically queries a database multiple times and aggregates results. Adding `allowed_callers: ["code_execution_20260120"]` to a tool definition is what makes that tool callable from within code execution (see [The `allowed_callers` field](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling#the-allowed-callers-field)):
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"model": "claude-opus-5",
"max_tokens": 4096,
"messages": [
{
"role": "user",
"content": "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue"
}
],
"tools": [
{
"type": "code_execution_20260120",
"name": "code_execution"
},
{
"name": "query_database",
"description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
"input_schema": {
"type": "object",
"properties": {
"sql": {
"type": "string",
"description": "SQL query to execute"
}
},
"required": ["sql"]
},
"allowed_callers": ["code_execution_20260120"]
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5
max_tokens: 4096
messages:
- role: user
content: >-
Query sales data for the West, East, and Central regions, then
tell me which region had the highest revenue
tools:
- type: code_execution_20260120
name: code_execution
- name: query_database
description: >-
Execute a SQL query against the sales database. Returns a list
of rows as JSON objects.
input_schema:
type: object
properties:
sql:
type: string
description: SQL query to execute
required:
- sql
allowed_callers:
- code_execution_20260120
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue",
}
],
tools=[
{"type": "code_execution_20260120", "name": "code_execution"},
{
"name": "query_database",
"description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
"input_schema": {
"type": "object",
"properties": {
"sql": {"type": "string", "description": "SQL query to execute"}
},
"required": ["sql"],
},
"allowed_callers": ["code_execution_20260120"],
},
],
)
print(response)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5",
max_tokens: 4096,
messages: [
{
role: "user",
content:
"Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue"
}
],
tools: [
{
type: "code_execution_20260120",
name: "code_execution"
},
{
name: "query_database",
description:
"Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
input_schema: {
type: "object" as const,
properties: {
sql: {
type: "string",
description: "SQL query to execute"
}
},
required: ["sql"]
},
allowed_callers: ["code_execution_20260120"]
}
]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 4096,
Messages = [
new() {
Role = Role.User,
Content = "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue"
}
],
Tools = [
new CodeExecutionTool20260120(),
new ToolUnion(new Tool()
{
Name = "query_database",
Description = "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
InputSchema = new InputSchema()
{
Properties = new Dictionary<string, JsonElement>
{
["sql"] = JsonSerializer.SerializeToElement(new { type = "string", description = "SQL query to execute" }),
},
Required = ["sql"],
},
AllowedCallers = ["code_execution_20260120"]
}),
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20260120: &anthropic.CodeExecutionTool20260120Param{}},
{OfTool: &anthropic.ToolParam{
Name: "query_database",
Description: anthropic.String("Execute a SQL query against the sales database. Returns a list of rows as JSON objects."),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"sql": map[string]any{
"type": "string",
"description": "SQL query to execute",
},
},
Required: []string{"sql"},
},
AllowedCallers: []string{"code_execution_20260120"},
}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.messages.CodeExecutionTool20260120;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(4096L)
.addUserMessage("Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue")
.addTool(CodeExecutionTool20260120.builder().build())
.addTool(Tool.builder()
.name("query_database")
.description("Execute a SQL query against the sales database. Returns a list of rows as JSON objects.")
.inputSchema(InputSchema.builder()
.properties(JsonValue.from(Map.of(
"sql", Map.of(
"type", "string",
"description", "SQL query to execute"
)
)))
.putAdditionalProperty("required", JsonValue.from(List.of("sql")))
.build())
.allowedCallers(List.of(Tool.AllowedCaller.of("code_execution_20260120")))
.build())
.build();
Message response = client.messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue'],
],
model: 'claude-opus-5',
tools: [
[
'type' => 'code_execution_20260120',
'name' => 'code_execution',
Cut at 300 lines.