Tool-Schema Drift Detector

A tool schema is hand-written once and then never touches the function again. Renaming a parameter, changing its type, or making it required does not break the build, fail a test, or fail at deploy. It breaks the next time a model calls the tool -- in production, days later, on someone else’s turn.

And it breaks two ways depending on the provider. Either the call is rejected, which is loud and survivable, or the argument is silently coerced and the handler runs on a wrong-typed or undefined value, returns something plausible, and the model proceeds on it.

THE WORST CASE is a parameter the handler REQUIRES that the schema never mentions. A model cannot send what it was never told about, so the handler receives undefined on every call it will ever get, forever, and whatever it does with that becomes the tool’s behaviour.

IT FAILS CLOSED. An unreadable signature reports UNKNOWN, never "no drift", and unknown counts as breaking in CI. A check that passes because it could not read the file is worse than no check: it produces a green tick that means nothing, and green ticks are trusted. null and [] are kept distinct -- [] means the function genuinely takes no parameters, null means we could not tell.

IT USES THE TYPESCRIPT COMPILER, NOT A REGEX. A regex fails on destructured parameters, defaults, generics, multi-line signatures and comments containing parentheses -- and it fails by returning a plausible wrong answer, reporting clean results for signatures it misread. That is the failure it exists to catch. Destructured object parameters get first-class handling because that is the standard tool-handler shape and its FIELDS are the real arguments.

IT REFUSES TO GUESS. An unresolvable type becomes unknown and is never reported as a mismatch; integer does not clash with number. A checker that cries wolf gets switched off, after which it catches nothing.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function diffSchema( schema: ToolJsonSchema, actual: ActualParam[] | null, opts: { toolName?: string } = {}, ): Drift[];
  export function hasBreakingDrift(drifts: Drift[]): boolean;
  export function formatDrifts(drifts: Drift[]): string;
  export function extractSignature(source: string, functionName: string): ActualParam[] | null;

  export type DriftSeverity = "breaking" | "warning" | "unknown";