{"record":{"id":"c2fd1f2f02cb1b18","repo":"agentscope-ai/agentscope","slug":"tool-name-r-not-found-in-mcp-self-name-r","errorCode":null,"errorMessage":"Tool {name!r} not found in MCP {self.name!r}.","messagePattern":"Tool (.+?) not found in MCP (.+?)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/agentscope/workspace/_gateway_client.py","lineNumber":369,"sourceCode":"        name: str,\n    ) -> GatewayMCPTool:\n        \"\"\"Look up a single tool by upstream name and wrap it.\n\n        Falls back to :meth:`list_raw_tools` on cache miss, then\n        searches the unfiltered cache so tools that ``enable_tools`` /\n        ``disable_tools`` would have hidden are still resolvable —\n        matching :meth:`MCPClient.get_tool`.\n\n        Raises:\n            `ValueError`:\n                No tool with that upstream name exists on the gateway.\n        \"\"\"\n        if self._cached_tools is None:\n            await self.list_raw_tools()\n        for raw in self._cached_tools or []:\n            if raw.name == name:\n                return self._wrap_tool(raw)\n        raise ValueError(\n            f\"Tool {name!r} not found in MCP {self.name!r}.\",\n        )\n\n    # ── helpers ───────────────────────────────────────────────────\n\n    def _wrap_tool(self, tool: mcp.types.Tool) -> GatewayMCPTool:\n        \"\"\"Build a :class:`GatewayMCPTool` bound to this client's\n        gateway facade.\n        \"\"\"\n        assert self._gateway is not None\n        return GatewayMCPTool(\n            mcp_name=self.name,\n            tool=tool,\n            gateway=self._gateway,\n            agent_id=self._agent_id,\n            session_id=self._session_id,\n        )\n","sourceCodeStart":351,"sourceCodeEnd":387,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/workspace/_gateway_client.py#L351-L387","documentation":"Raised by GatewayMCPClient.get_tool(name) when no upstream tool with that exact name exists in the cached tool list (after a list_raw_tools() refresh on cache miss). This is a plain lookup miss: the name doesn't match any raw.name from the MCP server's advertised tools. Note enable_tools/disable_tools filtering does NOT hide tools from get_tool — it searches the unfiltered cache — so a mismatch means the upstream server genuinely doesn't expose that name.","triggerScenarios":"`await client.get_tool(\"fetch\")` when the MCP server exposes e.g. \"web_fetch\" or an mcp__-prefixed name; calling get_tool before connect/list succeeded but the MCP exposes zero tools; typos or renamed tools after an upstream MCP server version change.","commonSituations":"Using the mcp__servername__tool prefixed name instead of the upstream bare name; upstream MCP server upgraded and renamed tools; typo in the tool name; assuming a tool exists without checking list_raw_tools() output.","solutions":["Print `await client.list_raw_tools()` (or `[t.name for t in ...]`) and use the exact upstream name shown","Drop any `mcp__<name>__` prefix — get_tool expects the bare upstream tool name","Catch ValueError and skip/fallback when the tool is optional","Pin or verify the upstream MCP server version if tools were renamed"],"exampleFix":"// before\ntool = await client.get_tool(\"mcp__fetch__fetch\")\n// after\ntool = await client.get_tool(\"fetch\")  # bare upstream name","handlingStrategy":"validation","validationCode":"tools = await client.list_raw_tools()\nnames = {t.name for t in tools}\nif name not in names:\n    raise KeyError(f\"available: {sorted(names)}\")\ntool = await client.get_tool(name)","typeGuard":"def tool_exists(client: GatewayMCPClient, name: str) -> bool:\n    return any(t.name == name for t in client._cached_tools or [])","tryCatchPattern":"try:\n    tool = await client.get_tool(name)\nexcept ValueError:\n    tool = None  # optional tool, skip","preventionTips":["List tools once and derive names dynamically instead of hardcoding","Use bare upstream names (no mcp__ prefix)","Treat optional tools with a ValueError catch-and-skip"],"tags":["mcp","tool-lookup","valueerror"],"backgroundTag":"tool-name-not-found","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}