diff --git a/tools/file_read b/tools/file_read
index bcada32..d173176 100644
--- a/tools/file_read
+++ b/tools/file_read
@@ -1,8 +1,29 @@
 #!/usr/bin/env python3
 # ollie:parallel read
 # ollie:tier cold
-# description: Read a file with accurate line numbers. Prefer segments (start/end) over full-file reads.
-# Args: <file_path> [start] [end] [--head=<n>]
+# ollie:prompt
+# ## file_read
+#
+# Read a file with line numbers. Prefer segments over full reads.
+#
+# **Args**: `[path]` or `[path, start, end]` or `[path, "--head=N"]`
+#
+# - `start`/`end`: 1-indexed line numbers, inclusive. Must be strings. Max segment: 2000 lines.
+# - No start/end: reads up to 500 lines from line 1.
+# - `--head=N`: read first N lines.
+#
+# ```
+# call_tool: calls=[{tool: "file_read", args: ["/abs/path"]}]
+# call_tool: calls=[{tool: "file_read", args: ["/abs/path", "100", "200"]}]
+# call_tool: calls=[{tool: "file_read", args: ["/abs/path", "--head=50"]}]
+# ```
+#
+# - BAD: `args: ["/path", 100, 200]` — numbers are not strings
+# - BAD: `args: ["/path", "match=foo"]` — not a valid argument
+# - GOOD: `args: ["/abs/path", "100", "200"]` — string line numbers
+#
+# **Constraints**: Absolute paths only.
+# ollie:end
 
 import sys
 import os