[Architecture]: Publish generation-oriented capability schemas instead of stripping descriptions, examples, defaults, and discriminators

[morluto]

Priority

P1/P2 agent-contract issue: exact inspection publishes a schema that is sufficient for validation but intentionally removes much of the information an agent or host needs to construct the first valid call.

Area

math.find CONTRACT/FULL views, JSON Schema projection, selected capability execution, invocation examples, nested/union request construction.

Summary

Jacobian’s exact CONTRACT view is described as validation-equivalent. To keep it compact, _compact_json_schema() recursively removes annotation and routing fields including:

title
description
examples
default
discriminator
readOnly
writeOnly

The remaining constraints can reject an invalid payload, but they may not explain:

• what a nested field means mathematically;
• which oneOf/union branch corresponds to the intended representation;
• whether omission is semantically equivalent to a documented default;
• the coordinate/order/canonicalization convention expected by a field;
• how sibling objects such as input and candidate relate;
• which value is an identifier, expression, artifact reference, or literal mathematical object.

This optimizes for a validator rather than for the model/host that must generate a valid request. Recent PRs repeatedly compensate by adding descriptor prose or one top-level invocation example for a specific failure. Those fixes are valuable, but the underlying schema projection remains semantically thin.

Audit baseline: current main, particularly:

• src/jacobian/adapters/mcp/projections.py
• src/jacobian/adapters/mcp/tools.py
• src/jacobian/contracts/capabilities.py
• docs/reference/tools.md

Current behavior

CONTRACT projection strips construction annotations

def _compact_json_schema(schema):
    dropped_annotations = {
        "title",
        "description",
        "examples",
        "default",
        "discriminator",
        "readOnly",
        "writeOnly",
    }
    ...

math.find(capability_id=..., view="CONTRACT") exposes this compact schema and validates examples against the full underlying schema.

FULL is not an ergonomic construction fallback

FULL adds the complete output schema, provider configuration, licenses, features, and audit metadata. An agent that needs one missing field description should not have to load the largest audit projection. Issue #932 already records that complete FULL descriptors can exceed arbitrary inline byte limits.

Whole-payload examples cannot explain every branch

Descriptor-owned invocation examples are helpful but optional and bounded. Discovery returns at most one example per card. A single payload cannot explain every valid representation, optional field, nested object, or discriminated branch.

PR #929 and issue #941 show the common input/candidate nesting failure. PR #925 adds sparse-polynomial canonicalization prose and a specific example after repeated malformed calls. These are symptoms of a construction contract that exists outside the schema the host actually sees.

Standards context

JSON Schema explicitly separates validation keywords from annotation keywords. description, default, and examples do not change acceptance, but they are intended to make schemas self-documenting and usable by documentation, form, and generation tooling:

https://json-schema.org/understanding-json-schema/reference/annotations

MCP tool definitions use JSON Schema not only for server validation but also to guide clients and language models in constructing and understanding tool inputs:

https://modelcontextprotocol.io/specification/2025-11-25/server/tools

“Validation-equivalent” is therefore necessary but not sufficient for an agent-facing tool contract.

Root cause

The architecture treats one projection as though it can serve three different consumers:

1. server-side validation;
2. host-side call generation/autocomplete;
3. compact model context.

Those consumers need the same constraints but different presentation. Removing every annotation minimizes bytes, while FULL maximizes audit completeness. There is no bounded middle representation optimized for call construction.

Proposed architecture

1. Distinguish canonical, validation, and generation projections

Keep one authoritative domain-owned schema contract, then expose explicit projections such as:

canonical_schema     complete contract identity and annotations
validation_schema    exact constraints used by the validator
construction_schema  bounded constraints + agent/host-relevant annotations

Names may differ. The projections must be derived from one source rather than maintained independently.

2. Preserve bounded semantic annotations in CONTRACT

CONTRACT should retain or separately project:

• concise field descriptions;
• validated defaults and examples;
• union/discriminator routing metadata;
• deprecation/read-only/write-only facts where relevant;
• coordinate/order/domain/canonicalization notes that affect correct construction;
• exact JSON pointers linking annotations to fields.

Apply explicit per-description, per-example, branch, and total byte limits. An omitted annotation needs a deterministic recovery path to the canonical schema resource rather than silent deletion.

3. Treat discriminators as generation-critical

Even where a JSON Schema discriminator is not required for validation semantics, it tells a host/model which property selects a branch. Preserve it in the construction schema and test oneOf/anyOf requests through supported clients.

4. Validate annotations at registration

• examples must validate against the owning branch/schema;
• defaults must validate and must not imply server-side filling unless the runtime actually applies that semantic default;
• descriptions must be bounded and non-contradictory with required/enum/range constraints;
• field annotations should be domain-owned, not inferred from names by the MCP adapter.

5. Feed schema-bound execution

The selected execution path in #1031 should give the host the construction-oriented schema, while authoritative runtime validation continues to use the canonical validation contract. Host-side generation remains an ergonomic layer, not a security boundary.

6. Provide canonical resources for large contracts

If the complete annotated schema is too large inline, return a compact typed construction projection plus a native ResourceLink/URI to the exact canonical schema. Do not force the agent to choose FULL merely to recover one field description.

Acceptance criteria

• CONTRACT exposes a bounded construction-oriented schema with field descriptions, branch routing, and validated examples/default semantics where useful.
• The canonical validation schema and construction projection are generated from one authoritative contract and carry related digests.
• oneOf/anyOf/discriminated requests can be constructed without guessing a branch selector.
• Common inline replay schemas structurally and descriptively show input and candidate as siblings.
• Sparse polynomial, labelled matrix, artifact-reference, and formal-proposition fixtures preserve their interpretation/canonicalization annotations.
• Annotation truncation is explicit and recoverable; it never silently changes validation constraints.
• Registration rejects invalid examples/defaults and bounds annotation sizes.
• [Superseded]: Improve concrete examples/contracts; do not add prepared-call tokens or dynamic selected tools #1031-selected tools use the construction schema while runtime validation remains authoritative.
• Model-in-the-loop tests report valid-first-call rate, retries, and context cost against both the current compact schema and the annotated construction schema.

Related work

• [Superseded]: Improve concrete examples/contracts; do not add prepared-call tokens or dynamic selected tools #1031 owns the host-consumable schema-bound selected execution path.
• [Bug]: Encode math.find browse, search, and inspect argument modes in its input schema #952 owns browse/search/inspect modes in the top-level math.find schema.
• Expose schema-valid invocation examples for exact replay verifiers #941 and PR Clarify inline verifier invocation envelopes #929 own immediate verifier invocation examples.
• PR Clarify sparse Jacobian syzygy inputs #925 is a concrete sparse-input presentation regression.
• mcp: define semantic pagination and transport limits for math.find #932 owns pagination and large exact-inspection transport.
• [Bug]: Preserve field-level, machine-actionable diagnostics for math.find and tool-envelope validation errors #1071 owns actionable validation errors after construction still fails.

Non-goals

• Weakening or replacing runtime validation.
• Returning every provider/audit field in the construction projection.
• Treating examples or descriptions as mathematical evidence.
• Having the MCP adapter guess domain semantics from property names.
• Filling JSON Schema default values unless the capability’s runtime contract explicitly defines that behavior.

[morluto]

Revalidated on current main. The old SUMMARY/CONTRACT/FULL descriptor projections and _compact_json_schema() annotation-stripping path are gone; repository search no longer finds those views. Current direct MathTool declarations carry their concrete request/result models and the MCP surface derives schemas from those authoritative types. Closing this projection-specific issue as completed. Any current example/schema ergonomics defect should cite the exact MathTool declaration or MCP field.