Stop making the LLM write your API's JSON
How I designed a structured-output schema for an LLM tool with zod and a small compiler, and what 643 calls to Claude Haiku, Sonnet and Opus 5.5 showed against Garmin's own workout JSON: a tie on accuracy, not on the bill.
- Code & method included
- AI-assisted, author-checked

From a pile of braces to the four things a runner cares about. (AI-generated illustration)
I run, and I write software. Garmin MCP is my unofficial, open-source MCP server for Garmin Connect, and one of its 21 tools writes instead of reading: create_workout turns "6 x 400 m at 3:50-4:05 with 90 s rest" into a structured workout on your Garmin calendar and watch.
It is also the biggest tool by far: 11,936 of the 38,762 bytes the model reads with every request, 31% of the tool list. Most of that is a workout schema I designed for the model, instead of passing Garmin's own workout JSON through. Earlier in this series I wrote about keeping the tool list small and testing which tool the model picks. This one asks what I had never measured: does the model write my format better than Garmin's?
So I wrote 43 workout requests with the expected workout for each, and had three current Claude models build every one twice in both formats, plus three variations of mine. One call each, no retry. I had run the same experiment on the previous generation earlier that day, and the contrast turned out to be the interesting part.
Two ways to write the same workout¶
Garmin Connect stores a workout as JSON with a lot of bookkeeping. Every sport, step type, end condition and target is an object with a numeric id and a key that must match. Steps carry a stepOrder numbered depth first across nested repeats, and each repeat group a childStepId shared with its children. A repeat states its count twice. A pace range is two speeds in metres per second, the slow one first. A strength load is in grams.

The example from the tool's own schema, and what the compiler sends to Garmin for it.
My format, which I will call the DSL, keeps only what a coach would say and leaves the bookkeeping to code. The model writes the intent; a compiler writes Garmin's JSON.
How to write a schema like this¶
The DSL is a zod schema in TypeScript. The MCP SDK turns it into the JSON Schema the model reads, and the same zod schema validates whatever the model sends back. Six pieces do most of the work. The code is from the repository, trimmed slightly for print.
1. Write values the way people say them. Pace is the string a runner would type, checked by a regular expression:
const PACE = /^\d{1,2}:[0-5]\d$/;
export const paceString = z
.string()
.regex(PACE, 'pace must be m:ss per km, e.g. "4:30"')
.refine((pace) => pace.replace(/[0:]/g, '') !== '', 'pace must be above 0:00')
.meta({ id: 'Pace', description: 'Pace as minutes:seconds per kilometre, e.g. "4:30"' });
.meta({ id }) turns it into a named definition, so every pace field in the tool points to one $defs/Pace instead of repeating it. This is what the model gets:
"Pace": {
"type": "string",
"pattern": "^\\d{1,2}:[0-5]\\d$",
"description": "Pace as minutes:seconds per kilometre, e.g. \"4:30\""
}
The .refine is gone. JSON Schema cannot say "anything but 0:00", so the model never sees that rule, and the server has to enforce it. The same is true of every rule that relates two fields.
2. Name the ends of a range. For pace, min and max are a trap: the minimum pace is the fastest. The field names say which end is which:
z.object({
type: z.literal('pace'),
min_per_km_fast: paceString.describe('Fast end of the pace range, m:ss per km'),
min_per_km_slow: paceString.describe('Slow end of the pace range, m:ss per km'),
}),
Durations and targets are discriminated unions on type, so each kind carries only its own fields: {"type": "time", "seconds": 90}, {"type": "distance", "meters": 400}, {"type": "hr_zone", "zone": 2}. A step with no duration ends on the lap button, which is what a coach means by "until you are done".
3. Let the structure nest the way the workout does. A repeat holds steps, and a step can be another repeat. In zod 4 a getter makes the recursion lazy, and the JSON Schema gets a $ref back to Step:
export const repeatStepSchema: z.ZodType<RepeatStep> = z
.object({
kind: z.literal('repeat'),
count: z.number().int().min(1).max(99).describe('How many times to repeat the nested steps'),
get steps(): z.ZodArray<z.ZodType<WorkoutStep>> {
return z.array(stepSchema).min(1).describe('Steps repeated together; may contain further repeats');
},
})
.meta({ id: 'RepeatStep' });
export const stepSchema = z.union([executableStepSchema, repeatStepSchema]).meta({ id: 'Step' });
The model writes {"kind": "repeat", "count": 3, "steps": [...]} as deep as the workout needs. There are no step numbers or group ids to keep in sync.
4. Show one complete example. The top-level description carries the whole 6 x 400 m workout as one line of JSON: warm-up, a repeat with an interval and a recovery, a cool-down on the lap button. One full example shows the nesting, the units and the shape of a target at once, which field descriptions on their own do not.
5. Do the bookkeeping and the cross-field checks in code. compileWorkout walks the tree, numbers the steps depth first, gives each repeat its group id and converts pace into Garmin's speeds. It is also where the rules the JSON Schema cannot carry live:
case 'pace': {
const fast = paceToMetersPerSecond(target.min_per_km_fast);
const slow = paceToMetersPerSecond(target.min_per_km_slow);
if (fast <= slow) {
throw new WorkoutDefinitionError(
`min_per_km_fast (${target.min_per_km_fast}) must be faster than min_per_km_slow (${target.min_per_km_slow})`,
path,
'The fast end is the smaller time per km, e.g. min_per_km_fast "4:00" and min_per_km_slow "4:15".',
);
}
// Garmin stores pace ranges as speeds, slow bound first.
return { targetType: TARGET_TYPES.pace_zone, targetValueOne: slow, targetValueTwo: fast };
}
At the end the compiler parses its own output with a strict schema of Garmin's JSON: only known ids and keys, fields that must come in pairs, a repeat count equal to its end condition. A bug in the compiler fails there, not in Garmin Connect.
6. Make the error point at the field. zod reports a bad step inside a union as "invalid union" at the step itself, which tells the model nothing. The server follows the branch whose error goes deepest, because that is the branch the model meant:
function deepestIssue(issue: z.core.$ZodIssue, prefix: PropertyKey[]): FlatIssue {
const path = [...prefix, ...issue.path];
if (issue.code === 'invalid_union' && issue.errors.length > 0) {
const branches = issue.errors.flatMap((branch) => (branch[0] ? [deepestIssue(branch[0], path)] : []));
if (branches.length > 0) return branches.reduce((best, b) => (b.path.length > best.path.length ? b : best));
}
return { path, message: issue.message };
}
So a swapped range in the 6 x 400 m comes back as:
{
"code": "INVALID_INPUT",
"message": "steps[1].steps[0].target: min_per_km_fast (4:05) must be faster than min_per_km_slow (3:50)",
"hint": "The fast end is the smaller time per km, e.g. min_per_km_fast \"4:00\" and min_per_km_slow \"4:15\"."
}
and "3.50" instead of "3:50" as steps[1].steps[0].target.min_per_km_fast: pace must be m:ss per km, e.g. "4:30". The model gets the field and the fix in one message before it tries again. The experiment below allows no retry, so it measures only the first attempt.
The production tool also has four presets and a dry_run preview; the experiment compared only the typed definition with Garmin's JSON.
The experiment¶
The 43 requests are things I would actually type, 22 in Polish and 21 in English: run intervals on pace, heart-rate zones and ranges, bike sessions on power zones and watts, cadence, swimming, strength with exercises and loads, nested repeats, steps that end on the lap button, a calorie target, a note on the watch, and five vague ones like "Coś lekkiego na 40 minut" (something easy for 40 minutes). For 38 I wrote the expected workout in the DSL; the five vague ones have constraints instead (sport, total time, nothing harder than zone 2...).
The model saw one tool, create_workout, in one of five shapes:
- DSL: the production schema. My generator reproduces the server's
definitionschema byte for byte. - Garmin JSON: Garmin's format documented with the same care: every unit, every valid id and key pair, the depth-first numbering, and the same 6 x 400 m example compiled to Garmin JSON.
- Three ablations of the DSL: pace as whole seconds per km (270), pace as metres per second (3.704), and the DSL with no descriptions at all.
Each call was claude -p against a tiny MCP server with just that tool, with no built-in tools, no settings, an empty working directory, --max-turns 1, and one appended instruction: call the tool once, do not ask questions, add only the steps the user describes. The models were Claude Haiku 5.5, Sonnet 5.5 and Opus 5.5, each running every request twice per format; the pace ablations ran on Haiku and Sonnet, the bare DSL on Haiku. That is 643 calls on Claude Code 2.1.330, all on 21 November 2026.
An answer counts as right on the first try when it passes the variant's schema, compiles, and matches the expected workout step by step once the repeats are unrolled: the same sport, step roles, durations within a second or a metre (two for the mile), zones exact, watts and bpm within 1 (3 for a share of FTP), pace within 3 seconds per km (10 for swimming and for "about 3:30"). An extra warm-up, a missing recovery right before the cool-down or the end, and a target the user did not ask for are forgiven. Haiku 5.5 needed that: in 32 answers it left out the recovery after the last interval, usually by writing the last repetition outside the repeat, which is arguably the better workout.

One of the nested requests: the expected tree, its preview, and the 29 steps the scorer compares.
Results: the gap is mostly gone¶

Right on the first try, per model and format. The lighter panel is the previous generation, run on an older Claude Code.
On the current models my format still comes out ahead, but only just: 87% against 81% with Haiku, 93% against 91% with Sonnet, 98% against 97% with Opus. With 86 answers per bar, all three differences are inside the noise. Every one of the 516 answers was valid against its schema, Garmin's 107-line format included, with correct id and key pairs.
The previous generation looked very different. Haiku 4.5 was right 74% of the time with the DSL and 53% with Garmin's JSON, a gap of 21 points. Sonnet 4.5 and Opus 4.6 already showed no difference. Those runs used Claude Code 2.1.34 instead of 2.1.330, with otherwise the same requests, schemas, settings and scorer, so I treat them as background rather than as a controlled comparison.
Where the errors are now¶

Calls with each kind of error, current models. A call can have several.
Pace is solved. In 258 Garmin JSON answers from the current models there was exactly one wrong pace: Haiku put a 4:00-4:10 interval at 4:10-4:20. Nobody swapped the two speeds. On the 14 requests with a pace target, Haiku 5.5 was right in 27 of 28 DSL answers and 25 of 28 Garmin JSON answers, and the misses were mostly not about pace.
The rest is shared by both formats. Garmin's strength catalogue has 52 categories and the schema shows three examples. The swing in "15 kettlebell swings" lives in HIP_RAISE; the models wrote HIP_SWING, KETTLEBELL or SWING, in 8 of 36 strength answers with the DSL and 10 of 36 with Garmin JSON. And Polish "Rower:" means bike, while English "rower" means someone who rows: 16 of 36 answers to my three Polish bike requests came back as other or cardio_training, in both formats. A Polish swim request that starts with "Basen:" (pool) became a run three times. That is also why Haiku 5.5 scored 80% in Polish and 95% in English with the DSL.
What the previous generation got wrong¶
The old runs show what the DSL was designed against. Haiku 4.5 got 23 Garmin JSON paces wrong in value and put the fast speed first in 16. Asked for 4:10-4:20 per km, it wrote 4.76 and 4.55 m/s, which is 3:30-3:40. On the 29 requests without a pace target, it scored the same in both formats; the whole gap was pace.
To check that, I kept the DSL as it is and changed only the pace field.

Same schema, same requests; only the way pace is written changes.
For Haiku 4.5 the order matched the arithmetic each format asks for: none for "4:30", one multiplication for seconds, a division and an ordering for speeds. Haiku 5.5 keeps a faint version of that order, 96% against 89%, two answers out of 28. Sonnet 5.5 got all of them right in every format.
The previous generation also found the DSL's own weak spot. The DSL has one pace unit, minutes per kilometre, and swimmers think per 100 m. In 9 of 10 previous-generation swim answers the model copied "1:50" straight into the per-km field. The current models converted it, to "18:20" and the like, in all 12 of their DSL answers; only once, in the variant with pace in seconds, did Haiku 5.5 slip back. The field still invites the mistake; the models just mostly stopped making it.
Removing every description and the example from the DSL hardly mattered this time: Haiku 5.5 went from 38 to 37 of 43, one run each.
What each format costs¶

The bill, and what it buys. Output tokens include the models' thinking.
This is where the formats still differ. Documented properly, Garmin's format is the bigger schema: 9,211 bytes against 5,861, about 1,700 more input tokens per call. The bigger cost is the answer. A Garmin workout took 2.5 to 3.5 times the output tokens at the median and 1.4 to 1.9 times the time: 7.4 s instead of 3.9 s with Sonnet. Per call that is 28% more money with Haiku, 42% with Sonnet and 36% with Opus, for the same or slightly worse workouts.
The preview catches most of it¶
create_workout with dry_run: true saves nothing and returns the steps as text from describeWorkout, so the user sees them before saying yes. I ran every answer through it.

Most wrong answers look wrong in the preview. Two kinds do not.
Most wrong answers look wrong there: a sport of "other", a pace 10 seconds off. Two kinds do not. The preview prints the exercise name, not its category, so HIP_SWING / KETTLEBELL_SWING reads as "Kettlebell swing". And it sorts the two pace bounds before printing them, so a swapped range in Garmin JSON reads as right; in the DSL the compiler refuses that case first.
Both point at the same thing: where the target system has a fixed vocabulary or a unit the user thinks in, the schema should carry it or check it. An exercise key checked against the catalogue cannot slip through a preview that prints only the name. A model that is usually right does not make that check unnecessary; it makes the remaining errors harder to see.
What this does not show¶
- One call, no retry. In real use the server answers an invalid DSL with the field and a hint, and the model tries again. The silent errors above would not be caught that way.
- My requests, my expected answers. 43 requests written by me, with tolerances I chose. The five vague ones are checked only against loose constraints.
- Small samples. 86 answers per format and model, 14 to 28 per ablation bar; a few points mean nothing.
- Two generations, two clients. The previous generation ran on Claude Code 2.1.34 with fewer runs for Opus 4.6; the current one on 2.1.330. The comparison between them is background, not a controlled test.
- Not sent to Garmin. "Right" means it matches my expected workout and the strict schema of what my compiler emits. Sonnet sometimes used Garmin's
fixed.restend condition, which I counted as a rest of the same length without checking how Garmin shows it.
If you design a tool schema for an LLM¶
- Measure again when the models change. The argument I built the DSL on, that small models cannot convert units, was true for Haiku 4.5 and is mostly not true for Haiku 5.5.
- Make the model write what the user said anyway. It still costs nothing in accuracy, and for Haiku 4.5 it was the difference between 53% and 74%.
- Put the bookkeeping in code. Ids, orders and group references cost two to three times the output tokens and about twice the time, even when the model gets them right.
- Fail loudly on what you can check. A compiler that refuses a swapped range turns a silent error into a retry.
- Carry or check the vocabulary. The errors left are exercise keys and sports, in both formats: words, not numbers.
- Look at the preview you show users. Mine hides two kinds of error.
The experiment is a set of scripts, 43 requests and the raw answers of both generations; the tool is create_workout in https://github.com/endurancetools/garmin-mcp, with the schema in packages/domain/src/workouts/definition.ts. The documentation is at https://endurancetools.github.io/garmin-mcp/.
Unofficial; not affiliated with or endorsed by Garmin.
Some illustrations in this article were generated with ChatGPT.