StackOneToolSet

Relevant source files

• README.md
• stackone_ai/toolset.py
• tests/test_toolset.py

This page provides a complete API reference for the StackOneToolSet class, the main entry point for tool discovery and management in the StackOne AI SDK.

For information about executing tools and converting them to framework-specific formats, see StackOneTool and Tools. For semantic search configuration details, see Semantic Search API. For integration with AI frameworks, see Framework Integrations.

---

Overview

StackOneToolSet is the primary interface for discovering and managing StackOne tools. It provides:

• Dynamic tool discovery via MCP backend with filtering by provider, action patterns, and account IDs
• Semantic search using natural language queries to find relevant tools
• Account management for multi-tenant scenarios
• Search configuration with auto-fallback between semantic and local search modes

The class coordinates between the MCP backend for tool definitions, the semantic search API for natural language discovery, and provides factory methods for creating tool instances.

Sources: stackone_ai/toolset.py313-852

---

Class Definition and Initialization

StackOneToolSet Constructor

Constructor Parameters

Parameter	Type	Required	Default	Description
api_key	str | None	No*	None	API key for authentication. If not provided, reads from STACKONE_API_KEY environment variable.
account_id	str | None	No	None	Default account ID for tool operations. Can be overridden per-method or via set_accounts().
base_url	str | None	No	DEFAULT_BASE_URL	Base URL for API requests. Override for custom deployments.
search	SearchConfig | None	No	{"method": "auto"}	Search configuration. Pass None to disable search entirely. Pass dict with method, top_k, min_similarity for custom defaults.

* Either api_key parameter or STACKONE_API_KEY environment variable must be provided.

Raises

• ToolsetConfigError: If no API key is provided via parameter or environment variable

Initialization Flow

Sources: stackone_ai/toolset.py316-350 stackone_ai/toolset.py338-343

---

Configuration Types

SearchConfig TypedDict

Field	Type	Description
method	SearchMode	Search backend: "auto" (try semantic, fallback to local), "semantic" (API only), or "local" (BM25+TF-IDF only)
top_k	int	Maximum number of results to return
min_similarity	float	Minimum similarity score threshold (0.0-1.0)

All fields are optional. When provided to constructor, these become defaults for search methods. Per-call parameters override these defaults.

Sources: stackone_ai/toolset.py36-53 stackone_ai/toolset.py33

---

Account Management

set_accounts

Sets default account IDs for tool filtering. Returns self for method chaining.

Parameters:

• account_ids: List of account ID strings to use as defaults

Returns: The StackOneToolSet instance for chaining

Example:

Sources: stackone_ai/toolset.py351-361

---

Tool Discovery Methods

fetch_tools

Fetches tools from the MCP backend with optional filtering. This is the primary method for explicit tool discovery.

Parameters:

Parameter	Type	Description
account_ids	list[str] | None	Account IDs to fetch tools for. If None, uses set_accounts() value or constructor account_id. If no accounts specified, fetches global tools.
providers	list[str] | None	Provider name filters (e.g., ["bamboohr", "hibob"]). Case-insensitive matching.
actions	list[str] | None	Action pattern filters with glob support (e.g., ["*_list_*", "bamboohr_*"]).

Returns: Tools collection containing matched tools

Raises: ToolsetLoadError if tool fetching fails

Filtering Logic

Sources: stackone_ai/toolset.py730-805 stackone_ai/toolset.py703-728

Account Resolution Strategy

Tools are fetched for multiple accounts by calling the MCP endpoint once per account:

1. Explicit account_ids parameter: Overrides all defaults
2. set_accounts() value: Used if no account_ids parameter
3. Constructor account_id: Used if neither above specified
4. Global fetch: If no accounts set anywhere, fetches tools without account filtering

Sources: stackone_ai/toolset.py775-782

Provider Filtering

Provider filtering extracts the first underscore-delimited segment of tool names and performs case-insensitive matching:

• Tool name: bamboohr_list_employees → Provider: bamboohr
• Matches provider list: ["BambooHR", "hibob"] (case-insensitive)

Sources: stackone_ai/toolset.py703-716 stackone_ai/toolset.py793-794

Action Filtering

Action filtering uses Python's fnmatch for glob pattern matching:

Pattern	Matches	Doesn't Match
*_list_*	bamboohr_list_employees, hibob_list_contacts	bamboohr_get_employee
bamboohr_*	bamboohr_list_employees, bamboohr_create_job	hibob_list_employees
bamboohr_list_employees	bamboohr_list_employees (exact)	All others

Sources: stackone_ai/toolset.py718-728 stackone_ai/toolset.py796-797

---

Semantic Search Methods

search_tools

Searches for and fetches tools using natural language queries with semantic or local BM25+TF-IDF search.

Parameters:

Parameter	Type	Description
query	str	Natural language description (e.g., "manage employee records", "send a message")
connector	str | None	Filter to single provider/connector (e.g., "bamboohr")
top_k	int | None	Maximum results. Overrides constructor default.
min_similarity	float | None	Similarity threshold 0.0-1.0. Overrides constructor default.
account_ids	list[str] | None	Account IDs to search within. Uses set_accounts() if not provided.
search	SearchMode | None	Search backend: "auto", "semantic", or "local". Overrides constructor default.

Returns: Tools collection with matched and fetched tools

Raises:

• ToolsetConfigError: If search is disabled (search=None in constructor)
• SemanticSearchError: If API fails and search="semantic"

Search Mode Behavior

Mode	Behavior
"auto"	Try semantic API first. On failure, fall back to local BM25+TF-IDF.
"semantic"	Use only semantic API. Raises SemanticSearchError if API unavailable.
"local"	Use only local BM25+TF-IDF. No API call made.

Search Flow

Sources: stackone_ai/toolset.py442-578 stackone_ai/toolset.py496-509 stackone_ai/toolset.py522-578

Semantic Search Implementation Details

The semantic search backend:

1. Connector-level parallelization: Searches each connector in parallel using ThreadPoolExecutor (max 10 workers)
2. Per-connector API calls: Each connector gets a separate API request to the semantic search endpoint
3. Result aggregation: All results combined, sorted by similarity score
4. Tool matching: Semantic results matched back to fetched tool definitions by action name
5. Normalization: API action names normalized to MCP format before matching

Sources: stackone_ai/toolset.py532-569

Local Search Implementation

Local search uses ToolIndex from stackone_ai.local_search module, which implements BM25+TF-IDF over tool names and descriptions:

1. Index built from already-fetched tools
2. BM25+TF-IDF scoring applied to query
3. Results filtered by min_score threshold
4. Optional connector filtering applied
5. Returns matched tools up to top_k limit

Sources: stackone_ai/toolset.py410-440

---

search_action_names

Lightweight search returning only action names and scores without fetching full tool definitions. Useful for inspecting search results or building custom filtering logic.

Parameters:

Parameter	Type	Description
query	str	Natural language query
connector	str | None	Single connector filter
account_ids	list[str] | None	Accounts to scope search. If provided, results filtered to connectors in those accounts.
top_k	int | None	Maximum results
min_similarity	float | None	Similarity threshold

Returns: list[SemanticSearchResult] with action names, scores, and metadata

Raises:

• ToolsetConfigError: If search is disabled
• No exceptions on API failure (returns empty list with warning log)

Result Normalization

Action names in results are normalized to MCP format (e.g., bamboohr::v1.0::list_employees → bamboohr_list_employees), but multiple API versions of the same action may appear with individual scores.

Sources: stackone_ai/toolset.py580-701 stackone_ai/toolset.py688-701

Account Scoping Behavior

When account_ids is provided:

1. fetch_tools(account_ids) called to determine available connectors
2. Semantic search limited to those connectors only
3. Parallel searches executed per connector
4. Results aggregated and sorted by score

When account_ids is None:

1. Single global semantic search (all connectors)
2. No connector pre-filtering

Sources: stackone_ai/toolset.py639-683

---

get_search_tool

Returns a callable SearchTool wrapper for use in agent loops. The returned object can be called directly with a query string to get a Tools collection.

Parameters:

• search: Override default search mode for this SearchTool instance

Returns: SearchTool instance

Raises: ToolsetConfigError if search is disabled

Example:

Sources: stackone_ai/toolset.py363-394

---

SearchTool Callable

The SearchTool class returned by get_search_tool() is a lightweight wrapper that makes search operations directly callable:

The SearchTool.__call__ method delegates to StackOneToolSet.search_tools() with merged configuration (constructor defaults + per-call overrides).

Sources: stackone_ai/toolset.py259-311 stackone_ai/toolset.py275-310

---

Property: semantic_client

Lazily initializes and returns a SemanticSearchClient instance configured with the toolset's API key and base URL. Used internally by search methods.

Returns: SemanticSearchClient instance

Note: The client is initialized on first access and cached in _semantic_client for subsequent calls.

Sources: stackone_ai/toolset.py396-408

---

Internal Tool Factory

_StackOneRpcTool

The toolset creates tools using the internal _StackOneRpcTool class, which implements RPC-style execution through the /actions/rpc endpoint:

Key aspects:

• RPC endpoint: All tools execute via POST /actions/rpc with action name in body
• Parameter mapping: body, headers, path, query parameters mapped to RPC payload structure
• Account injection: Account ID added to x-account-id header if present
• Schema normalization: Required fields marked nullable=False, optional fields nullable=True

Sources: stackone_ai/toolset.py815-828 stackone_ai/toolset.py171-257 stackone_ai/toolset.py200-224

---

Exception Classes

ToolsetError

Base exception for all toolset-related errors.

Sources: stackone_ai/toolset.py81-84

ToolsetConfigError

Raised when there is a configuration error (e.g., missing API key, search disabled when attempting search operations).

Common triggers:

• Missing API key in constructor and environment
• Attempting search operations when search=None

Sources: stackone_ai/toolset.py87-90 stackone_ai/toolset.py340-343 stackone_ai/toolset.py386-388

ToolsetLoadError

Raised when there is an error loading tools from the MCP backend.

Sources: stackone_ai/toolset.py93-96 stackone_ai/toolset.py801-804

---

Authentication and HTTP Configuration

Authentication Header Construction

API authentication uses HTTP Basic Auth with the API key:

Format: Authorization: Basic <base64(api_key:)>

Sources: stackone_ai/toolset.py126-128

User-Agent Header

All requests include a User-Agent header with SDK version:

Version is extracted from package metadata or defaults to "dev" when running from source.

Sources: stackone_ai/toolset.py57-68

MCP Headers

MCP requests include:

• Authorization: Basic auth header
• User-Agent: SDK version string
• x-account-id: Account ID (if specified)

Sources: stackone_ai/toolset.py806-813

---

Thread Safety and Async Support

_run_async Helper

The toolset uses _run_async() to run async MCP operations synchronously, with special handling for nested event loops:

Behavior:

• Outside event loop: Uses asyncio.run()
• Inside event loop: Spawns a daemon thread with new event loop to avoid nesting issues

This allows synchronous toolset methods to internally use async MCP client operations.

Sources: stackone_ai/toolset.py99-123

---

Usage Patterns

Pattern 1: Explicit Tool Discovery

Pattern 2: Semantic Search with Fallback

Pattern 3: Agent Loop with SearchTool

Pattern 4: Multi-Account Setup

Pattern 5: Inspect Before Fetch

Sources: stackone_ai/toolset.py313-852 README.md54-104