agentscope-ai/agentscope · error · ValueError

The tool group description is required for tool group '{name

Error message

The tool group description is required for tool group '{name}' (Only the 'basic' tool group can have an optional description).

What it means

ToolGroup.__init__ requires a description for every group except the reserved 'basic' one; creating a named group without a description raises ValueError.

Source

Thrown at src/agentscope/tool/_tool_group.py:72

            name (`Literal["basic"] | str`):
                The name of the tool group.
            description (`str | None`):
                The description of the tool group.
            instructions (`str | None`, optional):
                Instructions included in the meta tool's result upon
                activation of this tool group, guiding the agent on how to
                properly use the meta tool.
            tools (`list[ToolBase] | None`, optional):
                The tools in this group.
            skills_or_loaders (`list[str | Skill | SkillLoaderBase] | None`, \
            optional):
                The skill paths, data, and loaders to access skills in this
                group.
            mcps (`list[MCPClient] | None`, optional):
                The mcps in this group.
        """
        if name != "basic" and description is None:
            raise ValueError(
                f"The tool group description is required for tool group "
                f"'{name}' (Only the 'basic' tool group can have an optional "
                f"description).",
            )

        self.name = name
        self.description = description or ""
        self.instructions = instructions
        self.tools = tools or []
        self.mcps = mcps or []

        # Skill
        self.skills_or_loaders = []
        for _ in skills_or_loaders or []:
            if isinstance(_, str):
                self.skills_or_loaders.append(LocalSkillLoader(directory=_))

            elif isinstance(_, (Skill, SkillLoaderBase)):

View on GitHub (pinned to e90f1c7592)

Solutions

1. Provide a short description for each non-basic group
2. Default description when loading config: ToolGroup(name=n, description=cfg.get('description') or f'Tools for {n}')
3. Only 'basic' may omit it

Example fix

# before
g = ToolGroup(name='search', skills=[...])
# after
g = ToolGroup(name='search', description='Web and file search tools', skills=[...])

desc = description or (None if name == 'basic' else f'Tools for {name}')

When it happens

Trigger: ToolGroup(name='search', skills=[...]) with description=None — e.g. building groups programmatically from user config that omits descriptions.

Common situations: YAML/JSON agent configs where only some groups have descriptions; assuming the description is optional for all groups after seeing 'basic' work without one.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• "Mem0Middleware requires a non-empty `user_id`."
• The table_format must be one of 'markdown' or 'json', got {t
• num_candidates must be between 1 and 10000
• Either client_gen or session must be provided, but not both.
• Invalid skill or loader: {_}. Must be a skill, skill loader,

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