[ENHANCEMENT] Improve read_file error messages to prevent AI agent loops

[toshiz1121]

Problem (one or two sentences)

When AI agents call read_file() without the required files parameter, the error message says "Missing value for required parameter 'args'" which is confusing and causes agents to repeatedly make the same mistake, entering infinite error loops.

Context (who is affected and when)

All users are affected whenever an AI agent attempts to read files. The problem is most visible during complex tasks where the agent needs to read multiple files and forgets the correct parameter format. This happens frequently in Code mode and causes workflow interruptions that require manual intervention.

Desired behavior (conceptual, not technical)

When the read_file tool is called incorrectly, the error message should clearly show the correct parameter name (files not args) and include a usage example so the AI agent can immediately self-correct without entering an error loop.

Constraints / preferences (optional)

• Keep the error message concise but informative
• Include a minimal working example in the error
• Should work for both single and multiple file reads
• Must be clear enough for AI agents to parse and learn from

Request checklist

• I've searched existing Issues and Discussions for duplicates
• This describes a specific problem with clear context and impact

Roo Code Task Links (optional)

No response

Acceptance criteria (optional)

Given an AI agent calls read_file() without parameters
When the tool returns an error
Then the error message includes:

• The correct parameter name "files"
• A minimal usage example: read_file({ files: [{ path: "file.ts" }] })
• A note about the 5-file limit
  And the AI agent can self-correct on the next attempt
  But the error should not be overly verbose (keep under 10 lines)

Proposed approach (optional)

Replace the current error message:
"Missing value for required parameter 'args (containing valid file paths)'"

With an enhanced message:
"Missing required parameter 'files'.

Usage:
read_file({ files: [{ path: "path/to/file.ts" }] })

Multiple files:
read_file({ files: [{ path: "file1.ts" }, { path: "file2.ts" }] })

Note: Maximum 5 files per request."

Additionally, enhance the tool's description field to include usage examples upfront, preventing the error before it happens.

Trade-offs / risks (optional)

Trade-offs:

• Slightly longer error messages (but still concise)
• May need to update error handling in multiple places

Risks:

• Minimal - this is a pure improvement with no breaking changes
• Error message changes are backward compatible

Alternatives considered:

1. Interactive prompting (too complex, changes tool behavior)
2. Auto-correction (risky, might read wrong files)
3. Enhanced documentation only (doesn't solve immediate error loop problem)

Why this approach:

• Simple to implement
• Immediate impact
• No breaking changes
• Helps AI agents learn correct usage
• Reduces support burden

Additional context:
Users currently work around this by adding custom rules to their workspace configuration, which is not ideal because users must discover and implement it themselves.

[roomote]

I've analyzed this issue and here's my proposed implementation plan:

Root Cause Analysis

The current error handling in ReadFileTool.ts (line 121) calls:

const errorMsg = await task.sayAndCreateMissingParamError("read_file", "args (containing valid file paths)")

This produces the confusing message: "Missing value for required parameter 'args (containing valid file paths)'."

The problem is that "args" is a legacy XML parameter name, while the native tool protocol uses "files" as the parameter name.

Proposed Implementation

Modify src/core/tools/ReadFileTool.ts to replace the generic error with a read_file-specific helpful error message:

1. Instead of using the generic sayAndCreateMissingParamError() function, create a custom error message that includes:

   • The correct parameter name ("files")
   • A minimal usage example showing the correct format
   • A note about the concurrent file reads limit

2. The new error message will be:

Missing required parameter 'files'.

Usage:
  read_file({ files: [{ path: "path/to/file.ts" }] })

Multiple files:
  read_file({ files: [{ path: "file1.ts" }, { path: "file2.ts" }] })

Note: Maximum 5 files per request.

3. Update the existing tests in src/core/tools/__tests__/readFileTool.spec.ts to verify the new error message format.

Benefits of This Approach

• Simple, surgical change in one file (plus tests)
• No breaking changes
• Immediately helps AI agents self-correct
• Uses the correct parameter name matching the native tool definition
• Includes actionable usage examples

Please mention @roomote in a comment saying that you approve this plan, and I'll proceed with the implementation.

[hannesrudolph]

@toshiz1121 Do you have partial file reads enabled?

[hannesrudolph]

Cant repro.