huggingface/smolagents · error · AgentToolCallError

{e}

Error message

{e}

What it means

execute_tool_call first validates arguments via validate_tool_arguments. ValueError/TypeError from validation (missing required args, wrong types) are re-raised as AgentToolCallError with the validator's message; any other exception during validation becomes AgentToolExecutionError. These are fed back to the model so it can correct its arguments.

Source

Thrown at src/smolagents/agents.py:1478

            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
            if isinstance(arguments, dict):
                return tool(**arguments) if is_managed_agent else tool(**arguments, sanitize_inputs_outputs=True)
            else:
                return tool(arguments) if is_managed_agent else tool(arguments, sanitize_inputs_outputs=True)

        except Exception as e:
            # Handle execution errors
            if is_managed_agent:
                error_msg = (
                    f"Error executing request to team member '{tool_name}' with arguments {str(arguments)}: {e}\n"
                    "Please try again or request to another team member"
                )

View on GitHub (pinned to 30bb116109)

Solutions

1. Read the message — it states which argument failed validation; adjust the tool's defaults/types so the model can succeed.
2. Give required parameters sensible defaults or make the docstring examples explicit about format.
3. Retry the run — the AgentToolCallError observation is appended to memory and the model usually corrects the call.

Example fix

# before
def get_weather(city: str, units: str): ...  # model omits 'units'

# after
def get_weather(city: str, units: str = 'celsius'): ...

from smolagents.tool_validation import validate_tool_arguments

# dry-run validation before the agent loop (tool + sample args)
try:
    validate_tool_arguments(tool, expected_args)
except (ValueError, TypeError) as e:
    print('adjust defaults:', e)

from smolagents.exceptions import AgentToolCallError

try:
    result = agent.run(task)
except AgentToolCallError:
    result = agent.run(task)  # model retries with corrected arguments

When it happens

Trigger: The model calls a tool with a missing required parameter, an extra parameter, or wrongly typed arguments (e.g. passing a string where an int is declared), and validate_tool_arguments raises ValueError/TypeError.

Common situations: Tool signatures with required params the model doesn't reliably fill; type-annotated tools (forward refs, Pydantic types) the validator can't introspect; models with weak schema adherence.

Related errors

• Attribute {attr} should have type {expected_type.__name__},
• Check {check_function.__name__} failed with error: {e}
• Object is not iterable
• Cannot add non-list value {value_to_add} to a list.
• Cannot unpack non-tuple value

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