Why Tool Descriptions Are the Real API Contract in MCP Servers

A developer building a Model Context Protocol (MCP) server discovered that prose descriptions — not code or schemas — function as the true API contract, determining whether an AI agent selects and uses a tool correctly. Across a small three-tool sample maintained for just one week, the same tool description drifted between two files, with minor but meaningful wording differences emerging within days. The author warns that at scale — fifty tools, multiple teams, a year of changes — such description drift could cause an MCP gateway to describe backend behavior that no longer matches its actual implementation. Unlike REST APIs, which rely on routes, status codes, and diffable OpenAPI documents as a ground-truth contract, MCP servers have no such fallback, making accurate prose the sole interface. The piece concludes that the highest-value content in any tool description is provenance — explaining where parameter values must come from — since this is information a JSON schema alone cannot convey and its absence can cause agents to hallucinate identifiers.