Describing tools

An analytics agent has two tools: get_data and query. The first reads a table, the second runs SQL. Each description is four words long. In production, the model calls query to read an entire table, hits a 30-second timeout, calls query again with the same request, then tries get_data with an invented table name. No line of the loop is at fault. The model did what you could expect of it: it guessed, because nobody told it anything.

A tool's description isn't documentation. It's the specification the model uses to make decisions. It serves as a function signature, a docstring, and an error contract all at once. An imprecise schema produces invalid calls; an ambiguous name produces calls to the wrong tool; a poorly formed return value produces needless loop iterations. These are the three dominant causes of drift in an agent, far ahead of the choice of model, and they can all be fixed in the file where you declare your tools.

A Complete Tool Schema

Here is the full shape of a usable declaration. Compare its information density with get_data.