Routing Tool Calls by Version When Two Schemas Run Live

The routing table maps a version string to a handler plus a compatibility mode. It is the only place that decides what a version means.

Three properties make this table useful.

It is data, not code. A table read from configuration or a feature flag service can change during an incident without a deploy. A routing table baked into a switch statement cannot.

Every version has a status. active is normal service. shadow runs the handler and logs the result without returning it, which lets you measure a new schema against real traffic before advertising it. retired means the version is no longer offered but may still be mapped. killed means reject everything for that version immediately. The status is what the kill switch flips.

The table is checked before the handler runs. This is the load-bearing decision. Version validation happens at the dispatcher boundary, so an unknown version produces a rejection with a stable error code and nothing else executes. No handler is called, no side effect is attempted, no partial write happens. That mirrors the central question in schema evolution work, whether old code can read new data and whether new code can read old data, which a survey of schema evolution tooling frames as the thing compatibility checks exist to answer. At the tool boundary, the dispatcher answers it.

The default for anything the routing table does not recognize is rejection. Not "try the newest schema," not "try each schema until one validates." Those two produce the worst incidents, because they silently reinterpret caller intent.

The dispatcher's decision order:

1. Extract the version from the envelope field, falling back to the header alias if the envelope is absent.
2. If no version is present, reject with missing_schema_version and HTTP 400.
3. Look the version up in the routing table. If absent, reject with unknown_schema_version and 400.
4. If the status is killed, reject with schema_version_killed and 409 or 410. Use 409 if the version may return, 410 if it will not.
5. If the status is retired with map_to_current, rewrite the payload into the current shape, then validate against the current schema. If validation fails, reject with schema_migration_failed and 400.
6. If the status is retired with none, reject with unknown_schema_version and 400.
7. Otherwise dispatch to the handler named in the row.

The error response should be parseable without reading prose. An agent that gets a rejection needs to know what to do next.

{
  "error": "unknown_schema_version",
  "message": "Schema version '1' is retired and cannot be mapped.",
  "supported_versions": ["2"],
  "migration_url": "https://docs.example.com/tools/invoices#v1-to-v2"
}

That shape follows a principle that makes tools usable by agents: a machine-readable error with an explicit next step beats a stack trace, and status codes should be a documented contract. One write-up on CLI design for agents makes the point that agents branch on exit or status codes, so returning the same code for every failure forces them to parse text and sometimes get it wrong. OpenStatus's account of rebuilding their CLI shows the same pattern applied to errors: tell the caller exactly what to provide.

The status choice carries meaning. 400 says the request itself is wrong and retrying unchanged is pointless, which is the right signal for an unknown version. A 500 tells the caller to retry, which it will, which is how a version mismatch becomes a retry storm.

The decision rule is narrow and worth stating precisely.

Map a retired version to the current schema only if the new schema accepts the old payload unchanged. Every field the old callers send still exists with the same name, type, and meaning. If a v1 caller sends {"amount": 249.00} and v2 expects {"amount_cents": 24900}, that is not a mapping candidate, because the old payload does not validate against the new schema. It is a breaking change.

Refuse when the change is breaking. Refuse when a field was removed, renamed, retyped, or given a new meaning. Refuse when an optional field became required. Refuse when validation got stricter, because a payload that passed before now fails and the caller has no way to learn why. These are the rules behind most safe API evolution advice, and Milan Jovanovic's argument against reflexive versioning states them directly: don't take anything away, don't change processing rules, don't make optional things required, and make everything you add optional.

Here is the same rule as a table for a design review.

There is a strong argument for avoiding the breaking change entirely. If you can add a new field next to the old one and leave the old field in place, you need no new version, and the routing question disappears for that change. Irina Dominte's deep dive on API versioning frames this as a choice between a new location, a backward-compatible change, and a full break, and notes you need a mix in practice. For tool schemas the additive path is usually cheap, because the model regenerates arguments per call; the expensive part is reprompting callers, not the schema.

Supporting two versions has a real cost. xMatters's versioning guidance recommends enforcing backward compatibility with tests on every change and verifying that endpoints accept the same request schemas and return the same response schemas across versions. That transfers directly: keep a fixture per retired version, run it against the mapping layer in continuous integration, and fail the build when a mapping stops validating.

A kill switch is a control keyed on the version string that stops new work for that version without a deploy. It exists for the case where you find a problem in a schema version and need to stop it in seconds.

The semantics need to be explicit, because "reject everything for version 2" is the wrong instruction.

New calls for a killed version are rejected with a stable code and a 409 or 410. They never reach the handler.

In-flight calls finish. A call that passed the routing check before the switch flipped runs to completion and returns its normal result. Killing a version should not abort writes halfway through, because a half-applied side effect is worse than a slow drain.

The switch is checked once, at dispatch time, and the result carried with the request. Do not re-check inside the handler; a handler that re-reads the switch mid-execution produces inconsistent behavior under load.

Two numbers make the timing concrete. Suppose the 99th percentile latency of a tool call is 900 ms. Once you flip the switch, calls already past the check finish within roughly a second, so the trigger for teardown is a couple of seconds. A later one is worth thinking about.

Observe the errors. In the same twenty-four hours, confirm the unknown_schema_version rate for version 1 is zero. If callers still hit the killed version, your error code is not reaching their branching logic, and the fix is a direct message to that caller, not a code change.

Only then remove the mapping code, delete the v1 handler, and delete the v1 fixture from the compatibility test suite in one pull request. Leaving the mapping in place "just in case" is how a v1 never dies. The checkpoints that matter: as-sent v1 traffic near zero before the kill, mapping failure rate at zero throughout, and no killed-version retries after the flip.