diff --git a/src/pages/docs.astro b/src/pages/docs.astro
index 4e7e842..cf7ef2d 100644
--- a/src/pages/docs.astro
+++ b/src/pages/docs.astro
@@ -462,6 +462,8 @@ import BaseLayout from '../layouts/BaseLayout.astro';
 - Verify libraries exist before using them (check imports, package.json, etc.)
 - Use absolute file paths
 - Read files before editing them
+- Prefer symbol_search -> symbol_resolve -> read_file_range for code understanding
+- Use grep_search when you need text-pattern search rather than symbol lookup
 - Add comments sparingly - focus on "why" not "what"
 - If unclear, ask for clarification
 
@@ -474,14 +476,18 @@ import BaseLayout from '../layouts/BaseLayout.astro';
 
 # Available Tools
 
-**get_workspace_structure** - Get project directory tree
-**list_dir** - List files/directories in a path
-**read_file** - Read file contents  
+**get_editor_state** - Get active file, cursor position, and open files
+**symbol_search** - Find functions, classes, methods, and types by name
+**symbol_resolve** - Resolve a symbol to its exact file and line range
+**symbol_references** - Find where a symbol is used
+**read_file_range** - Read targeted line ranges from a file
+**read_file** - Read full file contents when broader context is needed
+**get_workspace_structure** - Get the project directory tree
+**grep_search** - Search for text or regex patterns across files
+**apply_patch** - Make precise edits to existing files
 **write_file** - Create or overwrite a file
-**apply_patch** - Replace specific content in a file (for edits)
-**grep_search** - Search for patterns across files
 **run_command** - Execute shell commands
-**get_editor_state** - Get currently open file and cursor position</code></pre>
+**todo_write** - Track multi-step work and show progress</code></pre>
           </div>
           
           <p class="instructions-note">
diff --git a/src/pages/tools.astro b/src/pages/tools.astro
index 157d388..bd1989d 100644
--- a/src/pages/tools.astro
+++ b/src/pages/tools.astro
@@ -19,8 +19,8 @@ import BaseLayout from '../layouts/BaseLayout.astro';
             <span class="title-accent">REFERENCE_</span>
           </h1>
           <p class="hero-description">
-            Complete reference for all tool calls available in Zaguán Blade.
-            Add these to your Local AI system prompts to enable file operations, search, editor control, and command execution.
+            Reference for the regular tool calls that Zaguán Blade supports.
+            Add these to your Local AI system prompts to extend usability with file operations, search, editor control, and command execution.
           </p>
           <div class="hero-note">
             <span class="hero-note-label">NOTE</span>
@@ -356,6 +356,10 @@ import BaseLayout from '../layouts/BaseLayout.astro';
                   <code>path</code> <code>size</code> <code>is_directory</code> <code>is_file</code> <code>modified</code> <code>readonly</code>
                 </div>
               </div>
+              <div class="tool-example">
+                <h4>Example</h4>
+                <pre is:raw><code>{ "path": "Cargo.toml" }</code></pre>
+              </div>
             </div>
           </div>
 
@@ -824,28 +828,19 @@ import BaseLayout from '../layouts/BaseLayout.astro';
         <h2 class="section-title">Tool Result Handling</h2>
         
         <div class="info-card">
-          <p class="info-text">The 50KB / 2000 line limits apply <strong>only to tool results</strong> - what zblade sends back to the model after executing a tool (e.g., the output of <code>read_file</code>). These limits only apply in <strong>local mode</strong>, when the Zagu&aacute;n Coder Daemon isn't handling storage.</p>
+          <p class="info-text">Tool results are automatically truncated if they exceed limits:</p>
           <div class="limits-row">
             <div class="limit-box">
               <span class="limit-value">50KB</span>
-              <span class="limit-label">Result max size</span>
+              <span class="limit-label">Max size</span>
             </div>
             <div class="limit-box">
               <span class="limit-value">2000</span>
-              <span class="limit-label">Result max lines</span>
+              <span class="limit-label">Max lines</span>
             </div>
           </div>
           <p class="info-text-secondary">When truncated, the first 100 lines and last 50 lines are shown with a truncation message.</p>
         </div>
-
-        <div class="info-card" style="margin-top: var(--space-lg);">
-          <p class="info-text"><strong>There are no size limits on incoming tool calls from the model.</strong> zblade will accept a <code>write_file</code> with any size content. The <code>write_file</code> handler itself has no caps - it writes whatever content string it receives directly to disk.</p>
-        </div>
-
-        <div class="tool-note" style="margin-top: var(--space-lg);">
-          <span class="note-icon">ℹ️</span>
-          <p class="note-text">zblade includes <strong>dropped tool call detection</strong>. If a tool call from the model never arrives (e.g., streaming progress events complete but the final tool call with arguments is dropped server-side), zblade will catch this and surface a clear error.</p>
-        </div>
       </div>
     </section>
 
@@ -885,24 +880,26 @@ import BaseLayout from '../layouts/BaseLayout.astro';
           <p class="info-text">
             To use these tools with a local AI, include the tool definitions in your system prompt. See the <a href="/docs#local-ai-prompts">Local AI System Prompts</a> section for setup instructions.
           </p>
-          
+
           <div class="code-block">
             <div class="code-header">
               <span class="code-filename">Example System Prompt Snippet</span>
-              <span class="code-lang">markdown</span>
+              <span class="code-lang">text</span>
             </div>
-            <pre is:raw><code># Available Tools
+            <pre is:raw><code>You have access to the following tools:
 
-**get_workspace_structure** - Get project directory tree
-**list_dir** - List files/directories in a path
-**read_file** - Read file contents
-**write_file** - Create or overwrite a file
-**apply_patch** - Replace specific content in a file (for edits)
-**grep_search** - Search for patterns across files
-**run_command** - Execute shell commands (use cwd parameter)
-**get_editor_state** - Get currently open file and cursor position</code></pre>
+- read_file: Read file contents. Args: {"path": "string"}
+- write_file: Write to file. Args: {"path": "string", "content": "string"}
+- grep_search: Search with regex. Args: {"pattern": "string", "path": "string"}
+- apply_edit: Edit file. Args: {"path": "string", "old_text": "string", "new_text": "string"}
+...
+
+To use a tool, respond with:
+&lt;tool_call&gt;
+{"name": "tool_name", "arguments": {...}}
+&lt;/tool_call&gt;</code></pre>
           </div>
-          
+
           <p class="info-text-secondary">
             The exact format depends on your AI provider's tool calling conventions.
           </p>