# Tool calling, JSON output and reasoning

Claudech models can call functions you define, return guaranteed-valid JSON, and expose their reasoning. All three use the standard Chat Completions fields.

## Tool calling

Describe your functions in `tools`. When the model decides one should be called, it returns a `tool_calls` array instead of (or alongside) content. You run the function, append the result as a `tool` message, and call the API again.

**JavaScript**

```javascript
const tools = [
  {
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Current weather for a city.',
      parameters: {
        type: 'object',
        properties: {
          city: { type: 'string', description: 'City name, e.g. "Lisbon"' },
          unit: { type: 'string', enum: ['celsius', 'fahrenheit'] },
        },
        required: ['city'],
      },
    },
  },
];

const messages = [{ role: 'user', content: "What's the weather in Lisbon?" }];

// 1. Ask the model
const first = await client.chat.completions.create({ model: 'claude-opus-5-5', messages, tools });
const call = first.choices[0].message.tool_calls?.[0];

if (call) {
  // 2. Run the function
  const args = JSON.parse(call.function.arguments);
  const result = await getWeather(args.city, args.unit ?? 'celsius');

  // 3. Send the result back
  messages.push(first.choices[0].message);
  messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify(result) });
  const second = await client.chat.completions.create({ model: 'claude-opus-5-5', messages, tools });
  console.log(second.choices[0].message.content);
}
```

**Python**

```python
import json

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": 'City name, e.g. "Lisbon"'},
                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
            },
            "required": ["city"],
        },
    },
}]

messages = [{"role": "user", "content": "What's the weather in Lisbon?"}]

first = client.chat.completions.create(model="claude-opus-5-5", messages=messages, tools=tools)
call = (first.choices[0].message.tool_calls or [None])[0]

if call:
    args = json.loads(call.function.arguments)
    result = get_weather(args["city"], args.get("unit", "celsius"))

    messages.append(first.choices[0].message)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
    second = client.chat.completions.create(model="claude-opus-5-5", messages=messages, tools=tools)
    print(second.choices[0].message.content)
```

**curl**

```bash
curl https://api.claudech.com/v1/chat/completions \
  -H "Authorization: Bearer $CLAUDECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "messages": [{ "role": "user", "content": "What'"'"'s the weather in Lisbon?" }],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] } },
          "required": ["city"]
        }
      }
    }]
  }'
```

The first response looks like this:

```json
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_7f3a1c",
            "type": "function",
            "function": { "name": "get_weather", "arguments": "{\"city\":\"Lisbon\",\"unit\":\"celsius\"}" }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}
```

### Controlling tool use

- `tool_choice` (string | object, default `"auto"`): `"auto"` lets the model decide; `"none"` disables tools for this turn; `"required"` forces at least one call; `{"type":"function","function":{"name":"get_weather"}}` forces a specific function.
- `tools[].function.strict` (boolean): Accepted for compatibility. Models validate arguments against the schema on a best-effort basis; always validate `arguments` in your code before executing anything.

Up to 128 tools may be sent per request. Tool definitions count toward prompt tokens, so keep descriptions concise.

> **Treat arguments as untrusted input**
>
> `function.arguments` is a string produced by the model. Parse it defensively, validate against your schema, and never pass it to a shell, SQL or `eval`.

### Streaming tool calls

When streaming, tool calls arrive incrementally in `delta.tool_calls`. Each fragment has an `index`; the first fragment for an index carries `id` and `function.name`, and subsequent fragments append to `function.arguments`. Concatenate by index until `finish_reason: "tool_calls"`. The OpenAI SDK helpers (`stream.finalChatCompletion()` in JavaScript, `ChatCompletionStream` in Python) do this for you.

## JSON output

Set `response_format` to receive syntactically valid JSON:

**JavaScript**

```javascript
const res = await client.chat.completions.create({
  model: 'claude-opus-5-5',
  response_format: { type: 'json_object' },
  messages: [
    { role: 'system', content: 'Extract fields and reply with JSON: {"name": string, "email": string | null}.' },
    { role: 'user', content: 'Hi, I am Ana Costa, reach me at ana@example.com' },
  ],
});
const data = JSON.parse(res.choices[0].message.content);
```

**Python**

```python
res = client.chat.completions.create(
    model="claude-opus-5-5",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": 'Extract fields and reply with JSON: {"name": string, "email": string | null}.'},
        {"role": "user", "content": "Hi, I am Ana Costa, reach me at ana@example.com"},
    ],
)
data = json.loads(res.choices[0].message.content)
```

- The word **JSON** must appear somewhere in your messages, otherwise the request is rejected upstream. Describe the shape you want in the system prompt.
- `{"type": "json_schema", ...}` is accepted and treated as `json_object`; the schema itself is not enforced by the model, so validate the result.
- If `finish_reason` is `length`, the JSON may be truncated. Raise `max_tokens`.
- For a strict structure, tool calling with `tool_choice: "required"` and a single function is often more reliable than JSON mode: the function's `parameters` schema guides the model.

## Reasoning controls

Reasoning models (`claude-opus-5-5`, `claude-opus-5-5`, `claude-opus-5`) think before answering. The thinking is returned as `reasoning_content` on the assistant message (or as `delta.reasoning_content` while streaming) and counted in `usage.completion_tokens_details.reasoning_tokens`. Reasoning tokens are billed as output tokens.

- `reasoning_effort` (string): One of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Lower effort answers faster and cheaper; higher effort thinks longer. Each model has a default (for example `claude-opus-5` defaults to `max`). `none` disables thinking on models that allow it.
- `thinking` (object): Alternative syntax: `{"type": "enabled"}` or `{"type": "disabled"}`. Ignored when `reasoning_effort` is present.

```json
{
  "model": "claude-opus-5-5",
  "reasoning_effort": "low",
  "messages": [{ "role": "user", "content": "Is 2027 a prime number? Answer yes or no." }]
}
```

### Multi-turn conversations with reasoning

Do **not** send previous `reasoning_content` back in subsequent turns; it is dropped upstream and only adds to prompt tokens. Send the assistant's `content` (and any `tool_calls`) as usual. Within a single tool-calling loop, however, including the assistant message exactly as returned (which may include `reasoning_content`) is fine and recommended.

## Vision

Models with the vision capability accept images as content parts:

```json
{
  "model": "claude-opus-5-5",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "What is written on this sign?" },
        { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,/9j/4AAQ...", "detail": "auto" } }
      ]
    }
  ]
}
```

Data URLs (PNG, JPEG, WebP, GIF) and publicly reachable HTTPS URLs are supported, up to 64 parts per message. Image tokens are counted as prompt tokens. Check `capabilities.vision` in `GET /v1/models` before sending images; models without vision reject image parts with `400 invalid_request`.

---

Source: https://claudech.com/docs/tools
