diff --git a/docs/agents-tools.md b/docs/agents-tools.md
index d4637cd..09a72cd 100644
--- a/docs/agents-tools.md
+++ b/docs/agents-tools.md
@@ -14,9 +14,11 @@ This document provides comprehensive reference documentation for building agents
   - [BaseTool](#basetool)
   - [Tool Parameters](#tool-parameters)
   - [Tool Implementation](#tool-implementation)
+  - [Registering with an Agent](#registering-with-an-agent)
 - [Retrieval Tools](#retrieval-tools)
   - [BaseRetrievalTool](#baseretrievaltool)
   - [Connecting to Retrievals](#connecting-to-retrievals)
+  - [Registering with an Agent](#registering-retrieval-tools-with-an-agent)
 - [Related Content](#related-content)
   - [BaseFAQ](#basefaq)
   - [BaseFixedResponse](#basefixedresponse)
@@ -414,6 +416,36 @@ class WeatherTool(BaseTool):
         return {"temp": 20, "condition": "sunny"}
 ```
 
+### Registering with an Agent
+
+> **Important:** Defining a tool class in `agents/tools.py` does **not** make it available to an agent automatically. You must explicitly import the tool and add an instance of it to the agent's `tools` list in `agents/<name>/agent.py`.
+
+```python
+# agents/<name>/agent.py
+
+from cogsol.agents import BaseAgent, genconfigs
+from cogsol.prompts import Prompts
+from ..tools import WeatherTool, OrderLookupTool  # Import your tool classes
+
+
+class SupportAgent(BaseAgent):
+    system_prompt = Prompts.load("support.md")
+    generation_config = genconfigs.QA()
+
+    # Each tool must be explicitly listed here as an instance
+    tools = [
+        WeatherTool(),
+        OrderLookupTool(),
+    ]
+```
+
+After updating `agent.py`, regenerate and apply migrations so the agent configuration is synced:
+
+```bash
+python manage.py makemigrations agents
+python manage.py migrate agents
+```
+
 ---
 
 ## Retrieval Tools
@@ -493,6 +525,11 @@ class SupportAgent(BaseAgent):
 2. Create the retrieval in `data/retrievals.py`
 3. Run `python manage.py makemigrations data`
 4. Run `python manage.py migrate data`
+5. Register the retrieval tool in the agent's `tools` list in `agents/<name>/agent.py` (see below)
+
+### Registering Retrieval Tools with an Agent
+
+> **Important:** Defining a retrieval tool class in `agents/searches.py` does **not** make it available to an agent automatically. Retrieval tools are registered with an agent exactly the same way as regular tools — see [Registering with an Agent](#registering-with-an-agent).
 
 ---
 
@@ -786,7 +823,13 @@ class KnowledgeBaseSearch(BaseRetrievalTool):
    python manage.py migrate data
    ```
 6. **Ingest Documents:** `python manage.py ingest knowledge_base /path/to/docs`
-7. **Connect to Agent:** Create retrieval tool in `agents/searches.py`
+7. **Create Retrieval Tool:** Create retrieval tool in `agents/searches.py`
+8. **Register with Agent:** Add the retrieval tool to the agent's `tools` list in `agents/<name>/agent.py` (see [Registering with an Agent](#registering-with-an-agent))
+9. **Migrate agents:**
+   ```
+   python manage.py makemigrations agents
+   python manage.py migrate agents
+   ```
 
 
 ## Prompts
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 2db7f72..723bb99 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -352,6 +352,12 @@ class EscalationLesson(BaseLesson):
 
 ## Adding Tools
 
+> **Note:** Adding a tool to your project is a two-step process:
+> 1. **Define** the tool class in `agents/tools.py` (or `agents/searches.py` for retrieval tools).
+> 2. **Register** it in the agent by importing it and adding an instance to the `tools` list in `agents/<name>/agent.py`.
+>
+> Simply defining the tool class is not enough — the agent will not use it until it is explicitly listed in `agent.py`.
+
 ### Step 1: Create a Custom Tool
 
 Edit `agents/tools.py` to add a useful tool. New projects include a commented example block; uncomment it or replace it with your own tool classes.