Add JetBrainsGetSymbolsOverviewTool

src/serena/resources/config/internal_modes/jetbrains.yml

@@ -6,6 +6,8 @@ prompt: |
 excluded_tools:
   - find_symbol
   - find_referencing_symbols
+  - get_symbols_overview
 included_optional_tools:
   - jet_brains_find_symbol
-  - jet_brains_find_symbol_references
+  - jet_brains_find_symbol_references
+  - jet_brains_get_symbols_overview

src/serena/tools/jetbrains_plugin_client.py

@@ -99,7 +99,6 @@ class JetBrainsPluginClient:
         :return: Dictionary containing 'symbols' list with matching symbols
         """
         request_data = {"namePath": name_path, "relativePath": relative_path, "includeBody": include_body, "depth": depth}
-
         return self._make_request("POST", "/findSymbol", request_data)
 
     def find_references(self, name_path: str, relative_path: str) -> dict[str, Any]:
@@ -111,9 +110,15 @@ class JetBrainsPluginClient:
         :return: dictionary containing 'symbols' list with symbol references
         """
         request_data = {"namePath": name_path, "relativePath": relative_path}
-
         return self._make_request("POST", "/findReferences", request_data)
 
+    def get_symbols_overview(self, relative_path: str) -> dict[str, Any]:
+        """
+        :param relative_path: the relative path to a source file
+        """
+        request_data = {"relativePath": relative_path}
+        return self._make_request("POST", "/getSymbolsOverview", request_data)
+
     def is_service_available(self) -> bool:
         try:
             response = self.heartbeat()

src/serena/tools/jetbrains_tools.py

@@ -98,3 +98,29 @@ class JetBrainsFindSymbolReferencesTool(Tool, ToolMarkerOptional):
             )
             result = json.dumps(response_dict)
         return self._limit_length(result, max_answer_chars)
+
+
+class JetBrainsGetSymbolsOverviewTool(Tool, ToolMarkerOptional):
+    """
+    Retrieves an overview of the top-level symbols within a specified file
+    """
+
+    def apply(
+        self,
+        relative_path: str,
+        max_answer_chars: int = TOOL_DEFAULT_MAX_ANSWER_LENGTH,
+    ) -> str:
+        """
+        Gets an overview of the top-level symbols in the given file.
+        Calling this is often a good idea before more targeted reading, searching or editing operations on the code symbols.
+
+        :param relative_path: the relative path to the file to get the overview of
+        :param max_answer_chars: max characters for the JSON result. If exceeded, no content is returned.
+        :return: a JSON object containing the symbols
+        """
+        with JetBrainsPluginClient() as client:
+            response_dict = client.get_symbols_overview(
+                relative_path=relative_path,
+            )
+            result = json.dumps(response_dict)
+        return self._limit_length(result, max_answer_chars)