agentscope-ai/agentscope · error · ValueError

The 'basic' tool group is reserved for the default tool grou

Error message

The 'basic' tool group is reserved for the default tool group. Don't include 'basic' in the tool_groups argument when you also provide tools, skills or mcps in the constructor.

What it means

Toolkit.__init__ rejects a tool_groups list that contains a group named 'basic': that name is reserved for the implicit default group holding constructor-level tools/skills/mcps.

Source

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

                The tool objects that belong to the "basic" tool group.
            skills_or_loaders (`list[str | Skill | SkillLoaderBase] | None`, \
            optional):
                The agent skill directories to be registered in the "basic"
                tool group.
            mcps (`list[MCPClient] | None`, optional):
                The mcp clients to be registered in the "basic" tool group.
            tool_groups (`list[ToolGroup] | None`, optional):
                The tool groups to be registered.
            meta_tool_response_template (`str`, optional):
                The template for meta tool responses.
            skill_instruction_template (`str`):
                A Jinja2 template for generating the agent skill instruction.
        """

        if tool_groups is not None and any(
            _.name == "basic" for _ in tool_groups
        ):
            raise ValueError(
                "The 'basic' tool group is reserved for the default tool "
                "group. Don't include 'basic' in the tool_groups argument "
                "when you also provide tools, skills or mcps in the "
                "constructor.",
            )

        self.tool_groups = [
            ToolGroup(
                name="basic",
                tools=tools or [],
                skills_or_loaders=skills_or_loaders or [],
                mcps=mcps or [],
            ),
        ] + (tool_groups or [])

        # Check name conflict for tool groups
        if len(set(_.name for _ in self.tool_groups)) != len(
            self.tool_groups,

View on GitHub (pinned to e90f1c7592)

Solutions

1. Rename your group to something other than 'basic'
2. Move those tools/skills to the Toolkit constructor's top-level arguments if they belong in the default group

Example fix

# before
Toolkit(tools=[t], tool_groups=[ToolGroup(name='basic', description='d', skills=[s])])
# after
Toolkit(tools=[t], skills=[s])

assert not any(g.name == 'basic' for g in tool_groups or [])

When it happens

Trigger: Toolkit(tools=[...], tool_groups=[ToolGroup(name='basic', ...)]) — mixing an explicitly named 'basic' group with top-level tools/skills/mcps.

Common situations: Copying an example ToolGroup config and forgetting to rename it; assembling groups dynamically and colliding with the reserved name.

Related errors

• Invalid logging level: {level}. Must be one of 'INFO', 'DEBU
• The 'reserve_ratio' of the context config must be smaller th
• The 'context_buffer_ratio' of the injection config must be s
• Input validation failed for tool '{tool_call.name}': {e.mess
• The injection template must contain the '{runtime_state}' pl

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