diff --git a/README.md b/README.md
index 078ab63..d60cb62 100644
--- a/README.md
+++ b/README.md
@@ -228,7 +228,10 @@ For the full catalog (or the meta search/execute tools), use the `.pydantic_ai()
 ```python
 toolset = StackOneToolSet()
 tools = toolset.pydantic_ai(account_ids=[os.environ["STACKONE_ACCOUNT_ID"]])
-# or pydantic_ai(mode="search_and_execute") for agent-driven discovery
+
+# For agent-driven discovery, enable search on the constructor:
+# toolset = StackOneToolSet(search={"method": "auto"})
+# tools = toolset.pydantic_ai(mode="search_and_execute")
 ```
 
 </details>
@@ -359,15 +362,15 @@ Search for tools using natural language queries. Works with both semantic (cloud
 
 ```python
 import os
+from stackone_ai import StackOneToolSet
 
-# Get a callable search tool
-toolset = StackOneToolSet()
+# Get a callable search tool — search must be enabled on the toolset
+toolset = StackOneToolSet(search={"method": "auto"})
 account_id = os.getenv("STACKONE_ACCOUNT_ID")
-all_tools = toolset.fetch_tools(account_ids=[account_id])
 search_tool = toolset.get_search_tool()
 
-# Search for relevant tools — returns a Tools collection
-tools = search_tool("manage employees", top_k=5)
+# Search for relevant tools — returns a Tools collection scoped to the account
+tools = search_tool("manage employees", top_k=5, account_ids=[account_id])
 
 # Execute a discovered tool directly
 tools[0](limit=10)
@@ -381,7 +384,9 @@ Discover tools using natural language instead of exact names. Queries like "onbo
 import os
 from stackone_ai import StackOneToolSet
 
-toolset = StackOneToolSet()
+# Search must be enabled on the constructor — pass `search={}` for defaults,
+# or set a backend / top_k explicitly.
+toolset = StackOneToolSet(search={"method": "auto"})
 
 # Search by intent — returns Tools collection ready for any framework
 account_id = os.getenv("STACKONE_ACCOUNT_ID")
diff --git a/stackone_ai/toolset.py b/stackone_ai/toolset.py
index 58caf60..fef9198 100644
--- a/stackone_ai/toolset.py
+++ b/stackone_ai/toolset.py
@@ -645,13 +645,14 @@ def get_search_tool(self, *, search: SearchMode | None = None) -> SearchTool:
 
         Example::
 
-            toolset = StackOneToolSet()
+            toolset = StackOneToolSet(search={"method": "auto"})
             search_tool = toolset.get_search_tool()
             tools = search_tool("manage employee records", account_ids=["acc-123"])
         """
         if self._search_config is None:
             raise ToolsetConfigError(
-                "Search is disabled. Initialize StackOneToolSet with a search config to enable."
+                "Search is disabled. Pass search={} (or search={'method': 'auto'}) to "
+                "StackOneToolSet(...) to enable. See README 'Search Tool' for options."
             )
 
         config: SearchConfig = {**self._search_config}
@@ -664,7 +665,8 @@ def _build_tools(self, account_ids: list[str] | None = None) -> Tools:
         """Build tool_search + tool_execute tools scoped to this toolset."""
         if self._search_config is None:
             raise ToolsetConfigError(
-                "Search is disabled. Initialize StackOneToolSet with a search config to enable."
+                "Search is disabled. Pass search={} (or search={'method': 'auto'}) to "
+                "StackOneToolSet(...) to enable. See README 'Search Tool' for options."
             )
 
         if account_ids:
@@ -713,8 +715,8 @@ def openai(
             toolset = StackOneToolSet()
             tools = toolset.openai()
 
-            # Meta tools for agent-driven discovery
-            toolset = StackOneToolSet()
+            # Meta tools for agent-driven discovery — search must be enabled
+            toolset = StackOneToolSet(search={"method": "auto"})
             tools = toolset.openai(mode="search_and_execute")
         """
         effective_account_ids = account_ids or (
@@ -783,7 +785,8 @@ def pydantic_ai(
             tools = toolset.pydantic_ai()
             agent = Agent("openai:gpt-5.4", tools=tools)
 
-            # Meta tools for agent-driven discovery
+            # Meta tools for agent-driven discovery — search must be enabled
+            toolset = StackOneToolSet(search={"method": "auto"})
             tools = toolset.pydantic_ai(mode="search_and_execute")
         """
         effective_account_ids = account_ids or (
@@ -929,7 +932,8 @@ def search_tools(
         """
         if self._search_config is None:
             raise ToolsetConfigError(
-                "Search is disabled. Initialize StackOneToolSet with a search config to enable."
+                "Search is disabled. Pass search={} (or search={'method': 'auto'}) to "
+                "StackOneToolSet(...) to enable. See README 'Search Tool' for options."
             )
 
         # Merge constructor defaults with per-call overrides
@@ -1082,7 +1086,8 @@ def search_action_names(
         """
         if self._search_config is None:
             raise ToolsetConfigError(
-                "Search is disabled. Initialize StackOneToolSet with search config to enable."
+                "Search is disabled. Pass search={} (or search={'method': 'auto'}) to "
+                "StackOneToolSet(...) to enable. See README 'Search Tool' for options."
             )
 
         # Merge constructor defaults with per-call overrides