How It Works · bigonotes

Tool calling is how a model takes actions in the world. A plain model call only generates text. With tool calling, the model can also ask your code to run functions you have defined, such as looking up an order or fetching the weather.

Describe the tools#

You list your functions in the API call. Each tool has three parts:

Part	What it tells the model
Name	What to call, for example `get_weather`
Description	What the tool does and when to use it
Parameter schema	Which arguments it takes, their types and which are required

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

The exact field names differ between providers, but every API asks for these three things.

The loop#

The model reads the conversation and either answers in text or asks for a tool; your code runs the tool and sends the result back, and the loop repeats until the model answers

You send the conversation and the tool list to the model.
The model decides a tool is needed. Instead of a text answer, it replies with a structured message: which function to call and with which arguments.
Your code reads that message, runs the function and gets a result.
You add the result to the conversation as a new message and call the model again.
The model reads the result. It either asks for another tool or gives a final text answer.

One example, step by step#

A user asks "What's the weather in Miami?"

Step	Who	What happens
1	Model	Replies with a call: `get_weather(city="Miami")`
2	Your code	Calls a weather API and gets back "82°F, sunny"
3	Your code	Sends "82°F, sunny" back as the tool result
4	Model	Answers "It's 82°F and sunny in Miami."

The model never saw the weather API. It only saw the tool description, asked for a call, and read the result your code sent back. The next note, Who runs it, explains why that matters.

Short line#

Tool calling is a loop. You describe your functions, the model replies with a structured request to call one, your code runs it and sends the result back, and the model either calls another tool or answers in text.

Key takeaways#

Tool calling lets a model trigger functions your code defines, not only generate text.
Each tool has a name, a description and a parameter schema.
When a tool is needed, the model replies with the function name and arguments instead of text.
Your code runs the function and sends the result back as a new message.
The loop repeats until the model gives a final text answer.

Core idea#

Tool calling lets a model trigger functions your code defines. It is a loop that repeats until the model gives a final text answer.

Describe each tool#

Part	What it tells the model
Name	What to call
Description	What it does and when to use it
Parameter schema	Arguments, types, which are required

The loop#

Send the conversation and the tool list.
The model replies with a function name and arguments, not text.
Your code runs the function.
Send the result back as a new message.
The model calls another tool or answers in text.

Example#

Step	Who	What happens
1	Model	Asks for `get_weather(city="Miami")`
2	Your code	Calls a weather API: "82°F, sunny"
3	Your code	Sends the result back
4	Model	"It's 82°F and sunny in Miami."

Pitfalls#

Do not think the model calls the API. It only asks. Your code runs it.

Short line#

Describe tools, the model asks for a call, your code runs it and sends the result back, repeat until a text answer.