> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Function calling

> Let the model ask your code to run a function, then continue with its result, the primitive behind every agent.

You describe your functions in the `tools` parameter; the model never runs anything itself. When it decides a tool would help, it replies with `tool_calls`, structured requests naming the function and its arguments, and pauses. Your code executes them and sends the results back, and the model writes its answer with those results in hand. Every model in [the catalog](/docs/models.md) supports tools.

## What a tool call looks like

A response that requests tools has `finish_reason: "tool_calls"` and an assistant message shaped like this, note `arguments` is a JSON *string* to parse, not an object:

```json theme={null}
{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_ab12cd34",
      "type": "function",
      "function": {
        "name": "get_weather",
        "arguments": "{\"location\": \"Paris\"}"
      }
    }
  ]
}
```

## The full round trip

Three legs: request with tools → execute what the model asked for → send results back as `role: "tool"` messages (one per call, echoing the `tool_call_id`):

```python Python theme={null}
import json
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://inference.pearlresearch.ai/v1",
    api_key=os.environ.get("PEARL_API_KEY"),
)

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name, e.g. Paris"}
                },
                "required": ["location"],
            },
        },
    }
]

def get_weather(location: str) -> dict:
    return {"location": location, "temp_c": 21, "conditions": "partly cloudy"}

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

# 1) The model decides it needs a tool and returns tool_calls.
response = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Pro-0813",
    messages=messages,
    tools=TOOLS,
)
msg = response.choices[0].message

# 2) Run each requested tool and append the results.
if msg.tool_calls:
    messages.append(msg)  # the assistant turn with tool_calls stays in history
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        result = get_weather(**args)
        messages.append(
            {
                "role": "tool",
                "tool_call_id": call.id,
                "content": json.dumps(result),
            }
        )

    # 3) Send the results back; the model writes the final answer.
    final = client.chat.completions.create(
        model="deepseek-ai/DeepSeek-V4-Pro-0813",
        messages=messages,
        tools=TOOLS,
    )
    print(final.choices[0].message.content)
else:
    print(msg.content)  # no tool needed
```

```typescript TypeScript theme={null}
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://inference.pearlresearch.ai/v1',
  apiKey: process.env.PEARL_API_KEY,
});

const tools = [
  {
    type: 'function' as const,
    function: {
      name: 'get_weather',
      description: 'Get the current weather for a location',
      parameters: {
        type: 'object',
        properties: {
          location: {type: 'string', description: 'City name, e.g. Paris'},
        },
        required: ['location'],
      },
    },
  },
];

const getWeather = (location: string) => ({location, tempC: 21, conditions: 'partly cloudy'});

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

// 1) The model decides it needs a tool and returns tool_calls.
const response = await client.chat.completions.create({
  model: 'deepseek-ai/DeepSeek-V4-Pro-0813',
  messages,
  tools,
});
const msg = response.choices[0].message;

if (msg.tool_calls?.length) {
  messages.push(msg); // the assistant turn with tool_calls stays in history

  // 2) Run each requested tool and append the results.
  for (const call of msg.tool_calls) {
    const args = JSON.parse(call.function.arguments);
    messages.push({
      role: 'tool',
      tool_call_id: call.id,
      content: JSON.stringify(getWeather(args.location)),
    });
  }

  // 3) Send the results back; the model writes the final answer.
  const final = await client.chat.completions.create({
    model: 'deepseek-ai/DeepSeek-V4-Pro-0813',
    messages,
    tools,
  });
  console.log(final.choices[0].message.content);
} else {
  console.log(msg.content); // no tool needed
}
```

> [!NOTE]
>
> Keep the assistant message containing `tool_calls` in the history when you send the results, the `tool` messages answer *it*. Dropping it is the most common cause of confused follow-ups.

## From round trip to agent

An agent is this round trip in a `while` loop: keep executing `tool_calls` and appending results until the model responds with plain content (or you hit your own step budget). The model may chain different tools across iterations to decompose a task, put the loop bound and any dangerous-action confirmation in *your* code, not in the prompt.

## Best practices

* Write `description` fields like documentation for a new teammate, what the tool does, when to use it, what it returns. Tool choice quality tracks description quality.
* Constrain arguments with JSON Schema: `enum` for closed sets, `required` for mandatory fields, reject-and-retry beats guessing.
* Return machine-readable results (JSON), and return *errors* as results too, a `{"error": "city not found"}` tool message lets the model recover or ask the user, instead of the loop dying.
* For latency-sensitive agents, start with GLM-5.3 Flash and move to DeepSeek V4 Pro 0813 when tasks need deeper reasoning between calls.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.