Serena

Instructions

Implementation Reference

• src/serena/tools/symbol_tools.py:47-77 (handler)

  The apply method implements the core logic of the 'get_symbols_overview' tool. It validates the file path, retrieves the symbol overview using the LanguageServerSymbolRetriever, converts to JSON, and limits the response length.
  class GetSymbolsOverviewTool(Tool, ToolMarkerSymbolicRead): """ Gets an overview of the top-level symbols defined in a given file. """ def apply(self, relative_path: str, depth: int = 0, max_answer_chars: int = -1) -> str: """ Use this tool to get a high-level understanding of the code symbols in a file. This should be the first tool to call when you want to understand a new file, unless you already know what you are looking for. :param relative_path: the relative path to the file to get the overview of :param depth: depth up to which descendants of top-level symbols shall be retrieved (e.g. 1 retrieves immediate children). Default 0. :param max_answer_chars: if the overview is longer than this number of characters, no content will be returned. -1 means the default value from the config will be used. Don't adjust unless there is really no other way to get the content required for the task. :return: a JSON object containing info about top-level symbols in the file """ symbol_retriever = self.create_language_server_symbol_retriever() file_path = os.path.join(self.project.project_root, relative_path) # The symbol overview is capable of working with both files and directories, # but we want to ensure that the user provides a file path. if not os.path.exists(file_path): raise FileNotFoundError(f"File or directory {relative_path} does not exist in the project.") if os.path.isdir(file_path): raise ValueError(f"Expected a file path, but got a directory path: {relative_path}. ") result = symbol_retriever.get_symbol_overview(relative_path, depth=depth)[relative_path] result_json_str = self._to_json(result) return self._limit_length(result_json_str, max_answer_chars)
• src/serena/tools/tools_base.py:359-366 (registration)

  The ToolRegistry automatically discovers and registers all subclasses of Tool in the serena.tools package, including GetSymbolsOverviewTool under the name 'get_symbols_overview'.
  for cls in iter_subclasses(Tool): if not any(cls.__module__.startswith(pkg) for pkg in tool_packages): continue is_optional = issubclass(cls, ToolMarkerOptional) name = cls.get_name_from_cls() if name in self._tool_dict: raise ValueError(f"Duplicate tool name found: {name}. Tool classes must have unique names.") self._tool_dict[name] = RegisteredTool(tool_class=cls, is_optional=is_optional, tool_name=name)
• src/serena/tools/tools_base.py:180-194 (schema)

  Generates FuncMetadata from the apply method's signature and docstring, which is used to define the MCP tool schema for input parameters and description.
  def get_apply_fn_metadata_from_cls(cls) -> FuncMetadata: """Get the metadata for the apply method from the class (static metadata). Needed for creating MCP tools in a separate process without running into serialization issues. """ # First try to get from __dict__ to handle dynamic docstring changes if "apply" in cls.__dict__: apply_fn = cls.__dict__["apply"] else: # Fall back to getattr for inherited methods apply_fn = getattr(cls, "apply", None) if apply_fn is None: raise AttributeError(f"apply method not defined in {cls}. Did you forget to implement it?") return func_metadata(apply_fn, skip_names=["self", "cls"])
• src/serena/tools/tools_base.py:118-125 (helper)

  Derives the MCP tool name 'get_symbols_overview' from the class name 'GetSymbolsOverviewTool' by removing 'Tool' suffix and converting to snake_case.
  @classmethod def get_name_from_cls(cls) -> str: name = cls.__name__ if name.endswith("Tool"): name = name[:-4] # convert to snake_case name = "".join(["_" + c.lower() if c.isupper() else c for c in name]).lstrip("_") return name