{"record":{"id":"3d2410772012de93","repo":"agentscope-ai/agentscope","slug":"toolnotfounderror-the-tool-named-tool-name-do","errorCode":null,"errorMessage":"ToolNotFoundError: The tool named '{tool_name}' doesn't exist.","messagePattern":"ToolNotFoundError: The tool named '(.+?)' doesn't exist\\.","errorType":"exception","errorClass":"ToolNotFoundError","httpStatus":null,"severity":"error","filePath":"src/agentscope/tool/_toolkit.py","lineNumber":591,"sourceCode":"        if tool_name not in tools:\n            # The dict above is already filtered to the basic + activated\n            # groups, so a tool from an inactive group is missing from it.\n            # Look the name up across all registered groups to distinguish\n            # \"inactive\" from \"doesn't exist\" - the same fallback call_tool\n            # performs - so the agent gets the activation hint instead of a\n            # misleading not-found error.\n            all_tools = await self._get_available_tools(\n                [_.name for _ in self.tool_groups],\n            )\n            if tool_name in all_tools:\n                raise ToolGroupInactiveError(\n                    f\"ToolGroupInactiveError: The tool '{tool_name}' in \"\n                    f\"group '{all_tools[tool_name].group}' is currently \"\n                    f\"inactive. You should first activate the group by \"\n                    f\"calling the \"\n                    f\"'{self.builtin_meta_tool.tool.name}' tool.\",\n                )\n            raise ToolNotFoundError(\n                f\"ToolNotFoundError: The tool named '{tool_name}' doesn't \"\n                f\"exist.\",\n            )\n\n        return tools[tool_name].tool\n\n    async def get_tool(self, name: str) -> ToolBase | None:\n        \"\"\"Get tool instance by its name.\n\n        Args:\n            name (`str`):\n                The name of the tool to be checked.\n\n        Returns:\n            `ToolBase | None`:\n                The tool instance, or `None` if no tool is found.\n        \"\"\"\n        tools = await self._get_available_tools(","sourceCodeStart":573,"sourceCodeEnd":609,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/tool/_toolkit.py#L573-L609","documentation":"Raised by Toolkit.check_tool_available when the requested tool name does not exist anywhere in the toolkit — neither in active groups nor in inactive ones. It is the plain not-found counterpart to ToolGroupInactiveError.","triggerScenarios":"Calling a tool by a name that no registered tool (in any group, active or inactive) has: typos, hallucinated tool names from the LLM, or tools removed via remove_tool before use.","commonSituations":"LLM hallucinating a tool name not in the schema; typos in tool names; referencing a tool after remove_tool(); wrong toolkit instance used by the agent.","solutions":["Verify the exact tool name against the toolkit's tool schemas (e.g. print the names from get_tool_schemas)","Check the tool wasn't removed with remove_tool and that the agent is wired to the right Toolkit instance","Catch ToolNotFoundError and feed the message back to the LLM so it can retry with a valid tool name"],"exampleFix":"# before\nawait toolkit.call_tool('searchdocument', {...})\n# after\nawait toolkit.call_tool('search_documents', {...})","handlingStrategy":"type-guard","validationCode":"known = {name for name, _ in (await toolkit.get_tool_schemas()).items()}\nif tool_name not in known:\n    raise ValueError(f'{tool_name} not in {sorted(known)}')","typeGuard":"def is_known_tool(name: str, known: set[str]) -> bool:\n    return name in known","tryCatchPattern":"try:\n    await toolkit.call_tool(name, args)\nexcept ToolNotFoundError as e:\n    # surface valid tool names to the LLM for retry","preventionTips":["Pin tool names as constants instead of free-form strings","Return the available tool list in the error feedback loop to the model"],"tags":["toolkit","not-found","tool-name","llm"],"backgroundTag":"tool-not-found","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}