Treat Your Tool Schema Like a Public API, Not an Implementation Detail
When you give an agent a set of tools, the name, parameters, and description of each tool function as a contract the model has learned to call correctly — through your examples, your descriptions, and whatever in-context learning got it there. Change that contract quietly and you don't just break the code that calls the tool; you break the model's learned expectations about what the tool does and how to invoke it, often in ways that don't show up as an error, just as a slightly wrong argument or a call that silently does the wrong thing.
Teams that ship agents to production tend to learn this the hard way: a parameter gets renamed for clarity, a default changes, a description gets tightened up — and call accuracy quietly drops for a week before anyone traces it back to the tool definition instead of the model.
The fix is unglamorous but familiar from ordinary API design: version your tool schemas, deprecate old parameters instead of renaming them outright, and re-run your tool-calling evals — even a small set — every time a tool definition changes, not just when the underlying implementation changes. Treat the schema and the implementation as two things that can each break independently, because they can.
The tell that you're not doing this yet: if you can't say when a specific tool's schema last changed without checking git blame on the implementation file, your tool contract and your code are coupled in a way that will eventually cost you a debugging session that looks like a model regression and is actually an undocumented interface change.