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

# 03 tool calling

# Tool Calling (Function Calling)

Let the model call your functions to get real-time data or perform actions.

## Defining Tools

Tools are defined using JSON Schema:

```json theme={null}
{
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name, e.g., 'Tokyo'"
          }
        },
        "required": ["location"]
      }
    }
  }]
}
```

## Tool Call Flow

```
1. User asks question → send with tools
2. Model returns tool_calls (not content)
3. Execute the function(s)
4. Send results back with role: "tool"
5. Model gives final answer
```

## Response with Tool Calls

When the model wants to call a tool:

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

## Sending Tool Results

After executing the tool, send the result:

```python theme={null}
messages = [
    {"role": "user", "content": "What's the weather in Tokyo?"},
    {
        "role": "assistant",
        "content": "",
        "tool_calls": [...]  # From previous response
    },
    {
        "role": "tool",
        "tool_call_id": "call_abc123",  # Must match!
        "name": "get_weather",          # Function name
        "content": "{\"temp\": 15, \"condition\": \"sunny\"}"
    }
]
```

## Complete Example

```python theme={null}
import json
import httpx

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

def get_weather(location):
    return {"location": location, "temp": 72, "condition": "sunny"}

# Step 1: Initial request
messages = [{"role": "user", "content": "What's the weather in NYC?"}]
response = httpx.post(URL, json={"messages": messages, "tools": TOOLS})
msg = response.json()["choices"][0]["message"]

# Step 2: Execute tool
if msg.get("tool_calls"):
    tc = msg["tool_calls"][0]
    args = json.loads(tc["function"]["arguments"])
    result = get_weather(**args)
    
    # Step 3: Send result
    messages.append({"role": "assistant", "content": "", "tool_calls": msg["tool_calls"]})
    messages.append({
        "role": "tool",
        "tool_call_id": tc["id"],
        "name": "get_weather",
        "content": json.dumps(result)
    })
    
    # Step 4: Get final answer
    final = httpx.post(URL, json={"messages": messages, "tools": TOOLS})
    print(final.json()["choices"][0]["message"]["content"])
```

## See Also

* [examples/03\_tool\_calling.py](../examples/03_tool_calling.py) - Single tool example
* [examples/05\_multi\_turn\_tools.py](../examples/05_multi_turn_tools.py) - Sequential tools
* [examples/06\_parallel\_tools.py](../examples/06_parallel_tools.py) - Parallel tools


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