The typical API client has changed; AI language models are now interacting with them automatically. This means the precision of API contracts has become critical to avoid costly errors.
A big shift is happening in how our APIs are used. It's no longer just human developers interacting with them. Imagine your internal scripts, database queries, and admin actions quietly becoming APIs, but the client isn't a developer reading your docs—it's an AI language model. This is the reality brought by the Model Context Protocol (MCP), and it's a game-changer for everyone in tech. So, what does this mean for you? When a human developer integrates your API, they absorb ambiguity with their judgment. They read the docs twice, test things, and email you if something doesn't make sense. An AI agent does none of that. It reads a tool's name, description, and input schema, forms a 'belief' about what it does, and then acts on that belief immediately, often in production, possibly hundreds of times an hour. Every ambiguity in a human-facing API might cost you a support ticket. But every ambiguity in an agent-facing tool costs you whatever the agent decided it meant, multiplied by every session that encounters that same uncertainty. This can lead to very expensive and unexpected problems. The solution isn't better prompting on the client side—those prompts are something you don't control. The real fix is a precise, robust 'contract' on the server side. This contract needs to be crystal clear. Your documentation should explicitly define how each tool works, understanding that the description and schema are the agent's sole source of truth. For validation errors, the contract must name the failing field so the agent can self-correct without human intervention. Retries need to be carefully designed, emphasizing idempotency to ensure actions aren't duplicated. As for destructive actions, they must be guarded only by what the contract explicitly flags. In essence, none of this is truly exotic. It’s the same level of rigor that a good OpenAPI specification already demands. The difference now is that you’re applying it with the assumption that the reader (the AI model) has perfect patience, absolutely no context outside the schema, and zero ability to ask a clarifying question. JSON Schema serves as the enforcement layer for this contract, and AI agents respect it far more reliably than they respect human prose. So, every single constraint you can express within your schema, make sure you express it. This is the key to success in this new era.
