Skip to content

outputSchema on 68 of 78 tools, generated by the type checker - #286

Merged
lana-20 merged 1 commit into
mainfrom
output-schema
Oct 26, 2026
Merged

lana-20 merged 1 commit into
mainfrom
output-schema

Conversation

@lana-20

@lana-20 lana-20 commented Oct 26, 2026

Copy link
Copy Markdown
Contributor

MCP tools may declare outputSchema: the shape of their structuredContent. Clients increasingly validate results against it and may refuse one that doesn't match, so a wrong schema is worse than none.

How it's made

internal/apisurface/outputschema type-checks internal/agent with go/types (standard library only):

  • It reads dispatch for each tool's handler.
  • It follows every return through Result(text, v) to v's static type, and through the Handlers methods it delegates to.
  • It writes a schema only when a tool always succeeds with one concrete type. For each of the other ten tools it prints why: text only, a result built elsewhere, or two possible types. For example, app_screenshot answers with an image and app_logs with one of two shapes.

The schema follows encoding/json: field names from JSON tags; omitempty fields optional and the rest required; pointers, slices, maps and interfaces nullable; a custom MarshalJSON type accepts anything. Extra keys are allowed, because reportHandled and reportIdle add notes to results.

make api runs it into internal/agent/outputschema_gen.go, and api-check (in make ci) fails when that file is stale.

Checked

  • TestEveryOutputSchemaHoldsItsTypesValues: every schema accepts its type's empty value (nil slices and pointers) and a filled one (every field set, every slice holding one element). Corrupting one schema's integer type fails it.
  • TestTheValidatorRefuses: the test's validator rejects a missing required field and a wrong type.
  • Live on the Android 15 emulator: mobium mcp results from 29 tool calls validated against the schemas its own tools/list served, using Python's jsonschema 4.26, an independent validator. 29 valid, 0 invalid. Not checked: three platform refusals, and app_find, which has no schema.

Docs: the MCP guide's section 3 explains the schemas. It also fixes the read-only count there: 22 tools, not 19. make ci green.

A client may validate a result against its tool's outputSchema, so a
wrong one is worse than none. internal/apisurface/outputschema reads
dispatch for each tool's handler, follows every return through Result and
the handlers it delegates to, and writes a schema only for a tool that
always answers with one concrete type, saying why for the other ten. The
schema follows encoding/json. make api runs it; api-check fails when it is
stale. A test holds every schema to empty and filled values of its type,
and fails on a corrupted one; live results from 29 tool calls on the
Android 15 emulator validated with jsonschema, none invalid.
@lana-20
lana-20 merged commit aa10af3 into main Oct 26, 2026
5 checks passed
@lana-20
lana-20 deleted the output-schema branch October 26, 2026 23:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant