Tools

A tool is a function your application knows how to run. You describe it on the request. The model can answer in text, or it can ask you to call that function. You run it, send the result back, and the model writes the reply. Chat Completions and Messages both do this. The tool description is different on each API. The examples use lume-3.5.

Chat Completions

POST /v1/chat/completions needs the scope chat:completions. Each tool has type set to function. You can send up to 64 tools. A function name matches ^[A-Za-z0-9_-]{1,64}$, and each function schema can be at most 16,384 bytes. tool_choice is none, auto, required, or one named function. parallel_tool_calls is a boolean. Leave tool_choice out and the model decides.

curl https://api.overcontrolgroup.com/v1/chat/completions \
  -H "Authorization: Bearer $OVERCONTROL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lume-3.5",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "What is the temperature in Lisbon?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_temperature",
          "description": "Get the temperature for a city.",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string"}
            },
            "required": ["city"]
          }
        }
      }
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OVERCONTROL_API_KEY"],
    base_url="https://api.overcontrolgroup.com/v1",
)

response = client.chat.completions.create(
    model="lume-3.5",
    max_tokens=256,
    messages=[{"role": "user", "content": "What is the temperature in Lisbon?"}],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "get_temperature",
                "description": "Get the temperature for a city.",
                "parameters": {
                    "type": "object",
                    "properties": {"city": {"type": "string"}},
                    "required": ["city"],
                },
            },
        }
    ],
)

print(response.choices[0].message.tool_calls)

When the model wants the function, finish_reason is tool_calls and message.content is null. function.arguments is a JSON string, not an object.

{
  "id": "chatcmpl_0123456789abcdef0123456789abcdef",
  "object": "chat.completion",
  "created": 1789430400,
  "model": "lume-3.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_0123456789abcdef",
            "type": "function",
            "function": {
              "name": "get_temperature",
              "arguments": "{\"city\":\"Lisbon\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 40,
    "completion_tokens": 12,
    "total_tokens": 52
  }
}

Run the function, then send the conversation back with the assistant message and a tool result:

{"role": "tool", "tool_call_id": "call_0123456789abcdef", "content": "18"}

The next completion is the reply your user sees. On a stream, that same call finishes with finish_reason tool_calls, and the arguments arrive in delta.tool_calls. Older clients can still send functions and function_call. A tool call then comes back as message.function_call, and finish_reason is function_call. New code should use tools. The response includes X-Request-Id.

Messages

POST /v1/messages needs messages:create and anthropic-version: 2023-06-01. A client tool has a name, a description, and an input_schema. Leave type out, or set it to custom. strict: true is rejected. strict: false is ignored. Server-side tools, including web search, code execution, and MCP tools, are rejected. A tool whose only job is to search other tools is rejected too.

curl https://api.overcontrolgroup.com/v1/messages \
  -H "x-api-key: $OVERCONTROL_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lume-3.5",
    "max_tokens": 256,
    "tools": [
      {
        "name": "get_temperature",
        "description": "Get the temperature for a city.",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": {"type": "string"}
          },
          "required": ["city"]
        }
      }
    ],
    "messages": [
      {"role": "user", "content": "What is the temperature in Lisbon?"}
    ]
  }'

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["OVERCONTROL_API_KEY"],
    base_url="https://api.overcontrolgroup.com",
)

message = client.messages.create(
    model="lume-3.5",
    max_tokens=256,
    tools=[
        {
            "name": "get_temperature",
            "description": "Get the temperature for a city.",
            "input_schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        }
    ],
    messages=[{"role": "user", "content": "What is the temperature in Lisbon?"}],
)

print(message.content)

A tool call is a content block, and stop_reason is tool_use. input is an object.

{
  "type": "tool_use",
  "id": "toolu_0123456789abcdef",
  "name": "get_temperature",
  "input": {"city": "Lisbon"}
}

Send the result on the next user message:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_0123456789abcdef",
      "content": "18"
    }
  ]
}

The result has to refer to a tool_use from an earlier assistant turn. On a stream, the arguments arrive as input_json_delta events. Streaming lists those events.

Streaming

Read a tool call as it is written.

Structured outputs

Ask for JSON text instead of a function call.

Get started

Text

Files

Migrate

Workspace

Integrations

Chat Completions

Messages

Next

Streaming

Structured outputs

​Chat Completions

​Messages

​Next

Streaming

Structured outputs

Chat Completions

Messages

Next