docs: Added documentation for the new rag__query builtin tool

Agents.md

@@ -315,6 +315,10 @@ The first time an agent starts with documents attached, Coyote offers to build t
 start. The choice is fixed once the knowledge base is built: changing it means removing the agent's built knowledge
 base and letting it rebuild, which re-embeds every document.
 
+When function calling is enabled, an agent with `documents` also gets the [`rag__query`](RAG#runtime-retrieval)
+built-in tool, which lets the LLM run additional retrieval on-demand during a turn (in addition to the up-front
+injection). [Graph agents](Graph-Agents) drive RAG through explicit `rag` nodes instead and do not receive this tool.
+
 # 4. Building Tools for Agents
 Building tools for agents is virtually identical to building custom tools, with one slight difference: instead of 
 defining a single function that gets executed at runtime (e.g. `main` for bash tools and `run` for Python tools), agent

RAG.md

@@ -120,6 +120,37 @@ below for more details on how to customize this.
 Finally, the text snippets that were looked up in RAG are passed to the model as additional context to your prompt, 
 giving the model query-specific context to answer your question.
 
+# Runtime Retrieval
+When a RAG is attached and function calling is enabled, Coyote exposes a `rag__query` built-in tool so the LLM can run
+additional retrieval on-demand during a turn. The up-front injection described in [How It Works](#how-it-works) still
+happens; `rag__query` is a follow-up channel for when the initial context does not cover the question.
+
+## Where it appears
+- **REPL `.rag <name>`:** Added when a RAG is attached, removed on `.exit rag`
+- **Agents with `documents` configured:** Auto-injected at agent init
+- **Graph agents:** Deliberately not exposed; graph agents drive retrieval explicitly via `rag` nodes in the workflow
+
+Use `.info tools` to confirm whether the tool is active for the next request. It is intentionally omitted from
+`.list tools` because it is context-driven, not user-toggleable.
+
+## Signature
+`rag__query({ query: string, top_k?: integer })`
+
+Returns:
+```json
+{
+  "rag_name": "<name>",
+  "count": 3,
+  "chunks": [
+    { "text": "...", "source": "path/or/url" }
+  ]
+}
+```
+
+`top_k` defaults to the RAG's [configured `top_k`](#top-k) when omitted. Retrieval uses the same hybrid path (vector +
+BM25 + optional graph + optional reranker) as up-front injection, so results are consistent whichever way retrieval
+happens.
+
 # Storage Drivers
 Every RAG picks a **storage driver** when it's created. The driver decides where your vectors and document text
 actually live: inside the RAG's own file, in a local database beside it, or in a Qdrant server you already run.

_Sidebar.md

@@ -57,6 +57,7 @@
   - [File Discovery](Workspace-Instructions#file-discovery)
   - [Configuration](Workspace-Instructions#configuration)
 - [RAG](RAG)
+  - [Runtime Retrieval](RAG#runtime-retrieval)
   - [Storage Drivers](RAG#storage-drivers)
   - [Attaching a Qdrant Collection](RAG#qdrant--attaching-an-existing-collection)
   - [Graph-Based RAG](RAG#graph-based-rag)