Enhance documentation for search agent integration workflow

docs/agents-tools.md

@@ -455,45 +455,76 @@ Note: If you omit `parameters` or leave it empty, the framework injects a defaul
 | `edit_available` | `bool` | `True` | Allow editing in UI |
 | `answer` | `bool` | `True` | Include in response |
 
-### Connecting to Retrievals
+### Creating a Search from Scratch
 
-Retrieval tools reference Content API retrievals defined in `data/retrievals.py`:
+Use this order when creating a new search capability:
+
+1. Define a Retrieval
+2. Create a Retrieval Tool (Search)
+3. Register the Search in the Agent
+
+#### Step 1: Define a Retrieval
+
+Purpose: configure semantic search over a created topic. 
+
+Prerequisite: create the topic package first:
+
+```bash
+python manage.py starttopic product_docs
+```
+
+Location: `data/retrievals.py`
 
 ```python
-# data/retrievals.py
 from cogsol.content import BaseRetrieval
 from data.product_docs import ProductDocsTopic
 
+
 class ProductDocsRetrieval(BaseRetrieval):
     name = "product_docs_search"
     topic = ProductDocsTopic
     num_refs = 10
+```
 
-# agents/searches.py
+#### Step 2: Create a Retrieval Tool (Search)
+
+Purpose: connect the retrieval definition to a tool the agent can call.
+
+Location: `agents/searches.py`
+
+```python
 from cogsol.tools import BaseRetrievalTool
 from data.retrievals import ProductDocsRetrieval
 
+
 class ProductDocsSearch(BaseRetrievalTool):
-    name = "product_docs_search"
-    description = "Search the product documentation"
+    name = "search_product_docs"
+    description = "Search product documentation"
     retrieval = ProductDocsRetrieval()
+    parameters = []
 ```
 
-#### Using in Agents
+#### Step 3: Register the Search in the Agent
+
+Add the search tool to the agent `tools` list. Without this step, the search is not used by the agent.
 
 ```python
 from cogsol.agents import BaseAgent
-from .searches import ProductDocsSearch
+from ..searches import ProductDocsSearch
+
 
 class SupportAgent(BaseAgent):
     tools = [ProductDocsSearch()]
 ```
 
-**Important:** Before using retrieval tools, you must:
-1. Create the topic in `data/`
-2. Create the retrieval in `data/retrievals.py`
-3. Run `python manage.py makemigrations data`
-4. Run `python manage.py migrate data`
+After you define the topic class, the retrieval class, and the search registration in the agent, run:
+
+```bash
+python manage.py makemigrations data
+python manage.py migrate data
+python manage.py makemigrations
+python manage.py migrate
+```
 
 ---
 

docs/getting-started.md

@@ -583,6 +583,8 @@ class ProductDocsRetrieval(BaseRetrieval):
     num_refs = 10
 ```
 
+This is required before creating the search tool.
+
 ### Step 6: Connect Retrieval to Agent
 
 Create a retrieval tool in `agents/searches.py`:
@@ -599,7 +601,7 @@ class ProductDocsSearch(BaseRetrievalTool):
     parameters = []
 ```
 
-Then add it to your agent in `agents/customersupport/agent.py`:
+Then addd it to your agent in `agents/customersupport/agent.py`:
 
 ```python
 from ..searches import ProductDocsSearch
@@ -612,6 +614,9 @@ class CustomerSupportAgent(BaseAgent):
     ]
 ```
 
+Without this registration in `tools`, the search will not be used.
+
+
 ### Step 7: Deploy Topics and Retrievals
 
 Create and apply migrations for your content: