{"record":{"id":"6dae7abc3536ad55","repo":"microsoft/autogen","slug":"tool-tool-name-not-found-available-tools","errorCode":null,"errorMessage":"Tool '{tool_name}' not found, available tools: {', '.join([t.name for t in tools_response.tools])}","messagePattern":"Tool '(.+?)' not found, available tools: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-ext/src/autogen_ext/tools/mcp/_base.py","lineNumber":153,"sourceCode":"\n        Args:\n            server_params (TServerParams): Parameters for the MCP server connection.\n            tool_name (str): The name of the tool to wrap.\n\n        Returns:\n            McpToolAdapter[TServerParams]: An instance of McpToolAdapter.\n\n        Raises:\n            ValueError: If the tool with the specified name is not found.\n        \"\"\"\n        async with create_mcp_server_session(server_params) as session:\n            await session.initialize()\n\n            tools_response = await session.list_tools()\n            matching_tool = next((t for t in tools_response.tools if t.name == tool_name), None)\n\n            if matching_tool is None:\n                raise ValueError(\n                    f\"Tool '{tool_name}' not found, available tools: {', '.join([t.name for t in tools_response.tools])}\"\n                )\n\n        return cls(server_params=server_params, tool=matching_tool)\n\n    def return_value_as_string(self, value: list[Any]) -> str:\n        \"\"\"Return a string representation of the result.\"\"\"\n\n        def serialize_item(item: Any) -> dict[str, Any]:\n            if isinstance(item, (TextContent, ImageContent, AudioContent)):\n                dumped = item.model_dump()\n                # Remove the 'meta' field if it exists and is None (for backward compatibility)\n                if dumped.get(\"meta\") is None:\n                    dumped.pop(\"meta\", None)\n                return dumped\n            elif isinstance(item, EmbeddedResource):\n                type = item.type\n                resource = {}","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-ext/src/autogen_ext/tools/mcp/_base.py#L135-L171","documentation":"McpToolAdapter.from_server_params opens a session, calls session.list_tools(), and searches for the requested tool_name; if no advertised tool matches exactly, ValueError is raised listing all available tool names. This is a discovery mismatch: the name you asked for is not what the server exposes.","triggerScenarios":"Calling from_server_params(server_params, tool_name='search') when the server registers the tool as 'web_search'; trailing whitespace or different casing in tool_name; the server exposing tools conditionally (disabled feature flags, env-gated tools); connecting to the wrong server entirely.","commonSituations":"Server upgraded and tool renamed; connecting to a different MCP server (wrong command/URL) than the one hosting the tool; case-sensitivity mistakes ('GitHub' vs 'github'); a fork of the server with renamed tools; the server returning an empty list because initialization failed partially.","solutions":["Log the error message — it enumerates available tools; use the exact name it lists.","Before creating the adapter, call session.list_tools() yourself and match names programmatically (strip/casefold) to find the right one.","Verify server_params (command, args, url) point to the server that actually exposes the tool.","Pin the MCP server version whose tool names your code expects."],"exampleFix":"# before\nadapter = await McpToolAdapter.from_server_params(params, \"search\")\n\n# after\nasync with create_mcp_server_session(params) as session:\n    await session.initialize()\n    names = [t.name for t in (await session.list_tools()).tools]\ntarget = next(n for n in names if n.casefold() == \"search\")\nadapter = await McpToolAdapter.from_server_params(params, target)","handlingStrategy":"validation","validationCode":"async with create_mcp_server_session(server_params) as session:\n    await session.initialize()\n    names = [t.name for t in (await session.list_tools()).tools]\nif tool_name not in names:\n    close = [n for n in names if n.casefold() == tool_name.casefold()]\n    raise ValueError(f\"{tool_name!r} not in {names}; closest: {close}\")","typeGuard":null,"tryCatchPattern":"try:\n    adapter = await McpToolAdapter.from_server_params(params, name)\nexcept ValueError as e:\n    if \"not found\" in str(e):\n        # message lists available tools; pick the right one and retry once\n        available = parse_available_tools(str(e))\n        name = next(n for n in available if n.casefold() == name.casefold())\n        adapter = await McpToolAdapter.from_server_params(params, name)\n    else:\n        raise","preventionTips":["Discover tool names via list_tools at startup and bind adapters by resolved name.","Pin MCP server versions whose tool names your prompts/agents reference.","Log available tools once at connection so mismatches are debuggable."],"tags":["mcp","discovery","tool-name","naming"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}