From ca7f3b8f001cbca32e8097ca255a77d99ea42a22 Mon Sep 17 00:00:00 2001
From: Nicolas Fernandez <nicolas@nicolasf.uy>
Date: Wed, 18 Mar 2026 10:54:56 -0300
Subject: [PATCH 1/2] Enhance documentation for search agent integration
 workflow

---
 docs/agents-tools.md    | 49 ++++++++++++++++++++++++++++++-----------
 docs/getting-started.md |  7 +++++-
 2 files changed, 42 insertions(+), 14 deletions(-)

diff --git a/docs/agents-tools.md b/docs/agents-tools.md
index f676c07..d7f52db 100644
--- a/docs/agents-tools.md
+++ b/docs/agents-tools.md
@@ -455,45 +455,68 @@ 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. 
+
+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 defining topic and retrieval classes, run:
+
+```bash
+python manage.py makemigrations data
+python manage.py migrate data
+```
 
 ---
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 275e6e0..dcd635d 100644
--- a/docs/getting-started.md
+++ b/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:

From 0197466ccff8cd7349355daaee402286568f260a Mon Sep 17 00:00:00 2001
From: Nicolas Fernandez <nicolas@nicolasf.uy>
Date: Wed, 18 Mar 2026 11:42:11 -0300
Subject: [PATCH 2/2] codex review update

---
 docs/agents-tools.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/docs/agents-tools.md b/docs/agents-tools.md
index d7f52db..c9b25cb 100644
--- a/docs/agents-tools.md
+++ b/docs/agents-tools.md
@@ -467,6 +467,12 @@ Use this order when creating a new search capability:
 
 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
@@ -511,11 +517,13 @@ class SupportAgent(BaseAgent):
     tools = [ProductDocsSearch()]
 ```
 
-After defining topic and retrieval classes, run:
+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
 ```
 
 ---