Tools: a function the model can call

A tool is a Python function with a name, a description and a schema for its arguments. The model never runs it; it asks for it by name, and your code runs it.

The shop keeps order statuses in a dictionary. Looking one up is ordinary Python.

from langchain.tools import tool

ORDERS = {"A17": "shipped on 3 March", "C40": "waiting for stock"}


@tool
def lookup_order(order_id: str) -> str:
    """Look up an order's shipping status by its id, such as A17."""
    status = ORDERS.get(order_id)
    return f"{order_id} {status}." if status else f"{order_id} is not an order we have."

@tool turns the function into a tool object. It takes the name from the function, the description from the docstring, and the argument types from the type hints.

What the model is told

print(lookup_order.name)
print(lookup_order.description)
print(lookup_order.args)

This is everything a model learns about the tool. The docstring is how it decides when to use it, so it says what the tool does and what an order id looks like. The schema tells it to send one string called order_id.

Running a tool yourself

print(lookup_order.invoke({"order_id": "A17"}))
print(lookup_order.invoke({"order_id": "B22"}))

A tool is called with a dictionary of arguments, the form a model produces. B22 is not in the dictionary, so the tool says so in words the model can pass on.

A tool without type hints

from langchain.tools import tool


@tool
def lookup_order(order_id):
    """Look up an order's shipping status by its id, such as A17."""
    return "unknown"


print(lookup_order.args)

Type hints are meant to be required, but 1.4.2 accepts the function anyway and drops the type from the schema, so a model is no longer told that order_id is a string. Keep the hints.