Describe Your Tools Like You're Training Someone New

Your agent has the right tool. It's just not using it. Here's why: an AI agent doesn't read your code. It reads the tool's description. That's the entire interface between the model and your function — not the implementation, not the variable names, just the string you wrote to describe what it does. A vague description gets a wrong guess, or no guess at all.

Why the description is the whole interface

When an agent decides which tool to call, it isn't reasoning about your source code — it's reasoning over the list of available tools and their descriptions, matching the user's request against what each one claims to do. A specific, accurate tool description lets the model produce the expected result more often; a vague one leaves it guessing.

This isn't unique to "agent tools" in the formal sense. The same mechanism shows up in plain function docstrings and in framework-specific node definitions. A Python docstring gives context to the agent so it understands what the function is for — not just for the human reading the code later. In LangGraph, a node's docstring tells the LLM what that function actually does, because the graph's routing decisions depend on the model reading that text, not the function body.

The difference in practice

Compare two tool descriptions for the exact same underlying function:

• get data — tells the model almost nothing. What data? From where? Under what conditions should this be called instead of some other tool?
• searches home inventory in Air Table — tells the model exactly when to reach for this one: the domain (home inventory), the source (a table), and the action (search).

Faced with a user request like "what's in my inventory," a model choosing between a dozen vaguely-named tools has to guess. Faced with the second description, it doesn't have to guess — the description already answers the question of when this tool applies.

How to write descriptions that work

1. Write it like you're training a new hire on their first day. State what the tool does and when someone should reach for it — not just its name.
2. Name the domain, not just the action. "Searches home inventory" beats "search" — the domain tells the model which of several similar tools applies to the current request.
3. Cover the negative case implicitly. If two tools are easy to confuse, make sure each description makes clear what it does not do, or what distinguishes it from its neighbor.
4. Apply the same standard to function docstrings, not just tool-calling schemas. If an agent (or a framework like LangGraph) reads a docstring to decide what a node does, that docstring is functionally the same thing as a tool description — write it with the same care.
5. Test with an ambiguous prompt. Give the agent a request that could plausibly match two tools and see which one it picks. If it picks wrong, the descriptions — not the model — are usually the problem.

Pitfalls

• Don't assume the model will infer intent from the function name. Function and tool names are often abbreviated or generic (get_data, process); the description is what carries the actual meaning.
• Don't write descriptions for a human audience only. A docstring that reads well in a code review but omits when to use the function is still an under-specified tool description from the agent's point of view.
• Don't let tool descriptions drift from what the tool actually does. If a tool's behavior changes but its description doesn't, agents will keep calling it in situations where it no longer applies — this is a silent failure mode that's easy to miss in testing.

Resources

• Anthropic — Tool use overview (writing effective tool descriptions)
• LangGraph — Nodes and how docstrings/descriptions inform routing