Tools: functions an agent can use

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 CrewAI runs it.

Lesson 2's clerk looked orders up in a dictionary. That lookup becomes a tool, so an agent can use it.

from crewai.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 from crewai.tools 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

from tools import lookup_order

print(lookup_order.name)
print(lookup_order.description)
print(lookup_order.args_schema.model_json_schema()["properties"])

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 says to send one string called order_id.

Running a tool yourself

from tools import lookup_order

print(lookup_order.run(order_id="A17"))
print(lookup_order.run(order_id="B22"))

run calls the function with keyword arguments, the way CrewAI will. B22 is not in the dictionary, so the tool says so in words a model can pass on.

A tool without a docstring

from crewai.tools import tool


@tool
def lookup_order(order_id: str) -> str:
    return "unknown"

A tool with no description is refused when it is defined. Without one, a model would have nothing to decide with.

Save tools.py. Lesson 9 gives the tool to an agent, and lesson 12 adds a second tool to the file.