From 5b9600bcaf2dc600e263f25654eb62a963bd027c Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Thu, 14 May 2026 18:17:46 +0200 Subject: [PATCH] Make tool descriptions more amenable to tool search mechanisms Avoid referencing other tools' names, general improvements --- CHANGELOG.md | 3 ++ src/serena/tools/file_tools.py | 24 +++------------- src/serena/tools/symbol_tools.py | 48 ++++++++++++++------------------ 3 files changed, 28 insertions(+), 47 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d02ecd5b..2281bd76 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ Status of the `main` branch. Changes prior to the next official version change will appear here. +* General: + - Make tool descriptions more amenable to tool search mechanisms as now used in several clients (e.g. avoid referencing other tools' names, etc.) + * Language Servers: - No longer store temporary files (e.g. downloads) in `~/solidlsp_tmp`; instead, use OS-specific temporary directories - Add **GDScript** (Godot Engine) support. Serena connects over TCP to the Godot editor's built-in LSP server (port 6008, same for Godot 3 and 4) — no separate language server process to install. Godot major version is auto-detected from `config_version` in `project.godot`. Note: Godot's LSP does not implement `workspace/symbol`; first workspace-wide scans fall back to per-file requests and can be slow for large projects (results are cached to disk). See the [GDScript Setup Guide](https://oraios.github.io/serena/03-special-guides/godot_gdscript_setup_guide_for_serena.html) for details. Closes #1446. diff --git a/src/serena/tools/file_tools.py b/src/serena/tools/file_tools.py index c913ca60..7e6a2288 100644 --- a/src/serena/tools/file_tools.py +++ b/src/serena/tools/file_tools.py @@ -24,8 +24,7 @@ class ReadFileTool(Tool): def apply(self, relative_path: str, start_line: int = 0, end_line: int | None = None, max_answer_chars: int = -1) -> str: """ - Reads the given file or a chunk of it. Generally, symbolic operations - like find_symbol or find_referencing_symbols should be preferred if you know which symbols you are looking for. + 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. @@ -337,8 +336,7 @@ class SearchForPatternTool(Tool): """ Offers a flexible search for arbitrary patterns in the codebase, including the possibility to search in non-code files. - Generally, symbolic operations like find_symbol or find_referencing_symbols - should be preferred if you know which symbols you are looking for. + Prefer symbolic operations if you know which symbols you are looking for! Pattern Matching Logic: For each match, the returned result will contain the full lines where the @@ -350,16 +348,6 @@ class SearchForPatternTool(Tool): Be careful to not use greedy quantifiers unnecessarily, it is usually better to use non-greedy quantifiers like .*? to avoid matching too much content. - File Selection Logic: - The files in which the search is performed can be restricted very flexibly. - Using `restrict_search_to_code_files` is useful if you are only interested in code symbols (i.e., those - symbols that can be manipulated with symbolic tools like find_symbol). - You can also restrict the search to a specific file or directory, - and provide glob patterns to include or exclude certain files on top of that. - The globs are matched against relative file paths from the project root (not to the `relative_path` parameter that - is used to further restrict the search). - Smartly combining the various restrictions allows you to perform very targeted searches. - :param substring_pattern: Regular expression for a substring pattern to search for :param context_lines_before: Number of lines of context to include before each match :param context_lines_after: Number of lines of context to include after each match @@ -379,12 +367,8 @@ class SearchForPatternTool(Tool): Don't adjust unless there is really no other way to get the content required for the task. Instead, if the output is too long, you should make a stricter query. - :param restrict_search_to_code_files: whether to restrict the search to only those files where - analyzed code symbols can be found. Otherwise, will search all non-ignored files. - Set this to True if your search is only meant to discover code that can be manipulated with symbolic tools. - For example, for finding classes or methods from a name pattern. - Setting to False is a better choice if you also want to search in non-code files, like in html or yaml files, - which is why it is the default. + :param restrict_search_to_code_files: whether to restrict the search to source files. + Otherwise, will search all non-ignored files (default). :return: A mapping from file paths to matched consecutive lines (0-based line numbers). """ relative_path = relative_path.strip() diff --git a/src/serena/tools/symbol_tools.py b/src/serena/tools/symbol_tools.py index caa42b3a..2045c0c5 100644 --- a/src/serena/tools/symbol_tools.py +++ b/src/serena/tools/symbol_tools.py @@ -167,25 +167,20 @@ class FindSymbolTool(Tool, ToolMarkerSymbolicRead): :param depth: depth up to which descendants shall be retrieved (e.g. use 1 to also retrieve immediate children; for the case where the symbol is a class, this will return its methods). Ignored if `include_body=True`. Default 0. - :param relative_path: Optional. Restrict search to this file or directory. If None, searches entire codebase. + :param relative_path: (optional) restrict search to this file or directory. If None, searches entire codebase. If a directory is passed, the search will be restricted to the files in that directory. If a file is passed, the search will be restricted to that file. - If you have some knowledge about the codebase, you should use this parameter, as it will significantly - speed up the search as well as reduce the number of results. :param include_body: whether to include the symbol's source code. Use judiciously. :param include_info: whether to include additional info (hover-like, typically including docstring and signature), about the symbol (ignored if include_body is True). Info is never included for child symbols. Note: Depending on the language, this can be slow (e.g., C/C++). - :param include_kinds: List of LSP symbol kind integers to include. - If not provided, all kinds are included. - :param exclude_kinds: Optional. List of LSP symbol kind integers to exclude. Takes precedence over `include_kinds`. - If not provided, no kinds are excluded. + :param include_kinds: (optional) limits results to the given LSP symbol kinds (integers) + :param exclude_kinds: (optional) list of LSP symbol kinds (integers) to exclude. :param substring_matching: If True, use substring matching for the last element of the pattern, such that "Foo/get" would match "Foo/getValue" and "Foo/getData". - :param max_matches: Maximum number of permitted matches. If exceeded, a shortened result is returned + :param max_matches: maximum number of permitted matches. If exceeded, a shortened result is returned which allows refining the search. -1 (default) means no limit. Set to 1 if you search for a single symbol. - :param max_answer_chars: Max characters for the JSON result. If exceeded, no content is returned. - -1 means the default value from the config will be used. + :param max_answer_chars: max result length; -1 for default :return: symbols (with locations) matching the name. """ if include_body: @@ -260,13 +255,13 @@ class FindReferencingSymbolsTool(Tool, ToolMarkerSymbolicRead): Finds references to the symbol at the given `name_path`. The result will contain metadata about the referencing symbols as well as a short code snippet around the reference. - :param name_path: for finding the symbol to find references for, same logic as in the `find_symbol` tool. + :param name_path: name path of the symbol :param relative_path: the relative path to the file containing the symbol for which to find references. Note: for external dependencies, this must be an identifier starting with `