Designing Tools People Actually Use
Why goal-oriented tools beat granular ones, and how a tool's description determines whether an AI model uses it correctly.
Design for the goal, not the operation
A common early mistake is mirroring your codebase's internal structure directly into tools, one tool per low-level operation. It maps cleanly to how a database client works, which is exactly the problem: an AI model isn't a database client. It has to plan a sequence of calls itself, and every extra step is another place for that plan to go wrong.
Four separate tools for what is, from the customer's side, one action: reporting a problem. The model has to correctly sequence all four calls itself, in the right order, every time, with no room for the server to enforce that order.
One call that creates the ticket, sets its priority, and returns both the ticket id and a suggested next step. The server owns the sequence internally, so it can't be called out of order because there's only one call to make.
This doesn't mean collapsing everything into a single giant tool either. The test is whether a tool corresponds to something a person would actually describe as one task. "Log a support issue" is one task. "Open a connection, then separately run a query, then separately close the connection" is three steps of one task, artificially separated.
The description is the interface
An AI model doesn't read your source code. It decides whether and how to call a tool based entirely on its name and its description. A vague description doesn't just look unpolished, it actively produces wrong tool calls.
The model has no idea what "handle" means here, what shape "data" should be, or what it gets back. It will guess, and it will guess wrong at least some of the time.
Every input is named and typed, every value has a stated meaning, and the return shape is described up front. The model can construct a correct call without ever seeing the function body.