Improve tool descriptions to guide proper file editing tool selection #3943
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
### Problem LLMs were frequently choosing `write_to_file` for file edits instead of more appropriate tools like `apply_diff`, `insert_content`, or `search_and_replace`. This was likely because the tool descriptions made it seem like files needed to be reconstructed rather than edited. ### Changes Made **write_to_file tool description:** - Clarified primary use cases: **creating new files** or **complete rewrites when intentionally required** - Changed opening from "write full content" to "write content" to reduce emphasis on full reconstruction - Updated parameter description to be more specific about when complete content is needed **apply_diff tool description:** - Enhanced description to emphasize "targeted modifications" and "precise, surgical edits" - Clarified that multiple search/replace operations can be performed in a single call - Removed misleading "only a single operation allowed" restriction - Better positioned as the preferred tool for making several targeted changes efficiently ### Impact These changes should guide LLMs toward: - Using `write_to_file` primarily for new files or intentional complete rewrites - Using `apply_diff` for targeted edits and modifications to existing files - Better understanding of when each tool is most appropriate The updated descriptions maintain necessary technical details while providing clearer guidance on tool selection without being overly prescriptive.
![ellipsis-dev[bot]](https://avatars.githubusercontent.com/in/64358?s=60&v=4){kind=small}
Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>
mrubens
reviewed
May 24, 2025
Co-authored-by: Matt Rubens <[email protected]>
Co-authored-by: Matt Rubens <[email protected]>
…into tool-desc-fix
…into tool-desc-fix
…into tool-desc-fix
mrubens
approved these changes
May 24, 2025
SmartManoj
pushed a commit
to SmartManoj/Raa-Code
that referenced
this pull request
Jun 13, 2025
* Fix linter warnings in the webview (part 2)
Replace protobus calls using object literals to use Message.create({...})
Fix incorrect property name detected after this change in webview-ui/src/components/settings/SettingsView.tsx
Optimised imports in vscode.
* Fix typo
* formatting
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Related GitHub Issue
Closes: #3941
Description
This PR improves the tool descriptions for file editing operations to guide LLMs toward better tool selection. The main issue was that LLMs were frequently choosing
write_to_filefor file edits instead of more appropriate tools likeapply_diff,insert_content, orsearch_and_replace, likely due to misleading tool descriptions.Key changes:
The changes maintain all necessary technical details while providing clearer guidance on tool selection without being overly prescriptive.
Test Procedure
Manual Testing:
write_to_fileemphasizes new file creation and complete rewritesapply_diffemphasizes targeted modifications and supports multiple operationsExpected Behavior:
apply_difffor targeted file modificationswrite_to_fileshould be used primarily for new files or intentional complete rewritesType of Change
srcor test files.Pre-Submission Checklist
npm run lint).console.log) has been removed.npm test).mainbranch.npm run changesetif this PR includes user-facing changes or dependency updates.Screenshots / Videos
N/A - This change affects internal tool descriptions and prompt engineering, not user-facing UI.
Documentation Updates
The changes are internal improvements to tool descriptions used by the AI system and don't affect user-facing functionality or APIs.
Additional Notes
This improvement should lead to more appropriate tool selection by LLMs, resulting in:
The changes are backward compatible and don't affect the tool APIs or functionality, only their descriptions.
Get in Touch
Discord username: [Your Discord username here]