{"record":{"id":"1b0fd61ea077928d","repo":"agentscope-ai/agentscope","slug":"tool-name-not-found-in-mcp-server-self-name","errorCode":null,"errorMessage":"Tool '{name}' not found in MCP server '{self.name}'","messagePattern":"Tool '(.+?)' not found in MCP server '(.+?)'","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/agentscope/mcp/_mcp_client.py","lineNumber":406,"sourceCode":"            RuntimeError: If not connected (for stateful connections).\n        \"\"\"\n        # Avoid circular import by importing here\n        from ..tool import MCPTool\n\n        # Fetch tools if not cached. Use list_raw_tools() to avoid the\n        # recursion list_tools() → get_tool() → list_tools().\n        if self._cached_tools is None:\n            await self.list_raw_tools()\n\n        # Find target tool\n        target_tool = None\n        for tool in self._cached_tools:\n            if tool.name == name:\n                target_tool = tool\n                break\n\n        if target_tool is None:\n            raise ValueError(\n                f\"Tool '{name}' not found in MCP server \" f\"'{self.name}'\",\n            )\n\n        # Create MCPTool based on stateful/stateless\n        if not self.is_stateful:\n            # Stateless: pass client generator\n            return MCPTool(\n                mcp_name=self.name,\n                tool=target_tool,\n                client_gen=self._get_client_gen,\n                timeout=self.execution_timeout,\n            )\n        else:\n            # Stateful: pass session\n            self._validate_connection()\n            return MCPTool(\n                mcp_name=self.name,\n                tool=target_tool,","sourceCodeStart":388,"sourceCodeEnd":424,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/mcp/_mcp_client.py#L388-L424","documentation":"get_tool() searches the client's cached tool list (_cached_tools) and raises ValueError when no tool with the given name exists on the MCP server. The cache is populated when tools are listed, so the name must exactly match the server-reported tool name.","triggerScenarios":"client.get_tool(\"seach\") typo; referencing a tool that the server renamed or no longer exposes; calling get_tool before list_tools populated the cache; tool names namespaced differently than expected (mcp__{name}__{tool} vs bare tool name).","commonSituations":"Typos or wrong casing in tool names; server version changes removing/renaming tools; assuming a tool exists from documentation rather than listing actual tools; forgetting to await connect()/list_tools() first on a stateful client.","solutions":["Call await client.list_tools() and print the available tool names, then use the exact name","Check for casing/typos and whether the fully-qualified mcp__{name}__{tool} form is required","Verify the server version still exposes the tool and that enable_tools/disable_tools filters are not hiding it"],"exampleFix":"// before\ntool = await client.get_tool(\"web_shearch\")\n\n// after\ntools = await client.list_tools()\nprint([t.name for t in tools])  # confirm exact name\ntool = await client.get_tool(\"web_search\")","handlingStrategy":"validation","validationCode":"names = {t.name for t in await client.list_tools()}\nif tool_name not in names:\n    raise KeyError(f\"{tool_name} not in {sorted(names)}\")\ntool = await client.get_tool(tool_name)","typeGuard":"def tool_exists(name: str, tools: list) -> bool:\n    return any(t.name == name for t in tools)","tryCatchPattern":"try:\n    tool = await client.get_tool(name)\nexcept ValueError as e:\n    if \"not found\" in str(e):\n        available = [t.name for t in await client.list_tools()]\n        raise ValueError(f\"{name} not in available tools {available}\") from e\n    raise","preventionTips":["Always list tools and use exact server-reported names","Log available tool names at startup for quick diagnosis","Beware enable/disable filters hiding tools from the cache"],"tags":["mcp","tool-not-found","lookup"],"backgroundTag":"tool-not-found","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}