A tool schema is an assertion

A tool schema offers relief from ambiguity. Instead of asking a model to improvise an API request, a server supplies a name, a description, and a JSON Schema for the arguments. The model fills known fields. The client validates them. The server returns a result that may have its own declared structure. The exchange becomes legible to software.

The current Model Context Protocol tool specification supports input and output schemas, structured content, resource links, and annotations. These features make integrations safer and easier to test. They also create a temptation to treat conformance as truth.

A schema proves something narrow: the value has the declared shape. It does not prove that the tool description is accurate, that a field means what its label suggests, that the server will honor an annotation, or that the operation's effects stop where the response says they stop. A valid request can be misleading, excessive, or aimed at the wrong object. A valid response can be stale, incomplete, or produced by an undisclosed downstream system.

Shape is not semantics

Suppose a tool exposes a field called customer_id. The schema can require a string. It cannot tell the client whether the value refers to a billing account, a natural person, a tenant, or an internal record that combines all three. Those distinctions may determine what data may be read and what actions may follow.

Descriptions fill some of the gap, but descriptions are assertions made by the server. MCP explicitly warns clients to treat tool annotations as untrusted unless they come from trusted servers. An annotation that calls a tool read-only or non-destructive is useful only when the client has reason to trust the issuer and when the implementation still matches the claim.

Even an honest schema ages. A backend adds a side effect. A field begins accepting a second identifier type. A tool that once returned a complete object starts returning a projection. The schema version may remain unchanged because every JSON document still validates. Behavioral drift can pass structural validation indefinitely.

A schema can certify the grammar of a call while remaining silent about the truth of its sentence.

This is not an argument against schemas. It is an argument for assigning them the correct evidentiary role. They constrain syntax, enable validation, and support compatibility. They should travel with a record of the tool call because they show what the client was told to expect. They should not substitute for testing the operation against the real environment.

Structured output can still carry untrusted content

The same issue appears on return. Structured output is easier to parse than prose, but a typed field can carry an untrusted instruction, a poisoned resource link, or a confident value with weak provenance. A client that lowers its guard because content arrived in a validated object has confused serialization with trust.

The MCP specification allows tools to return embedded resources and links that may not appear in ordinary resource listings. This is powerful: a tool can point to exactly the evidence relevant to its result. It also means the result can introduce a new retrieval target during execution. The client must decide whether the URI scheme, host, path, and content are appropriate before following it.

JSON Schema itself is now a more explicit compatibility surface in MCP; the November 2025 revision establishes JSON Schema 2020-12 as the default dialect. That helps implementations agree on validation. It does not make two independently named fields equivalent, or ensure that an older client understands a new semantic constraint.

A robust client should separate four decisions: whether the message validates, whether the issuer is trusted, whether the operation is authorized, and whether the result is fit for the next use. These decisions can share evidence, but none can safely stand in for the others.

Version the promise around the schema

Tool evidence should therefore include more than the tool name and arguments. It should preserve the server identity, protocol revision, tool definition or digest, schema dialect, relevant annotations, normalized arguments, returned content type, and observed effect. If the client overrode an annotation or accepted a schema mismatch, that exception belongs in the same account.

Compatibility failures should remain visible rather than being repaired into silence. If a client drops an unknown field, coerces a number into text, or falls back from structured content to a serialized text block, the exchange may still succeed. The evidence should show the negotiation and coercion that occurred. A later implementation may interpret the same response differently, and “the schema validated” will not explain why.

Tool names deserve similar caution. A familiar verb can conceal a different object or effect across servers. Namespace, server identity, and definition digest should accompany the name so that “archive,” “send,” or “approve” cannot be mistaken for a globally stable operation.

Testing should probe meaning as well as format. Does a read-only tool actually leave state unchanged? Does an identifier resolve within the caller's tenant? Does an output marked complete omit records under pagination or policy filtering? Does a resource link cross into a different trust domain? These are contract tests for the promise surrounding the schema.

The result is a more honest form of interoperability. Systems can rely on common structural conventions without pretending that a common envelope creates common trust. A schema becomes one check in a chain of checks, which is exactly where it is strongest.

Well-formed calls are necessary. Consequential systems also need well-founded calls: operations whose meaning, authority, issuer, and effects can be defended after the parser has said yes.

— Dispatches · Summit Cognitive