Reducing context

Pipeworx exposes 1,007 tools through one URL. Most agent flows only need 5–20 of them per session. Here’s how to keep your tool surface small without giving up coverage.

The four levers

In rough order of leverage, biggest to smallest:

1. Scope by URL parameter at connect time

gateway.pipeworx.io/mcp                       # full surface (~all 1,007 tools available, but pre-filtered to ~20 most relevant)
gateway.pipeworx.io/mcp?vertical=housing      # housing pack bundle (~30 tools)
gateway.pipeworx.io/mcp?task=search+papers    # semantic-task scope (~20 tools)
gateway.pipeworx.io/<pack>/mcp                # single pack

The vertical and task filters are evaluated at connect time. The agent’s tools/list returns ONLY the matching tools — the rest never enter context.

2. Use discover_tools for on-demand expansion

If the connect-time scope was too narrow, the agent calls:

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

Top-20 most relevant tools by name + description. The agent calls them by name without the gateway re-listing everything.

3. Use compound _intel tools to collapse multi-call patterns

Five calls become one:

fintech_company_deep_dive({ ticker: "AAPL" })
// → SEC + AlphaVantage + CFPB in one response, one transcript entry

See Compound tools.

4. Use Resources for citations instead of re-fetching

Embed pipeworx://... URIs in output. Other agents (or future-you) can resources/read them — no need to keep the data in context.

Mounting Pipeworx multiple times

If you need broad coverage but want session-level scoping, mount with different scopes:

{
  "mcpServers": {
    "pipeworx-fin":     { "url": "https://gateway.pipeworx.io/mcp?vertical=fintech" },
    "pipeworx-pharma":  { "url": "https://gateway.pipeworx.io/mcp?vertical=pharma" },
    "pipeworx-broad":   { "url": "https://gateway.pipeworx.io/mcp" }
  }
}

The agent picks the namespace per call. Each tools/list is small. Total context ~3x a single scope, vs. 50x if all 1,007 were exposed.

What NOT to do

  • Don’t import every pack individually. mcps[fred], mcps[edgar], mcps[bls] — quickly accumulates context. Use a vertical or ?task= instead.
  • Don’t disable caching to “always get fresh data.” The cache TTLs match the underlying source’s update frequency. Disabling it just burns calls.
  • Don’t repeatedly re-list tools. If you call tools/list more than once per session, your client config is wrong (or your task changed enough to warrant a different scope).

Measuring

The gateway returns _meta.cost and _meta.cache.fresh_until on every response. Logging these in your agent gives you the data to tune scopes empirically — if 90% of your calls are within one vertical, scope to it.

Last reviewed May 8, 2026