Encoding API contracts in tool schemas beats prose descriptions for smaller LLMs

A developer team discovered in May 2026 that two AI models — Opus 4.7 and Sonnet 4.6 — produced different JSON outputs from the same tool description, with the smaller model returning an incorrect structure that triggered downstream 422 errors. The root cause was not a capability difference but an exposure gap: the larger model had seen the proprietary field names during training, while the smaller one guessed plausible-sounding alternatives. Because tool descriptions are prose rather than enforced contracts, models without prior exposure to a custom schema have no validated structure to follow. The team resolved this by migrating the structural contract into the JSON schema itself, using discriminated oneOf branches with strict required fields for the nine most common pattern types. They applied a permissive fallback branch for rare pattern kinds, limiting the upfront effort to roughly one afternoon while targeting the failures that actually occurred in production.