diff --git a/navi/tools/filesystem.py b/navi/tools/filesystem.py
index 85a7478..e664cf1 100644
--- a/navi/tools/filesystem.py
+++ b/navi/tools/filesystem.py
@@ -199,21 +199,28 @@
 class FilesystemTool(Tool):
     name = "filesystem"
     description = (
-        "Operate on the local filesystem.\n"
-        "Standard actions: "
-        "read — file text (offset+limit for large files); "
-        "write — create/overwrite; "
-        "append — add to end; "
-        "list — directory contents; "
-        "find — glob pattern search; "
-        "info — size, lines, dates, permissions; "
+        "Operate on the local filesystem. "
+        "ALWAYS prefer AI actions over manual read+write — they produce more accurate results "
+        "and handle files of any size automatically:\n"
+        "  • query — use INSTEAD of read when you need to extract or look up information. "
+        "Examples: 'what arguments does function X take?', 'on which line is class Y defined?', "
+        "'does this config contain key Z?', 'list all TODO comments'. "
+        "Pass the question in 'question'.\n"
+        "  • smart_edit — use INSTEAD of read+write for any semantic change to a file. "
+        "Examples: 'rename function foo to bar', 'add a docstring to method X', "
+        "'remove all commented-out code', 'change timeout from 30 to 60'. "
+        "Pass the instruction in 'instruction'. Returns a diff of what changed.\n"
+        "Standard actions (use only when AI actions are not applicable): "
+        "read — raw file text (offset+limit for large files); "
+        "write — create or overwrite a file; "
+        "append — add text to end; "
+        "list — directory contents with sizes; "
+        "find — search files by glob pattern; "
+        "info — size, line count, dates, permissions; "
         "move — rename or move; "
-        "delete — remove file or directory; "
-        "exists — check if path exists.\n"
-        "AI actions (require 'question' / 'instruction'): "
-        "query — ask a natural language question about a file's content, works on any size file; "
-        "smart_edit — apply a natural language edit instruction precisely, returns a diff of changes.\n"
-        "Tip: call info before reading an unknown file to check its size."
+        "delete — remove file or directory tree; "
+        "exists — check if path exists. "
+        "Tip: call info before reading an unknown file to check its size first."
     )
     parameters = {
         "type": "object",
@@ -257,11 +264,24 @@
             },
             "question": {
                 "type": "string",
-                "description": "Natural language question about the file's content (for query).",
+                "description": (
+                    "Natural language question about the file's content (for query). "
+                    "Examples: 'What does function calculate() return?', "
+                    "'On which line is class UserManager defined?', "
+                    "'What environment variables does this script read?', "
+                    "'Are there any hardcoded passwords?'"
+                ),
             },
             "instruction": {
                 "type": "string",
-                "description": "Natural language edit instruction (for smart_edit), e.g. 'rename function foo to bar'.",
+                "description": (
+                    "Natural language edit instruction (for smart_edit). "
+                    "Examples: 'Rename function process to handle_request', "
+                    "'Add type hints to all function signatures', "
+                    "'Replace the hardcoded URL with a constant BASE_URL', "
+                    "'Delete the block comment on lines 10-20', "
+                    "'Add logging to the save() method'"
+                ),
             },
         },
         "required": ["action", "path"],