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