Update tool descriptions

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/serena/tools/file_tools.py

@@ -34,7 +34,7 @@ class ReadFileTool(Tool):
         Reads the given file or a chunk of it.
 
         :param relative_path: the relative path to the file to read
-        :param start_line: the 0-based index of the first line to be retrieved.
+        :param start_line: the 0-based index of the first line to be retrieved, negative values count from the end of the file.
         :param end_line: the 0-based index of the last line to be retrieved (inclusive). If None, read until the end of the file.
         :param max_answer_chars: if the file (chunk) is longer than this number of characters,
             no content will be returned. Don't adjust unless there is really no other way to get the content
@@ -61,7 +61,7 @@ class CreateTextFileTool(EditingToolWithDiagnostics):
 
     def apply(self, relative_path: str, content: str) -> str:
         """
-        Write a new file or overwrite an existing file.
+        Write a new file or overwrite an existing file with the given content.
 
         :param relative_path: the relative path to the file to create
         :param content: the (appropriately encoded) content to write to the file
@@ -182,16 +182,12 @@ class ReplaceContentTool(EditingToolWithDiagnostics):
         r"""
         Replaces one or more occurrences of a given pattern in a file with new content.
 
-        This is the preferred way to replace content in a file whenever the symbol-level
-        tools are not appropriate.
-
-        VERY IMPORTANT: The "regex" mode allows very large sections of code to be replaced without fully quoting them!
-        Use a regex of the form "beginning.*?end-of-text-to-be-replaced" to be faster and more economical!
-        ALWAYS try to use wildcards to avoid specifying the exact content to be replaced,
-        especially if it spans several lines. Note that you cannot make mistakes, because if the regex should match
-        multiple occurrences while you disabled `allow_multiple_occurrences`, an error will be returned, and you can retry
-        with a revised regex.
-        Therefore, using regex mode with suitable wildcards is usually the best choice!
+        VERY IMPORTANT: The "regex" mode allows very large sections of code to be replaced WITHOUT
+        quoting them fully: use a needle of the form "beginning.*?end-of-text-to-be-replaced" with
+        wildcards instead of pasting the exact original text — shorter, cheaper, and you cannot make
+        mistakes, because an ambiguous match returns an error you can refine, so wildcards are safe.
+        Prefer regex mode with suitable wildcards for long multi-line replacements; use the
+        symbol-level editors when replacing a whole method/class.
 
         :param relative_path: the relative path to the file
         :param needle: the string or regex pattern to search for.

src/serena/tools/jetbrains_tools.py

@@ -40,6 +40,7 @@ class JetBrainsFindSymbolTool(Tool, ToolMarkerSymbolicRead, ToolMarkerOptional):
         Specify `depth > 0` to retrieve children (e.g., methods of a class).
         Important: through `search_deps=True` dependencies can be searched, which
         should be preferred to web search or other less sophisticated approaches to analyzing dependencies.
+        You will always receive at least quick info on the symbol (even if `include_info=False`).
 
         A name path is a path in the symbol tree *within a source file*.
         For example, the method `my_method` defined in class `MyClass` would have the name path `MyClass/my_method`.
@@ -52,6 +53,7 @@ class JetBrainsFindSymbolTool(Tool, ToolMarkerSymbolicRead, ToolMarkerOptional):
          * a relative path like "class/method", which will match any symbol with that name path suffix
          * an absolute name path "/class/method" (absolute name path), which requires an exact match of the full name path within the source file.
         Append an index `[i]` to match a specific overload only, e.g. "MyClass/my_method[1]".
+        In any path component, using `*` will match any sequence of characters (excluding /), e.g. "Class/*substring*" matches a member substring.
 
         :param name_path_pattern: the name path matching pattern (see above)
         :param depth: depth up to which descendants shall be retrieved (e.g. use 1 to also retrieve immediate children;
@@ -60,7 +62,7 @@ class JetBrainsFindSymbolTool(Tool, ToolMarkerSymbolicRead, ToolMarkerOptional):
         :param relative_path: Optional. Restrict search to this file or directory. If not specified, searches entire codebase.
             Note: for external dependencies, this must be an identifier starting with `<ext` that you have received
             earlier (don't try to guess!).
-        :param include_body: If True, include the symbol's source code. Use judiciously.
+        :param include_body: If True, include the symbol's full source code.
         :param include_info: whether to include additional info (hover-like, typically including docstring and signature),
             about the symbol.
             Default False; info is never included for child symbols or if include_body is True.
@@ -265,8 +267,9 @@ class JetBrainsFindReferencingSymbolsTool(Tool, ToolMarkerSymbolicRead, ToolMark
         max_answer_chars: int = -1,
     ) -> str:
         """
-        Finds symbols that reference the symbol at the specified symbol, i.e. returns symbols whose definitions (e.g. a function body) contain a reference to the given symbol.
-        The result will contain metadata about the referencing symbols.
+        Finds all symbols that reference the given symbol — its callers / usages / dependents, i.e. the
+        symbols whose own definition (e.g. a method body) contains a reference to it. For each, returns its
+        name path, file, and the surrounding line of code.
 
         :param name_path: name path of the symbol for which to find references
         :param relative_path: the relative path to the file containing the symbol (must be a file, not a directory)
@@ -328,11 +331,9 @@ class JetBrainsGetSymbolsOverviewTool(Tool, ToolMarkerSymbolicRead, ToolMarkerOp
         include_file_documentation: bool = False,
     ) -> 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.
-        Before requesting a symbol overview, it is usually a good idea to narrow down the scope of the overview
-        by first understanding the basic directory structure of the repository that you can get from memories
-        or by using the `list_dir` and `find_file` tools (or similar).
+        Gets an overview of the top-level symbols defined in the given file (classes, methods, fields) — its
+        STRUCTURE, without their bodies. This is the cheap, structure-first way to learn what a file
+        contains: it costs far less context than reading the whole file.
 
         :param relative_path: the relative path to the file to get the overview of
         :param depth: depth up to which descendants shall be retrieved.
@@ -590,8 +591,8 @@ class JetBrainsDebugTool(Tool, ToolMarkerOptional, ToolMarkerBeta):
         repl_key: str = "default",
     ) -> str:
         """
-        Debug code interactively by evaluating Groovy expressions in a persistent REPL.
-        Important: Debugging should only be applied if the user has requested it!
+        Debug code by evaluating Groovy/Java expressions in a persistent REPL attached to the IDE's
+        debugger (run configs, breakpoints, stepping, inspection of live state).
 
         Use the `serena_info` tool with topic `jet_brains_debug_repl` for usage information.