Tool responses are serialized twice on the wire, inflating token cost for structured-content clients

[jakewan]

Context

Discovered while sizing the response budget for #74. When a tool returns typed structured output, the MCP SDK emits the result twice — once as structuredContent and once as a back-compat TextContent block (the spec's backward-compatibility suggestion for clients that don't read structuredContent).

Problem

Every tool response crosses the wire at roughly twice its necessary size. For a client that reads structuredContent (which the current consumers do), the TextContent copy is pure overhead: it inflates token cost on every call and doubles the pressure against the tool-result token cap that #74's size bound exists to respect — so the bound has to budget for the doubling and trims earlier than it otherwise would.

Evidence

The SDK sets StructuredContent and, when the handler returns no explicit Content, also copies the same JSON into a TextContent block (go-sdk v1.6.1, mcp/server.go). #74's size-bound default is set conservatively specifically to account for this ~2× wire payload.

Suggested approaches (options)

Suppressing the redundant copy (e.g. returning a non-nil Content so the SDK omits the back-compat block) roughly halves every response — but it should be decided on generic-user grounds, not the current sole-consumer set (per this project's design-fork-adjudication lens):

• Verify what target clients actually consume — does the client read structuredContent or the text block, and does the token cap count one copy or both? Suppression breaks any client that reads only the text block.
• Survey whether MCP clients broadly support structuredContent (the 2025-06-18 spec direction); if so, the back-compat copy is vestigial for all users and suppression is safe generically.

[jakewan]

main is now on go-sdk v1.7.0 (#123), and the doubling this issue describes survives it — the SDK still copies outJSON into a TextContent block when the handler returns no explicit Content.

One refinement to the suggested approach, new in v1.7.0:

if res.Content == nil {
    res.Content = []Content{&TextContent{Text: string(outJSON)}}
} else if !isObjectJSON(outJSON) {
    res.Content = append(res.Content, &TextContent{Text: string(outJSON)})
}

v1.6.1 had only the first branch. So returning a non-nil Content suppresses the copy only when the structured output marshals to a JSON object; for an array or primitive the SDK now appends the text block regardless. Overstory's facts are all objects, so the approach still works here — but its precondition is narrower than it was, and version-dependent.

[jakewan]

A live data point on how early the halved budget bites. A full project_summary of this repository, with 20 open issues and limit 25, came back size-bounded: finalBytes 19,685 against the default maxBytes of 20,000, with one recommendations candidate dropped. So the size bound is not only a large-repository safety valve; it fires on ordinary repositories today.

That has a correctness consequence beyond token cost. The size bound doesn't honor the recommendation reserve, which #164 tracks. Removing the duplicate copy wouldn't fix #164, but it would make the budget fire less often.