Tool calling and structured output API

Beginner: the model proposes; the application executes

Tool calling does not grant a model server authority. The request tools describe allowed functions and arguments. When the model returns a call, the application verifies identity, tenant authorization, tool name, and arguments before performing any operation, then returns a result for the next model turn. Structured output constrains a final answer with JSON Schema for extraction, classification, or form generation. Neither feature replaces business rules.

Minimal tool request

Copycurl "$BASE_URL/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": "Get the delivery status for order A123",
    "tools": [{
      "type": "function",
      "name": "get_order_status",
      "description": "Read an order visible to the current user",
      "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"],
        "additionalProperties": false
      },
      "strict": true
    }]
  }'

A response can contain a function-call item, call ID, and JSON arguments. Accept only registered tools, validate arguments again, and verify that the order belongs to the caller. Return a tool result correlated to the original call ID. Treat every model-generated identifier, URL, command, and amount as untrusted input.

Structured output and refusal branches

Use the supported endpoint's response_format or text-format schema for final JSON and enable strict. Specify types, required properties, enums, lengths, and additionalProperties: false. After parsing, still validate date range, numeric precision, entity existence, and authorization. A model can refuse, encounter a safety policy, or hit an output limit; the parser must distinguish refusal, truncation, protocol failure, and valid JSON.

Copy{"type":"json_schema","name":"ticket","strict":true,"schema":{"type":"object","properties":{"category":{"type":"string","enum":["billing","technical"]},"summary":{"type":"string"}},"required":["category","summary"],"additionalProperties":false}}

Safe execution and idempotency

Give every tool its own permission, timeout, input limit, network egress policy, and rate limit. Use parameterized database queries, an HTTP destination allowlist with SSRF protection, and a least-privilege sandbox for code. Write operations need an application idempotency key and confirmation policy. A repeated call ID must return the existing result instead of charging or ordering again. Tool output can itself contain prompt injection, so structure, truncate, and label it as untrusted before sending it back to the model.

Errors, loops, and observability

Return tool failures as structured {code,message,retryable} data without exposing stacks or secrets. Bound total steps, per-tool calls, tokens, spend, and wall-clock time, and detect repeated arguments. Log trace, response ID, call ID, tool name, argument hash, authorization decision, latency, state, and side-effect ID with sensitive fields redacted. Function arguments can arrive as streamed fragments; execute only after the completion event.

Expert: schema evolution and agent governance

Version tools and output schemas. Adding an optional property can remain compatible, while removing or changing semantics requires a new version and canary. Replay recorded requests, tool results, and final answers against authorization, duplicate execution, partial failure, timeout, refusal, and model-upgrade cases. Put a policy engine and human approval around high-risk writes, separating what the model wants to call from what the system permits. Recover from a persisted state machine, never from the assumption that the model remembers prior side effects.