Null Is Not Zero: What an MCP Tool Description Has to Carry
A REST API's documentation is read by a developer once. An MCP tool description is the one piece of text a model reads on every single call, which makes it where you stop an agent misreporting your numbers. It is also prose, so it goes stale like prose. AddressIntel reads building permits and parcel records across the SF Peninsula and scores what could be built on a given lot. It already had a…
The MCP tool description is crucial because it is read by a model on every single call, ensuring the agent does not misrepresent numbers. It is prose that becomes outdated like any other writing. The tool description is not documentation; it is the contract, enforced by nothing. This is particularly important for this data, as it can confidently be wrong.
A null ROI is not zero, a score that ranks candidates is not a return, and negative numbers are usually correct. Any mistake in this description could lead to inventing a deal that does not exist. The description keeps each tool's validation schema and its advertised JSON Schema side by side in one object. It is crucial to specify the shape of the tool and the input it expects.
Two decisions in the transport layer are essential: handling an unset API key and error shaping. An unset key defaults to "demo," which the API recognizes as a public tier with limited requests and rows. Error shape is vital because a readable error in the failure envelope helps the agent determine how to proceed. The descriptions are where the guardrails live.
For example, the list_market_signals tool has a description ending with instructions on interpreting null values as unmodelable, with an unmodelable reason. This is an instruction to the model, not documentation. The purpose of these instructions is to prevent agents from incorrectly summarizing data. The null values in the data are not due to jurisdictional issues but rather indicate that no curated allowable floor area governs a single-family rebuild on that parcel.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
