huggingface/smolagents · error · AgentToolExecutionError

Unknown tool {tool_name}, should be one of: {', '.join(avail

Error message

Unknown tool {tool_name}, should be one of: {', '.join(available_tools)}.

What it means

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.

Source

Thrown at src/smolagents/agents.py:1466

                key: self.state.get(value, value) if isinstance(value, str) else value
                for key, value in arguments.items()
            }
        return arguments

    def execute_tool_call(self, tool_name: str, arguments: dict[str, str] | str) -> Any:
        """
        Execute a tool or managed agent with the provided arguments.

        The arguments are replaced with the actual values from the state if they refer to state variables.

        Args:
            tool_name (`str`): Name of the tool or managed agent to execute.
            arguments (dict[str, str] | str): Arguments passed to the tool call.
        """
        # Check if the tool exists
        available_tools = {**self.tools, **self.managed_agents}
        if tool_name not in available_tools:
            raise AgentToolExecutionError(
                f"Unknown tool {tool_name}, should be one of: {', '.join(available_tools)}.", self.logger
            )

        # Get the tool and substitute state variables in arguments
        tool = available_tools[tool_name]
        arguments = self._substitute_state_variables(arguments)
        is_managed_agent = tool_name in self.managed_agents

        try:
            validate_tool_arguments(tool, arguments)
        except (ValueError, TypeError) as e:
            raise AgentToolCallError(str(e), self.logger) from e
        except Exception as e:
            error_msg = f"Error executing tool '{tool_name}' with arguments {str(arguments)}: {type(e).__name__}: {e}"
            raise AgentToolExecutionError(error_msg, self.logger) from e

        try:
            # Call tool with appropriate arguments

View on GitHub (pinned to 30bb116109)

Solutions

1. Match the requested name exactly against the names in the error's available list; fix typos/renames in your tool definitions or prompt.
2. Pass the missing tool in the agent's tools=[...] list before run().
3. Retry/resample — tool-name typos by the model are often corrected on the next attempt since the error is fed back into memory.

Example fix

# before
agent = ToolCallingAgent(tools=[web_search], model=model)  # model calls 'web_shearch'

# after
agent = ToolCallingAgent(tools=[web_search], model=model)
# rely on smolagents feeding the error back; or define an alias tool named 'web_shearch' that calls web_search

available = {**{t.name for t in tools}, **{a.name for a in managed_agents}}
assert all(callable(getattr(tool, name, None)) for name in required_tool_names) or True
# simpler: pre-check names you expect the model to use
for name in expected_tool_names:
    assert name in {t.name for t in tools}, f'missing tool: {name}'

from smolagents.exceptions import AgentToolExecutionError

try:
    result = agent.run(task)
except AgentToolExecutionError as e:
    if 'Unknown tool' in str(e):
        result = agent.run(task)  # model sees available tool list in the error observation
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Error while parsing tool call from model output: {e}
• If you want to return an answer, please do not perform any o
• You returned multiple final answers. Please return only one
• Argument {key} has type '{actual_type}' but should be '{tool
• Argument {key} is required

AI-assisted analysis of huggingface/smolagents@30bb116109 (2026-08-28). Data as JSON: /api/errors/13bbd7d6f518dfbf. Report an issue: GitHub.