Why does renaming a tool's parameter break my agent even though my tests still pass?

Because the model doesn’t call a tool the way your code calls a function. It decides which tool to use and how to fill each argument by reading that tool’s name, description, and parameter schema fresh at inference time, not by referencing a stable identifier your code checks. Rename a parameter or reword its description and you’ve changed exactly what the model reads before it forms a call, even though nothing in your handler’s logic moved.

Your tests still pass because they exercise the code path against the new schema, confirming your handler accepts the renamed field. None of them assert that the model still picks the right tool or fills the right argument once the wording changes, because that’s a model decision, not a code path. Treat a tool’s name and description as a contract with a reader beyond your code, and check tool-selection behavior against eval traffic before merging a rename, not just your test suite.