Picture an assistant that answers "What time is it in Tokyo, and what is 234 × 17?": for the first half it queries a clock API, for the second it does arithmetic. An LLM on its own can do neither reliably. Tool calling (also called function calling) gives it the right to ask for Python functions to be called: you run them, then feed the result back. It is the mechanism that turns a chatbot into an autonomous agent, and it runs entirely locally with Ollama.
What you will learn
- What tool calling is and how it differs from structured outputs
- Connect a first Python tool to an Ollama LLM
- Handle several tools and let the LLM choose
- Build an agent loop that chains several tool calls within a single user request
Tool calling vs Structured Outputs: don't confuse them
| Structured Outputs | Tool Calling | |
|---|---|---|
| Goal | Force the format of the output | Ask the LLM to invoke a function |
| The model produces… | JSON that conforms to a schema | A call intent: function name + arguments |
| Who runs it? | Nobody, it is the final answer | You (the Python code) run the function |
| Use cases | Entity extraction, classification | Agents, search, API integrations |
If you have not yet read Structured outputs with Ollama, start with that guide to see the contrast.
The complete flow in 5 steps
When we say "the LLM calls a tool", that is a shorthand. In reality, the Python code orchestrates everything. Here is the real cycle:
- You send the LLM the user's question and the list of available tools, as a JSON schema.
- The LLM decides whether it needs a tool. If so, it returns a
tool_callsobject with the name and the arguments. It runs nothing. - Your code runs the matching Python function.
- You send back to the LLM the same conversation, plus a new message with the
toolrole that contains the result. - The LLM writes a final answer in natural language, relying on that result.
You are the orchestrator. The LLM has no access to the system.
Prerequisites and installation
# Model used in this lesson (tools capability declared)ollama pull qwen3
# Python project (creates pyproject.toml), then the dependencymkdir lab-ollama-tools && cd lab-ollama-toolsuv inituv add "ollama==0.6.3"The outputs in this guide come from Ollama 0.40.16 and the ollama Python SDK 0.6.3, on CPU only. The qwen3 tag without a suffix designates the 8.2-billion-parameter model, quantized to Q4_K_M. Quantization stores each weight on a few bits, here a little under 5 on average (about 0.6 bytes), to make the file lighter: it weighs 5.2 GB.
First tool: the weather
We will give the LLM a single tool: a get_weather(city) function that returns made-up weather. The goal is to see the full flow from end to end.
from ollama import Client
MODEL = "qwen3"HOST = "http://localhost:11434"
# 1. La fonction Python qui sera appeléedef get_weather(city: str) -> dict: """Retourne une météo factice pour une ville française.""" db = { "Paris": {"temp_c": 14, "condition": "Nuageux", "humidite": 78}, "Marseille": {"temp_c": 22, "condition": "Ensoleillé", "humidite": 45}, } return db.get(city, {"error": f"Ville inconnue : {city}"})
# 2. Le schéma de l'outil (JSON Schema standard)TOOLS = [ { "type": "function", "function": { "name": "get_weather", "description": "Obtenir la météo actuelle d'une ville française.", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "Nom de la ville."}, }, "required": ["city"], }, }, }]
client = Client(host=HOST)messages = [ {"role": "user", "content": "Quel temps fait-il à Marseille ?"},]
# Tour 1 : on envoie la question + les outilsresponse = client.chat(model=MODEL, messages=messages, tools=TOOLS, options={"temperature": 0})msg = response["message"]print("Le LLM a-t-il décidé d'appeler un outil ?", bool(msg.get("tool_calls")))
# Tour 2 : on exécute l'outil et on lui renvoie le résultatmessages.append(msg)for call in msg.get("tool_calls") or []: if call["function"]["name"] == "get_weather": args = call["function"]["arguments"] result = get_weather(args["city"]) messages.append({"role": "tool", "content": str(result), "tool_name": "get_weather"})
# Tour 3 : le LLM formule la réponse finale pour l'utilisateurfinal = client.chat(model=MODEL, messages=messages, options={"temperature": 0})print(final["message"]["content"])The strings in the script are in French: the user's question ("Quel temps fait-il à Marseille ?", "What is the weather like in Marseille?"), the tool description and the made-up weather data are what the model reads and returns, so the outputs below are in French as well. Save the script in the project folder, then run it with uv run 01-single-tool.py: uv uses the project environment created by uv init and uv add. The same command works for the following scripts.
With qwen3, the model "thinks" before answering: this reasoning is on by default. Without the think parameter, the message.thinking field of the response is filled in. Adding think=False to client.chat turns it off and reduces latency.
A measurement gives the order of magnitude, on a short question with no tool: 2.5 s with think=False (13 tokens generated), against 29.8 s by default (191 tokens) and 33 s with think=True (244 tokens). The machine is an Intel Core i7-12650H CPU (16 threads, no GPU), running qwen3 at 8 billion parameters and Ollama 0.40.16. This measurement does not cover a call with tools.
Real output with qwen3:
Le LLM a-t-il décidé d'appeler un outil ? TrueÀ Marseille, la température est de **22°C** (soit **71,6°F**), et le temps est **ensoleillé**. L'humidité est à **45%**, ce qui rend l'air agréable et sec. Parfait pour une promenade en plein air ! ☀️The first line ("Did the LLM decide to call a tool? True") confirms that the model asked for the tool to be called. The second is the final answer: "In Marseille, the temperature is 22°C (71.6°F), and the weather is sunny. The humidity is 45%, which makes the air pleasant and dry. Perfect for an outdoor walk!" Its wording varies from one run to the next; only the facts that come from the tool (22 °C, sunny, 45%) stay the same.
Several tools: the LLM chooses
In practice, you give the LLM several tools and it picks the right one according to the question. The logic is the same: you extend the TOOLS list and add a dispatcher, here a DISPATCH dictionary that maps a tool's name to the matching Python function.
The calculer function filters the characters before calling eval, which is enough for a demonstration. In production, replace it with a real expression parser: a filter is not enough to make eval safe.
from ollama import Client
def calculer(expression: str) -> str: """Évalue une expression mathématique simple.""" allowed = set("0123456789+-*/. ()") if not all(c in allowed for c in expression): return "Expression non autorisée." return str(eval(expression, {"__builtins__": {}}, {}))
def recherche_doc(query: str) -> str: """Retourne un extrait fictif de doc interne.""" db = { "ollama": "Ollama est un runtime local pour LLM open-source.", "qwen3": "Qwen3 est une famille de modèles de langage disponible dans Ollama.", } for key, val in db.items(): if key in query.lower(): return val return "Aucun résultat."
TOOLS = [ {"type": "function", "function": { "name": "calculer", "description": "Calculer une expression mathématique.", "parameters": {"type": "object", "properties": {"expression": {"type": "string"}}, "required": ["expression"]}, }}, {"type": "function", "function": { "name": "recherche_doc", "description": "Rechercher dans la doc interne (Ollama, qwen3).", "parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}, }},]
DISPATCH = {"calculer": calculer, "recherche_doc": recherche_doc}
# Le LLM choisit lequel utiliserclient = Client(host="http://localhost:11434")def ask(question: str) -> None: messages = [{"role": "user", "content": question}] response = client.chat(model="qwen3", messages=messages, tools=TOOLS, options={"temperature": 0}) msg = response["message"] if not msg.get("tool_calls"): print("→", msg.get("content", "")) return messages.append(msg) for call in msg["tool_calls"]: name = call["function"]["name"] result = DISPATCH[name](**call["function"]["arguments"]) print(f" Tool: {name} → {result}") messages.append({"role": "tool", "content": str(result), "tool_name": name}) final = client.chat(model="qwen3", messages=messages, options={"temperature": 0}) print("→", final["message"]["content"])
ask("Combien font 234 * 17 ?")ask("C'est quoi qwen3 ?")Real output with qwen3:
Tool: calculer → 3978→ Le résultat de $ 234 \times 17 $ est :
$$\boxed{3978}$$ Tool: recherche_doc → Qwen3 est une famille de modèles de langage disponible dans Ollama.→ Qwen3 est une famille de modèles de langage de pointe développés par Alibaba Cloud, faisant partie de la série Qwen. Ces modèles sont conçus pour exceller dans diverses tâches, notamment la génération de texte, la compréhension naturelle, la génération de code, et la résolution de problèmes complexes. Ils prennent en charge plusieurs langues, y compris le français, et sont optimisés pour offrir des performances élevées dans des scénarios de dialogue, de rédaction et d'analyse.
Actuellement, Qwen3 est disponible via la plateforme Ollama, permettant aux utilisateurs de l'intégrer facilement dans leurs applications ou projets. Si vous avez des questions spécifiques sur ses fonctionnalités ou son utilisation, n'hésitez pas à demander ! 😊Each question triggers a different tool: calculer for the multiplication, recherche_doc for the question about qwen3. The model then rephrases the result in its own way (here with math markup for 3978, "The result of 234 × 17 is: 3978"), and that wording varies from one run to the next. It also does more than rephrase: the answer about qwen3 mentions Alibaba Cloud and capabilities of the model that the tool's result did not contain (the tool only said "Qwen3 is a family of language models available in Ollama"). The model fills in with what it believes it knows, a trap described below.
Agent loop: chaining several tools
An LLM can also chain several tools within a single user request. Example: "Who directed Inception, and how long is the film in hours?". The LLM has to:
- Call
chercher_film(titre="Inception")→ duration in minutes - Call
convertir_minutes(minutes=148)→ "2h28" format - Write the final answer by combining both results
This takes a loop that keeps going as long as the LLM asks for tools, and a MAX_TURNS safeguard that stops it if it goes around in circles.
from ollama import Client
MAX_TURNS = 5 # Garde-fou : interdit plus de 5 tours pour 1 question utilisateur
def chercher_film(titre: str) -> str: db = {"Inception": {"realisateur": "Christopher Nolan", "annee": 2010, "duree_min": 148}} return str(db.get(titre, {"error": f"Film inconnu : {titre}"}))
def convertir_minutes(minutes: int) -> str: h, m = divmod(minutes, 60) return f"{h}h{m:02d}"
TOOLS = [ {"type": "function", "function": { "name": "chercher_film", "description": "Métadonnées d'un film par titre.", "parameters": {"type": "object", "properties": {"titre": {"type": "string"}}, "required": ["titre"]}, }}, {"type": "function", "function": { "name": "convertir_minutes", "description": "Convertir des minutes en heures+minutes.", "parameters": {"type": "object", "properties": {"minutes": {"type": "integer"}}, "required": ["minutes"]}, }},]DISPATCH = {"chercher_film": chercher_film, "convertir_minutes": convertir_minutes}
client = Client(host="http://localhost:11434")messages = [{"role": "user", "content": "Quel est le réalisateur d'Inception et combien dure le film en heures ?"}]
for turn in range(MAX_TURNS): response = client.chat(model="qwen3", messages=messages, tools=TOOLS, options={"temperature": 0}) msg = response["message"] if not msg.get("tool_calls"): print(f"[Tour {turn+1}] Réponse finale : {msg['content']}") break messages.append(msg) for call in msg["tool_calls"]: name = call["function"]["name"] result = DISPATCH[name](**call["function"]["arguments"]) print(f"[Tour {turn+1}] {name} → {result}") messages.append({"role": "tool", "content": str(result), "tool_name": name})else: print(f"Boucle interrompue après {MAX_TURNS} tours.")Real output with qwen3:
[Tour 1] chercher_film → {'realisateur': 'Christopher Nolan', 'annee': 2010, 'duree_min': 148}[Tour 2] convertir_minutes → 2h28[Tour 3] Réponse finale : Le réalisateur d'**Inception** est **Christopher Nolan**. La durée du film est de **2h28**.The LLM chained the two tools without any intervention. In the output, "Tour" means "turn", and the final line reads "Final answer: The director of Inception is Christopher Nolan. The film's duration is 2h28." Turn 3 no longer contains tool_calls: the loop stops and the final answer combines both results.
Pitfalls to know
The LLM sometimes calls a tool needlessly. On a simple question such as "Bonjour" ("Hello"), an LLM may decide to call a tool anyway. Add to the system prompt: "Only use a tool if it is necessary to answer."
Which model should you choose for tool calling?
Not every Ollama model supports tool calling, and each model's page on ollama.com/library says what it can do. The four models below are common models from the library. The sizes are those of the latest tag shown on ollama.com/library, that is, the size of the file to download. Only qwen3 was used for the outputs in this guide.
| Model | File size |
|---|---|
qwen3 | 5.2 GB |
gemma4 | 6.6 GB (the latest tag is e4b) |
llama3.1 | 4.9 GB |
mistral | 4.4 GB |
Reliability depends on your tools and your prompts, so you need to measure it on your own case. After a call, ollama ps shows the memory actually used (SIZE column) and the split between CPU and GPU (PROCESSOR column): the memory used exceeds the file size because of the context. For speed, ollama run --verbose qwen3 "Bonjour" prints the eval rate line at the end of the response, in tokens per second.
To compare, replace qwen3 with another model from the list in the examples and compare the tool_calls you get.
Going further: agent frameworks
Ollama's native tool calling is enough to learn the mechanism. For more complex agents (memory, multi-step, fallback, observability), a framework takes over. The Function calling guide (in French) goes deeper into Pydantic validation of arguments and a tool's error handling, and the Building AI agents in Python path (in French) chains these steps:
- PydanticAI (in French): typed agents with Pydantic validation at every step
- LangGraph (in French): state graph, agents with persistent memory
- smolagents (in French): agents that write Python code to solve a task
Key takeaways
- Tool calling = the LLM decides what to call, you run it, you send back the result, the LLM answers. The cycle has five steps.
- The LLM has no access to the system: it proposes the call, and your code runs it.
- Agent loop = repeat the cycle until the LLM no longer proposes a tool, with a
MAX_TURNSsafeguard. - Measure on your machine:
ollama psfor memory,ollama run --verbosefor speed. - Validate downstream: a correct tool result does not guarantee a correct final answer from the LLM.
Knowledge check
Check that you have the essentials of this guide. The questions cover only what was just explained here.
Knowledge check
Check what you have learned with this interactive quiz
How it works
- The timer starts when you click Start
- Multiple choice, true/false and short answer questions
- You can move between questions
- Detailed results are shown at the end
Starts the quiz and the timer
Review
(0/0)Score by domain
A domain groups several guides and gets several questions, so its score is more reliable than a per-topic score, which often rests on a single question.
Summary
Strengths
No topic passed at 80% on at least two questions yet.
Weak areas
No topic below the pass mark.
Recommended next
Hints before you try again?
A new full quiz with random questions
Work again only on the questions you missed
FAQ
qwen3; (2) the Ollama server is too old, update it; (3) the description of the tools is too vague for the model.type ("integer") describes the expected type to the model, but nothing guarantees it will respect it: it may return "148" instead of 148. Convert and validate the arguments (int(), or a Pydantic model) before calling your function, and describe the parameter precisely in the description.DISPATCH[name](**args) in a try/except. On error, send the LLM a message such as {"error": "...", "details": "..."}: it can then write an answer suited to the user.MAX_TURNS safeguard: for turn in range(MAX_TURNS) stops after that many turns, even if the LLM still asks for a tool. The else block of the for loop then runs and can print an interruption message, which makes the case visible.