[GH-ISSUE #264] Reduce MCP discovery payload and align text with structured results #154

New issue

Closed

opened 2026-10-15 18:21:45 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-15 18:21:45 +00:00

Owner

Originally created by @morluto on GitHub (Jul 16, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/264

Problem

REA's exact MCP output schemas are valuable, but the current 84-tool discovery response is approximately 1 MB and repeats large Evidence/application/capture structures across many tools. Session tools also return text that is not the serialization of their advertised structuredContent shape.

This makes discovery expensive for hosts and models, obscures the input contract behind large output declarations, and weakens backwards-compatible result equivalence.

Measured current surface

From the current main tools/list response:

Component	Serialized size
Complete response	1,026,448 bytes
Input schemas	271,289 bytes
Output schemas	720,668 bytes
Tool descriptions	19,220 bytes

Largest individual definitions include:

compare_web_captures: about 64 KB;
compare_application_versions: about 45 KB;
reconcile_javascript_runtime: about 40 KB;
trace_application_feature: about 38 KB;
compare_bundles: about 34 KB;
compare_process_captures: about 32 KB.

The existing strengths must be preserved:

all 84 tools publish output schemas;
success values are validated before return;
output roots are closed;
contract tests reject unconstrained output holes;
successful calls return structuredContent.

Text/structured mismatch

toCallToolResult wraps session structured results as:

{ "result": "...value..." }

but serializes only the unwrapped value into text. MCP recommends returning the serialized structured object in text for backwards compatibility. Consumers using text and consumers using structuredContent therefore observe different JSON shapes.

Design direction

Reduce repeated discovery weight without replacing exact contracts with generic unknown results:

Prefer session-owned Evidence IDs or MCP resource links where a complete Evidence record is already available by identity.
Avoid embedding repeated full Evidence envelopes in comparison inputs when bounded IDs/resources can provide the same authenticated record.
Keep exact normalized result schemas, authority, confidence, truncation, and unknown semantics.
Reuse $defs within schemas and avoid mechanically duplicating branches where JSON Schema can express a reference.
Evaluate capability-aware tool exposure and tools/list_changed through #101 rather than assuming every client needs every provider-specific schema at once.
Add a deterministic discovery-size budget and per-tool regression report.
Add descriptions strategically to semantic output fields without multiplying boilerplate across every repeated Evidence leaf.

Tool-list pagination may help transport cost, but should be used only if target hosts reliably consume every page; it is not a substitute for reducing duplicated schemas.

Acceptance criteria

Session text content serializes the same candidate object returned in structuredContent.
Tests compare parsed text JSON with structuredContent for session and non-session successes.
Every successful structuredContent value continues to validate against its advertised output schema.
No exact schema is replaced by an unrestricted generic result.
Repeated Evidence inputs use IDs/resources where session ownership makes that safe and behaviorally equivalent.
Caller-visible authority, confidence, limitation, truncation, pagination, and residual-unknown fields remain explicit.
A deterministic test reports total tools/list, aggregate input/output schema, and largest-tool sizes.
CI fails on an agreed material schema-size regression.
The packed and published server expose the same catalog digest and schema-size report.
Any dynamic catalog reduction follows #101 and emits truthful list-change notifications.

Non-goals

Dropping output schemas to save bytes.
Hiding unsupported or unknown behavior.
Assuming cross-tool JSON references are portable without host verification.
Sacrificing Evidence v2 integrity or CLI/MCP semantic parity.

Originally created by @morluto on GitHub (Jul 16, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/264 ## Problem REA's exact MCP output schemas are valuable, but the current 84-tool discovery response is approximately 1 MB and repeats large Evidence/application/capture structures across many tools. Session tools also return text that is not the serialization of their advertised `structuredContent` shape. This makes discovery expensive for hosts and models, obscures the input contract behind large output declarations, and weakens backwards-compatible result equivalence. ## Measured current surface From the current `main` `tools/list` response: | Component | Serialized size | | --- | ---: | | Complete response | 1,026,448 bytes | | Input schemas | 271,289 bytes | | Output schemas | 720,668 bytes | | Tool descriptions | 19,220 bytes | Largest individual definitions include: - `compare_web_captures`: about 64 KB; - `compare_application_versions`: about 45 KB; - `reconcile_javascript_runtime`: about 40 KB; - `trace_application_feature`: about 38 KB; - `compare_bundles`: about 34 KB; - `compare_process_captures`: about 32 KB. The existing strengths must be preserved: - all 84 tools publish output schemas; - success values are validated before return; - output roots are closed; - contract tests reject unconstrained output holes; - successful calls return `structuredContent`. ## Text/structured mismatch `toCallToolResult` wraps session structured results as: ```json { "result": "...value..." } ``` but serializes only the unwrapped value into text. MCP recommends returning the serialized structured object in text for backwards compatibility. Consumers using text and consumers using `structuredContent` therefore observe different JSON shapes. ## Design direction Reduce repeated discovery weight without replacing exact contracts with generic `unknown` results: 1. Prefer session-owned Evidence IDs or MCP resource links where a complete Evidence record is already available by identity. 2. Avoid embedding repeated full Evidence envelopes in comparison inputs when bounded IDs/resources can provide the same authenticated record. 3. Keep exact normalized result schemas, authority, confidence, truncation, and unknown semantics. 4. Reuse `$defs` within schemas and avoid mechanically duplicating branches where JSON Schema can express a reference. 5. Evaluate capability-aware tool exposure and `tools/list_changed` through #101 rather than assuming every client needs every provider-specific schema at once. 6. Add a deterministic discovery-size budget and per-tool regression report. 7. Add descriptions strategically to semantic output fields without multiplying boilerplate across every repeated Evidence leaf. Tool-list pagination may help transport cost, but should be used only if target hosts reliably consume every page; it is not a substitute for reducing duplicated schemas. ## Acceptance criteria - [ ] Session text content serializes the same candidate object returned in `structuredContent`. - [ ] Tests compare parsed text JSON with `structuredContent` for session and non-session successes. - [ ] Every successful `structuredContent` value continues to validate against its advertised output schema. - [ ] No exact schema is replaced by an unrestricted generic result. - [ ] Repeated Evidence inputs use IDs/resources where session ownership makes that safe and behaviorally equivalent. - [ ] Caller-visible authority, confidence, limitation, truncation, pagination, and residual-unknown fields remain explicit. - [ ] A deterministic test reports total `tools/list`, aggregate input/output schema, and largest-tool sizes. - [ ] CI fails on an agreed material schema-size regression. - [ ] The packed and published server expose the same catalog digest and schema-size report. - [ ] Any dynamic catalog reduction follows #101 and emits truthful list-change notifications. ## Non-goals - Dropping output schemas to save bytes. - Hiding unsupported or unknown behavior. - Assuming cross-tool JSON references are portable without host verification. - Sacrificing Evidence v2 integrity or CLI/MCP semantic parity.

bsakaguchi

2026-10-15 18:21:45 +00:00

closed this issue
added the
area: mcp

enhancement
labels

bsakaguchi commented

2026-10-15 18:21:46 +00:00

Author

Owner

@morluto commented on GitHub (Jul 16, 2026):

REA 2.0 compact-contract slice: comparisons now resolve session-owned Evidence IDs (bundle comparison uses two approved bounded files), structured text is exactly JSON.stringify(structuredContent), compact Evidence results return result/evidence_id/evidence_uri plus resource links, and a generated beta.4 report enforces 512 KiB tools/list and 64 KiB/tool. Current measured list: 518457 bytes; largest tool: 33869 bytes.

@morluto commented on GitHub (Jul 16, 2026): REA 2.0 compact-contract slice: comparisons now resolve session-owned Evidence IDs (bundle comparison uses two approved bounded files), structured text is exactly JSON.stringify(structuredContent), compact Evidence results return result/evidence_id/evidence_uri plus resource links, and a generated beta.4 report enforces 512 KiB tools/list and 64 KiB/tool. Current measured list: 518457 bytes; largest tool: 33869 bytes.

bsakaguchi referenced this issue

2026-10-16 21:11:48 +00:00

[PR #203] [MERGED] fix: resolve triaged correctness issues #1854

bsakaguchi added

enhancement

and removed

enhancement

labels

2026-10-31 00:28:46 +00:00