[FEATURE]: ToolSearch for lazy/deferred tool discovery to reduce per-turn context size #20489

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Problem

OpenCode currently injects the full tool manifest into every LLM turn. As the plugin/MCP ecosystem grows, this manifest grows with it — adding hundreds or thousands of tokens to every request. Most of those tools are irrelevant to the current task.

This compounds across multi-agent sessions: each spawned sub-agent also gets the full manifest, multiplying the wasted context. At scale (10+ MCP servers, 50+ tools) this is a meaningful cost and context-window pressure problem.

claw-code implements a ToolSearch tool that enables a deferred tool pattern: only a small core tool set is injected upfront, and the agent can discover additional tools by searching by name or keyword before invoking them.

Proposed solution

// packages/opencode/src/tool/tool-search.ts

export const ToolSearchTool = Tool.define({
  name: "ToolSearch",
  description: "Search for available tools by name or keyword. Use this before invoking an unfamiliar tool, or when looking for MCP tools that may not be loaded in your current context.",
  parameters: z.object({
    query: z.string().min(1),
    max_results: z.number().int().min(1).max(20).default(5)
  }),
  execute: async ({ query, max_results }) => {
    const allTools = await ToolRegistry.listAll() // includes deferred/unloaded MCP tools
    const matches = fuzzySearch(allTools, query, max_results)
    return {
      query,
      matches: matches.map(t => ({ name: t.name, description: t.description, loaded: t.loaded })),
      total_available: allTools.length,
      pending_mcp_servers: ToolRegistry.pendingServers()
    }
  }
})

Deferred tool pattern

Agent context (small core): bash, read_file, write_file, glob_search, grep_search, ToolSearch
                                                                                       ^
                                                                                       |
                                              Agent calls ToolSearch("linear create issue")
                                              --> discovers: linear__create_issue (MCP, not yet loaded)
                                              --> runtime loads that specific MCP tool on demand
                                              --> agent invokes it

Why this matters

• Reduces base context size per turn proportional to the number of installed MCP servers
• Scales gracefully: 1 tool vs. 100 tools costs the same upfront (just ToolSearch is always present)
• Agents can discover tools they don't know about without the manifest bloating every turn
• Particularly valuable for OpenRouter/multi-provider setups where many MCP servers may be configured

Acceptance criteria

• ToolSearch tool is registered with ReadOnly permission
• Search matches on both tool name and description with fuzzy matching
• Results include whether the tool is currently loaded or deferred (not yet instantiated)
• A deferred tool becomes available for invocation after being returned by ToolSearch
• Configuration option tools.lazyLoad: true enables the deferred pattern (default: false for backward compatibility)
• Full manifest injection remains the default — deferred loading is opt-in

Related / cross-reference

• claw-code reference: https://github.com/instructkr/claw-code/tree/main/rust (ToolSearch tool)
• Sub-agent tool-set isolation: [FEATURE]: Sub-agent tool-set isolation by role (Explore / Plan / Verification scopes) #20483
• Background task result batching (cost context): [FEATURE]: Silent result collection for background tasks to avoid consuming LLM turns #20460
• Learnings from claude-code source: Lessons from claude-code-main? #20475
• Original RFC: [FEATURE]: Rust-backed async diff engine via claw-code (fixes write/edit freeze + unlocks claw-code Rust primitives) #20479