Unit 07.00: A tool narrow enough to be safe

A tool's description and schema are shown to the model, which makes them part of the interface rather than documentation.

What the model sees, and what actually holds

The @tool decorator derives the name, description and argument schema from the function.

The code defines a lookup tool and prints all three, then calls it with three inputs.

from langchain_core.tools import tool

ACCOUNTS = {"ACC-1187": {"plan": "individual", "balance": 42.5}}


@tool
def lookup_account(account_id: str) -> str:
    """Return the record for one account id. Read-only."""
    if not account_id.startswith("ACC-"):
        return "REFUSED: account_id must start with ACC-"
    record = ACCOUNTS.get(account_id)
    return str(record) if record else f"NOT FOUND: {account_id}"


print("name       :", lookup_account.name)
print("description:", lookup_account.description)
print("args schema:", lookup_account.args)

for candidate in ["ACC-1187", "1187", "ACC-9999"]:
    print(f"{candidate:12} -> {lookup_account.invoke({'account_id': candidate})}")

# The description and the schema are what the model is shown, so they are part
# of the interface. "Read-only" in the docstring tells the model what this is
# for; the `startswith` check is what actually holds.

The docstring becomes the description, so it is written for the model - "read-only" tells it what this is for. But the docstring is a hint, and the startswith check is what holds.

That distinction is the whole unit. The description shapes which tool gets chosen; the validation decides what happens when it is chosen wrongly. You need both, and only one of them is a guarantee.

The mistake this prevents

The mistake is writing the docstring for other developers. The model reads it and uses it to decide when to call the tool, so a vague description produces wrong tool selection - and a description mentioning capabilities the function lacks produces calls it cannot serve.

Takeaway

The docstring and schema are the model's interface to the tool. Write them for the model, and put the guarantees in validation rather than in prose.

Mark complete