Analysis: MCP tool search for token cost reduction#815
Open
mistercrunch wants to merge 4 commits into
Open
Conversation
Analyzes the ~13K token overhead of Agor's 44 MCP tools sent with every API call. Evaluates FastMCP's tool search pattern and recommends a hybrid approach (Option D) that extracts tool definitions into a registry and adds search_tools for on-demand discovery — yielding 88-96% token reduction with minimal risk. Includes prototype implementation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds detailed comparison of official SDK, FastMCP (TS), and mcp-framework for "plugin into existing server" use case. Only the official SDK cleanly mounts into Express. Updates recommendation to Option D (phased): tool search now, SDK migration later. Adds decision matrix. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
After deeper analysis of the SDK's RegisteredTool API (enable/disable/ remove/update/sendToolListChanged), the SDK migration IS the tool search implementation. Discovered tools become first-class tools via enable() + sendToolListChanged() — strictly better than FastMCP's call_tool proxy. Decomposed into 4 phases: 1. SDK scaffolding + Express mount (0.5 day) 2. Migrate 44 tools to Zod schemas + annotations (2-3 days) 3. Add search_tools with enable/disable pattern (1 day) 4. Configuration + backwards compat (0.5 day) Also adds FastMCP vs SDK comparison table, tool annotation decisions, and new file structure (10 domain files replacing 4,300-line monolith). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Key discovery: Anthropic shipped tool_search_tool as a first-class API feature. Claude Code already auto-enables it when MCP tools exceed 10K tokens — meaning Agor sessions already benefit from ~85% token reduction without any server-side changes. Three layers of tool search now documented: 1. Claude Code client-side (automatic, already working) 2. Messages API defer_loading (for Agent SDK, not yet used) 3. MCP Server enable/disable (requires SDK migration) Also adds references to SEP-1821 (dynamic tool discovery), SEP-1888 (progressive disclosure), and third-party approaches (Speakeasy, mcp2cli, ToolHive, Redis). SDK migration recommendation stands but for different reasons: architecture cleanup, tool annotations, Zod validation, non-Claude agent support. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
notifications/tools/list_changedsupportsearch_toolsfor on-demand discoverytool-search.tsSee
MCP_TOOL_SEARCH_ANALYSIS.mdfor the full analysis.Test plan
notifications/tools/list_changedworks with Claude Code in practicealwaysVisibletool set🤖 Generated with Claude Code