diff --git a/internal/agent/tools/write.md b/internal/agent/tools/write.md
index 6cdf0351d12563a688984f1047f2052a504cf3bd..fbe58a5648911375d8ae002fa9a1a83c7d81a305 100644
--- a/internal/agent/tools/write.md
+++ b/internal/agent/tools/write.md
@@ -1,4 +1,4 @@
-Creates or updates files in filesystem for saving/modifying text content.
+Create or overwrite a file with given content; auto-creates parent dirs. Cannot append. Read the file first to avoid conflicts. For surgical changes use edit or multiedit.
 
 <usage>
 - Provide file path to write