diff --git a/internal/agent/tools/ls.md b/internal/agent/tools/ls.md
index ba4fd7462dfefd540fc9e33b672a73f6e412ca7a..cb7c6756e0e19c57e6fe0ffc8a0297d4810cda4a 100644
--- a/internal/agent/tools/ls.md
+++ b/internal/agent/tools/ls.md
@@ -1,4 +1,4 @@
-Shows files and subdirectories in tree structure for exploring project organization.
+List files and directories as a tree; skips hidden files and common system dirs; max 1000 files. Use glob to find files by pattern, grep to search contents.
 
 <usage>
 - Provide path to list (defaults to current working directory)