Tool calling
Tool calling is a feature of chat models in which the model, instead of answering in text, returns a request to run a named function with specific arguments, and the code around it runs the function and sends the result back.
Last updated: 08 Oct, 2026 · LangChain 1.4
In AI agents the agent called get_weather by itself. Here is that exchange opened up: how a function becomes a tool, what the model returns when it wants one, how to run the call, and how to point a tool at a real API.
Writing a tool with the @tool decorator
The video defines a tool as a name, a description and a set of arguments, joined to a function. The @tool decorator from langchain.tools builds that from a Python function. The tool takes its name from the function, its description from the docstring, and its argument schema from the type hints.
from langchain.tools import tool
@tool
def get_weather(location: str) -> str:
"""Get the weather at a location."""
return f"It's sunny in {location}."A tool object has the three parts as attributes. Printing them shows what the model will be sent:
print(get_weather.name)
print(get_weather.description)
print(get_weather.args)get_weather
Get the weather at a location.
{'location': {'title': 'Location', 'type': 'string'}}The name is the function's name, the description is the docstring, and the arguments come from the type hint: location is a string. These three travel to the model with every request.
The docstring is required. Without it the decorator has no description to give the model, so it refuses:
from langchain.tools import tool
try:
@tool
def get_weather(location: str) -> str:
return f"It's sunny in {location}."
except Exception as error:
print(type(error).__name__ + ":", error)ValueError: Function must have a docstring if description not provided.
Binding a tool to a model with bind_tools
A chat model only knows about a tool when the tool is sent with the request. model.bind_tools([...]) returns a copy of the model that sends each tool's name, description and argument schema with every call. Syntax: model_with_tools = model.bind_tools([tool_one, tool_two]).
The video runs this on a Qwen model hosted on Groq, which Groq has since retired. The code here uses groq:openai/gpt-oss-120b; the calls are the same.
from langchain.chat_models import init_chat_model
model = init_chat_model("groq:openai/gpt-oss-120b")
model_with_tools = model.bind_tools([get_weather])Calling model_with_tools.invoke(...) with a question the tool can answer does not return text. It returns an AIMessage whose tool_calls list holds the requests:
ai_message = model_with_tools.invoke("What's the weather like in Boston?")
print(repr(ai_message.content))
for call in ai_message.tool_calls:
print(call["name"], call["args"])''
get_weather {'location': 'Boston'}- The content is empty. The model did not write an answer.
- The tool call is the answer.
get_weatherwith the argument{'location': 'Boston'}, built from the question and the argument schema. Each call also carries an id, which its result must carry back. - Nothing has run. The model returned a request and
get_weatherhas not been called. The model matched the question to the tool's description to choose it. - One call per reply. On Groq, gpt-oss makes one tool call per reply, so a question that needs two lookups takes two rounds.
Running the tool call and sending back the result
The model asked; something has to answer. The video calls the full exchange the tool execution loop, and it has four steps:
- Send the question as a user message and call the model.
- Add the model's
AIMessageto the message list, so the history keeps the request. - Run each tool call with
get_weather.invoke(call). Passing the whole call returns aToolMessagethat carries the call's id. - Add the
ToolMessageto the list and call the model again. It now has the result and writes the answer.
messages = [{"role": "user", "content": "What's the weather like in Boston?"}]
ai_message = model_with_tools.invoke(messages)
messages.append(ai_message)for call in ai_message.tool_calls:
tool_message = get_weather.invoke(call)
messages.append(tool_message)The whole loop, with the second model call that produces the answer:
messages = [{"role": "user", "content": "What's the weather like in Boston?"}]
ai_message = model_with_tools.invoke(messages)
messages.append(ai_message)
for call in ai_message.tool_calls:
tool_message = get_weather.invoke(call)
messages.append(tool_message)
print(tool_message)
print(model_with_tools.invoke(messages).text)content="It's sunny in Boston." name='get_weather' tool_call_id='fc_aad79212-26ee-4042-a2fc-bf80990160bb' It’s currently sunny in Boston.
- The tool message. Its
contentis what the function returned and itstool_call_idis the id of the request it answers. That match is how the model pairs a result with its call. - The answer. The last line is the model's own sentence, written from the tool message.
.textis a property that returns the reply as plain text, so it takes no parentheses.
create_agent from the last lesson runs exactly this loop, and keeps going until the model answers without asking for a tool.
A tool that calls a real API
The video's weather tool returns a fixed sentence and says an API call could go in its place. This one makes the call. It uses Open-Meteo, a free weather service that needs no key: one request turns a city name into coordinates, a second returns the current temperature.
Two choices in the tool matter. The docstring says what the tool returns and in which unit. And when the city is not found, the tool returns a sentence instead of raising an error, so the model can read it and tell the user.
import json
import urllib.parse
import urllib.request
from langchain.agents import create_agent
from langchain.tools import tool
def fetch(url):
with urllib.request.urlopen(url, timeout=15) as response:
return json.load(response)
@tool
def get_temperature(city: str) -> str:
"""Get the current air temperature in Celsius for a city."""
query = urllib.parse.urlencode({"name": city, "count": 1})
found = fetch("https://geocoding-api.open-meteo.com/v1/search?" + query)
if not found.get("results"):
return f"No city called {city} was found."
place = found["results"][0]
query = urllib.parse.urlencode({
"latitude": place["latitude"], "longitude": place["longitude"], "current": "temperature_2m",
})
now = fetch("https://api.open-meteo.com/v1/forecast?" + query)["current"]
return f"{place['name']}, {place.get('country', '')}: {now['temperature_2m']} C"
agent = create_agent("groq:openai/gpt-oss-120b", tools=[get_temperature])
for city in ["Bengaluru", "Zzyzxqwv"]:
question = f"What is the temperature in {city} right now?"
result = agent.invoke({"messages": [{"role": "user", "content": question}]})
print(city, "->", result["messages"][-1].content)Bengaluru -> The current temperature in Bengaluru is **21.8 °C**. Zzyzxqwv -> I’m not able to locate a city named **Zzyzxqwv**, so I can’t retrieve a temperature for it. If you meant a different location (perhaps a nearby town or a city with a similar name), please let me know and I’ll be happy to look up the current temperature for you.
- The first city. The model called the tool, the tool made two requests to Open-Meteo, and the answer repeats the temperature the tool returned, in Celsius as the docstring said. The captured run printed 21.8 °C; the number is the temperature at the moment of the run, so yours will differ.
- The city that does not exist. The tool returned its "No city called ... was found." sentence instead of raising. The model read it, said it could not locate the city, and offered to look up a nearby name. A tool that raises an exception stops the whole run, so a sentence the model can read is the better answer to an expected failure.
A free Tavily key for web searchOptional
The video's agents search the web with TavilySearch from the langchain-tavily package, which needs a TAVILY_API_KEY. No other example here needs it. Install the package:
pip install "langchain-tavily==0.2.18"Getting a free Tavily keyOptional
Sign up at app.tavily.com. The API key is on the dashboard and starts with tvly-. The free plan gives 1,000 API credits a month and needs no card. Set the key the same way as the Groq key:
export TAVILY_API_KEY=tvly-...Or add it to the .env file under the Groq key:
GROQ_API_KEY=gsk_...
# optional, only the web search examples use it
TAVILY_API_KEY=tvly-...TavilySearch(max_results=2) is a ready-made tool. It goes into the tools list like any function, and the model reads its description from the package. Without the key, creating it stops with an error that names TAVILY_API_KEY.
from langchain.agents import create_agent
from langchain_tavily import TavilySearch
agent = create_agent(
model="groq:openai/gpt-oss-120b",
tools=[TavilySearch(max_results=2)],
system_prompt="Search the web before you answer. Reply in two sentences.",
)
result = agent.invoke({"messages": [{"role": "user", "content": "What is LangGraph?"}]})
called = [call["name"] for m in result["messages"] for call in getattr(m, "tool_calls", [])]
print(called)
print(result["messages"][-1].content)['tavily_search'] LangGraph is an open‑source, graph‑based framework built on top of LangChain that lets developers design, run, and manage complex LLM‑powered AI agent workflows as nodes and edges, enabling cyclic and more flexible execution patterns【0†L1-L4】. By representing agents as graphs, LangGraph simplifies orchestration, state handling, and scalability compared to traditional linear chain approaches【1†L1-L5】.
- The tool name. The model called
tavily_search, the name the package gives its tool, before it answered. - The answer. The two sentences come from the search results the tool returned. The bracketed marks are the model's pointers to the results it read, not links.
Three ways to give a model a tool
| bind_tools by hand | create_agent | The loop in LangGraph | |
|---|---|---|---|
| What you write | Bind the tool, run the calls, add the messages | A model, a tools list, a system prompt | Nodes and edges that call the model and the tools |
| Who runs the tool | Your code | The agent | A tool node |
| Repeats until the model answers | Only if you write the loop | Yes | Yes, once the edge back to the model exists |
| Fits | Learning what is sent and returned | Most tool-using apps | Custom control flow |
Where you use tool calling
- Live data. A weather, price or order-status lookup the model could never know from training.
- Actions. A function that sends a message, writes a row or files a ticket, with the model choosing when.
- Calculation and lookup. Arithmetic, database queries and search, where an exact answer beats a guess.
ToolMessage with the same call id, the model has no result to answer from. Keep the docstring honest too: the model chooses a tool by reading it, so a vague docstring leads to the wrong tool or to none.Related
- Previous: AI agents
- Next: ReAct agents
- See also: Tools and bind_tools in the LangChain course
- Reference: LangChain tools
- Change the question in the first
bind_toolsexample to"Tell me a joke". Printai_message.tool_callsand see whether the model asks for the tool at all. - Add a second argument to
get_weather,unit: str, and read how the argument schema printed byget_weather.argschanges. - Ask the temperature tool for a city name with a typo and read how the model reports the sentence the tool returned.
You understood something today that you didn't yesterday.