I once had an agent call a tool named get_data seventeen times in a row, each time with slightly different arguments, none of which worked. The tool wasn't broken. The name was.
get_data tells the model nothing about what data, from where, or why it might fail. So it guessed. Seventeen times.
Tool schemas are the real API surface of your agent. Not your backend. Not your prompt. The schema — name, description, parameter shape, and what comes back on failure — is the only contract the model actually reasons over when deciding what to do next. Get it wrong and you're not debugging your code, you're debugging the model's confusion.
Here's what actually moved the needle.
Name the tool like a function, not a folder
get_data, process_request, handle_action — these are the kind of names a junior dev leaves as a TODO. The model treats them the same way: as a placeholder it fills in with assumptions.
Compare:
{ "name": "get_data" }{ "name": "get_customer_invoice_by_id" }The second name is doing work. It tells the model the entity (), the operation (), and the required shape () — before it even reads the description. A model choosing between five tools with vague names will pick wrong more often than one choosing between five tools whose names alone disambiguate intent.
