Use JSON structured outputs when your application needs Claude’s final response to match a schema that your code can parse without guesswork. Use programmatic tool calling when the hard part is the tool work itself: many calls, loops, conditional sequencing, or large tool results that should be filtered in code before Claude reasons over them. The two features solve different problems, and they are not alternative modes of the same thing. One restriction matters most: tools marked strict: true are not supported with programmatic tool calling.
Two features that act at different points in a request
The confusion usually comes from the word “structured.” JSON structured outputs shape what Claude writes back to you. Programmatic tool calling changes how Claude calls your tools and what it sees from them. The table below sets out the differences.
As an Amazon Associate I earn from qualifying purchases.
| Decision axis | JSON structured outputs | Programmatic tool calling |
|---|---|---|
| Main job | Constrains the format of Claude’s final response to a JSON schema. | Lets Claude compose tool calls in code and process the results there. |
| Typical need | Extracting fields, generating a structured report, or returning a predictable API response. | Fanning out across many records, repeating or conditionally sequencing calls, or reducing large intermediate results before the model reasons over them. |
| What is constrained | The shape of the response JSON. | The tool-call workflow, which runs as Python inside a code-execution container. |
| Main advantage | Output that complies with the schema, so downstream code can parse it. | Fewer model round trips, and less intermediate tool data in Claude’s context, for suitable workloads. |
| Main cost or constraint | Requires a supported schema. | Container startup and script generation add overhead; the benefit depends on workflow shape and tool configuration. |
| Compatibility note | Can be used alongside strict tool use. | Requires the code-execution tool; tools with strict: true are not supported. |
What JSON structured outputs control
You pass a JSON schema in output_config.format with type set to json_schema. Claude’s reply then comes back in the text content block and conforms to that schema. Anthropic describes this as constrained decoding, which is aimed at schema-compliant responses rather than at the tool-calling loop. The current documentation also notes that SDK helpers can parse the result into a typed object. A minimal request fragment looks like this (the schema is illustrative):
{
"output_config": {
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"invoice_number": { "type": "string" },
"total": { "type": "number" }
},
"required": ["invoice_number", "total"]
}
}
}
}First-use latency
The first request that uses a particular schema can take longer, because the schema is compiled into a grammar. Anthropic’s documentation says compiled grammars are cached for 24 hours after their last use, so the penalty mainly lands on new or rarely used schemas. Keep schemas stable across requests where you can.
What programmatic tool calling does
With programmatic tool calling, Claude writes Python that calls the tools you have configured, possibly inside loops or with pre- and post-processing. That code runs in a sandboxed code-execution container. The request pauses while your client supplies tool results, then execution resumes. Only the script’s final output goes back into Claude’s context, which is the main reason it can reduce token use on large results.
- Include the code-execution tool in the request and mark each tool Claude may call from code with
allowed_callers: ["code_execution_20260120"]. - Claude writes Python that calls those tools, optionally repeating or branching across records.
- When the code calls a tool, the API returns a
tool_useblock. Programmatic blocks carry acallervalue that identifies code execution, so your client can tell them apart from direct calls. - Your client runs the tool and returns the result, continuing the request with the container ID so the code can resume.
- When the script finishes, only its final output is added to Claude’s context, and Claude produces the answer from that.
Configuration details that trip up implementations
- The minimum code-execution tool version is
code_execution_20260120. allowed_callersshapes how Claude is presented with tools. It is not a hard API security boundary, so your client should be ready to handle direct tool calls as well.- Programmatic tool results come back as strings or text. Define the output format clearly in your tool design, because your code and Claude have to parse it.
tool_choicecannot force programmatic calling of one specific tool.
Choosing between them for a given workload
Choose JSON structured outputs when
- Your application stores or parses fields and needs them in a predictable structure.
- Claude is extracting facts from text or images, producing a report, or returning a machine-readable API response.
- Your main concern is malformed JSON, missing required fields, inconsistent types, or schema violations.
Choose programmatic tool calling when
- The task fans out across many records or repeats tool calls.
- Tool responses are large and can be filtered, aggregated, or summarized in code before Claude reasons over them.
- The workflow needs loops, conditionals, or several tool calls without a model turn between each one.
- Retrieval or search is iterative, with queries refined and results filtered as the work proceeds.
Where programmatic tool calling is a weaker fit
- Strictly sequential reasoning, where each step needs Claude’s judgment before the next call.
- Small tool responses, where the container overhead outweighs the savings.
- Workflows that need immediate feedback to the user between calls.
Using JSON outputs and strict tool use together
JSON outputs and strict tool use are separate features. JSON outputs control the format of Claude’s final response. Strict tool use validates tool names and input parameters against the tool definitions. Anthropic says the two can be used independently or together, so a single request can both shape the answer and validate the calls behind it.
Programmatic tool calling narrows this. Tools marked strict: true are not supported when they are called programmatically, so if a tool needs strict parameter validation, it cannot sit in the programmatic path. In that case, validate its inputs in your own code. Before shipping any combination, confirm the exact API parameters and model support on Anthropic’s current documentation, since both change over time.
Recommended Free Tools
Performance figures and what they do not show
Anthropic publishes three benchmark results for programmatic tool calling. Each is vendor-reported, and the documentation page we reviewed does not show a publication date for any of them.
- Adding programmatic tool calling to basic search tools improved performance by an average of 11% and used 24% fewer input tokens on the BrowseComp and DeepSearchQA agentic search benchmarks.
- On a 75-tool project-management agent benchmark, billed input tokens fell by roughly 38% with no change in task accuracy.
- On τ²-bench, where turns make one or two sequential calls, scores were unchanged and cost was roughly 8% higher.
The pattern is the trade-off Anthropic itself describes: fixed container startup and script-generation overhead, set against savings from fewer model turns and less intermediate context. The gains appear where calls fan out or results are large. They do not appear, and can reverse, where calls are sequential and small. Treat the figures as evidence about those benchmark setups, not as a forecast for your workload. Measure your own token counts and latency with and without the feature before committing.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Failure points to check before shipping
- Unsupported model. Claude Haiku 4.5 accepts the code-execution version but does not support programmatic tool calling. Check the live list of supported models and platforms, since it can change.
- Strict tools in the programmatic path. Tools with
strict: trueare not supported with programmatic calling. Move their validation into your code or keep them out of the programmatic path. - Untrusted tool output. If tool output is interpreted or executed, it creates code-injection risk. Validate external data before processing it.
- Data retention. Programmatic calling shares code-execution infrastructure, and Anthropic says container artifacts and outputs are retained for up to 30 days. Confirm the retention and data-handling terms that apply to your deployment.
- Schema compilation. Expect first-use latency for new schemas, as described above, and test latency with a realistic schema rather than a toy one.
Sources: Anthropic’s Claude Platform documentation on structured outputs and on programmatic tool calling, accessed October 7, 2026. Model support, parameter names and retention details are subject to change.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Free tools Windows power users keep installed
One-click scans. No signup required.
