← All guides · Agent reliability in production

Structured Outputs vs Tool Calling: When to Use Each

Part 2 of Agent reliability in production · 1,883 words · ~9 min read · published 2026-08-26 · updated 2026-08-26 · Markdown variant

A decision framework for structured outputs versus tool calling in AI agents, with runnable JSON Schema examples for OpenAI, Anthropic, Gemini, vLLM/SGLang, and llama.cpp, plus mitigation code for truncation, refusal, and grammar-compilation latency.

Part of the Agent Guardrails and the AI Agent Reliability Playbook guide.

Structured outputs and tool calling sit side by side in one summary table inside the agent reliability in production pillar. This article expands only the structured-outputs half into a full decision guide: a framework for picking a schema-constrained reply over a function call, the per-provider schema subsets shown in runnable code, and both failure modes that survive even under a strict-mode guarantee. It does not re-derive tool-calling's own failure-mode table, BFCL scoring, or parallel-call ordering — see tool-calling contracts for AI agents for that half of the picture.

When should you reach for structured outputs instead of a tool call?

Reach for structured outputs when the task ends with the model's own answer in machine-parseable form, and reach for tool calling when the task requires your application to execute an external action. The distinction is about what happens after the model responds, not about how complex the output schema is. Sentiment-tag a support transcript into {"sentiment": "frustrated", "priority": 2} and nothing outside the model has to run — the object itself is the deliverable, so structured outputs are the right mechanism. Look up a customer's subscription tier and cancel a pending renewal, and the model's output has to name a function and its arguments for your application code to execute — that is a tool call, not a final answer.

Neither mechanism substitutes for the other: a single agent turn can need one alone, both in sequence, or both inside the same call depending on what the provider allows. Three task shapes make this concrete:

• Extraction and classification — pulling structured fields out of unstructured text, or assigning a label with a confidence score. No external system needs to be touched; structured outputs alone are correct here.
• Multi-step agentic action — looking up a record, then acting on it. Tool calling drives the lookup and the action; structured outputs have no role unless the very last step is also a report back to the user in a fixed shape.
• Tool call followed by a schema-valid summary — an agent that queries an API via tool calling and then has to hand the orchestrating system a schema-valid result object combines both: the tool call for the action, structured outputs for the final reply.

Whether a given provider lets you request both mechanisms in the same call, rather than as two sequential requests, is a compatibility detail that varies by provider — covered in the FAQ below — and is worth checking before you design a contract that assumes one call does both.

What schema subset does each provider actually support?

Each provider supports a different subset of JSON Schema under its strict-mode guarantee, and the differences are large enough that a schema portable across all of them has to be written to the narrowest common subset, not the richest one any single provider allows. As of August 2026, five schema-subset comparisons matter in practice: OpenAI, Anthropic, Gemini's two schema modes, and the two dominant self-hosted patterns.

OpenAI: response_format with json_schema and strict: true

OpenAI's strict mode enforces two structural rules on every object node: additionalProperties must be false, and every declared property must be listed as required — model an optional field as a nullable type union rather than leaving it out of required. A root-level anyOf is rejected, and including a default value anywhere in the schema makes the call fail outright rather than being silently dropped.

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "ticket_classification",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "category": { "type": "string", "enum": ["billing", "technical", "account"] },
          "confidence": { "type": "number" },
          "escalate": { "type": ["boolean", "null"] }
        },
        "required": ["category", "confidence", "escalate"],
        "additionalProperties": false
      }
    }
  }
}

Supported on gpt-4o (2024-08-06 and later), GPT-4.1, GPT-5, and the o-series; older snapshots fall back to the weaker json_object mode described below. response_format and tools are mutually exclusive within a single call.

Anthropic: output_config.format

Anthropic's native structured outputs shipped in late 2025 and are GA on current models as of August 2026, with no beta header required. The canonical call-time parameter is output_config.format set on messages.create itself — a separate top-level output_format create-parameter exists in some SDK surfaces but is deprecated, so new integrations should target output_config directly rather than copying an older example that uses the deprecated name.

{
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "category": { "type": "string" },
          "confidence": { "type": "number" },
          "notes": {
            "anyOf": [
              { "type": "string" },
              { "type": "null" }
            ]
          }
        },
        "required": ["category", "confidence"]
      }
    }
  }
}

Unlike OpenAI, Anthropic's schema support includes anyOf and $ref/$defs, but not recursive schemas, and per-request limits apply to tool count and optional/union parameter counts — check current docs for exact caps rather than assuming last year's limits still hold. This is separate from strict: true on an individual tool definition, which constrains that tool's arguments, not the model's final reply — the two are configured independently even though both live under the Anthropic API.

Gemini: responseSchema versus responseJsonSchema — two different modes, not one

Gemini splits schema support across model generations into two genuinely different parameters, and treating them as interchangeable is the most common integration mistake. responseSchema, used with responseMimeType: "application/json" on Gemini 1.5 and 2.0, accepts only an OpenAPI-based subset of JSON Schema — no anyOf, no $ref:

{
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "object",
      "properties": {
        "category": { "type": "string" },
        "confidence": { "type": "number" }
      },
      "required": ["category", "confidence"]
    }
  }
}

Gemini 2.5 and later additionally accept responseJsonSchema, which supports the fuller JSON Schema feature set — anyOf, $ref, and limited recursion — and accepts a schema derived directly from a Pydantic or Zod model:

{
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseJsonSchema": {
      "type": "object",
      "properties": {
        "category": { "type": "string" },
        "notes": { "anyOf": [{ "type": "string" }, { "type": "null" }] }
      },
      "required": ["category"]
    }
  }
}

A schema written for responseJsonSchema's richer feature set is not guaranteed to work unmodified if sent as responseSchema against an older model — check which parameter a given model generation actually accepts before assuming a schema is portable across your own Gemini model pins. Some 2.5 snapshots have also been reported to fail structured output when tool-call messages are present in history, and an overly complex schema can trigger a 400 — shortening property names, reducing enum sizes, or flattening nested arrays are the standard workarounds.

Self-hosted: guided_json (vLLM, SGLang) and grammar (llama.cpp)

There is no hosted-provider flag to set for a self-hosted deployment, so the schema constraint has to be enforced by the serving stack itself, at the point where tokens are sampled. vLLM and SGLang expose a guided_json parameter that takes a JSON Schema directly; both runtimes route it through the XGrammar library by default as of 2025, which compiles the schema into a pushdown automaton with low per-token overhead:

response = client.chat.completions.create(
    model="your-self-hosted-model",
    messages=[{"role": "user", "content": "Classify this support ticket."}],
    extra_body={
        "guided_json": {
            "type": "object",
            "properties": {
                "category": {"type": "string"},
                "confidence": {"type": "number"}
            },
            "required": ["category", "confidence"]
        }
    },
)

llama.cpp instead compiles a GBNF (GGML Backus-Naur Form) grammar, either hand-written or auto-converted from a JSON Schema, into the same kind of token-level constraint via its own grammar parameter — the parameter name and grammar format are specific to llama.cpp and not interchangeable with vLLM's guided_json. Outlines is a third self-hosted option available on the same runtimes, using finite-state-machine masking, though it does not support recursive schemas — XGrammar or llguidance are the alternatives when recursion is required. The full per-provider table this section expands is in structured outputs and JSON mode; the equivalent grammar-based mechanism as it applies to tool-call arguments specifically, rather than a final-answer schema, is covered in tool-calling contracts for AI agents.

Why does a strict schema guarantee still fail in production?

A strict schema guarantee still fails in production because two conditions bypass constrained decoding entirely rather than merely stressing it: the response can be truncated before the object closes, or the model can refuse instead of generating at all. Neither condition is caught by checking the HTTP status code, because both return a normal 200 response — the schema violation is only visible in the stop_reason field, which is why a 200 status must never be treated as proof of a valid object.

Checking stop_reason before you parse anything

A stop_reason of "max_tokens" means generation was cut off mid-object before the schema could close, and a stop_reason of "refusal" means a safety response overrode the schema entirely — both need to be checked as first-class branches before any parsing is attempted:

def get_structured_response(client, request):
    response = client.messages.create(**request)

    if response.stop_reason == "max_tokens":
        raise TruncatedOutputError(
            "Response cut off before schema closed; raise max_tokens or simplify the schema"
        )
    if response.stop_reason == "refusal":
        raise SchemaRefusalError(
            "Model refused instead of generating a schema-valid object"
        )

    # Only now is a 200-status response actually safe to parse.
    return json.loads(response.content[0].text)

Treating these as parse-time exceptions rather than upstream validation failures is the difference between a crash your monitoring never explains and a distinguishable, loggable failure mode your retry-and-repair loop can act on directly.

First-request grammar-compilation latency

As of August 2026, the first request against a new or changed JSON Schema is measurably slower than subsequent requests on Anthropic and on every self-hosted grammar backend, because the schema has to compile into a grammar before generation can start, and a schema change invalidates any cached compilation. A production deploy that only sees this delay on a real user's first request has shipped the mitigation in the wrong place — a warm-up call at deploy time, before traffic arrives, moves the cost off the request path entirely:

def warm_up_schema_cache(client, schema, model):
    """Call once per deploy, per distinct schema, before serving real traffic.
    Absorbs first-request grammar-compilation latency outside the request path."""
    client.messages.create(
        model=model,
        max_tokens=16,
        messages=[{"role": "user", "content": "warm-up: reply with a minimal valid object"}],
        output_config={"format": {"type": "json_schema", "schema": schema}},
    )

The other side of this mitigation is discipline, not code: avoid frequent schema churn in the same way you'd avoid frequent cache-key churn, since each distinct schema version pays this compilation cost again on its own first request regardless of how many times an earlier version of the schema already warmed up.

Where this leaves you

The task shape decides the mechanism: pick structured outputs when the last step is the model's own answer in a fixed shape, and pick tool calling when the last step is an action your application has to execute. Check each provider's actual schema subset before assuming a contract written for one provider ports cleanly to another, since OpenAI's, Anthropic's, and Gemini's two schema modes each draw the line differently. Whichever mechanism you use, treat stop_reason as a required check before parsing and warm up a new schema's grammar before real traffic hits it — a strict-mode guarantee only holds for the requests that actually reach a complete, non-refused generation. For the twelve-discipline reliability stack this decision sits inside, see the agent reliability in production pillar; for the orthogonal question of making the tool-calling side of an agent's output reliable, see tool-calling contracts for AI agents.

#agents #reliability #structured-outputs #json-schema #constrained-decoding #production