Support dynamic tool discovery to prevent prompt context bloat

[dvcrn]

Problem

Zed sends full JSON schemas and descriptions for every enabled built-in and MCP tool on every turn.

Connecting tool-dense MCP servers (such as GitHub, GitLab, or browser automation servers) adds dozens of tool definitions directly into the request payload. For servers with 30 to 100 tools, schema definitions alone consume 20,000 to 60,000 tokens before conversation history is added. This limits usable context, increases API costs, and increases the rate of tool-selection errors by the model.

Currently, the only workaround is manually curating tool booleans in agent.profiles inside settings.json, which does not scale across projects or workflows.

Proposed solution

Implement on-demand tool loading with a configuration setting similar to the tool-access controls found in Claude Code, Codex, OpenCode, and Grok:

• when_needed (on-demand): Zed loads only core tools with full schemas. Other tools appear only by name in a lightweight registry list. The model fetches full tool schemas via a built-in tool_search primitive when it needs them.
• always (current behavior): All enabled tools are loaded upfront with their full JSON schemas.

Tool workflow in when_needed mode

1. Resident tools: A minimal set of core primitives is always loaded with full schemas (for example: read_file, edit_file, write_file, grep, terminal, spawn_agent, tool_search).
2. Deferred tools: All other tools (secondary built-ins and MCP tools) are listed by name only in the prompt, without parameter schemas or descriptions.
3. On-demand tool retrieval (tool_search): When the model needs an unretrieved tool, it queries the registry either by keyword or by exact name:

   tool_search({
     "query": "github pull requests",
     "max_results": 3
   })

   or for direct name matching:

   tool_search({
     "query": "select:mcp:github:create_pull_request,mcp:github:list_pull_requests",
     "max_results": 2
   })

   Zed matches against the local registry of tool names and descriptions, returning the full function schemas in the tool result. Once returned, those tools become callable for the rest of the session.

Handling direct calls to unloaded tools

Because the model can see deferred tool names, it may occasionally attempt to call a tool before loading its schema. When this occurs, Zed should reject the call with an explicit error directing the model to fetch the schema first:

{
  "error": "Tool 'mcp:github:create_issue' is deferred and its schema is not loaded in this session. Call tool_search(query: \"select:mcp:github:create_issue\", max_results: 1) to retrieve the parameter schema before calling this tool."
}

This prevents malformed arguments and allows the model to self-correct in the next turn.

Proposed tool_search schema

{
  "name": "tool_search",
  "description": "Find and load schemas for deferred tools into context. Use keywords to search descriptions, or 'select:<tool_name>' for direct lookup by name.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Query to find deferred tools. Supports keywords for search or 'select:name1,name2' for direct name matching."
      },
      "max_results": {
        "type": "integer",
        "default": 5,
        "description": "Maximum number of results to return."
      }
    },
    "required": ["query", "max_results"]
  }
}

Proposed configuration

Add a setting to settings.json under agent:

{
  "agent": {
    // "when_needed" | "always"
    "tool_access": "when_needed"
  }
}

This could also be exposed in the Agent Panel tool menu:

• Load tools when needed: Keeps deferred tools out of the prompt until queried, reducing context usage and compaction frequency.
• Always: Preloads all tool schemas for models or setups that do not support dynamic search turns.

Impact

• Reduces initial context usage by 80% to 90% in workspaces with multiple MCP servers.
• Prevents context overflow errors on long threads that use multiple integrations.
• Lets users connect comprehensive MCP servers without needing to curate per-tool boolean lists in configuration files.

[capitaharlock]

The when_needed mode needs one more explicit decision: where does a fetched schema live after tool_search returns it? It has to go somewhere. Re-injecting it into the system prompt invalidates the cached prefix and re-bills that prefix, while keeping it as a tool result in conversation history still re-ships it on every later turn, so a long session can converge back toward the always payload with retrieval round-trips on top. Are retrieved schemas meant to go back into the prefix or stay as tool results?

[dvcrn]

For /chat/completion spec, each request to the inference API is already the full object containing messages, system instructions and tools. So when Zed builds the request object to send back to the inference layer, it would fill in the tool definitions.

Re-injecting it into the system prompt invalidates the cached prefix and re-bills that prefix

Yes you wouldn't inject it into the system prompt, but stick to spec and put it into the tools key, together with object schema and tool description. This is what's already happening, but instead of all tools across all servers that are connected, only the tools that are loaded would be with full schema + description

while keeping it as a tool result in conversation history still re-ships it on every later turn, so a long session can converge back toward the always payload with retrieval round-trips on top

I can't follow with what you mean here. Only the tools that are explicitly requested and discovered would get loaded into the request object for future turns, and never all.

For example, the GitHub remote "all" toolset (https://api.githubcopilot.com/mcp/x/all) has 53 tools. Currently if I connect Zed to the GitHub MCP, all 53 tools including their tool descriptions and tool schemas are being loaded into the full request context, on every single message, even if I don't use GitHub.

With the proposed tool search, the agent would do:

1. Search tool "pull request"
2. Discover the 5 or so tools related to PRs and loads them
3. Zed request context grows by 5 tools + schema + description, instead of 53

The remaining ones would never get fully loaded unless the LLM / user requests them.

It gets worse when you use MCP gateways like the Cloudflare one or MCP Nest, which bundle multiple MCP servers into one single OAuth endpoint. I have in total 250+ (!) tools in mine, spread across 18 connected MCP servers. The amount is never a problem because the harness never loads all tools and discovers when needed. But in Zed, it adds a huge amount of bloat to every session.

[auruhm]

Real-world data point: 67 MCP tools = ~42k tokens per turn, and the only lever today is per-project booleans

Confirming the magnitude in the post with a measured case, and answering @capitaharlock's question with a concrete argument for Zed.

Setup. Zed 1.20.2 (native agent), macOS, one workspace with 7 local MCP servers (1C platform tooling: platform docs, code metadata, metadata graph, standard-subsystem search, syntax check, code templates, code review). Result: 67 tools, 163 KB of tool name + description + JSON schema ≈ 42k input tokens on every request, before any conversation history. One server with 11 tools accounts for 52.6 KB (~13.5k tokens) on its own — a third of the whole tax.

Two consequences worth naming in the discussion:

• agent.profiles is the only available lever, and it is the wrong granularity. In our workspace every one of those servers is needed sometimes, and almost never on the same turn. Curating booleans per project means either paying the tax or losing tools mid-task; it does not scale.
• The tax is also paid on turns that have nothing to do with those servers, which inflates the prefix that has to be re-processed and re-billed on each turn.

Cross-harness evidence that deferred loading pays off (same prompt, measured): a Claude Code session with tool search disabled sent 26,280 input tokens at 70.7 s TTFT; with tool search enabled the identical request sent 6,537 input tokens at 11.5 s. Worth noting that Claude Code silently disables tool search when ANTHROPIC_BASE_URL points at a non-first-party host — i.e. it is exactly the third-party-provider setups (like routing Zed or an ACP agent through a gateway) that pay the full tool payload unless the env override is set.

Other harnesses already treat this as a solved problem: Codex has ToolExposure::Deferred (codex-rs/core/src/mcp_tool_exposure.rs) with 8 KB per spec / 64 KB total budgets; VS Code caps tools per request (128) and routes the rest through virtual tools. Zed is the outlier.

On @capitaharlock's question — where a retrieved schema lives is the whole design, and for Zed specifically it should be conversation history, not the system prefix:

1. Zed re-sends the entire prefix every turn. Any mutation of it re-bills everything upstream and invalidates provider prompt caching.
2. If retrieved schemas are injected into the prefix, a session that retrieves tools incrementally converges back toward always plus retrieval round-trips — the concern raised above is not hypothetical.
3. Keeping retrieved schemas as ordinary tool results makes their lifetime governed by the existing compaction mechanism, which is already the thing that fails on tool-dense setups.

So: when_needed + name-only registry in the prefix + retrieved schemas as tool results. Two additions we would ask for beyond agent.tool_access:

• Per-server granularity. Marking a whole MCP server as deferred is the unit that actually matches how people connect servers (e.g. keep read_file/edit_file/grep/terminal resident, defer all 7 servers).
• Keep the registry listing cheap but discriminative. Name + a one-line description per deferred tool (not just the name) is what makes the search query in step 3 land on the right tool without paying for schemas.

[G36maid]

+1 on this — filed a follow-up in #66626 (codemode), deferred schemas solve the tool-definition cost, but tool results still round-trip through the model; a codemode tool closes that too (pi and OpenCode 2.0 ship it today). I think they're one roadmap — exposure: direct | deferred | codemode per server. @dvcrn

[dvcrn]

I know you want this in Zed but how I currently solve both issues is using Cloudflare MCP portals: I connected my mcp servers to a Cloudflare MCP portal instead of Zed directly, enabled code-mode on the portal and connected that to Zed

Now Zed sees only 3 code-mode related tools instead of the otherwise 300+ tools. Cloudflare is handling the entire code-mode implementation

[G36maid]

Great to hear a working setup — that's the aggregation-layer approach paying off. One gap though: MCP portals are an HTTP-gateway model, so they fit SaaS APIs, but local servers (like ghidra-mcp, moodle-mcp and markitdown are all stdio/local) can't route through one without exposing local data as a cloud endpoint.