Tool calls

Tool calls (also known as function calling) allow models to invoke external functions to perform specific actions, such as fetching data, executing computations, or interacting with APIs. This enables models to go beyond text generation and perform real-world tasks.

Supported models

All models in the TB catalog support tool calls except where noted in the Model catalog.

How it works

1. Define tools: Provide a list of function definitions in the tools parameter.
2. Model decides: The model may call one or more tools in its response.
3. Execute: Your code executes the tool calls and returns the results.
4. Model generates final answer: The model uses the tool results to produce its final response.

Tool definition format

Each tool is defined with a name, description, and JSON Schema for parameters:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get the current weather for a location",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City name or coordinates"
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"]
        }
      },
      "required": ["location"]
    }
  }
}

Supported JSON Schema types

Request example with tools

{
  "model": "deepseek-r1",
  "messages": [
    { "role": "user", "content": "What's the weather in Tokyo today?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string" }
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Response with tool calls

When the model decides to call a tool, the response contains tool_calls:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"Tokyo\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Executing tool calls and returning results

Your code should:

1. Parse the tool_calls from the response.
2. Execute each tool with the provided arguments.
3. Add a new message to the conversation with the tool results.
4. Send the updated conversation back to the API.

{
  "model": "deepseek-r1",
  "messages": [
    { "role": "user", "content": "What's the weather in Tokyo today?" },
    {
      "role": "assistant",
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"location\": \"Tokyo\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temperature\": 22, \"condition\": \"sunny\"}"
    }
  ],
  "tools": [...]
}

The model then generates its final answer using the tool results.

Tool choice strategies

Strict mode

Some models support strict: true in tool definitions, which enforces stricter JSON Schema validation:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "strict": true,
    "parameters": { ... }
  }
}

In strict mode:

• All parameters must be defined in the schema.
• Additional properties are not allowed.
• The model must follow the schema exactly.

Best practices

1. Be specific with descriptions: Clear function and parameter descriptions help the model choose the right tool.
2. Use tool_choice: "auto" for flexibility: Let the model decide when tools are needed.
3. Handle errors gracefully: If a tool call fails, return a descriptive error in the content field.
4. Keep tool results concise: Large tool results may hit token limits. Summarize when possible.

See also

• Model catalog
• Chat completions
• Thinking Mode