model passes a comma string where my tool schema says string[], zod to json schema tool-schema

Start with the $ref. Emit the schema inlined and see if the failure rate moves. Providers vary in how thoroughly they resolve $ref and definitions in tool parameters, and a parameter the model cannot see the type of is a parameter it guesses at. Most zod converters have an option for this - zod-to-json-schema takes $refStrategy: 'none', which duplicates the shared object into each tool instead of pointing at it. Your schemas get bigger and uglier and the model stops improvising.

After that, flatten the anyOf. .optional() producing a union of a type and null is usually harmless, but anyOf at the top level of a parameter is where things get vague. If you have anything like z.union([z.string(), z.array(z.string())]) anywhere, delete the string branch - offer a model two ways to send something and it will use the one you did not want.

And put an example in the description. labels: string[] - e.g. ["urgent","billing"] is worth more than any amount of schema pedantry.

Also just accept both and normalise. You are validating at the boundary anyway:

const labels = z.preprocess(
  v => typeof v === 'string' ? v.split(',').map(s => s.trim()) : v,
  z.array(z.string())
)

This is not giving up. A retry costs a full round trip, two steps of context and a visibly confused agent; a coercion costs four lines. Fix the schema too, but stop making the user wait for a round trip over a comma.

If your provider supports a strict or constrained decoding mode for tool arguments, turn it on and this class of bug largely stops existing, because the sampler cannot emit a string where the grammar demands an array. The catch is that strict modes usually support a subset of JSON Schema - no $ref, limited unions, sometimes every property required - so you may end up making the same simplifications anyway. Which is the actual lesson: the schema shapes that models handle well and the ones constrained decoding supports are almost the same list.

Whatever you change, do not evaluate it on vibes. Save 200 real tool calls from your logs, replay them through the new schema, and count. Every one of these threads has somebody who fixed it with a description tweak and somebody else for whom that changed nothing, and the difference is always that neither of them measured.

Long shot from a day I lost: check whether the field name itself is steering it. We had tags next to a filter string in the same tool, and a lot of the malformed calls looked like the model had blended the two parameters. Renamed one and the confusion dropped noticeably. No idea how to predict that in advance, but it is worth eyeballing the neighbours of a parameter that keeps getting mangled.

"urgent,billing" is technically a string of labels. It is not wrong, it is just not helpful, which describes a lot of my week.