From fb09d0e366c27dc5f69ea9eceffc6b4bd971f97c Mon Sep 17 00:00:00 2001
From: Ollie Agent <ollie@example.com>
Date: Tue, 21 Jul 2026 13:18:57 +0200
Subject: [PATCH] file_read: add ollie:prompt block for auto-discovery

Usage documentation is now embedded in the script header and
automatically extracted into the system prompt by BuildRuntime.
This replaces the corresponding section in tools-file.md.
---
 tools/file_read | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

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