{"record":{"id":"13bbd7d6f518dfbf","repo":"huggingface/smolagents","slug":"unknown-tool-tool-name-should-be-one-of","errorCode":null,"errorMessage":"Unknown tool {tool_name}, should be one of: {', '.join(available_tools)}.","messagePattern":"Unknown tool (.+?), should be one of: (.+?)\\.","errorType":"exception","errorClass":"AgentToolExecutionError","httpStatus":null,"severity":"error","filePath":"src/smolagents/agents.py","lineNumber":1466,"sourceCode":"                key: self.state.get(value, value) if isinstance(value, str) else value\n                for key, value in arguments.items()\n            }\n        return arguments\n\n    def execute_tool_call(self, tool_name: str, arguments: dict[str, str] | str) -> Any:\n        \"\"\"\n        Execute a tool or managed agent with the provided arguments.\n\n        The arguments are replaced with the actual values from the state if they refer to state variables.\n\n        Args:\n            tool_name (`str`): Name of the tool or managed agent to execute.\n            arguments (dict[str, str] | str): Arguments passed to the tool call.\n        \"\"\"\n        # Check if the tool exists\n        available_tools = {**self.tools, **self.managed_agents}\n        if tool_name not in available_tools:\n            raise AgentToolExecutionError(\n                f\"Unknown tool {tool_name}, should be one of: {', '.join(available_tools)}.\", self.logger\n            )\n\n        # Get the tool and substitute state variables in arguments\n        tool = available_tools[tool_name]\n        arguments = self._substitute_state_variables(arguments)\n        is_managed_agent = tool_name in self.managed_agents\n\n        try:\n            validate_tool_arguments(tool, arguments)\n        except (ValueError, TypeError) as e:\n            raise AgentToolCallError(str(e), self.logger) from e\n        except Exception as e:\n            error_msg = f\"Error executing tool '{tool_name}' with arguments {str(arguments)}: {type(e).__name__}: {e}\"\n            raise AgentToolExecutionError(error_msg, self.logger) from e\n\n        try:\n            # Call tool with appropriate arguments","sourceCodeStart":1448,"sourceCodeEnd":1484,"githubUrl":"https://github.com/huggingface/smolagents/blob/30bb1161095dbae2271e6bc3cc4c219cc3897a57/src/smolagents/agents.py#L1448-L1484","documentation":"ToolCallingAgent.execute_tool_call resolves the requested tool name against the merged dict of self.tools and self.managed_agents. A name absent from both raises AgentToolExecutionError listing the available names — the model hallucinated a tool or the developer never attached it.","triggerScenarios":"The LLM emits a tool call named e.g. 'web_shearch' or 'calculator' when only 'web_search' was passed in tools=[...]; also calling execute_tool_call directly with an unregistered name.","commonSituations":"Tool renamed/refactored but prompts or examples still reference the old name; model hallucinating tool names not in the system prompt; forgetting to pass a tool when constructing the agent.","solutions":["Match the requested name exactly against the names in the error's available list; fix typos/renames in your tool definitions or prompt.","Pass the missing tool in the agent's tools=[...] list before run().","Retry/resample — tool-name typos by the model are often corrected on the next attempt since the error is fed back into memory."],"exampleFix":"# before\nagent = ToolCallingAgent(tools=[web_search], model=model)  # model calls 'web_shearch'\n\n# after\nagent = ToolCallingAgent(tools=[web_search], model=model)\n# rely on smolagents feeding the error back; or define an alias tool named 'web_shearch' that calls web_search","handlingStrategy":"fallback","validationCode":"available = {**{t.name for t in tools}, **{a.name for a in managed_agents}}\nassert all(callable(getattr(tool, name, None)) for name in required_tool_names) or True\n# simpler: pre-check names you expect the model to use\nfor name in expected_tool_names:\n    assert name in {t.name for t in tools}, f'missing tool: {name}'","typeGuard":null,"tryCatchPattern":"from smolagents.exceptions import AgentToolExecutionError\n\ntry:\n    result = agent.run(task)\nexcept AgentToolExecutionError as e:\n    if 'Unknown tool' in str(e):\n        result = agent.run(task)  # model sees available tool list in the error observation\n    else:\n        raise","preventionTips":["List tool names explicitly in the task/system prompt.","Keep tool names short, lowercase, and unambiguous.","Rely on smolagents feeding the error back to the model; retry rather than abort."],"tags":["smolagents","unknown-tool","tool-calling","hallucinated-name"],"backgroundTag":"unknown-tool-name","analyzedSha":"30bb1161095dbae2271e6bc3cc4c219cc3897a57","analyzedAt":"2026-08-28T18:52:54.169Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}