Update SDK as per PR suggestions

Author: shashi-stackone

README.md

@@ -318,10 +318,10 @@ tools = toolset.fetch_tools(actions=["hris_*"])
 utility_tools = tools.utility_tools()
 
 # Search for relevant tools using natural language
-results = utility_tools.search_tool.call(query="manage employees", limit=5)
+results = utility_tools.get_search_tool()(query="manage employees", top_k=5)
 
 # Execute discovered tools dynamically
-result = utility_tools.execute_tool.call(toolName="hris_list_employees", params={"limit": 10})
+result = utility_tools.get_execute_tool()(toolName="hris_list_employees", params={"limit": 10})
 ```
 
 ## Semantic Search

examples/semantic_search_example.py

@@ -244,7 +244,7 @@ def example_utility_tools_semantic():
     print(f'Step 3: Calling tool_search with query="{query}"...')
     print("  (Searches are scoped to your linked connectors)")
     print()
-    result = utility.search_tool.call(query=query, limit=5)
+    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:

examples/utility_tools_example.py

@@ -50,7 +50,7 @@ def example_utility_tools_basic():
     utility_tools = all_tools.utility_tools()
 
     # Search for employee management tools
-    result = utility_tools.search_tool.call(query="manage employees create update list", limit=5)
+    result = utility_tools.get_search_tool()(query="manage employees create update list", top_k=5)
 
     print("Found relevant tools:")
     for tool in result.get("tools", []):
@@ -76,7 +76,7 @@ def example_utility_tools_with_execution():
     utility_tools = all_tools.utility_tools()
 
     # Step 1: Search for relevant tools
-    search_result = utility_tools.search_tool.call(query="list all employees", limit=1)
+    search_result = utility_tools.get_search_tool()(query="list all employees", top_k=1)
 
     tools_found = search_result.get("tools", [])
     if tools_found:
@@ -88,7 +88,7 @@ def example_utility_tools_with_execution():
         # Step 2: Execute the found tool
         try:
             print(f"\nExecuting {best_tool['name']}...")
-            result = utility_tools.execute_tool.call(toolName=best_tool["name"], params={"limit": 5})
+            result = utility_tools.get_execute_tool()(toolName=best_tool["name"], params={"limit": 5})
             print(f"Execution result: {result}")
         except Exception as e:
             print(f"Execution failed (expected in example): {e}")

stackone_ai/models.py

@@ -332,6 +332,13 @@ def call(self, *args: Any, options: JsonDict | None = None, **kwargs: Any) -> Js
 
         return self.execute(kwargs if kwargs else None)
 
+    def __call__(self, *args: Any, options: JsonDict | None = None, **kwargs: Any) -> JsonDict:
+        """Make the tool directly callable.
+
+        Alias for :meth:`call` so that ``tool(query="…")`` works.
+        """
+        return self.call(*args, options=options, **kwargs)
+
     def to_openai_function(self) -> JsonDict:
         """Convert this tool to OpenAI's function format
 
@@ -598,11 +605,11 @@ def utility_tools(
             toolset = StackOneToolSet()
             tools = toolset.fetch_tools()
             utility = tools.utility_tools(search_method="semantic")
-            result = utility.search_tool.call(query="onboard new hire")
+            result = utility.get_search_tool()(query="onboard new hire")
 
             # Local BM25+TF-IDF search (default)
             utility = tools.utility_tools()
-            result = utility.search_tool.call(query="onboard new hire")
+            result = utility.get_search_tool()(query="onboard new hire")
         """
         from stackone_ai.utility_tools import create_tool_execute
 
@@ -632,8 +639,7 @@ def utility_tools(
 class UtilityTools(Tools):
     """Utility tools collection with typed accessors for search and execute tools."""
 
-    @property
-    def search_tool(self) -> StackOneTool:
+    def get_search_tool(self) -> StackOneTool:
         """Get the tool_search utility tool.
 
         Returns:
@@ -642,13 +648,12 @@ def search_tool(self) -> StackOneTool:
         Raises:
             StackOneError: If tool_search is not found in the collection
         """
-        tool = self.get_tool("tool_search")
-        if tool is None:
-            raise StackOneError("tool_search not found in this UtilityTools collection")
-        return tool
+        for tool in self.tools:
+            if tool.name == "tool_search":
+                return tool
+        raise StackOneError("tool_search not found in this UtilityTools collection")
 
-    @property
-    def execute_tool(self) -> StackOneTool:
+    def get_execute_tool(self) -> StackOneTool:
         """Get the tool_execute utility tool.
 
         Returns:
@@ -657,7 +662,7 @@ def execute_tool(self) -> StackOneTool:
         Raises:
             StackOneError: If tool_execute is not found in the collection
         """
-        tool = self.get_tool("tool_execute")
-        if tool is None:
-            raise StackOneError("tool_execute not found in this UtilityTools collection")
-        return tool
+        for tool in self.tools:
+            if tool.name == "tool_execute":
+                return tool
+        raise StackOneError("tool_execute not found in this UtilityTools collection")

stackone_ai/toolset.py

@@ -406,10 +406,10 @@ def _search_one(c: str) -> list[SemanticSearchResult]:
             if search_tool:
                 fallback_params: dict[str, Any] = {
                     "query": query,
-                    "limit": top_k,
+                    "top_k": top_k,
                 }
                 if min_similarity is not None:
-                    fallback_params["minScore"] = min_similarity
+                    fallback_params["min_score"] = min_similarity
                 result = search_tool.execute(fallback_params)
                 matched_names = [t["name"] for t in result.get("tools", [])]
                 # Filter by available connectors and preserve relevance order

stackone_ai/utility_tools.py

@@ -201,13 +201,13 @@ def create_tool_search(index: ToolIndex) -> StackOneTool:
                     '(e.g., "tools for managing employees", "create time off request")'
                 ),
             },
-            "limit": {
+            "top_k": {
                 "type": "number",
                 "description": "Maximum number of tools to return (default: 5)",
                 "default": 5,
                 "nullable": True,
             },
-            "minScore": {
+            "min_score": {
                 "type": "number",
                 "description": "Minimum relevance score (0-1) to filter results (default: 0.0)",
                 "default": 0.0,
@@ -225,11 +225,11 @@ def execute_filter(arguments: str | JsonDict | None = None) -> JsonDict:
             kwargs = arguments or {}
 
         query = kwargs.get("query", "")
-        limit = int(kwargs["limit"]) if kwargs.get("limit") is not None else 5
-        min_score = float(kwargs["minScore"]) if kwargs.get("minScore") is not None else 0.0
+        top_k = int(kwargs["top_k"]) if kwargs.get("top_k") is not None else 5
+        min_score = float(kwargs["min_score"]) if kwargs.get("min_score") is not None else 0.0
 
         # Search for tools
-        results = index.search(query, limit, min_score)
+        results = index.search(query, top_k, min_score)
 
         # Format results
         tools_data = [
@@ -310,13 +310,13 @@ def create_semantic_tool_search(
                     '(e.g., "onboard a new team member", "request vacation days")'
                 ),
             },
-            "limit": {
+            "top_k": {
                 "type": "number",
                 "description": "Maximum number of tools to return (default: 5)",
                 "default": 5,
                 "nullable": True,
             },
-            "minSimilarity": {
+            "min_similarity": {
                 "type": "number",
                 "description": (
                     "Minimum similarity score (0-1) to filter results. "
@@ -340,8 +340,8 @@ def execute_search(arguments: str | JsonDict | None = None) -> JsonDict:
             kwargs = arguments or {}
 
         query = kwargs.get("query", "")
-        limit = int(kwargs["limit"]) if kwargs.get("limit") is not None else 5
-        min_similarity = float(kwargs["minSimilarity"]) if kwargs.get("minSimilarity") is not None else None
+        top_k = int(kwargs["top_k"]) if kwargs.get("top_k") is not None else 5
+        min_similarity = float(kwargs["min_similarity"]) if kwargs.get("min_similarity") is not None else None
         connector = kwargs.get("connector")
 
         all_results: list[SemanticSearchResult] = []
@@ -361,7 +361,7 @@ def execute_search(arguments: str | JsonDict | None = None) -> JsonDict:
                             semantic_client.search,
                             query=query,
                             connector=c,
-                            top_k=limit,
+                            top_k=top_k,
                             min_similarity=min_similarity,
                         ): c
                         for c in connectors_to_search
@@ -377,12 +377,12 @@ def execute_search(arguments: str | JsonDict | None = None) -> JsonDict:
             response = semantic_client.search(
                 query=query,
                 connector=connector,
-                top_k=limit,
+                top_k=top_k,
                 min_similarity=min_similarity,
             )
             all_results = list(response.results)
 
-        # Sort by score, deduplicate, apply limit
+        # Sort by score, deduplicate, apply top_k
         all_results.sort(key=lambda r: r.similarity_score, reverse=True)
         seen: set[str] = set()
         tools_data: list[dict[str, object]] = []
@@ -399,7 +399,7 @@ def execute_search(arguments: str | JsonDict | None = None) -> JsonDict:
                     }
                 )
 
-        return {"tools": tools_data[:limit]}
+        return {"tools": tools_data[:top_k]}
 
     execute_config = ExecuteConfig(
         name=name,

tests/test_semantic_search.py

@@ -550,7 +550,7 @@ def test_semantic_tool_search_execute(self, mock_search: MagicMock) -> None:
         client = SemanticSearchClient(api_key="test-key")
         tool = create_semantic_tool_search(client)
 
-        result = tool.execute({"query": "create employee", "limit": 5})
+        result = tool.execute({"query": "create employee", "top_k": 5})
 
         assert "tools" in result
         assert len(result["tools"]) == 1
@@ -581,7 +581,7 @@ def test_semantic_tool_search_with_min_similarity(self, mock_search: MagicMock)
         client = SemanticSearchClient(api_key="test-key")
         tool = create_semantic_tool_search(client)
 
-        result = tool.execute({"query": "test", "limit": 10, "minSimilarity": 0.5})
+        result = tool.execute({"query": "test", "top_k": 10, "min_similarity": 0.5})
 
         assert len(result["tools"]) == 1
         assert result["tools"][0]["name"] == "high_score_action"
@@ -623,8 +623,8 @@ def test_semantic_tool_search_has_correct_parameters(self) -> None:
 
         props = tool.parameters.properties
         assert "query" in props
-        assert "limit" in props
-        assert "minSimilarity" in props
+        assert "top_k" in props
+        assert "min_similarity" in props
         assert "connector" in props
 
 
@@ -677,7 +677,7 @@ def _search_side_effect(
         client = SemanticSearchClient(api_key="test-key")
         tool = create_semantic_tool_search(client, available_connectors={"bamboohr", "hibob"})
 
-        result = tool.execute({"query": "create employee", "limit": 10})
+        result = tool.execute({"query": "create employee", "top_k": 10})
 
         # Should have searched each connector separately
         assert mock_search.call_count == 2
@@ -755,7 +755,7 @@ def test_no_connectors_queries_full_catalog(self, mock_search: MagicMock) -> Non
         client = SemanticSearchClient(api_key="test-key")
         tool = create_semantic_tool_search(client)  # No available_connectors
 
-        result = tool.execute({"query": "create employee", "limit": 5})
+        result = tool.execute({"query": "create employee", "top_k": 5})
 
         # Should make a single call without connector scoping
         mock_search.assert_called_once_with(
@@ -1216,7 +1216,7 @@ def test_semantic_tool_search_deduplicates_versions(self, mock_search: MagicMock
 
         client = SemanticSearchClient(api_key="test-key")
         tool = create_semantic_tool_search(client)
-        result = tool.execute({"query": "list employees", "limit": 10})
+        result = tool.execute({"query": "list employees", "top_k": 10})
 
         # Should deduplicate: only one result
         assert len(result["tools"]) == 1

tests/test_utility_tools.py

@@ -255,7 +255,7 @@ def test_search_tool_execute_with_json_string(self, sample_tools):
         search_tool = create_tool_search(index)
 
         # Execute with JSON string
-        json_input = json.dumps({"query": "employee", "limit": 2, "minScore": 0.0})
+        json_input = json.dumps({"query": "employee", "top_k": 2, "min_score": 0.0})
         result = search_tool.execute(json_input)
 
         assert "tools" in result
@@ -271,8 +271,8 @@ def test_search_tool_execute(self, sample_tools):
         result = search_tool.execute(
             {
                 "query": "manage employees",
-                "limit": 3,
-                "minScore": 0.0,
+                "top_k": 3,
+                "min_score": 0.0,
             }
         )
 
@@ -293,7 +293,7 @@ def test_search_tool_call(self, sample_tools):
         search_tool = create_tool_search(index)
 
         # Call with kwargs
-        result = search_tool.call(query="candidate", limit=2)
+        result = search_tool.call(query="candidate", top_k=2)
 
         assert "tools" in result
         assert len(result["tools"]) <= 2
@@ -384,7 +384,7 @@ def test_utility_tools_functionality(self, tools_collection):
         result = search_tool.execute(
             {
                 "query": "create employee",
-                "limit": 1,
+                "top_k": 1,
             }
         )
 
@@ -489,6 +489,6 @@ def test_utility_tools_with_custom_alpha(self, sample_tools):
         assert "alpha=0.3" in search_tool.description
 
         # Test it works
-        result = search_tool.execute({"query": "list employees", "limit": 3})
+        result = search_tool.execute({"query": "list employees", "top_k": 3})
         assert "tools" in result
         assert len(result["tools"]) > 0