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

# Function calling

> Let a model choose tools, return structured arguments, and continue after your application executes the tool.

Function calling, also called tool calling, lets a model decide when to call an external function and what arguments to pass. The model does not execute the function. Your application executes it, sends the result back, and asks the model to produce the final answer.

Use function calling to build assistants that can query databases, check order status, fetch weather, search internal systems, or trigger controlled actions.

## Workflow

1. Send the user message and a list of available tools.
2. The model returns one or more tool calls with JSON arguments.
3. Your application validates and executes the tool calls.
4. Send the tool results back as `tool` messages.
5. The model uses the results to generate the final response.

## Define tools

Declare available tools in the `tools` array. Each function uses JSON Schema for its arguments.

```json theme={null}
{
  "model": "gpt-4o",
  "messages": [
    {"role": "user", "content": "What is the weather in Beijing today?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name, such as Beijing or Shanghai"
            }
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}
```

`tool_choice` controls tool selection:

* `auto`: the model decides whether to call a tool.
* `none`: tool calling is disabled for this request.
* `{"type":"function","function":{"name":"get_weather"}}`: force a specific function.

## Read the tool call

When the model wants to call a tool, it returns `tool_calls`:

```json theme={null}
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\": \"Beijing\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}
```

Parse `function.arguments` as JSON and keep the `id`. You need that ID when returning the tool result.

## Return tool results

After your application runs `get_weather`, append a `tool` message using the matching `tool_call_id`:

```json theme={null}
{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"temp\": \"25 C\", \"condition\": \"sunny\"}"
}
```

Then send the full conversation back to the model so it can produce the final answer.

## Complete Python example

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

client = OpenAI(api_key="sk-your-key", base_url="https://moxus.ai/v1")

def get_weather(city: str) -> dict:
    return {"temp": "25 C", "condition": "sunny"}

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }
]

messages = [{"role": "user", "content": "What is the weather in Beijing today?"}]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

message = response.choices[0].message

if message.tool_calls:
    messages.append(message)
    for call in message.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),
            }
        )

    final = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=tools,
    )
    print(final.choices[0].message.content)
else:
    print(message.content)
```

## Notes

* Validate arguments before executing a function.
* Return tool results as strings, usually serialized JSON.
* A model may request multiple tool calls in one response.
* Tool calling support depends on the selected model.
* Every additional round consumes tokens, so keep tool outputs concise.

## Next steps

* [Structured output](/en/guide/structured-output)
* [Reasoning models](/en/guide/reasoning)