Structured Outputs & Tool Calling

Structured output asks a model for JSON. Tool calling lets the model request a function that your application executes. The available fields depend on the API format and model, so keep one format throughout the conversation and validate every model-produced value in your application.

Choose an API formatCopy Anchor Link

Use built-in tools only with the API format that documents them; TokenLab does not convert those tools between formats.

JSON ModeCopy Anchor Link

For a JSON object that works across many chat models, use Chat Completions JSON mode:

{
  "model": "gpt-5.6-terra",
  "messages": [
    {
      "role": "user",
      "content": "Return a JSON object with city and weather."
    }
  ],
  "response_format": { "type": "json_object" }
}

Chat Completions accepts text and json_object. json_schema and strict are model- and format-specific; use them only when the selected model documents support.

Always parse and validate returned JSON on your server. JSON mode does not replace application-level schema validation.

Complete a tool callCopy Anchor Link

TokenLab returns the function name and arguments; your application executes it:

1. Send messages plus tool definitions.
2. Read the model response for tool_calls, function_call, Anthropic tool_use, or Gemini function call parts.
3. Execute the tool in your own backend.
4. Append the tool result in the same API format.
5. Continue the conversation until the model returns a final answer.

Keep the same API format until the tool call and final answer are complete. The four formats represent tool state differently.

Chat Completions ExampleCopy Anchor Link

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {
        "role": "user",
        "content": "Extract name and email as JSON. If needed, look up the customer."
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "Look up a customer by email",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'

Write a useful schemaCopy Anchor Link

• Keep schemas small and explicit. Large nested schemas add tokens and reduce reliability.
• Prefer required fields for values your product cannot continue without.
• Use enums for closed sets that your UI or backend depends on.
• Include examples in the prompt when the model struggles with a shape.
• If a field is not supported, remove it or use an API format that documents it.

Before executing a toolCopy Anchor Link

• Record the API format, model, tool names, and schema field names.
• Validate tool arguments before executing any side effect.
• Apply your own permission checks before tool execution.
• Make tool execution idempotent when a client retry can repeat the same tool call.
• Do not log secrets returned by tools into model-visible messages.

API ReferenceCopy Anchor Link