oraios/serena · error · ValueError

Invalid tool name: {tool_name}{caller_context_for_logging}

Error message

Invalid tool name: {tool_name}{caller_context_for_logging}

What it means

Tool.check_valid_tool_name validates a tool name before use: names in the deleted-tools set return False (logged warning), while names that are not valid (not registered and not known) raise ValueError. It is called from Tool.apply to reject calls to tools that do not exist in the current registry.

Source

Thrown at src/serena/tools/tools_base.py:689

                tools = self.get_tool_classes_default_enabled()

        tool_dict: dict[str, type[Tool] | Tool] = {}
        for tool_class in tools:
            tool_dict[tool_class.get_name_from_cls()] = tool_class
        for tool_name in sorted(tool_dict.keys()):
            tool_class = tool_dict[tool_name]
            print(f" * `{tool_name}`: {tool_class.get_tool_description().strip()}")

    def is_valid_tool_name(self, tool_name: str) -> bool:
        return tool_name in self._tool_dict

    def check_valid_tool_name(self, tool_name: str, caller_context_for_logging: str = "") -> bool:
        """Returns True if the tool name is valid, False if it is deleted, and raises ValueError if it is invalid."""
        if self.is_deleted_tool_name(tool_name):
            log.warning(f"Tool name is deleted: {tool_name}{caller_context_for_logging}")
            return False
        if not self.is_valid_tool_name(tool_name):
            raise ValueError(f"Invalid tool name: {tool_name}{caller_context_for_logging}")
        return True

    def is_deleted_tool_name(self, tool_name: str) -> bool:
        return tool_name in self._deleted_tools

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Verify the tool name against the list exposed to the client (tools/list or registry listing) and fix the name
2. Check if the tool was renamed/deleted in the current Serena version and use the new name
3. Ensure the active tool context/_mode includes the tool before calling it
4. Catch ValueError and return a helpful message to the agent listing valid tools

Example fix

// before
if registry.check_valid_tool_name(tool_name):
    apply_tool(tool_name)
// after
try:
    if registry.check_valid_tool_name(tool_name):
        apply_tool(tool_name)
except ValueError:
    log.warning(f"Unknown tool {tool_name}; valid: {registry.get_all_tool_names()}")

valid = registry.check_valid_tool_name(tool_name, caller_context_for_logging=" from my_client")
if valid:
    tool.apply(...)

def is_valid_tool(registry, name: str) -> bool:
    try:
        return registry.check_valid_tool_name(name)
    except ValueError:
        return False

When it happens

Trigger: Calling apply (or check_valid_tool_name directly) with a tool_name that is neither a deleted name nor a valid registered tool name — typically a typo or a tool from another Serena version/context.

Common situations: LLM agent hallucinating a tool name; client caches stale tool lists after server config changed; renamed tools between versions; requesting context-inactive tools.

Related errors

• Tool named '{tool_name}' not found.
• Invalid topic: {topic}
• Pass either content or source_file_path
• Invalid glob brace expression in {pattern!r}: empty braces a
• Invalid glob brace expression in {pattern!r}: unmatched brac

AI-assisted analysis of oraios/serena@7fcbca7e62 (2026-08-29). Data as JSON: /api/errors/7348b28ff98725a8. Report an issue: GitHub.