Generative AI and Agentic AILangChain 1.4 · LangGraph 1.2 · Python 3.12 or 3.13
Dashboard
0%

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

Creating a tool and binding it to a model · from the Complete Agentic AI Course video · 1:00:03 to 1:04:15

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.

python
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:

Example
print(get_weather.name)
print(get_weather.description)
print(get_weather.args)

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:

Example
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)

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.

python
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:

ExampleAPI keyFrom the video, run on Groq
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"])
  • The content is empty. The model did not write an answer.
  • The tool call is the answer. get_weather with 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_weather has 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 tool execution loop · from the Complete Agentic AI Course video · 1:04:15 to 1:06:14

The model asked; something has to answer. The video calls the full exchange the tool execution loop, and it has four steps:

  1. Send the question as a user message and call the model.
  2. Add the model's AIMessage to the message list, so the history keeps the request.
  3. Run each tool call with get_weather.invoke(call). Passing the whole call returns a ToolMessage that carries the call's id.
  4. Add the ToolMessage to the list and call the model again. It now has the result and writes the answer.
python
messages = [{"role": "user", "content": "What's the weather like in Boston?"}]

ai_message = model_with_tools.invoke(messages)
messages.append(ai_message)
python
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:

ExampleAPI keyFrom the video, run on Groq
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)
  • The tool message. Its content is what the function returned and its tool_call_id is 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. .text is 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.

ExampleAPI keyReal API, run on Groq
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)
  • 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.

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:

bash
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.

ExampleAPI keyThe video's web search tool, run on Groq
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)
  • 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 handcreate_agentThe loop in LangGraph
What you writeBind the tool, run the calls, add the messagesA model, a tools list, a system promptNodes and edges that call the model and the tools
Who runs the toolYour codeThe agentA tool node
Repeats until the model answersOnly if you write the loopYesYes, once the edge back to the model exists
FitsLearning what is sent and returnedMost tool-using appsCustom 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.
Watch out. The model only asks for a tool call. If the code never runs it and never sends back a 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.
Try it yourself
  • Change the question in the first bind_tools example to "Tell me a joke". Print ai_message.tool_calls and 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 by get_weather.args changes.
  • Ask the temperature tool for a city name with a typo and read how the model reports the sentence the tool returned.
PreviousAI agents

You understood something today that you didn't yesterday.