SpanDetail output schema is serialised twice, 13% of the MCP tool surface

[Abhinash-Singh]

Requirement

The MCP tool surface is the fixed cost every agent session pays before fetching any
telemetry. Operators running smaller-context models need that surface to be as
small as it can be without losing information, so the budget goes to spans rather
than to schema boilerplate.

Problem

SpanDetail is serialised in full in two separate output schemas. MCP has no
shared-definitions mechanism (no $defs/$ref in the emitted schemas), so a type
used by more than one tool is repeated verbatim.

Measured against jaeger all-in-one at b3076cc with memory storage and
ai.mcp: {}, reading tools/list off the wire (compact JSON):

• 9 tools, 15,048 bytes of tool definitions
• Output schemas: 9,763 bytes — 64% of that
• Input schemas: 3,254 bytes (21%); descriptions: 1,378 bytes (9%)

The repeated definition is 1,799 bytes, appearing at:

• get_span_details.outputSchema.properties.spans.items
• get_trace_errors.outputSchema.properties.spans.items

with three further duplicated types nested inside it, already counted within that
1,799: events.items (317 B), links.items (306 B), status (250 B).

Separately, the 162-byte trace_id input schema is shared by get_critical_path
and get_trace_errors.

Recoverable total: 1,961 bytes, 13% of the tool surface.

Credit to @Animesh-Parashar, who first surfaced the SpanDetail duplication in
#9135. One refinement on the figure quoted there: 3,598 bytes is the combined size
of both copies, but one definition has to exist regardless, so deduplication
recovers one copy — 1,799 bytes, not 3,598. Worth pinning down before it becomes
the justification for a change, since it halves the payoff.

A methodology note for anyone re-measuring: comparing whole schemas for
byte-identity finds almost none of this. SpanDetail is nested inside two
different output schemas rather than repeated at top level, so the detection has to
recurse into subschemas.

Proposal

Options, roughly in increasing order of effort:

1. Do nothing, but document it. 13% is real but not dramatic, and it is a fixed
   cost rather than a per-call one. Response payloads are unbounded and currently
   ship twice (~2.2× overhead, see [Feature/🧑‍🎓 LFX] Evaluating and Optimizing the Jaeger AI Assistant: MCP Tools + Skills #9135), so they dominate the total budget. This
   may simply be the wrong thing to optimise first.
2. Emit $defs + $ref in the output schemas if the Go SDK's schema generator
   can be persuaded to, and if the models consuming these reliably resolve $ref.
   That second condition is the risk: a model that does not resolve refs sees a
   less useful schema, which would trade context bytes for accuracy — the wrong
   direction.
3. Narrow get_trace_errors' output. It returns the full SpanDetail per span;
   an error-focused tool may not need every field, in which case the duplication
   partly disappears as a side effect of a tighter contract.

I lean toward (1) or (3). (2) is the obvious fix but its benefit depends on model
behaviour we have not measured, and this is exactly the kind of change the
evaluation work in #9135 exists to decide empirically rather than by intuition.

Open questions

• Does the Go SDK's schema generation support $defs/$ref emission today?
• Is there a preference for keeping tool schemas fully self-contained, deliberately,
  so that no client needs ref resolution?
• Is output-schema size worth optimising at all given JSON_SCHEMA_FOR_FUNC_DECL
  gates whether these reach the model in the first place?

Happy to send a PR for whichever direction maintainers prefer, though I would
rather see the direction settled here first than guess.

[labmimors]

I would not make $ref the default yet, for a more basic reason than model behavior: this duplication is across two independent Tool.outputSchema documents. A local $defs is scoped to one schema, so putting $defs/SpanDetail in both tools still serializes the definition twice. Recovering the 1,799 bytes across tools therefore needs either a shared external URI/resolver or a client-side catalog packing/rehydration step; neither falls out of local $defs alone.

There is also an implementation detail at the measured revision: Jaeger pins go-sdk v1.6.1, whose typed AddTool path calls jsonschema.ForType with empty options and emits the inline schema by default (source). A manually supplied schema can contain $ref, but it still needs an explicit resolution/packaging contract to share a definition across tools.

My ordering would therefore be:

1. Inline as the compatibility control.
2. $ref as an experimental arm only after defining where the shared schema lives and who resolves it.
3. Narrow get_trace_errors as the first production candidate. It matches the tool’s error-focused contract and can reduce both the advertised schema and returned payload, provided the benchmark proves that removed fields are not required for diagnosis.

I would gate the three arms at two wire boundaries, not one:

Arm	Provider compatibility	Request bytes	Call correctness
Current inline	Baseline: every supported provider accepts the exact outbound schema	Record compact tools/list bytes and the final serialized provider request’s tool/function section	Baseline tool choice, argument validation, retry count, and trace-scenario oracle
Shared $ref	No provider rejection, silent keyword stripping, or unresolved reference after adapter serialization	Must reduce the final provider request, not merely the MCP response	No new ref/schema/argument failures; no regression on the frozen trace-solvable scenarios
Narrow contract	Same provider matrix as inline	Record both schema-request bytes and per-call result bytes	Same root-cause/evidence oracle; any omitted field needed by a scenario is a hard failure, with get_span_details retained for drill-down

I would run JSON_SCHEMA_FOR_FUNC_DECL both off and on. With it off, an output-schema change should show zero provider-request reduction; with it on, capture the actual outbound HTTP body after SDK serialization. That avoids treating an MCP-wire saving as a model-facing saving. Freeze trace fixtures, Skills/prompts, provider/model versions, seeds where available, and arm source digests before the run.

Disclosure: I maintain MCP Lens. Its component runner is only an example of the measurement/provenance shape—exact UTF-8 JSON bytes, pinned inputs, and a pre/post source-drift failure—not evidence that Jaeger will see the same savings (immutable runner).

[Abhinash-Singh]

@labmimors this is the correction the issue needed, and it invalidates option 2 as I
wrote it.

You are right that $defs is scoped to a single schema document. Two tools each
carrying $defs/SpanDetail serialise the definition twice — I described "emit
$defs + $ref" as if it were a deduplication mechanism, when within the current
one-document-per-tool shape it is only a local factoring and recovers nothing
across tools. Recovering the 1,799 bytes needs a shared location and a resolution
contract, which is a different and much larger change than I implied.

The go-sdk v1.6.1 detail is useful too: the typed AddTool path calling
jsonschema.ForType with empty options means inline is not merely the current
choice, it is the default that would have to be actively worked around.

Adopting your ordering, and revising my own lean:

1. Inline as the compatibility control.
2. $ref as an experimental arm only once the shared-schema location and
   resolver are defined — with provider acceptance of the outbound schema as a
   gate before call correctness is even measurable.
3. Narrow get_trace_errors as the first production candidate, since it cuts
   the advertised schema and the returned payload, and it is justifiable on
   contract grounds independent of any byte saving.

I had leaned toward "do nothing but document it" partly on the reasoning that this
is a fixed cost while response payloads are unbounded. That reasoning was wrong, and
@Priyanshu-byte-coder's correction in #9135 is why: the static surface is re-sent on
every turn, so 1,799 bytes is ~450 tokens paid per turn, ~4,500 across a ten-turn
trajectory. Still small — around 5% of a realistic total — so the conclusion
survives, but the reason does not. It should be deprioritised because it is small,
not because it is fixed.

Which makes (3) the more interesting item regardless of the duplication: narrowing
the error tool touches the per-turn schema cost and the per-response payload cost at
once, and unlike (2) it does not depend on unmeasured client behaviour.

One thing your two-boundary table implies that I want to make explicit, since it
affects whether (2) is ever testable: provider compatibility is a hard gate, not a
metric. If any supported provider rejects or mis-handles a $ref-bearing schema,
the arm produces no comparable trajectory at all rather than a worse one — so that
check has to run before the benchmark, not inside it.