get rid of the utility tools completely as discussed

Author: shashi-stackone

README.md

@@ -306,22 +306,23 @@ result = feedback_tool.call(
 - "Are you ok with sending feedback to StackOne? The LLM will take care of sending it."
 - Only call the tool after the user explicitly agrees.
 
-## Utility Tools (Beta)
+## Search Tool
 
-Utility tools enable dynamic tool discovery and execution without hardcoding tool names.
+Search for tools using natural language queries. Works with both semantic (cloud) and local BM25+TF-IDF search.
 
 ### Basic Usage
 
 ```python
-# Get utility tools for dynamic discovery
-tools = toolset.fetch_tools(actions=["hris_*"])
-utility_tools = tools.utility_tools()
+# Get a callable search tool
+toolset = StackOneToolSet()
+all_tools = toolset.fetch_tools(account_ids=["your-account-id"])
+search_tool = toolset.get_search_tool()
 
-# Search for relevant tools using natural language
-results = utility_tools.get_search_tool()(query="manage employees", top_k=5)
+# Search for relevant tools — returns a Tools collection
+tools = search_tool("manage employees", top_k=5)
 
-# Execute discovered tools dynamically
-result = utility_tools.get_execute_tool()(toolName="hris_list_employees", params={"limit": 10})
+# Execute a discovered tool directly
+tools[0](limit=10)
 ```
 
 ## Semantic Search
@@ -352,7 +353,7 @@ For more examples, check out the [examples/](examples/) directory:
 - [OpenAI Integration](examples/openai_integration.py)
 - [LangChain Integration](examples/langchain_integration.py)
 - [CrewAI Integration](examples/crewai_integration.py)
-- [Utility Tools](examples/utility_tools_example.py)
+- [Search Tool](examples/search_tool_example.py)
 - [Semantic Search](examples/semantic_search_example.py)
 
 ## Development

examples/utility_tools_example.py examples/search_tool_example.pyexamples/utility_tools_example.py renamed to examples/search_tool_example.py

@@ -1,9 +1,9 @@
 #!/usr/bin/env python
 """
-Example demonstrating utility tools for dynamic tool discovery and execution.
+Example demonstrating dynamic tool discovery using search_tool.
 
-Utility tools allow AI agents to search for relevant tools based on natural language queries
-and execute them dynamically without hardcoding tool names.
+The search tool allows AI agents to discover relevant tools based on natural language
+queries without hardcoding tool names.
 
 Prerequisites:
 - STACKONE_API_KEY environment variable set
@@ -12,7 +12,7 @@
 
 This example is runnable with the following command:
 ```bash
-uv run examples/utility_tools_example.py
+uv run examples/search_tool_example.py
 ```
 """
 
@@ -31,8 +31,8 @@
 _account_ids = [aid.strip() for aid in os.getenv("STACKONE_ACCOUNT_ID", "").split(",") if aid.strip()]
 
 
-def example_utility_tools_basic():
-    """Basic example of using utility tools for tool discovery"""
+def example_search_tool_basic():
+    """Basic example of using the search tool for tool discovery"""
     print("Example 1: Dynamic tool discovery\n")
 
     # Initialize StackOne toolset
@@ -46,20 +46,20 @@ def example_utility_tools_basic():
         print("No tools found. Check your linked accounts.")
         return
 
-    # Get utility tools for dynamic discovery
-    utility_tools = all_tools.utility_tools()
+    # Get a search tool for dynamic discovery
+    search_tool = toolset.get_search_tool()
 
-    # Search for employee management tools
-    result = utility_tools.get_search_tool()(query="manage employees create update list", top_k=5)
+    # Search for employee management tools — returns a Tools collection
+    tools = search_tool("manage employees create update list", top_k=5, account_ids=_account_ids)
 
-    print("Found relevant tools:")
-    for tool in result.get("tools", []):
-        print(f"  - {tool['name']} (score: {tool['score']:.2f}): {tool['description']}")
+    print(f"Found {len(tools)} relevant tools:")
+    for tool in tools:
+        print(f"  - {tool.name}: {tool.description}")
 
     print()
 
 
-def example_utility_tools_with_execution():
+def example_search_tool_with_execution():
     """Example of discovering and executing tools dynamically"""
     print("Example 2: Dynamic tool execution\n")
 
@@ -73,22 +73,20 @@ def example_utility_tools_with_execution():
         print("No tools found. Check your linked accounts.")
         return
 
-    utility_tools = all_tools.utility_tools()
+    search_tool = toolset.get_search_tool()
 
     # Step 1: Search for relevant tools
-    search_result = utility_tools.get_search_tool()(query="list all employees", top_k=1)
+    tools = search_tool("list all employees", top_k=1, account_ids=_account_ids)
 
-    tools_found = search_result.get("tools", [])
-    if tools_found:
-        best_tool = tools_found[0]
-        print(f"Best matching tool: {best_tool['name']}")
-        print(f"Description: {best_tool['description']}")
-        print(f"Relevance score: {best_tool['score']:.2f}")
+    if tools:
+        best_tool = tools[0]
+        print(f"Best matching tool: {best_tool.name}")
+        print(f"Description: {best_tool.description}")
 
-        # Step 2: Execute the found tool
+        # Step 2: Execute the found tool directly
         try:
-            print(f"\nExecuting {best_tool['name']}...")
-            result = utility_tools.get_execute_tool()(toolName=best_tool["name"], params={"limit": 5})
+            print(f"\nExecuting {best_tool.name}...")
+            result = best_tool(limit=5)
             print(f"Execution result: {result}")
         except Exception as e:
             print(f"Execution failed (expected in example): {e}")
@@ -97,8 +95,8 @@ def example_utility_tools_with_execution():
 
 
 def example_with_openai():
-    """Example of using utility tools with OpenAI"""
-    print("Example 3: Using utility tools with OpenAI\n")
+    """Example of using search tool with OpenAI"""
+    print("Example 3: Using search tool with OpenAI\n")
 
     try:
         from openai import OpenAI
@@ -109,20 +107,19 @@ def example_with_openai():
         # Initialize StackOne toolset
         toolset = StackOneToolSet()
 
-        # Get BambooHR tools and their utility tools using MCP-backed fetch_tools()
-        bamboohr_tools = toolset.fetch_tools(account_ids=_account_ids, actions=["bamboohr_*"])
-        utility_tools = bamboohr_tools.utility_tools()
+        # Search for BambooHR employee tools
+        tools = toolset.search_tools("manage employees", account_ids=_account_ids, top_k=5)
 
         # Convert to OpenAI format
-        openai_tools = utility_tools.to_openai()
+        openai_tools = tools.to_openai()
 
-        # Create a chat completion with utility tools
+        # Create a chat completion with discovered tools
         response = client.chat.completions.create(
             model="gpt-4",
             messages=[
                 {
                     "role": "system",
-                    "content": "You are an HR assistant. Use tool_search to find appropriate tools, then tool_execute to execute them.",
+                    "content": "You are an HR assistant with access to employee management tools.",
                 },
                 {"role": "user", "content": "Can you help me find tools for managing employee records?"},
             ],
@@ -158,18 +155,11 @@ def example_with_langchain():
         toolset = StackOneToolSet()
 
         # Get tools and convert to LangChain format using MCP-backed fetch_tools()
-        tools = toolset.fetch_tools(account_ids=_account_ids, actions=["bamboohr_list_*"])
-        langchain_tools = tools.to_langchain()
+        tools = toolset.search_tools("list employees", account_ids=_account_ids, top_k=5)
+        langchain_tools = list(tools.to_langchain())
 
-        # Get utility tools as well
-        utility_tools = tools.utility_tools()
-        langchain_utility_tools = utility_tools.to_langchain()
-
-        # Combine all tools
-        all_langchain_tools = list(langchain_tools) + list(langchain_utility_tools)
-
-        print(f"Available tools for LangChain: {len(all_langchain_tools)}")
-        for tool in all_langchain_tools:
+        print(f"Available tools for LangChain: {len(langchain_tools)}")
+        for tool in langchain_tools:
             print(f"  - {tool.name}: {tool.description}")
 
         # Create LangChain agent
@@ -179,15 +169,15 @@ def example_with_langchain():
             [
                 (
                     "system",
-                    "You are an HR assistant. Use the utility tools to discover and execute relevant tools.",
+                    "You are an HR assistant. Use the available tools to help the user.",
                 ),
                 ("human", "{input}"),
                 ("placeholder", "{agent_scratchpad}"),
             ]
         )
 
-        agent = create_tool_calling_agent(llm, all_langchain_tools, prompt)
-        agent_executor = AgentExecutor(agent=agent, tools=all_langchain_tools, verbose=True)
+        agent = create_tool_calling_agent(llm, langchain_tools, prompt)
+        agent_executor = AgentExecutor(agent=agent, tools=langchain_tools, verbose=True)
 
         # Run the agent
         result = agent_executor.invoke({"input": "Find tools that can list employee data"})
@@ -206,7 +196,7 @@ def example_with_langchain():
 def main():
     """Run all examples"""
     print("=" * 60)
-    print("StackOne AI SDK - Utility Tools Examples")
+    print("StackOne AI SDK - Search Tool Examples")
     print("=" * 60)
     print()
 
@@ -220,8 +210,8 @@ def main():
         return
 
     # Basic examples that work without external APIs
-    example_utility_tools_basic()
-    example_utility_tools_with_execution()
+    example_search_tool_basic()
+    example_search_tool_with_execution()
 
     # Examples that require OpenAI API
     if os.getenv("OPENAI_API_KEY"):

examples/semantic_search_example.py

@@ -53,14 +53,11 @@
    inspecting results before committing to a full fetch. When account_ids are
    provided, each connector is searched in parallel (same as search_tools).
 
-3. utility_tools()  — Agent-loop pattern
+3. get_search_tool()  — Agent-loop pattern
 
-   Creates tool_search and tool_execute utility tools that agents can call
-   inside an agentic loop. Pass search_method="semantic" to enable
-   cloud-based semantic search; without it, local BM25+TF-IDF is used.
-   When created via utility_tools(), tool_search is automatically scoped
-   to the user's linked connectors. The agent searches, inspects, and
-   executes tools dynamically.
+   Returns a callable SearchTool that wraps search_tools(). Call it
+   with a natural language query to get a Tools collection back.
+   Designed for agent loops where the LLM decides what to search for.
 
 
 This example is runnable with the following command:
@@ -213,43 +210,38 @@ def example_search_tools_with_connector():
     print()
 
 
-def example_utility_tools_semantic():
-    """Using utility tools with semantic search for agent loops.
+def example_search_tool_agent_loop():
+    """Using get_search_tool() for agent loops.
 
-    Pass search_method="semantic" to utility_tools() to enable cloud-based
-    semantic search. Without it, utility_tools() uses local BM25+TF-IDF
-    search instead.
-
-    When created via utility_tools(), tool_search is automatically scoped to
-    the connectors available in your fetched tools collection.
+    get_search_tool() returns a callable that wraps search_tools().
+    Call it with a query to get a Tools collection back — designed
+    for agent loops where the LLM decides what to search for.
     """
     print("=" * 60)
-    print("Example 4: Utility tools with semantic search")
+    print("Example 4: Search tool for agent loops")
     print("=" * 60)
     print()
 
     toolset = StackOneToolSet()
 
     print("Step 1: Fetching tools from your linked accounts via MCP...")
-    tools = toolset.fetch_tools(account_ids=_account_ids)
-    print(f"Loaded {len(tools)} tools.")
+    all_tools = toolset.fetch_tools(account_ids=_account_ids)
+    print(f"Loaded {len(all_tools)} tools.")
     print()
 
-    print("Step 2: Creating utility tools with semantic search enabled...")
-    print('  Pass search_method="semantic" to enable cloud-based semantic search.')
-    utility = tools.utility_tools(search_method="semantic")
+    print("Step 2: Getting a callable search tool...")
+    search_tool = toolset.get_search_tool()
 
     query = "cancel an event or meeting"
     print()
-    print(f'Step 3: Calling tool_search with query="{query}"...')
+    print(f'Step 3: Calling search_tool("{query}")...')
     print("  (Searches are scoped to your linked connectors)")
     print()
-    result = utility.get_search_tool()(query=query, top_k=5)
-    tools_data = result.get("tools", [])
-    print(f"tool_search returned {len(tools_data)} results:")
-    for tool_info in tools_data:
-        print(f"  [{tool_info['score']:.2f}] {tool_info['name']}")
-        print(f"         {tool_info['description']}")
+    tools = search_tool(query, top_k=5, account_ids=_account_ids)
+    print(f"search_tool returned {len(tools)} tools:")
+    for tool in tools:
+        print(f"  - {tool.name}")
+        print(f"    {tool.description}")
 
     print()
 
@@ -409,7 +401,7 @@ def main():
 
     example_search_tools()
     example_search_tools_with_connector()
-    example_utility_tools_semantic()
+    example_search_tool_agent_loop()
 
     # Framework integration patterns
     example_openai_agent_loop()

examples/test_examples.py

@@ -30,7 +30,7 @@ def get_example_files() -> list[str]:
     "index.py": ["mcp"],
     "file_uploads.py": ["mcp"],
     "stackone_account_ids.py": ["mcp"],
-    "utility_tools_example.py": ["mcp"],
+    "search_tool_example.py": ["mcp"],
     "semantic_search_example.py": ["mcp"],
     "mcp_server.py": ["mcp"],
 }

stackone_ai/__init__.py

@@ -1,19 +1,19 @@
 """StackOne AI SDK"""
 
-from stackone_ai.models import StackOneTool, Tools, UtilityTools
+from stackone_ai.models import StackOneTool, Tools
 from stackone_ai.semantic_search import (
     SemanticSearchClient,
     SemanticSearchError,
     SemanticSearchResponse,
     SemanticSearchResult,
 )
-from stackone_ai.toolset import StackOneToolSet
+from stackone_ai.toolset import SearchTool, StackOneToolSet
 
 __all__ = [
     "StackOneToolSet",
     "StackOneTool",
     "Tools",
-    "UtilityTools",
+    "SearchTool",
     # Semantic search
     "SemanticSearchClient",
     "SemanticSearchResult",