From 5cae1d8ddf2317527f731d546f80bacf00e2312a Mon Sep 17 00:00:00 2001
From: Dominik Jain <dominik.jain@oraios-ai.de>
Date: Tue, 8 Sep 2026 20:38:29 +0200
Subject: [PATCH] Explain max_answer_chars centrally in the REPL tool
 description

The parameter is documented once in the tool description instead of in every facade method.
---
 src/serena/repl/api/edit_api.py  | 2 --
 src/serena/repl/api/fs_api.py    | 6 ------
 src/serena/repl/api/jb_api.py    | 9 ---------
 src/serena/repl/api/lsp_api.py   | 6 ------
 src/serena/repl/api/shell_api.py | 2 --
 src/serena/tools/repl_tools.py   | 5 +++++
 6 files changed, 5 insertions(+), 25 deletions(-)

diff --git a/src/serena/repl/api/edit_api.py b/src/serena/repl/api/edit_api.py
index aa150e92..be09770e 100644
--- a/src/serena/repl/api/edit_api.py
+++ b/src/serena/repl/api/edit_api.py
@@ -169,8 +169,6 @@ class EditApi(FacadeApi):
         :param expected_count: optional guard for calls without occurrence_ids: the number of
             occurrences you expect to be replaced. If the actual count differs, nothing is changed and
             an error containing the prospective changes is raised. -1 disables the guard.
-        :param max_answer_chars: if the rendered output exceeds this many characters, a shortened version is
-            used. -1 uses the configured default.
         :return: in a dry run, the prospective changes (`ReplacementPreview`); otherwise a summary of the applied replacements
         """
         replacement = MultiFileReplacement(
diff --git a/src/serena/repl/api/fs_api.py b/src/serena/repl/api/fs_api.py
index 09e0a54d..b457035e 100644
--- a/src/serena/repl/api/fs_api.py
+++ b/src/serena/repl/api/fs_api.py
@@ -187,8 +187,6 @@ class FsApi(FacadeApi):
         :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, 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 rendered content is longer than this number of characters, no content is rendered;
-            -1 for the configured default. Don't adjust unless there is really no other way to get the content required for the task.
         :return: the content
         """
         project = self._get_project()
@@ -237,8 +235,6 @@ class FsApi(FacadeApi):
         :param relative_path: the relative path to the directory to list; pass "." to scan the project root
         :param recursive: whether to scan subdirectories recursively
         :param skip_ignored_files: whether to skip files and directories that are ignored
-        :param max_answer_chars: if the rendered listing is longer than this number of characters, no content is rendered;
-            -1 for the configured default. Don't adjust unless there is really no other way to get the content required for the task.
         :return: the listing
         """
         project = self._get_project()
@@ -313,8 +309,6 @@ class FsApi(FacadeApi):
             (useful when looking for class/method definitions); otherwise also search non-code files.
         :param skip_ignored_files: whether to skip ignored sub-paths (default: True)
         :param multiline: whether to apply multi-line matching (default: True), enabling the flags re.DOTALL and re.MULTILINE
-        :param max_answer_chars: if the rendered output exceeds this many characters, a progressively shortened summary is
-            rendered instead. -1 for the configured default.
         :return: the matches, rendered as a mapping from file paths to matched consecutive lines (0-based line numbers)
         """
         project = self._get_project()
diff --git a/src/serena/repl/api/jb_api.py b/src/serena/repl/api/jb_api.py
index 9c8e196c..2ed024f4 100644
--- a/src/serena/repl/api/jb_api.py
+++ b/src/serena/repl/api/jb_api.py
@@ -245,7 +245,6 @@ class JetBrainsApi(FacadeApi):
         :param search_deps: If True, also search in project dependencies (e.g., libraries).
         :param max_matches: Maximum number of permitted matches. If exceeded, an error containing a shortened result is raised,
              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 result (-1 for default). If exceeded, no content/a shortened result is returned.
         :return: the symbols matching the pattern
         """
         if name_path_pattern.replace("*", "").replace("/", "") == "":
@@ -292,7 +291,6 @@ class JetBrainsApi(FacadeApi):
         :param relative_path: the relative path to the file containing the symbol (must be a file, not a directory)
             Note: for external dependencies, this must be an identifier starting with `<ext` that you have received
             earlier (don't try to guess!).
-        :param max_answer_chars: max characters for the result (-1 for default). If exceeded, no content/a shortened result is returned.
         :return: the referencing symbols
         """
         with self._client() as client:
@@ -326,7 +324,6 @@ class JetBrainsApi(FacadeApi):
         :param relative_path: the relative path to the file to get the overview of
         :param depth: depth up to which descendants shall be retrieved.
             Default (-1) results in a language specific choice: 1 for java and kotlin and 0 for other languages
-        :param max_answer_chars: max characters for the result (-1 for default). If exceeded, no content/a shortened result is returned.
         :param include_file_documentation: whether to include the file's docstring. Default False.
         :return: the overview
         """
@@ -377,8 +374,6 @@ class JetBrainsApi(FacadeApi):
         :param hierarchy_type: which hierarchy to retrieve: "super" for parent classes/interfaces,
             "sub" for subclasses/implementations, or "both" for both directions. Default is "both".
         :param depth: depth limit for hierarchy traversal (None or 0 for unlimited). Default is 1.
-        :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.
         :return: the file-grouped hierarchy, with keys "supertypes" and/or "subtypes" (and "levels_not_included"
             if the depth limit truncated the hierarchy)
         """
@@ -579,8 +574,6 @@ class JetBrainsApi(FacadeApi):
             If not specified, all applicable inspections are run.
         :param start_line: optional 1-based start line to restrict the inspection range.
         :param end_line: optional 1-based end line to restrict the inspection range.
-        :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.
         :return: the inspection results including severity, message, and location.
         """
         with self._client() as client:
@@ -604,8 +597,6 @@ class JetBrainsApi(FacadeApi):
         :param language: optional language to filter by (e.g. "Java", "Python", "Kotlin").
         :param group_path_contains: optional substring to match against the inspection group path
             (e.g. "probable bugs", "code style").
-        :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.
         :return: the list of available inspections including name, group path, and language.
         """
         with self._client() as client:
diff --git a/src/serena/repl/api/lsp_api.py b/src/serena/repl/api/lsp_api.py
index 0459f408..8d827ff6 100644
--- a/src/serena/repl/api/lsp_api.py
+++ b/src/serena/repl/api/lsp_api.py
@@ -368,7 +368,6 @@ class LspApi(FacadeApi):
         :param relative_path: the relative path to the file to get the overview of
         :param depth: depth up to which descendants shall be retrieved.
             Default (-1) results in a language specific choice: 1 for java and kotlin and 0 for other languages
-        :param max_answer_chars: max result length; -1 for default. If exceeded, a shortened result is returned.
         :return: the top-level symbols of the file
         """
         # Note: file system sync not required (relevant file is opened in the language server explicitly)
@@ -454,7 +453,6 @@ class LspApi(FacadeApi):
             (i.e. the name of the symbol, e.g. "foo" in "Class/foo" or "my_method" in "my_method").
         :param max_matches: Maximum number of permitted matches. If exceeded, an error containing a shortened result is raised,
              which allows refining the search. -1 (default) means no limit. Set to 1 to search for a unique symbol.
-        :param max_answer_chars: max result length; -1 for default
         :return: the symbols (with locations) matching the name path pattern
         """
         # Note: file system sync not required; the symbol finder opens all relevant source files explicitly in the case of changes
@@ -514,7 +512,6 @@ class LspApi(FacadeApi):
         :param relative_path: the relative path to the file containing the symbol for which to find references.
         :param include_kinds: (optional) limits results to the given LSP symbol kinds (integers, i.e. values of `SymbolKind`)
         :param exclude_kinds: optional list of LSP symbol kinds (integers, i.e. values of `SymbolKind`) to exclude.
-        :param max_answer_chars: max result length; -1 for default
         :return: the references to the symbol
         """
         # file system sync needed for case where symbol finder does not perform a global search, updating everything
@@ -551,7 +548,6 @@ class LspApi(FacadeApi):
             about the implementing symbols.
         :param include_kinds: (optional) limits results to the given LSP symbol kinds (integers, i.e. values of `SymbolKind`)
         :param exclude_kinds: (optional) list of LSP symbol kinds (integers, i.e. values of `SymbolKind`) to exclude.
-        :param max_answer_chars: max result length; -1 for default
         :return: the symbols implementing the given symbol
         """
         self._get_project().ls_sync_file_system_changes()
@@ -635,7 +631,6 @@ class LspApi(FacadeApi):
         :param end_line: the last 0-based line to include. Defaults to -1, which means until the end of the file.
         :param min_severity: minimum LSP severity to include, where 1=Error, 2=Warning, 3=Information, 4=Hint.
             Diagnostics with lower-or-equal numeric severity are returned.
-        :param max_answer_chars: max result length; -1 for default
         :return: the grouped diagnostics for the requested file.
         """
         self._get_project().ls_sync_file_system_changes()
@@ -675,7 +670,6 @@ class LspApi(FacadeApi):
         :param check_symbol_references: whether to additionally collect diagnostics for symbols that reference the symbol.
         :param min_severity: minimum LSP severity to include, where 1=Error, 2=Warning, 3=Information, 4=Hint.
             Diagnostics with lower-or-equal numeric severity are returned.
-        :param max_answer_chars: max result length; -1 for default
         :return: the grouped diagnostics for the requested symbol and, optionally, its referencing symbols.
         """
         self._get_project().ls_sync_file_system_changes()
diff --git a/src/serena/repl/api/shell_api.py b/src/serena/repl/api/shell_api.py
index 56ba2679..9f4db097 100644
--- a/src/serena/repl/api/shell_api.py
+++ b/src/serena/repl/api/shell_api.py
@@ -70,8 +70,6 @@ class ShellApi(FacadeApi):
         :param cwd: the working directory to execute the command in (absolute, or relative to the project root).
             If None, the project root will be used.
         :param capture_stderr: whether to capture and return stderr output
-        :param max_answer_chars: if the rendered output is longer than this number of characters, no content is rendered;
-            -1 for the configured default. Don't adjust unless there is no other way to get the content required for the task.
         :return: the output (object with properties stdout, stderr, return_code and cwd)
         """
         project_root = self._get_project().project_root
diff --git a/src/serena/tools/repl_tools.py b/src/serena/tools/repl_tools.py
index f47bf82f..72633ae5 100644
--- a/src/serena/tools/repl_tools.py
+++ b/src/serena/tools/repl_tools.py
@@ -34,6 +34,11 @@ class SerenaReplTool(Tool, ToolMarkerOptional, ToolMarkerBeta):
         Returned objects are rendered in a form suitable for you; lists are rendered element-wise.
         Returned strings are passed through unchanged.
 
+        Output size: methods with a `max_answer_chars` parameter limit the size of the rendered result (-1 uses the
+        configured default). If the limit is exceeded, a shortened result (or no content) is rendered instead;
+        adjust the limit only if there is no other way to obtain the content required for the task (e.g. by
+        narrowing the query or processing the result in code and returning only what is needed).
+
         Persistence: variables, functions and classes defined at the top level of your code persist across calls
         within your session (like the cells of a notebook), so you can reuse results and define helper functions once.
         `s.vars()` lists the persisted items, `s.clear()` removes them. Do not store facades (`s.<facade>`) in