Skip to main content
Agent loops typically alternate between “call a tool” and “return a final answer.” This pattern is for manual tool handling: the model emits a structured tool_call envelope, and your application is responsible for executing the tool and continuing the loop. That is different from OpenAI-style built-in tool calling, where the API returns tool call objects in its own response format. Without a strict output contract, the model might mix fields from both branches, invent new action types, or omit the information your executor needs to dispatch. A oneOf schema with a const discriminator eliminates this: the model picks exactly one branch, emits exactly the right fields, and your orchestration code can dispatch without parsing heuristics.

​
Use case

You run an agent that can either call a tool or return a final answer. You want one schema that covers both outcomes, with a confidence score on every action for routing and observability.

​
Schema pattern

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "kind": { "const": "tool_call" },
        "tool": { "type": "string", "enum": ["search_docs", "lookup_order", "send_email"] },
        "arguments": { "type": "object", "additionalProperties": true },
        "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
      },
      "required": ["kind", "tool", "arguments", "confidence"],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "kind": { "const": "final_answer" },
        "answer": { "type": "string", "minLength": 1, "maxLength": 1200 },
        "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
      },
      "required": ["kind", "answer", "confidence"],
      "additionalProperties": false
    }
  ]
}

from typing import Annotated, Any, Literal
from pydantic import BaseModel, ConfigDict, Field

class ToolCall(BaseModel):
    model_config = ConfigDict(extra="forbid")
    kind: Literal["tool_call"]
    tool: Literal["search_docs", "lookup_order", "send_email"]
    arguments: dict[str, Any]
    confidence: float = Field(..., ge=0, le=1)

class FinalAnswer(BaseModel):
    model_config = ConfigDict(extra="forbid")
    kind: Literal["final_answer"]
    answer: str = Field(..., min_length=1, max_length=1200)
    confidence: float = Field(..., ge=0, le=1)

AgentOutput = Annotated[ToolCall | FinalAnswer, Field(discriminator="kind")]

import { z } from "zod";

const agentOutputSchema = z.discriminatedUnion("kind", [
  z.object({
    kind: z.literal("tool_call"),
    tool: z.enum(["search_docs", "lookup_order", "send_email"]),
    arguments: z.record(z.string(), z.any()),
    confidence: z.number().min(0).max(1),
  }).strict(),
  z.object({
    kind: z.literal("final_answer"),
    answer: z.string().min(1).max(1200),
    confidence: z.number().min(0).max(1),
  }).strict(),
]);

curl https://api.dottxt.ai/v1/chat/completions \
  -H "Authorization: Bearer $DOTTXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-20b",
    "messages": [{ "role": "user", "content": "Use the lookup_order tool to check order ORD-9842." }],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "agent_output",
        "schema": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "kind": { "const": "tool_call" },
                "tool": { "type": "string", "enum": ["search_docs", "lookup_order", "send_email"] },
                "arguments": { "type": "object", "additionalProperties": true },
                "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
              },
              "required": ["kind", "tool", "arguments", "confidence"],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "kind": { "const": "final_answer" },
                "answer": { "type": "string", "minLength": 1, "maxLength": 1200 },
                "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
              },
              "required": ["kind", "answer", "confidence"],
              "additionalProperties": false
            }
          ]
        }
      }
    }
  }'

​
Prompt snippet

Choose exactly one action.
- If a tool is required, return kind="tool_call" with tool and arguments.
- If no tool is required, return kind="final_answer" with answer.
Never include fields from both branches.

​
Example outputs

Tool call: 
{
  "kind": "tool_call",
  "tool": "lookup_order",
  "arguments": {
    "order_id": "ORD-9842"
  },
  "confidence": 0.94
}
Final answer: 
{
  "kind": "final_answer",
  "answer": "Order ORD-9842 shipped on 2026-02-20 and is expected tomorrow.",
  "confidence": 0.88
}

​
Why this works

oneOf enforces mutual exclusivity: the model must produce either a tool_call or a final_answer, never a hybrid. Your executor reads kind, dispatches to the right handler, and never needs to guess what the model intended. The const discriminator on kind removes ambiguity. Without it, both branches might structurally overlap (both could have a string field), and validation alone couldn’t tell them apart. Confidence appears in both branches, so your orchestration layer can apply the same routing logic regardless of action type, for example, escalating to a human when confidence drops below a threshold.