Reading an MCP tool¶
A Model Context Protocol server lists each tool with an
inputSchema and, optionally, an outputSchema. read_tool reads one entry into its two
contracts, so a call and its result can be checked, and two versions of a tool compared:
from valgebra_jsonschema import read_tool
def listing(units):
return {
"name": "get_weather",
"inputSchema": {
"type": "object",
"properties": {"location": {"type": "string"}, "units": {"enum": units}},
"required": ["location"],
},
"outputSchema": {
"type": "object",
"properties": {"reading": {"type": "number"}},
"required": ["reading"],
},
}
old = read_tool(listing(["celsius"]))
new = read_tool(listing(["celsius", "kelvin"]))
assert old.arguments.is_valid({"location": "Paris"})
assert not old.arguments.is_valid({"location": "Paris", "units": "kelvin"})
assert old.result.is_valid({"reading": 21.5})
# A new version replaces an old one where it takes every call the old one took,
# and returns only what the old one promised.
assert old.arguments.relation_to(new.arguments) == "subset"
assert new.result.relation_to(old.result) == "subset"
Dialects¶
The protocol states a schema's dialect, and each reads here as:
a document's $schema |
read as |
|---|---|
| absent | draft 2020-12, as the protocol states |
| draft 2020-12 | draft 2020-12 |
| draft 2019-09 | rewritten by upgrade: an array items, and $recursiveRef |
| draft-07, draft-06, draft-04 | rewritten by upgrade, as older drafts says |
| anything else | UnsupportedDialect, whose message says the dialect is not supported |
UnsupportedDialect is an Unsupported, so a caller refusing a schema it cannot read catches
both, and one answering the protocol's error can tell them apart. A document in another
dialect with no $schema is read as 2020-12: name its dialect with {"$schema": uri, **schema}.
What a tool's schema may hold¶
- Any 2020-12 keyword. The inventory lists what each
does here. A keyword that is refused raises
Unsupportednaming it, and is never skipped. formatis an annotation, as 2020-12 makes it, so it admits every value.read_tool(spec, assert_format=True)reads nine formats as assertions, and refuses any other (format on request).- No reference is fetched. A
$refoutside the document is refused, which is how the protocol's rule against dereferencing a network reference reads here. - Bounds hold what a document may cost. A document past
MAX_NESTINGis refused before it is walked, and valgebra refuses a set past the bounds it holds. inputSchemanames an object:type: "object", or a root that is a bare$refto one, as zod's named schemas are.outputSchemamay be any schema.
What a model vendor enforces¶
A tool author emits a subset of 2020-12 for a model to generate from, and which subset is the
vendor's. OpenAI's strict structured outputs ask additionalProperties: false and every property
required, and leave out allOf, not and if. Anthropic's strict tools leave out numeric and
length constraints and recursion. Gemini's responseSchema is an OpenAPI 3.0 subset, whose
nullable is outside the vocabularies, so here it is an annotation that asserts nothing. These
are the vendors' to change, so no test here holds them. Whichever subset a tool emits, a contract
checks the membership of the value returned.