LLM Lab

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.

Where this sits in a LangChain agent
Model→Tools→Agent loop (create_agent)→Middleware→Memory (checkpointer)→Integrations (MCP)→Guardrails

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.

@toolsent with the requestchoosesvalidatenext requestPython functiondef convert_currency(...)tool schemaname · description · argsmodeltool call{name, args, id}your app runs ittool messageresult + call id
What @tool does and where each piece goes. The model only ever sees the schema and later the result; your application turns its tool call into a real function call.

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 LangChain tool. The docstring is the description the model reads when deciding whether to call it, so write it for the model.

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.

app sends tools + question→model returns a tool call→app runs the tool→app sends the result→model answers
The model never runs the tool itself. It writes a structured call (name and arguments); the application validates and executes it, then sends the result back as a new message.

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

Check yourself · 1 of 3

How does the model know a tool exists?

Check yourself · 2 of 3

The model returns a tool call. What must the application do next?

Check yourself · 3 of 3

Why validate the tool input against the schema before running it?

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”.
All books
Labinspect the trace
How to read this
  • The stage map lights the step of the round trip; Back and Next move through the messages.
  • Each card is one message between the app and the model: its kind, its direction, and its exact content (JSON where the API uses JSON).