[Superseded]: Improve concrete examples/contracts; do not add prepared-call tokens or dynamic selected tools

[morluto]

Disposition

Closed as not planned. The original ergonomics diagnosis remains useful, but the proposed schema-bound execution mechanisms would introduce another stateful handoff protocol.

The issue identified a real problem: after math.find, an agent must place a capability-specific nested request into generic math.run arguments, and weak models can choose the wrong wrapper level.

The proposed alternatives—per-session dynamically materialized tools, prepared invocation tokens bound to catalog/policy/provider identities, stale-contract recovery, or selected-set discriminated unions—would add temporary tool lifecycle, contract-token state, version binding, host adapters, and another validation path.

Simpler endpoint

Keep the fixed math.find / math.run surface and make each selected operation easy to call through ordinary static data:

• compact search card;
• exact concrete request schema/model on inspection;
• one valid copyable invocation example with the complete math.run wrapper;
• precise invalid-input diagnostics from the same concrete parser;
• direct operation ID and stable field names;
• no duplicate generic input/candidate envelopes where a concrete checker request can be simpler.

Evaluate whether those concrete contract/example improvements solve the observed #929/#941 failures before adding any host-level mechanism.

If a future MCP SDK provides a standard stateless selected-schema mechanism, evaluate that concrete feature separately. Do not implement a private token/tool-materialization protocol in Jacobian.

Do not introduce

• per-session dynamic selected tools;
• tools/list_changed lifecycle for operation selection;
• prepared invocation/contract tokens;
• catalog/policy/provider generation binding in handles;
• selected-set oneOf schema compilers;
• a temporary validator/tool registry;
• another compatibility path beside ordinary math.run;
• stale-handle recovery state machines.

Canonical owners

• [Architecture][Deletion]: Keep package-owned kernel declarations; delete built-in installation and mutable catalog #1466 — compact package-owned discovery/inspection.
• [Architecture][Deletion]: Delete SchemaRegistry; use each operation’s concrete model/parser as the authority #1477/[Architecture][Deletion]: Parse each selected request once; remove JSON repair and internal revalidation #1467 — concrete model/schema and parse-once validation.
• [Architecture][Deletion]: Remove custom MCP validation/projection where MCP SDK 2.0 already owns it #1494 — use MCP SDK directly, without private projection/tool frameworks.
• [Feature]: Make capability contracts easier for agents to discover and compose #28 and model-in-the-loop tests — measure whether concrete examples/contracts suffice.

[morluto]

Recommended staged design

The strongest root-cause statement is:

math.find returns a type as data
math.run accepts an untyped object as an argument

The runtime eventually validates the request correctly, but the capability-specific type has already been erased at the host call-generation boundary. Invocation examples reduce guessing; they do not remove this type-erasure boundary.

Stage 1: prepared invocation contract

A practical first implementation can avoid depending immediately on dynamic tools/list_changed support. Exact inspection should optionally return a bounded prepared invocation object such as:

{
  "prepared_invocation_version":"1",
  "canonical_tool":"math.run",
  "capability_id":"matrix.determinant.compute",
  "capability_version":"...",
  "mode":"EXPLORE",
  "input_schema_digest":"sha256:...",
  "catalog_digest":"sha256:...",
  "policy_digest":"sha256:...",
  "provider_digest":"sha256:...",
  "payload_schema":{},
  "envelope_schema":{},
  "invocation_token":"opaque-bounded-token"
}

The token does not authorize execution. It binds the selected contract identity so math.run can reject stale or mismatched prepared calls and return one typed re-inspection path.

A host adapter can consume this object to install a temporary validator or generate a capability-specific local binding. Hosts without that support retain generic math.run as a compatibility path.

Stage 2: bounded selected-tool materialization

Where the host supports dynamic tools, materialize only the small selected set, not the full portfolio. The selected tool should inherit from the authoritative descriptor:

• exact input schema;
• capability output schema/projection;
• canonical capability ID and version;
• effect annotations from [Design]: Split mutating controls from pure math.run so MCP annotations are truthful #1034;
• provider/policy availability;
• tenant and cancellation behavior.

A temporary host symbol must still normalize to canonical math.run plus the capability ID in telemetry.

Required failure semantics

Reject before adapter execution when:

• the wrapper level is wrong;
• input and candidate are nested incorrectly;
• the capability version or schema digest is stale;
• policy or provider identity changed;
• the prepared token belongs to another tenant/session;
• the selected mode is no longer supported.

The response should contain exactly one bounded, machine-actionable next step back to exact inspection. Do not return the complete catalog.

Evaluation gate

Use the same frozen tasks under three arms:

1. generic math.run plus contract text;
2. generic math.run plus invocation example;
3. schema-bound selected execution.

Measure:

• valid first execution call;
• pre-dispatch versus post-dispatch rejection;
• retries and repeated discovery;
• discovery-to-execution continuation;
• manual fallback;
• final and intermediate mathematical correctness;
• model-visible bytes, prompt tokens, and elapsed time.

The #929 and #941 verifier cases should be mandatory regressions. #1029 is a prerequisite: the prepared contract is useful only when every packaged surface preserves the canonical schema and identity.

[morluto]

2026-07-28 protocol constraint on the selected-tool design

The final MCP 2026-07-28 lifecycle changes the viability of candidate A in this issue.

The latest tools contract says the tool list may vary by request authorization, but must not vary per connection or as a side effect of earlier requests on that connection. Protocol-level sessions are removed; cross-call state is carried through explicit server-minted handles passed as normal tool arguments.

References:

• https://modelcontextprotocol.io/specification/draft/server/tools
• https://blog.modelcontextprotocol.io/posts/2026-07-28/
• migration owner: [Compatibility]: Migrate remote MCP and doctor to the final 2026-07-28 stateless protocol lifecycle #1076

Therefore a connection/session-local flow such as:

math.find exact inspection
    -> mutate only this connection's tools/list
    -> expose temporary selected capability tool

should not be the preferred final design.

The prepared-invocation approach already described here is a better protocol fit:

stable math.find
    -> server-minted prepared contract handle
    -> stable math.run (or another stable executor)
       with expected capability contract digest + handle

The handle should be:

• explicit in ordinary tool arguments;
• bounded to capability ID/version/contract digest ([Architecture]: Content-address capability contracts and enforce schema/version compatibility #1073);
• bound to policy/catalog/provider identity as required;
• tenant/auth scoped;
• verifiable on any stateless server instance or backed by appropriate shared durable state;
• non-authorizing with respect to checker authority and assurance;
• rejected with one typed re-inspection path when stale or mismatched.

A capability-specific tool list can still be considered only when it is deterministic for the current request authorization and not produced as connection-local mutable state. Cross-host evaluation must include the final 2026-07-28 stateless HTTP lane, not only an in-process or 2025 session-based client.