Tools

Function calling for reliable actions.

Tools allow models to call structured functions (your code) instead of hallucinating actions. This is essential for agentic workflows and production integrations.

Defining tools

{
  "model": "provider/model",
  "messages": [{"role":"user","content":"What's the weather in Paris?"}],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "getWeather",
        "description": "Get the current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string"}
          },
          "required": ["city"]
        }
      }
    }
  ]
}

Tool calls in responses

Assistant requests a tool call

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_1",
            "type": "function",
            "function": {
              "name": "getWeather",
              "arguments": "{"city":"Paris"}"
            }
          }
        ]
      }
    }
  ]
}

Sending tool results back

{
  "model": "provider/model",
  "messages": [
    {"role":"user","content":"What's the weather in Paris?"},
    {
      "role":"assistant",
      "tool_calls":[{"id":"call_1","type":"function","function":{"name":"getWeather","arguments":"{\"city\":\"Paris\"}"}}]
    },
    {"role":"tool","tool_call_id":"call_1","content":"{"temp_c":18,"conditions":"Cloudy"}"}
  ]
}