The first agent I shipped had a tool called query . It took a string and returned rows. The model used it constantly, wrongly, and with growing desperation, because query told it nothing about what could be queried, what the schema was, or what a failure meant. Renaming it search_orders_by_customer_email and giving the parameter a real description fixed most of the behaviour without touching the model or the prompt. That is the general shape of tool design: the model’s competence with your tools is mostly a function of how well you described them. The definition is documentation for a reader who cannot ask questions A tool definition is read once, cold, by something that cannot open your codebase or ping you on Slack. Everything it needs must be in the schema. { "name" : "search_orders" , "description" : "Search a customer's orders by email address. Returns at most 50 orders, newest first. Only orders from the last 24 months are indexe...