Fun fact: swapping UUIDs for plain integers in your MCP tool parameters cuts agent errors.
When you compare UUID-based tool parameters against integer alternatives, you get several errors, and the reason is simple …
A UUID like a3f9c1e2-88b4-4d1e-9c77-… is not something the model can reason about. So, when the model needs to fill in that parameter, it is not recalling a value; it is pattern matching against what a UUID looks like. That produces a plausible-looking string that does not exist in your system.
This is the core mismatch between how APIs and MCP tools get consumed.
REST APIs are built for a client that already has the ID, fetched a moment ago from a database query. Even MCP is called by a model that is generating the parameter value from context, and context is made of ‘words’.
The fix is simple - never let the model see the raw UUID in the first place. Resolve it internally (if possible). If a tool needs to reference an entity, expose a human-readable name (even a var name works) or a simple index, and translate that back to the UUID on your side.
This is worth remembering the next time you are about to pass your database’s primary key straight through to a tool schema.
Hope this helps.