What a tool call is: Tool calling basics

The model only asks for a function to be run. Your code runs it. How to describe a tool so the model can choose it.

Tool (function) calling

You tell the model which functions exist: a name, a description, and a JSON Schema for the arguments. When it decides a function would help, its reply contains a tool call: the function name and a JSON string of arguments, instead of (or as well as) text. The model does not run anything. Your program runs the function and sends the result back as a message, so the model can use it.

Models need this because they cannot see current data or act on other systems by themselves. A tool is the bridge.

One tool call is two round trips to the model and one run of your own function.

Describe the tool

class WeatherArgs(BaseModel):
    model_config = ConfigDict(extra="forbid")
    city: str = Field(min_length=1, description="City name, for example 'Pune'")

Tool("get_weather", "Current weather for a city.", WeatherArgs, get_weather)

tool.schema() produces what you send in the request:

{"name": "get_weather", "description": "Current weather for a city.",
 "parameters": {"additionalProperties": false, "properties": {"city": {"type": "string", "minLength": 1, "description": "..."}}, "required": ["city"], ...}}

The model sees only this text. Three consequences:

Names and descriptions are prompts. A vague name or description makes the model pick the wrong tool or skip it. Say what the tool does, when to use it, and when not to.
Describe every argument, with an example value, a unit or an allowed set. This is the cheapest accuracy gain you have.
Fewer, clearer tools beat many overlapping ones. Each schema costs input tokens on every call (module 6) and gives the model more ways to choose badly.

extra="forbid" matters. Without it, Pydantic silently ignores an argument the tool does not know. If a model asks for {"city": "Pune", "units": "f"}, it believes it asked for Fahrenheit, and your tool quietly returns Celsius. With the setting, the model gets an error that names the unknown field.

Check yourself

Why does the example give Tool a description as well as a name? (The model sees only the name, description and schema, so the description is how it learns when to use the tool.)