agentscope-ai/agentscope · error · ToolNotFoundError

ToolNotFoundError: The tool named '{tool_name}' doesn't exis

Error message

ToolNotFoundError: The tool named '{tool_name}' doesn't exist.

What it means

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.

Source

Thrown at src/agentscope/tool/_toolkit.py:591

        if tool_name not in tools:
            # The dict above is already filtered to the basic + activated
            # groups, so a tool from an inactive group is missing from it.
            # Look the name up across all registered groups to distinguish
            # "inactive" from "doesn't exist" - the same fallback call_tool
            # performs - so the agent gets the activation hint instead of a
            # misleading not-found error.
            all_tools = await self._get_available_tools(
                [_.name for _ in self.tool_groups],
            )
            if tool_name in all_tools:
                raise ToolGroupInactiveError(
                    f"ToolGroupInactiveError: The tool '{tool_name}' in "
                    f"group '{all_tools[tool_name].group}' is currently "
                    f"inactive. You should first activate the group by "
                    f"calling the "
                    f"'{self.builtin_meta_tool.tool.name}' tool.",
                )
            raise ToolNotFoundError(
                f"ToolNotFoundError: The tool named '{tool_name}' doesn't "
                f"exist.",
            )

        return tools[tool_name].tool

    async def get_tool(self, name: str) -> ToolBase | None:
        """Get tool instance by its name.

        Args:
            name (`str`):
                The name of the tool to be checked.

        Returns:
            `ToolBase | None`:
                The tool instance, or `None` if no tool is found.
        """
        tools = await self._get_available_tools(

View on GitHub (pinned to e90f1c7592)

Solutions

1. Verify the exact tool name against the toolkit's tool schemas (e.g. print the names from get_tool_schemas)
2. Check the tool wasn't removed with remove_tool and that the agent is wired to the right Toolkit instance
3. Catch ToolNotFoundError and feed the message back to the LLM so it can retry with a valid tool name

Example fix

# before
await toolkit.call_tool('searchdocument', {...})
# after
await toolkit.call_tool('search_documents', {...})

known = {name for name, _ in (await toolkit.get_tool_schemas()).items()}
if tool_name not in known:
    raise ValueError(f'{tool_name} not in {sorted(known)}')

def is_known_tool(name: str, known: set[str]) -> bool:
    return name in known

try:
    await toolkit.call_tool(name, args)
except ToolNotFoundError as e:
    # surface valid tool names to the LLM for retry

When it happens

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

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

Related errors

• <system-reminder>{error_message} Your argument string is de
• Session '{session_id}' not found.
• Knowledge base {knowledge_base_id!r} not found.
• Credential {record.data.embedding_model_config.credential_id
• Session {session_id!r} not found.

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/3d2410772012de93. Report an issue: GitHub.