{"slug": "mcp-discovery-why-your-mcp-server-needs-better-tool-discovery-than-you-think-85", "title": "MCP Discovery: Why Your MCP Server Needs Better Tool Discovery Than You Think (After 85 Production Outages)", "summary": "A developer who built 10+ MCP servers and experienced 85 production outages found that poor tool discovery causes more failures than bad code. The engineer built a fuzzy discovery layer in Java Spring Boot to handle LLM hallucinations of tool names, reducing errors from mismatched tool calls.", "body_md": "Honestly, 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\nMCP is pretty straightforward, right? You implement `tools/list`\n\nand `tools/call`\n\n, 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`\n\ninstead of `search_papers`\n\n. 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`\n\nerror, 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\nLet me count the ways I've messed this up:\n\nThis is the big one. My tool is called `search_papers`\n\n. The LLM thinks \"search papers\" → `search_paper`\n\n(singular). Or `search_knowledge`\n\n→ wrong again. Or `find_paper`\n\n→ nope.\n\nEvery time it happens, you get:\n\n```\nError: Tool not found: search_paper\nAvailable 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\nWhen I started, my tool descriptions were:\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\nIt's not just tool names—it's parameter names too. My parameter is called `query`\n\n, but the LLM keeps passing `question`\n\nor `search_term`\n\n. Same problem: error, retry, failure.\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\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@Component\npublic 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```\npublic 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\npublic record MatchResult(ToolDefinition tool, double score) {}\n```\n\nAfter deploying this, I checked my logs. Here's what happened:\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\nI used to write tool descriptions like this:\n\n```\n{\n  \"name\": \"search_papers\",\n  \"description\": \"Searches papers\"\n}\n```\n\nUseless. Now I write:\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\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\nIt's not just tool names—parameters get hallucinated too. I added parameter aliasing:\n\n```\npublic 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```\npublic 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\nI ended up building a proper tools registry that holds all the metadata in one place:\n\n```\n@Configuration\npublic 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\npublic interface McpTool {\n    ToolDefinition getDefinition();\n    Object call(Map<String, Object> args) throws ToolException;\n}\n\npublic 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\nLet's be honest—this adds complexity. Is it worth it?\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`\n\nis 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\nLet me leave you with the actual numbers from my server after two weeks:\n\n| Metric | Before Fuzzy Discovery | After Fuzzy Discovery |\n|---|---|---|\n| Tool Not Found Errors/day | 14 | 2 |\n| Successful Tool Calls/day | 287 | 301 |\n| Success Rate | 95.1% | 99.3% |\n| User Complaints about \"it doesn't work\" | 2-3/week | 0 |\n\nThat's the difference between \"this is flaky\" and \"this just works\".\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?", "url": "https://wpnews.pro/news/mcp-discovery-why-your-mcp-server-needs-better-tool-discovery-than-you-think-85", "canonical_source": "https://dev.to/kevinten10/mcp-discovery-why-your-mcp-server-needs-better-tool-discovery-than-you-think-after-85-production-3kg", "published_at": "2026-06-25 13:22:01+00:00", "updated_at": "2026-06-25 13:43:38.537678+00:00", "lang": "en", "topics": ["developer-tools", "large-language-models", "artificial-intelligence"], "entities": ["MCP", "Java Spring Boot", "FuzzyMatcher", "McpDiscoveryFilter", "OncePerRequestFilter", "ToolDefinition", "CallToolRequest", "HttpServletRequest"], "alternates": {"html": "https://wpnews.pro/news/mcp-discovery-why-your-mcp-server-needs-better-tool-discovery-than-you-think-85", "markdown": "https://wpnews.pro/news/mcp-discovery-why-your-mcp-server-needs-better-tool-discovery-than-you-think-85.md", "text": "https://wpnews.pro/news/mcp-discovery-why-your-mcp-server-needs-better-tool-discovery-than-you-think-85.txt", "jsonld": "https://wpnews.pro/news/mcp-discovery-why-your-mcp-server-needs-better-tool-discovery-than-you-think-85.jsonld"}}