Our API docs told AI agents to do the exact thing that fails

A developer at Deskcrew discovered that their API's type mismatch between numeric IDs returned by tools and string IDs expected by input schemas broke 107 of 121 possible tool chains for AI agents. The documentation explicitly instructed agents to pass the ID as returned, but the type mismatch caused validation failures. The team fixed it with a guarded preprocessor that converts only positive safe integers to strings, leaving the JSON Schema unchanged.

We run a helpdesk that AI agents can operate over MCP: list tickets, read a thread, draft a reply for a human to approve. Last week a real agent paid for a call, chained it into a second call, and hit a wall. What we found underneath was embarrassing enough to write up, because I think half the "agent-ready" APIs out there have the same bug. Our create ticket tool returns this: { "ticketId": 47, "customerId": 18, "status": "active" } And our get ticket context tool accepts this: { "ticketId": { "type": "string", "minLength": 1 } } See it? The id comes OUT as a JSON number, because the database hands out integer ids. It goes IN as a string, because someone wrote z.string in the input schema. So the most natural two-step an agent can perform, take the id from one response and pass it to the next tool, fails validation before the handler ever runs: ticketId: Expected string, received number We audited every tool after the first report. All 24 fields that return an id emit numbers. All 14 fields that accept one demanded strings. Of 121 possible tool chains, 107 were broken. The part that hurts: every input schema's own description said "the id, as returned by list tickets". The documentation was actively instructing agents into the failure. Humans never chain raw ids; they click. Agents chain constantly, and they do it literally. They take your output and feed it to your input, exactly as documented. Our test suite never caught it because every test wrapped ids defensively: js const res = await runTool draftReply, { ticketId: String ticket.id } That String is the whole story. The tests encoded what a careful human author would type, not what a literal-minded agent actually sends. The suite was green for months while the surface was broken for every real agent. We widened the acceptors. Changing the emitters returning "47" instead of 47 would silently change the response shape for every existing client, so that was off the table. But the obvious wideners both have traps: z.union z.string , z.number changes your published JSON Schema to an anyOf . If your tool list is advertised to clients MCP's tools/list , an OpenAPI doc , that is a contract change every client can see, and some will handle it badly. z.coerce.string accepts everything. null becomes "null" , undefined becomes "undefined" , and a missing id turns from a clean validation error into a confusing "not found" three layers deeper.What we shipped is a guarded preprocess: js const numericIdToString = v: unknown = typeof v === 'number' && Number.isSafeInteger v && v 0 ? String v : v export const idSchema = = z.preprocess numericIdToString, z.string .min 1 Only a positive safe integer is rewritten. Everything else passes through untouched, so null , {} , floats, and negatives still fail with the same messages they always had. And the generated JSON Schema is byte-identical to the old z.string .min 1 , so the published contract does not move at all. We verified that with a test that renders both schemas and compares the JSON. String , no Number .Agents are the most literal API consumers you will ever have. They follow your docs exactly, which means your docs finally get tested. If you want to poke at the surface that taught us this, the agent door is documented at deskcrew.io/agents https://deskcrew.io/agents . Free reads, and the paid actions quote you a price before you commit to anything. What's the equivalent bug in your API? I'd genuinely like to know if the number-vs-string id split is as common as I suspect.