Choose native JSON, strict tools, or prompting

Learning objective

Compare exam-guide tool-use extraction with current native JSON outputs (output_config.format), strict tool inputs (strict: true), and prompt-only JSON.

Core idea

Choose the output mechanism from the boundary your consumer needs. If it needs a final record, native JSON outputs constrain the response to a schema. If it needs arguments to a named operation, strict tool use constrains those arguments. Asking for JSON in a prompt expresses a preference without either enforcement mechanism.

The distinction is not whether JSON appears somewhere in the response. Both native JSON outputs and tool inputs carry structured data, but they occupy different places and serve different workflows. A consumer that reads generated response text needs a different adapter from one that dispatches tool_use blocks.

The exam guide emphasizes tool-use extraction. You should recognize that pattern while also distinguishing the Messages API’s native response-format mechanism. Neither mechanism proves that the extracted values are faithful to the source.

How it works

Constrain the final response with JSON outputs

Set output_config.format with type: "json_schema" and a schema. Anthropic uses constrained decoding to produce a response matching that supported schema. The generated JSON is returned in a text content block rather than as arguments to an extraction tool.

The following request fragment specifies the response contract:

{
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "invoice_number": { "type": ["string", "null"] }
        },
        "required": ["invoice_number"],
        "additionalProperties": false
      }
    }
  }
}

This fragment belongs inside a Messages API request with the usual model, messages, and output-token settings. Parse the JSON text after checking the response outcome. Parsing remains part of consumption; the guarantee concerns how the text is generated, not the elimination of a JSON parser from your program.

Anthropic documents structured outputs as generally available on the Claude API, Claude Platform on AWS, Google Cloud, and Microsoft Foundry; on Amazon Bedrock, support is limited to the legacy integration for Claude Opus 4.6, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Opus 4.5, and Claude Haiku 4.5, and excludes Claude in Amazon Bedrock. Do not infer support for every model or integration from availability on one platform. These platform boundaries apply to JSON outputs and strict tool use.

The output_config.format request shape does not require a beta header. The output_format request parameter is deprecated; the Python SDK’s client.messages.parse() helper still accepts an output_format argument and sends output_config.format on the wire. Distinguish the helper’s argument from the API request parameter.

Constrain arguments with strict tool use

Set strict: true on each tool definition whose arguments need enforcement. Its input_schema specifies the contract, and the resulting object lives in tool_use.input. Grammar-constrained sampling prevents the ordinary type and required-field failures of non-strict tool inputs.

Strict mode does not itself require a call. With tool_choice: {"type": "auto"}, Claude can return text instead. On models that support forced selection, tool_choice: {"type": "any"} combines a required call with strict inputs; see 4.3.3. On models that reject forcing, a strict tool still constrains any call Claude actually emits, but absence of that call remains an application outcome to handle.

JSON outputs and strict tool use can coexist in one request. One constrains what Claude says in its final structured response; the other constrains the inputs it supplies when requesting operations. Using both is appropriate when the workflow actually has both consumers, not because two schema declarations prove the facts twice.

Recognize the limits of a prompt instruction

“Return only JSON matching this schema” is a prompt instruction. It can guide content, but it does not enable output_config.format or strict: true. Anthropic documents possible malformed JSON, missing required fields, inconsistent types, and schema violations without structured outputs, even with careful prompting.

Prompt-only JSON is therefore a choice to accept those failure modes. It can fit an exploratory response that a person reads, but it leaves a machine consumer responsible for rejecting or repairing invalid output. Adding examples or stronger wording does not transform that request into constrained decoding.

Prompts still have a role alongside enforcement: they describe what evidence to use and how to interpret it. The schema describes the output shape. Format-normalization instructions belong alongside the schema, rather than replacing its enforcement mechanism.

Key distinctions and trade-offs

Use the following comparison to locate the consumer and the guarantee:

The structured-output schema subset matters for both strict tools and JSON outputs. Objects require additionalProperties: false. Unsupported schema features return a 400 error. Numerical constraints such as minimum and maximum are among them. SDK helpers can strip these constraints from the wire schema and add them to field descriptions; a helper that validates responses also checks the original constraints client-side. Otherwise, keep value checks in the consumer rather than assuming any general-purpose JSON Schema can be copied unchanged.

Two compatibility and outcome boundaries change the architecture. Enabling citations together with output_config.format returns a 400 error because citation blocks require interleaving with text. If native citations are a requirement, separate that response from the strict JSON contract rather than enabling an incompatible combination.

Also, schema enforcement is not unconditional completion. A safety refusal has stop_reason: "refusal" and can supersede the schema despite HTTP 200. A response ending with stop_reason: "max_tokens" can be incomplete; Anthropic’s remedy is retrying with a higher max_tokens. Treat these outcomes explicitly before parsing or accepting a record. String enum capitalization also has a documented exception: compare enum values case-insensitively and avoid categories distinguished only by case.

Architecture / decision scenario

A document service has three consumers. Its ingestion endpoint needs one invoice record, its enrichment worker requests supplier lookups, and an analyst experiments with an extraction prompt.

Give ingestion output_config.format because its deliverable is a final JSON record. Its adapter checks the stop reason, parses the text payload, and applies evidence checks. A refusal is not interpreted as a broken invoice record; a token-limited response follows the documented higher-max_tokens recovery path.

Give the enrichment worker strict: true on the tools whose inputs it dispatches. If it also produces a final report in JSON, add a separate output_config.format contract for that report. Check required-call behavior independently; strict inputs do not make auto compulsory.

The analyst’s prompt-only response can remain an experiment, but it does not establish an ingestion guarantee. If the analyst requests native citations, do not add them to the same request as output_config.format; use a compatible evidence response as a separate stage. Across all three consumers, a valid amount still needs comparison with the document. The choice of output interface does not settle factual correctness.

Common exam traps

• Treating every response containing JSON as a native JSON output.
• Using strict: true as if it forces a tool call.
• Parsing tool_use.input as though it were a generated text string.
• Treating prompt examples as equivalent to constrained decoding.
• Assuming schema compliance proves an invoice’s totals or attribution.
• Combining native citations with output_config.format.
• Ignoring refusal or token-limit outcomes because HTTP succeeded.

Where the exam guide differs

What to remember

output_config.format constrains the response; strict: true constrains tool inputs. Tool selection, schema support, response completion, and factual validity remain separate decisions. Read the contract where the chosen interface actually returns it.

Knowledge check

References

• Anthropic, Structured outputs
• Anthropic, Strict tool use
• Anthropic, Define tools
• Anthropic, Claude Certified Architect – Foundations Exam Guide