Clarify distinction between script tools and retrieval tools in documentation

docs/agents-tools.md

@@ -94,18 +94,21 @@ class QAAgent(BaseAgent):
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `tools` | `list[BaseTool]` | `[]` | Main tools available to agent |
-| `pretools` | `list[BaseTool]` | `[]` | Pre-processing tools |
+| `tools` | `list[BaseTool \| BaseRetrievalTool]` | `[]` | Main tools available to agent |
+| `pretools` | `list[BaseTool \| BaseRetrievalTool]` | `[]` | Pre-processing tools |
 
 ```python
 from cogsol.agents import BaseAgent
-from .tools import SearchTool, CalculatorTool
+from ..tools import CalculatorTool
+from ..searches import ProductDocsSearch
 
 class AssistantAgent(BaseAgent):
-    tools = [SearchTool(), CalculatorTool()]
+    tools = [CalculatorTool(), ProductDocsSearch()]
     pretools = [ContextLoader()]
 ```
 
+Use script tools (`BaseTool`) for capabilities/actions and retrieval tools (`BaseRetrievalTool`) for document search. Both are configured in the same list.
+
 #### Limits
 
 | Attribute | Type | Default | Description |
@@ -238,7 +241,7 @@ def definition(cls) -> dict[str, Any]:
 
 ## Tools
 
-Tools extend agent capabilities with custom functionality.
+Tools (`BaseTool`) are general Python capabilities that execute actions such as calculations, formatting, API calls, or orchestration.
 
 ### BaseTool
 
@@ -286,30 +289,24 @@ Define parameters using the `@tool_params` decorator:
 ```python
 from cogsol.tools import BaseTool, tool_params
 
-class SearchTool(BaseTool):
-    description = "Search the knowledge base"
+class CurrencyFormatterTool(BaseTool):
+    description = "Format a numeric amount as currency"
 
     @tool_params(
-        query={
-            "description": "Search query string",
-            "type": "string",
+        amount={
+            "description": "Amount to format",
+            "type": "number",
             "required": True
         },
-        limit={
-            "description": "Maximum results to return",
-            "type": "integer",
-            "required": False
-        },
-        include_metadata={
-            "description": "Include metadata in results",
-            "type": "boolean",
+        currency={
+            "description": "Currency symbol",
+            "type": "string",
             "required": False
         }
     )
     def run(self, chat=None, data=None, secrets=None, log=None,
-            query: str = "", limit: int = 10, include_metadata: bool = False):
-        # Implementation
-        pass
+            amount: float = 0.0, currency: str = "$"):
+        return f"{currency}{amount:,.2f}"
 ```
 
 #### Parameter Schema
@@ -329,14 +326,14 @@ class SearchTool(BaseTool):
 Parameters can also be defined in the docstring:
 
 ```python
-class SearchTool(BaseTool):
+class GreetingTool(BaseTool):
     def run(self, chat=None, data=None, secrets=None, log=None,
-            query: str = "", limit: int = 10):
+            name: str = "", formal: bool = False):
         """
-        query: The search query to execute.
-        limit: Maximum number of results to return.
+        name: Person to greet.
+        formal: Whether to use a formal greeting.
         """
-        pass
+        return f"Hello, {name}." if formal else f"Hi {name}!"
 ```
 
 ### Tool Implementation
@@ -369,9 +366,8 @@ def run(
 The `run()` method should return the tool's response:
 
 ```python
-def run(self, chat=None, data=None, secrets=None, log=None, query: str = ""):
-    results = self._search(query)
-    response = self._format_results(results)
+def run(self, chat=None, data=None, secrets=None, log=None, text: str = ""):
+    response = text.upper()
     return response  # String or structured data
 ```
 
@@ -418,7 +414,7 @@ class WeatherTool(BaseTool):
 
 ## Retrieval Tools
 
-Retrieval tools connect agents to Content API retrievals for semantic search over document collections.
+Retrieval tools (`BaseRetrievalTool`) are searches specialized for semantic retrieval over topic documents in the Content API.
 
 ### BaseRetrievalTool
 
@@ -483,7 +479,7 @@ class ProductDocsSearch(BaseRetrievalTool):
 
 ```python
 from cogsol.agents import BaseAgent
-from .searches import ProductDocsSearch
+from ..searches import ProductDocsSearch
 
 class SupportAgent(BaseAgent):
     tools = [ProductDocsSearch()]

docs/index.md

@@ -134,33 +134,37 @@ from cogsol.prompts import Prompts
 class SupportAgent(BaseAgent):
     system_prompt = Prompts.load("support.md")
     generation_config = genconfigs.QA()
-    tools = [SearchTool(), DocsSearch()]
+    tools = [
+        DateTool(),    # Script tool: executes Python capability
+        DocsSearch(),  # Retrieval tool: searches topic documents
+    ]
     temperature = 0.3
 
     class Meta:
         name = "SupportAgent"
         chat_name = "Customer Support"
 ```
 
+Both tool types are configured in the same `tools` list. Use script tools for actions/calculations and retrieval tools for document search.
+
 ### Tools
 
-Tools extend agent capabilities with custom logic:
+Tools are Python capabilities that perform actions with custom logic, extending the agent's capabilities::
 
 ```python
-from cogsol.tools import BaseTool, tool_params
+from cogsol.tools import BaseTool
+from datetime import datetime
 
-class SearchTool(BaseTool):
-    description = "Search the knowledge base"
-
-    @tool_params(query={"description": "Search query", "type": "string", "required": True})
-    def run(self, chat=None, data=None, secrets=None, log=None, query: str = ""):
-        results = perform_search(query)
-        return format_results(results)
+class DateTool(BaseTool):
+    description = "Return the current date in YYYY-MM-DD format"
+
+    def run(self, chat=None, data=None, secrets=None, log=None):
+        return datetime.utcnow().strftime("%Y-%m-%d")
 ```
 
 ### Retrieval Tools
 
-Retrieval tools connect agents to Content API retrievals:
+Retrieval tools (searches) are specialized for semantic retrieval from topic documents through the Content API:
 
 ```python
 from cogsol.tools import BaseRetrievalTool