From 4acde68ddc3ca8338beb742b22392875d772cdc1 Mon Sep 17 00:00:00 2001
From: Levi Neely <141506390+lneely@users.noreply.github.com>
Date: Tue, 19 May 2026 10:25:56 +0000
Subject: [PATCH] prompts: clarify raw JSON requirement; add bad/good examples
 for tool args

SYSTEM_PROMPT.md: add explicit raw-JSON warning and bad/good examples
under execute_code, and a canonical JSON block alongside the pseudocode.

tools-file.md: add a note that call_tool args must be a JSON array of
strings, never a plain string, with a bad/good example pair.
---
 prompts/SYSTEM_PROMPT.md | 9 +++++++++
 prompts/tools-file.md    | 4 ++++
 2 files changed, 13 insertions(+)

diff --git a/prompts/SYSTEM_PROMPT.md b/prompts/SYSTEM_PROMPT.md
index fc3b0c8..c34c0f8 100644
--- a/prompts/SYSTEM_PROMPT.md
+++ b/prompts/SYSTEM_PROMPT.md
@@ -159,12 +159,21 @@ cat $OLLIE/s/{id}/models
 
 Run inline code. Each step needs `code` (required) and optionally `language`.
 
+**Tool arguments are raw JSON objects, not shell-escaped strings.** Never backslash-escape the outer JSON quotes.
+- BAD: `"{\"steps\":[{\"code\":\"date\"}]}"`
+- GOOD: `{"steps":[{"code":"date"}]}`
+
 ```
 execute_code: steps=[{code: "date"}]
 execute_code: steps=[{code: "grep -r TODO src/ | wc -l"}]
 execute_code: steps=[{code: "make build"}], timeout=120
 ```
 
+Canonical JSON form:
+```json
+{"steps":[{"code":"date"}]}
+```
+
 ## call_tool
 
 Run named tool scripts. Each call needs `tool` (required) and optionally `args`.
diff --git a/prompts/tools-file.md b/prompts/tools-file.md
index 0953c22..360667f 100644
--- a/prompts/tools-file.md
+++ b/prompts/tools-file.md
@@ -12,6 +12,10 @@
 
 **Trigger condition**: any time you need to read, write, search, or enumerate files.
 
+**`call_tool` args must be a JSON array of strings, never a plain string**:
+- BAD: `{tool: "file_read", args: "/path/to/file"}`
+- GOOD: `{tool: "file_read", args: ["/path/to/file"]}`
+
 **Calling convention**:
 ```
 call_tool: calls=[{tool: "file_read", args: ["/abs/path", "start", "end"]}]       # segment (preferred)