langchain-ai/langchain · error · ToolException

Too many arguments to single-input tool {self.name}.

Error message

Too many arguments to single-input tool {self.name}.
                Consider using StructuredTool instead. Args: {all_args}

What it means

Tool (the single-input tool class) accepts exactly one argument per invocation. After converting the input to args/kwargs, more than one value was present, so it raises ToolException (runtime, model-visible) suggesting StructuredTool for multi-argument tools.

Source

Thrown at libs/core/langchain_core/tools/simple.py:96

            tool_input: The input to the tool.
            tool_call_id: The ID of the tool call.

        Raises:
            ToolException: If the tool input is invalid.

        Returns:
            The Pydantic model args and kwargs.
        """
        args, kwargs = super()._to_args_and_kwargs(tool_input, tool_call_id)
        # For backwards compatibility. The tool must be run with a single input
        all_args = list(args) + list(kwargs.values())
        if len(all_args) != 1:
            msg = (
                f"""Too many arguments to single-input tool {self.name}.
                Consider using StructuredTool instead."""
                f" Args: {all_args}"
            )
            raise ToolException(msg)
        return tuple(all_args), {}

    def _run(
        self,
        *args: Any,
        config: RunnableConfig,
        run_manager: CallbackManagerForToolRun | None = None,
        **kwargs: Any,
    ) -> Any:
        """Use the tool.

        Args:
            *args: Positional arguments to pass to the tool
            config: Configuration for the run
            run_manager: Optional callback manager to use for the run
            **kwargs: Keyword arguments to pass to the tool

        Returns:

View on GitHub (pinned to e32fa9a52e)

Solutions

1. Switch to StructuredTool / @tool with a typed function for multi-argument tools
2. Make the tool's input schema explicit (args_schema with a single field) so the model only sends one argument
3. If extra args come from the model, tighten the tool description/schema so only the expected argument is produced

Example fix

# before
my_tool = Tool(name="search", func=lambda q: search(q), description="Search")
my_tool.invoke({"query": "cats", "limit": 5})   # ToolException

# after
@tool
def search(query: str, limit: int = 5) -> str:
    """Search with an optional limit."""
    return _search(query, limit)

def invoke_single_input_tool(tool, tool_input):
    """Coerce to exactly one value before invoking a single-input Tool."""
    if isinstance(tool_input, dict):
        values = list(tool_input.values())
        if len(values) != 1:
            msg = f"Expected exactly 1 argument, got {len(values)}: {tool_input}"
            raise ValueError(msg)
        tool_input = values[0]
    return tool.invoke(tool_input)

def is_single_value_input(x: object) -> bool:
    return not isinstance(x, dict) or len(x) == 1

from langchain_core.tools import ToolException

try:
    out = tool.invoke(payload)
except ToolException as e:
    if "Too many arguments" in str(e):
        out = structured_tool.invoke(payload)  # retry via multi-arg tool
    else:
        raise

When it happens

Trigger: Tool(func).invoke({'a': 1, 'b': 2}); a single-input tool invoked by a model that generated multiple arguments; tool.run('x', 'y').

Common situations: An LLM hallucinating extra parameters for a string-input tool; schemas not constrained so the model passes dicts with several keys; using Tool where the underlying function really needs multiple parameters.

Related errors

• Runnable must have an object schema.
• Tool input must be str or dict. If dict, dict arguments must
• Invalid args_schema: expected BaseModel or dict, got {args_s
• Function must have either a docstring or description when in
• Too many arguments for tool decorator. A decorator

AI-assisted analysis of langchain-ai/langchain@e32fa9a52e (2026-08-14). Data as JSON: /api/errors/5da401dece940c9d. Report an issue: GitHub.