fix: update parameter names and enhance documentation for read_file tool

Author: hannesrudolph

docs/advanced-usage/available-tools/read-file.md

@@ -19,14 +19,18 @@ The tool accepts parameters in two formats depending on your configuration:
 - `start_line` (optional): The starting line number to read from (1-based indexing)
 - `end_line` (optional): The ending line number to read to (1-based, inclusive)
 
+:::note Legacy Format
+While the single-file parameters (`path`, `start_line`, `end_line`) are still supported for backward compatibility, we recommend using the newer `args` format for consistency and future compatibility.
+:::
+
 ### Enhanced Format (Multi-File - Experimental)
 
 When [Concurrent File Reads](/features/experimental/concurrent-file-reads) is enabled, the tool accepts an `args` parameter containing multiple file entries:
 
 - `args` (required): Container for multiple file specifications
   - `file` (required): Individual file specification
     - `path` (required): The path of the file to read
-    - `lines` (optional): Line range specification (e.g., "1-50" or "100-150")
+    - `line_range` (optional): Line range specification (e.g., "1-50" or "100-150")
 
 ---
 
@@ -119,11 +123,12 @@ The tool uses a clear decision hierarchy to determine how to read a file:
    - This applies only when **all** of the following conditions are met:
      - Neither `start_line` nor `end_line` is specified.
      - The file is identified as a text-based file (not binary like PDF/DOCX).
-     - The file's total line count exceeds an internal limit (e.g., `maxReadFileLine`, often around 500 lines).
+     - The file's total line count exceeds the `maxReadFileLine` setting (default: 500 lines).
    - When automatic truncation occurs:
      - The tool reads only the *first* `maxReadFileLine` lines.
      - It appends a notice indicating truncation (e.g., `[Showing only 500 of 1200 total lines...]`).
      - For code files, it may also append a summary of source code definitions found within the truncated portion.
+   - **Special Case - Definitions Only Mode**: When `maxReadFileLine` is set to `0`, the tool returns only source code definitions without any file content.
 
 3. **Default Behavior: Read Entire File**
    - If neither an explicit range is given nor automatic truncation applies (e.g., the file is within the line limit, or it's a supported binary type), the tool reads the entire content.
@@ -203,7 +208,33 @@ When reading a large text file without specifying a line range, the tool automat
 [Showing only 500 of 1500 total lines. Use start_line and end_line to read specific ranges.]
 // Optional: Source code definitions summary might appear here for code files
 ```
-*(Output shows the beginning lines up to the internal limit, plus a truncation notice. Use line ranges for full access.)*
+*(Output shows the beginning lines up to the `maxReadFileLine` limit, plus a truncation notice. Use line ranges for full access.)*
+
+### Reading Definitions Only
+
+When `maxReadFileLine` is set to `0` in user settings, the tool returns only source code definitions without file content:
+
+**Input:**
+```xml
+<!-- Assuming maxReadFileLine is set to 0 in user settings -->
+<read_file>
+<path>src/services/auth.service.ts</path>
+</read_file>
+```
+
+**Simulated Output:**
+```xml
+<file>
+  <path>src/services/auth.service.ts</path>
+  <list_code_definition_names>
+    class AuthService
+      method validateUser
+      method generateToken
+  </list_code_definition_names>
+  <notice>Showing only 0 of 150 total lines. Use start_line and end_line to read specific ranges.</notice>
+</file>
+```
+*(This mode provides a quick overview of file structure without reading content.)*
 
 ### Attempting to Read a Non-Existent File
 
@@ -234,7 +265,7 @@ If the file is excluded by rules in a `.rooignore` file:
 
 **Simulated Output (Error):**
 ```
-Error: Access denied to file '.env' due to .rooignore rules.
+Error: Access denied by .rooignore rules
 ```
 
 ---
@@ -305,12 +336,12 @@ To read specific sections from multiple files:
 <args>
   <file>
     <path>src/app.ts</path>
-    <lines>1-20</lines>
-    <lines>45-60</lines>
+    <line_range>1-20</line_range>
+    <line_range>45-60</line_range>
   </file>
   <file>
     <path>src/utils.ts</path>
-    <lines>10-25</lines>
+    <line_range>10-25</line_range>
   </file>
 </args>
 </read_file>
@@ -382,7 +413,7 @@ When some files are approved and others are denied or blocked:
   </file>
   <file>
     <path>src/secret-config.ts</path>
-    <error>User denied access</error>
+    <error>User denied access to file</error>
   </file>
 </files>
 ```