Six tools exceed the MCP response cap on a default no-argument call, with no parameter available to bound the payload #256

New issue

Closed

opened 2026-08-13 17:07:48 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-13 17:07:48 +00:00

Member

Summary

Six tools cannot be called successfully over MCP at all. Invoked with no arguments against the default server they return 60–220 KB and are truncated by the client response cap. Most expose no parameter that would bound the result, so there is no caller-side workaround.

In every case the summary layer the caller actually wants is small; an unbounded detail array crowds it out.

Evidence

Measured against eco.coilysiren.me:3001, all no-argument calls:

tool	response	dominant key	share	bounding param?
`get_species` (name="Wheat")	220,134	`population` 219,432 B	99.7%	none
`price_recipe`	197,311	recipe graph index	99%	see #254
`get_trades`	187,259	`trades` 174,990 B (528 rows)	93%	none
`get_stores`	170,921	`stores` 90,789 + `traders` 79,011	99%	none
`get_currency`	145,598	`currencies` 70,575 + `personal` 70,030	97%	`currency` — but see below
`get_crafting_atlas`	70,135	`flows` 47,863 (1,187 rows)	68%	none
`get_civics`	60,084	`recentDemographics` 40,385	67%	none

`get_species` — the documented mitigation targets the wrong field

The include_image description says it is off by default because "the image runs to ~285 KB and will exceed an MCP client's response cap on its own." With include_image at its default false and photoDataUri: null, the response is still 220 KB — because population alone is 219,432 bytes. The image was never the problem. Everything else in the payload (taxonomy, wikiExtract, photoUrl, attribution) totals 412 bytes.

`get_currency` — the only filter path leads to a dead end

currency does shrink the response, by emptying currencies / personal / minted. But on this server no currency resolves to a name (see the separate eco-app#58-related issue), so:

get_currency(currency="Gold") → notFound: true
get_currency(currency="ZzzNotARealCurrency") → notFound: true, byte-identical response

suggestions returns raw numeric ids (["2533707", "2967954", "131058", ...]). So the unfiltered call is over cap and every filtered call is notFound. There is no input that yields per-currency detail.

Expected

A limit / top parameter on the unbounded arrays (trades, stores, traders, flows, recentDemographics, recentSettlements, population, currencies, personal), defaulting to a slice that keeps a no-argument call inside the cap — the pattern get_progression already uses well with include_timelines: false + citizen, and that get_world already uses with its top-N lists.

get_progression is the model to copy: it returns a rich summary by default, keeps full timelines behind an opt-in flag, and warns "citizens truncated to busiest 80 of 165 (trends + leaderboards cover all)". That call succeeds comfortably.

Repro

mcp__eco__get_civics()
mcp__eco__get_trades()
mcp__eco__get_stores()
mcp__eco__get_crafting_atlas()
mcp__eco__get_currency()
mcp__eco__get_species(name="Wheat")

Found during a QA sweep of all 25 Eco MCP tools. 8 of 25 are unusable over MCP for this reason (these six plus get_recipes / price_recipe, tracked in #254).

## Summary Six tools cannot be called successfully over MCP at all. Invoked with **no arguments** against the default server they return 60–220 KB and are truncated by the client response cap. Most expose no parameter that would bound the result, so there is no caller-side workaround. In every case the summary layer the caller actually wants is small; an unbounded detail array crowds it out. ## Evidence Measured against `eco.coilysiren.me:3001`, all no-argument calls: | tool | response | dominant key | share | bounding param? | |---|---:|---|---:|---| | `get_species` (name="Wheat") | 220,134 | `population` 219,432 B | 99.7% | none | | `price_recipe` | 197,311 | recipe graph index | 99% | see #254 | | `get_trades` | 187,259 | `trades` 174,990 B (528 rows) | 93% | none | | `get_stores` | 170,921 | `stores` 90,789 + `traders` 79,011 | 99% | none | | `get_currency` | 145,598 | `currencies` 70,575 + `personal` 70,030 | 97% | `currency` — but see below | | `get_crafting_atlas` | 70,135 | `flows` 47,863 (1,187 rows) | 68% | none | | `get_civics` | 60,084 | `recentDemographics` 40,385 | 67% | none | ### `get_species` — the documented mitigation targets the wrong field The `include_image` description says it is off by default because "the image runs to ~285 KB and will exceed an MCP client's response cap on its own." With `include_image` at its default `false` and `photoDataUri: null`, the response is **still 220 KB** — because `population` alone is 219,432 bytes. The image was never the problem. Everything else in the payload (taxonomy, wikiExtract, photoUrl, attribution) totals **412 bytes**. ### `get_currency` — the only filter path leads to a dead end `currency` does shrink the response, by emptying `currencies` / `personal` / `minted`. But on this server no currency resolves to a name (see the separate eco-app#58-related issue), so: - `get_currency(currency="Gold")` → `notFound: true` - `get_currency(currency="ZzzNotARealCurrency")` → `notFound: true`, byte-identical response `suggestions` returns raw numeric ids (`["2533707", "2967954", "131058", ...]`). So the unfiltered call is over cap and every filtered call is `notFound`. There is no input that yields per-currency detail. ## Expected A `limit` / `top` parameter on the unbounded arrays (`trades`, `stores`, `traders`, `flows`, `recentDemographics`, `recentSettlements`, `population`, `currencies`, `personal`), defaulting to a slice that keeps a no-argument call inside the cap — the pattern `get_progression` already uses well with `include_timelines: false` + `citizen`, and that `get_world` already uses with its top-N lists. `get_progression` is the model to copy: it returns a rich summary by default, keeps full timelines behind an opt-in flag, and warns `"citizens truncated to busiest 80 of 165 (trends + leaderboards cover all)"`. That call succeeds comfortably. ## Repro ``` mcp__eco__get_civics() mcp__eco__get_trades() mcp__eco__get_stores() mcp__eco__get_crafting_atlas() mcp__eco__get_currency() mcp__eco__get_species(name="Wheat") ``` Found during a QA sweep of all 25 Eco MCP tools. 8 of 25 are unusable over MCP for this reason (these six plus `get_recipes` / `price_recipe`, tracked in #254).

coilyco-ops referenced this issue from a commit

2026-08-13 18:03:49 +00:00

fix(tools): bound the detail arrays that put six tools over the response cap

coilyco-ops closed this issue

2026-08-13 18:03:49 +00:00

coilyco-ops referenced this issue

2026-08-13 19:47:02 +00:00

Invariant: limit must bound every unbounded array, and truncation must always warn — sweep all 25 MCP tools #267