Context Tax

The single biggest agent design problem: every tool definition the model sees costs tokens. Not when called — just to be available. A large MCP server can spend tens of thousands of tokens on tools/list before the user types a word, and connecting several of them eats a serious fraction of the context window before any work begins.

Pipeworx is an extreme case of the problem, which is why it has to solve it. Serving the whole catalog at once is not an option we could offer even if we wanted to: measured on 2026-08-03, a full tools/list against gateway.pipeworx.io/mcp returns 5,378 tools in 6.6 MB — on the order of 1.6M tokens, larger than any current model’s context window.

This is the context tax, and it caps how many MCPs an agent can usefully carry.

The naïve approach: fewer tools

The obvious response — “use fewer MCPs” — is the wrong tradeoff. You give up capability to save tokens. The agent that could have answered your question can’t, because the relevant tool wasn’t loaded.

How Pipeworx avoids the tax

A single Pipeworx connection wraps 5,411 tools across 1,404 packs, but the agent never carries all of them. Three mechanisms:

1. Pre-filter at the gateway URL

gateway.pipeworx.io/mcp?task=housing+market

The ?task= parameter does semantic search over the catalog at connect time. The agent’s tools/list returns only the most relevant tools, plus the gateway meta-tools.

Measured on 2026-08-03, ?task=housing+market returned 48 tools in 94.6 KB — about 1.4% of the full catalog’s payload. The default recommended endpoint, pipeworx.io/mcp, returned 38 tools in 62.5 KB. You can reproduce either number by POSTing {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}} to the URL and measuring the response.

2. On-demand discovery via discover_tools

When the prefilter is too narrow or the task shifts mid-session, the agent calls:

discover_tools({ query: "find federal contracts for cybersecurity" })

It returns the top 20 matches with names + descriptions. The agent can then call them by name without re-listing.

3. Compound tools that collapse N calls into 1

The _intel tools bundle 3–5 calls into one:

fintech_company_deep_dive({ ticker: "AAPL" })
// → SEC filings + stock quote + income statement + CFPB complaints, in one response

Same data, one round-trip’s worth of context instead of five.

What this means for your design

  • Recommended connection (pipeworx.io/mcp) loads ~38 tools — the gateway-native meta-tools plus the catalog pack — and routes everything else at runtime via ask_pipeworx / discover_tools.
  • Task-scoped (gateway.pipeworx.io/mcp?task=housing+market) loads the meta-tools + the ~20 most relevant pack tools.
  • Full surface (gateway.pipeworx.io/mcp, no parameters) exposes every tool schema in the catalog — use it only when your client does its own tool filtering.
  • Compound calls keep transcripts short — one tool call carrying five tools’ worth of data is one entry in the agent’s history, not five.

Adjacent issues

  • Tool-list churn. If a gateway re-issues different tool sets per turn, the model gets confused about what’s available. Pipeworx keeps tool-lists stable within a session.
  • Lost in the middle. Retrieval accuracy degrades as context fills, and degrades most for material in the middle of a long context — a general finding about long-context models, not a Pipeworx measurement. Pipeworx’s _meta.cache.fresh_until lets agents detect when they’re re-reading their own cached data.
  • Output schema reduces re-listing. Every tool’s outputSchema tells the agent the response shape before calling — no test calls just to learn what’s coming back.

Read more

  • Meta-tools — how ask_pipeworx, discover_tools, resolve_entity, compare_entities work
  • Resources — citing entities by URI without re-fetching
  • Prompts — server-side workflow templates

Last reviewed August 3, 2026