Tools with @tool
A tool call is a structured request the model writes instead of prose: which function to run, with which arguments. The application does the running.
Describing a tool
Each tool is a name, a description the model reads to decide when to use it, and an input schema (JSON Schema) for its arguments. These go into the request next to the messages.
The round trip
When the model decides a tool helps, it stops and returns a tool call instead of an answer. The application validates the arguments, runs the function, and sends the result back as a new message. The model then continues: another call, or the final answer.
Step through the messages in the lab. The format is simplified; real APIs differ in field names but share this shape.
In LangChain
Decorate a Python function with @tool. Its name, type hints and docstring become the tool’s name, argument schema and description, which is all the model sees. Pass tools to create_agent, or attach them to a chat model with bind_tools if you want to handle the tool calls yourself.
from langchain.tools import tool
@tool
def convert_currency(amount: float, src: str, dst: str) -> float:
"""Convert an amount between two currencies at today's rate."""
return amount * get_rate(src, dst)
# what the model sees: a name, a description and a schema of the arguments
print(convert_currency.name, convert_currency.args)A worked example
The app sends a tool description for convert_currency with its parameters, and the question “How much is 250 euros in Vietnamese dong?”. The model replies not with text but with a tool call: convert_currency(amount = 250, from = EUR, to = VND). The app checks the arguments against the schema, runs the function, and sends back the result 7,050,000 tagged with the call’s ID. Only then does the model write the answer.
In practice
Clear tool names and descriptions matter as much as the code: the model chooses tools from their descriptions alone. Validate every argument, give helpful error messages when a call fails so the model can retry, and require confirmation for actions that change things.
Easy to confuse
- The model never executes the tool; your application does, with its own permissions.
- A tool call can be well formed and still wrong, such as the right function with the wrong currency code.
How does the model know a tool exists?
Tool definitions are part of the prompt; the description is what the model reads to decide when to use the tool.
The model returns a tool call. What must the application do next?
The model cannot execute code. The application runs the tool and returns a tool result so the model can continue.
Why validate the tool input against the schema before running it?
Tool inputs are generated text; check them like any untrusted input before acting.
Read more in the books
- LangChain and LangGraph documentation, LangChain: LangChain: Tools.
- AI Engineering, Chip Huyen: Ch. 6, “RAG and Agents”: agents (tools).
- Artificial Intelligence: A Modern Approach (4th ed.), Russell, Norvig: Ch. 2, “Intelligent Agents”.