What a tool actually is

A tool is a Python function with a docstring. The decorator reads your function and writes the description the model needs.

python

from agents import function_tool


@function_tool
def lookup_order(order_id: str) -> str:
    """Look up the status of an order by its id."""
    return f"Order {order_id} shipped on 3 March."

Nothing about that is special except the one line above it. The function is ordinary Python and you can still call it yourself.

Example

print("name:       ", lookup_order.name)
print("description:", lookup_order.description)
print("arguments:  ", list(lookup_order.params_json_schema["properties"]))

Where each piece came from

What the model sees	Where you wrote it
the name	the function name
the description	the docstring
the arguments and their types	the type hints on the parameters

Nothing was invented. Every part of that description is something you already wrote for the next human to read, and the decorator collected it.

Why the docstring matters more than you think

The model never sees the body of your function. It sees the name, the description and the argument list, and it decides from those three things alone whether this is the right tool to use.

Write the docstring for the model

A docstring that says gets data will get the tool called at random, or never. Say what it does and when it should be used. This is the highest value editing you can do to an agent that is misbehaving.

Try it yourself

Delete the docstring and print the description again.
Add a second argument with a type hint and look at the arguments.
Change str to int and see what the schema says.

PreviousYour first agent

You understood something today that you didn't yesterday.