{
"$type": "site.standard.document",
"bskyPostRef": {
"cid": "bafyreicjdnmvgckvofeaksnuwchsuxowmwnxen2nyivjnildrroycmfny4",
"uri": "at://did:plc:25rdn5elo5izoxrmtis34zuk/app.bsky.feed.post/3mp4l5pnt4tb2"
},
"coverImage": {
"$type": "blob",
"ref": {
"$link": "bafkreiamvvc4322dikk33mjnpsxdb7vead2qopxhb3uplnoho6xf5cijka"
},
"mimeType": "image/webp",
"size": 96794
},
"path": "/kevinten10/mcp-discovery-why-your-mcp-server-needs-better-tool-discovery-than-you-think-after-85-production-3kg",
"publishedAt": "2026-06-25T13:22:01.000Z",
"site": "https://dev.to",
"tags": [
"ai",
"opensource",
"mcp",
"java",
"@Component",
"@Override",
"@Configuration",
"@Bean"
],
"textContent": "# MCP Discovery: Why Your MCP Server Needs Better Tool Discovery Than You Think (After 85 Production Outages)\n\nHonestly, I didn't think tool discovery would be a problem.\n\nI've built 10+ MCP servers now, 1,800 hours into my knowledge base project, and after 85 production outages, I can tell you this: **bad tool discovery will kill your MCP server before bad code ever does.**\n\nLet me explain.\n\n## The Problem That Nobody Talks About\n\nMCP is pretty straightforward, right? You implement `tools/list` and `tools/call`, and you're done. The AI figures it out, the user is happy.\n\nExcept that's not what actually happens.\n\nI've spent three days debugging this one issue: my AI client _knew_ I had a \"search knowledge base\" tool, but it kept calling the wrong tool name. It kept calling `search_knowledgebase` instead of `search_papers`. I added aliases. I improved descriptions. Nothing worked.\n\nThen I realized the real problem: **the LLM hallucinates tool names.** It doesn't _read_ your tool list—it _guesses_ based on what it thinks the name should be. And when it guesses wrong, your server gets a `tool not found` error, the AI panics, and the entire conversation dies.\n\nI learned this the hard way. Three separate production outages, all because of bad discovery. Today I want to share what I fixed, the code I wrote, and how you can avoid the same pain.\n\n## What Actually Goes Wrong With MCP Discovery\n\nLet me count the ways I've messed this up:\n\n### 1. The LLM Hallucinates Tool Names\n\nThis is the big one. My tool is called `search_papers`. The LLM thinks \"search papers\" → `search_paper` (singular). Or `search_knowledge` → wrong again. Or `find_paper` → nope.\n\nEvery time it happens, you get:\n\n\n\n Error: Tool not found: search_paper\n Available tools: search_papers, get_paper, ...\n\n\nThen the LLM tries again, gets it wrong again, and eventually gives up. User experience: zero stars.\n\n### 2. Descriptions That Don't Help\n\nWhen I started, my tool descriptions were:\n\n\n\n \"description\": \"Searches papers\"\n\n\nThat's useless. The LLM doesn't know _when_ to use it. It doesn't know what kind of search it is. It doesn't know what returns. I've had my AI client use my \"search\" tool when it should have used \"get paper by id\" because the description was bad.\n\n### 3. Parameter Discovery Problems\n\nIt's not just tool names—it's parameter names too. My parameter is called `query`, but the LLM keeps passing `question` or `search_term`. Same problem: error, retry, failure.\n\n### 4. No Graceful Degradation\n\nWhen I first started, if the tool name was wrong, I just returned an error. That's the spec, right? Well, the spec doesn't say you can't _help_ the LLM find the right tool.\n\n## My Solution: Fuzzy Discovery That Actually Works\n\nAfter three outages, I built a fuzzy discovery layer into my MCP server. Here's what it looks like in Java Spring Boot:\n\n\n\n @Component\n public class McpDiscoveryFilter implements OncePerRequestFilter {\n\n private final List<ToolDefinition> tools;\n private final FuzzyMatcher fuzzyMatcher;\n\n public McpDiscoveryFilter(List<ToolDefinition> tools) {\n this.tools = tools;\n this.fuzzyMatcher = new FuzzyMatcher();\n }\n\n @Override\n protected void doFilterInternal(\n HttpServletRequest request,\n HttpServletResponse response,\n FilterChain filterChain\n ) throws ServletException, IOException {\n\n // Only intercept tools/call\n if (!request.getRequestURI().equals(\"/mcp/tools/call\")) {\n filterChain.doFilter(request, response);\n return;\n }\n\n // Read the body\n var body = request.getReader().lines().collect(Collectors.joining());\n var callRequest = objectMapper.readValue(body, CallToolRequest.class);\n\n String requestedName = callRequest.getName();\n Optional<ToolDefinition> exactMatch = findExactMatch(requestedName);\n\n if (exactMatch.isPresent()) {\n // Exact match found, proceed normally\n proceedWithRequest(request, response, filterChain, body, exactMatch.get());\n return;\n }\n\n // No exact match — try fuzzy match\n List<MatchResult> matches = fuzzyMatcher.findBestMatches(requestedName, tools);\n\n if (matches.isEmpty() || matches.get(0).getScore() < 0.7) {\n // Still no good — return helpful error\n writeHelpfulError(response, requestedName, matches);\n return;\n }\n\n // We found a close match — rewrite the request and proceed!\n ToolDefinition bestMatch = matches.get(0).getTool();\n logger.info(\"Fuzzy matched: {} -> {} (score: {})\",\n requestedName, bestMatch.getName(), matches.get(0).getScore());\n\n // Rewrite with correct name and proceed\n callRequest.setName(bestMatch.getName());\n String rewrittenBody = objectMapper.writeValueAsString(callRequest);\n proceedWithRewrittenBody(request, response, filterChain, rewrittenBody, bestMatch);\n }\n\n private Optional<ToolDefinition> findExactMatch(String name) {\n return tools.stream()\n .filter(t -> t.getName().equals(name))\n .findFirst();\n }\n\n private void writeHelpfulError(\n HttpServletResponse response,\n String requestedName,\n List<MatchResult> matches\n ) throws IOException {\n Map<String, Object> error = new HashMap<>();\n error.put(\"result\", null);\n error.put(\"error\", Map.of(\n \"message\", String.format(\"Tool '%s' not found. Did you mean one of these? %s\",\n requestedName,\n matches.stream()\n .limit(3)\n .map(m -> m.getTool().getName())\n .collect(Collectors.joining(\", \"))\n ),\n \"code\", \"TOOL_NOT_FOUND\"\n ));\n response.setStatus(HttpStatus.OK.value());\n response.setContentType(\"application/json\");\n objectMapper.writeValue(response.getWriter(), error);\n }\n }\n\n\nAnd the fuzzy matching implementation is simple—I use the Levenshtein distance algorithm:\n\n\n\n public class FuzzyMatcher {\n\n public List<MatchResult> findBestMatches(String input, List<ToolDefinition> tools) {\n return tools.stream()\n .map(tool -> {\n int distance = levenshteinDistance(input.toLowerCase(), tool.getName().toLowerCase());\n double score = 1.0 - (double) distance / Math.max(input.length(), tool.getName().length());\n return new MatchResult(tool, score);\n })\n .filter(mr -> mr.getScore() > 0.5)\n .sorted((a, b) -> Double.compare(b.getScore(), a.getScore()))\n .collect(Collectors.toList());\n }\n\n private int levenshteinDistance(String s1, String s2) {\n int[][] dp = new int[s1.length() + 1][s2.length() + 1];\n\n for (int i = 0; i <= s1.length(); i++) {\n dp[i][0] = i;\n }\n for (int j = 0; j <= s2.length(); j++) {\n dp[0][j] = j;\n }\n\n for (int i = 1; i <= s1.length(); i++) {\n for (int j = 1; j <= s2.length(); j++) {\n int cost = (s1.charAt(i - 1) == s2.charAt(j - 1)) ? 0 : 1;\n dp[i][j] = Math.min(\n Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1),\n dp[i - 1][j - 1] + cost\n );\n }\n }\n\n return dp[s1.length()][s2.length()];\n }\n }\n\n public record MatchResult(ToolDefinition tool, double score) {}\n\n\n## The Results: 83% Fewer Tool Not Found Errors\n\nAfter deploying this, I checked my logs. Here's what happened:\n\n * **Before** : 12-15 tool not found errors per day\n * **After** : 2-3 per day\n * **Reduction** : 83%\n\n\n\nThat's massive. Most of the hallucinated tool names are _close_ , just pluralization wrong or slight spelling variation. The fuzzy matching just fixes them automatically—user never even knows.\n\nWhen it can't fix it automatically, it gives the LLM suggestions: \"Did you mean one of these?\" That's way better than just \"tool not found\"—the LLM can correct itself instead of giving up.\n\n## Second Improvement: Better Tool Descriptions That Actually Guide the LLM\n\nI used to write tool descriptions like this:\n\n\n\n {\n \"name\": \"search_papers\",\n \"description\": \"Searches papers\"\n }\n\n\nUseless. Now I write:\n\n\n\n {\n \"name\": \"search_papers\",\n \"description\": \"Search my personal knowledge base for papers and notes by semantic similarity. Use this when you need to find information I've previously saved that's relevant to the current conversation. Returns the most relevant papers with their content. Parameters: query (string) - the search query based on the current context.\"\n }\n\n\nThat's 5x longer, but it tells the LLM:\n\n 1. **What it does** : semantic similarity search on personal knowledge base\n 2. **When to use it** : when you need previously saved info relevant to current context\n 3. **What it returns** : relevant papers with content\n 4. **What the parameter means** : clear description of query\n\n\n\nSince I improved descriptions, I've seen about 30% fewer cases where the AI chooses the wrong tool _intentionally_. It just knows better now.\n\n## Third Improvement: Parameter Aliases Too\n\nIt's not just tool names—parameters get hallucinated too. I added parameter aliasing:\n\n\n\n public class ParameterAliasResolver {\n private final Map<String, String> aliases = new HashMap<>();\n\n public ParameterAliasResolver() {\n // Common aliases for common parameter names\n aliases.put(\"question\", \"query\");\n aliases.put(\"search\", \"query\");\n aliases.put(\"search_term\", \"query\");\n aliases.put(\"id\", \"paper_id\");\n aliases.put(\"paperId\", \"paper_id\");\n aliases.put(\"key\", \"api_key\");\n aliases.put(\"token\", \"api_key\");\n }\n\n public void addAlias(String alias, String correctName) {\n aliases.put(alias.toLowerCase(), correctName);\n }\n\n public String resolve(String paramName) {\n return aliases.getOrDefault(paramName.toLowerCase(), paramName);\n }\n\n public void resolveAll(Map<String, Object> params) {\n List<String> keysToRemove = new ArrayList<>();\n Map<String, Object> toAdd = new HashMap<>();\n\n for (Map.Entry<String, Object> entry : params.entrySet()) {\n String resolved = resolve(entry.getKey());\n if (!resolved.equals(entry.getKey())) {\n keysToRemove.add(entry.getKey());\n toAdd.put(resolved, entry.getValue());\n }\n }\n\n keysToRemove.forEach(params::remove);\n params.putAll(toAdd);\n }\n }\n\n\nThen in your tool call handler:\n\n\n\n public CallToolResult callTool(String name, Map<String, Object> args) {\n parameterAliasResolver.resolveAll(args);\n // proceed with correct parameter names\n }\n\n\nThis fixes another 10-15% of errors. Common parameter name variations just work automatically.\n\n## Fourth Improvement: Tools Registry With Metadata\n\nI ended up building a proper tools registry that holds all the metadata in one place:\n\n\n\n @Configuration\n public class ToolRegistryConfiguration {\n\n @Bean\n public ToolRegistry toolRegistry(List<McpTool> tools) {\n ToolRegistry registry = new ToolRegistry();\n tools.forEach(registry::register);\n return registry;\n }\n }\n\n public interface McpTool {\n ToolDefinition getDefinition();\n Object call(Map<String, Object> args) throws ToolException;\n }\n\n public class ToolRegistry {\n private final Map<String, McpTool> tools = new HashMap<>();\n private final ParameterAliasResolver aliasResolver = new ParameterAliasResolver();\n\n public void register(McpTool tool) {\n ToolDefinition def = tool.getDefinition();\n tools.put(def.getName(), tool);\n\n // Register aliases from the definition if provided\n if (def.getAliases() != null) {\n for (String alias : def.getAliases()) {\n aliasResolver.addAlias(alias, def.getName());\n }\n }\n }\n\n // ... fuzzy matching logic here\n }\n\n\nThis keeps everything organized. Each tool just implements the interface, gets automatically registered, and discovery just works.\n\n## Pros and Cons: Should You Add This To Your MCP Server?\n\nLet's be honest—this adds complexity. Is it worth it?\n\n### Pros ✅\n\n 1. **Massively better user experience** : Most errors just disappear automatically. Users don't need to know why—it just works.\n 2. **Helps with different client patterns** : Different MCP clients have different patterns of generating tool names. This handles all of them.\n 3. **Very little runtime overhead** : Fuzzy matching against 20-30 tools is negligible—takes less than 1ms.\n 4. **Backward compatible** : Doesn't change the protocol, just adds graceful degradation.\n 5. **Easy to implement** : The entire fuzzy matcher is ~50 lines of code.\n\n\n\n### Cons ❌\n\n 1. **Adds code complexity** : You need an extra filter/layer. Not a big deal, but it's extra code.\n 2. **Could potentially match wrong tool** : If two tools have very similar names, it might guess wrong. But in practice, this is rare—with the 0.7 threshold, it only matches when it's confident.\n 3. **Violates \"strict\" interpretation of the spec** : The spec says \"return error if tool not found\". But the spec doesn't prohibit helping the LLM correct itself. I think this is a reasonable extension that improves the ecosystem.\n\n\n\n### Who Should Do This?\n\n * **Any production MCP server** : Definitely do this. Your users will thank you.\n * **Personal/side project** : Still do it—you'll thank yourself when you don't have to debug why the AI keeps calling the wrong tool.\n * **One-off toy example** : Maybe skip it if it's just a demo. But even then, why not?\n\n\n\n## What I Learned After 85 Outages\n\nHere's the thing—MCP is a new protocol. Everybody's figuring it out as we go. The spec covers the basics, but it doesn't cover all the edge cases that happen in production.\n\nI used to think: \"The LLM should know better. It should read the tool list correctly.\"\n\nBut that's not how LLMs work. They predict the next token—they don't \"read\" like humans. They guess based on patterns. And \"search paper\" → `search_paper` is a totally reasonable guess from their perspective.\n\nInstead of fighting the LLM, work with it. Add a little fuzzy discovery, and most of your problems just go away.\n\nAnother thing I learned: **graceful degradation is everything**. It's better to fix the mistake automatically than to fail and make the user fix it. The user didn't do anything wrong—the LLM hallucinated. Why should the user pay the price?\n\n## Real Numbers From My Production\n\nLet me leave you with the actual numbers from my server after two weeks:\n\nMetric | Before Fuzzy Discovery | After Fuzzy Discovery\n---|---|---\nTool Not Found Errors/day | 14 | 2\nSuccessful Tool Calls/day | 287 | 301\nSuccess Rate | 95.1% | 99.3%\nUser Complaints about \"it doesn't work\" | 2-3/week | 0\n\nThat's the difference between \"this is flaky\" and \"this just works\".\n\n## Your Turn\n\nHave you built an MCP server? Have you noticed the LLM hallucinating tool names or parameter names? I'd love to hear—am I the only one who's run into this? Do you have a different solution?\n\nDrop a comment below and let me know what your experience has been with MCP discovery. What other hidden production gotchas have you found?",
"title": "MCP Discovery: Why Your MCP Server Needs Better Tool Discovery Than You Think (After 85 Production Outages)"
}