Advanced Tool Filtering
Relevant source files
The following files were used as context for generating this wiki page:
Advanced Tool Filtering scopes the SaaS toolset discovered by the StackOne AI SDK. This feature reduces the number of tools presented to a Large Language Model (LLM), ensuring the tool catalog fits within the model's context window. Users narrow the discovery results by targeting specific accounts, providers, or action patterns.
Sources: README.md:12-25, CLAUDE.md:21-25
Filtering Architecture
The fetch_tools() method serves as the primary interface for tool discovery and filtering. Filters execute locally against a cached listing of the tool catalog. Changing a filter does not trigger a network re-fetch of the tools unless the catalog cache is explicitly cleared or the account scope changes.
Sources: README.md:105-108, tests/test_fetch_tools.py:410-420
Discovery Flow
The SDK follows a specific sequence to resolve which tools to return. If no account is specified, the SDK performs account discovery to find all active linked accounts before applying filters.
The SDK applies filters using AND logic across different filter types. Sources: README.md:105-108, stackone_ai/tools.py:750-760
Filter Criteria
The SDK supports three distinct filter parameters in the fetch_tools() method. These parameters combine to restrict the returned Tools collection.
| Parameter | Type | Description |
|---|---|---|
account_ids | list[str] | Restricts discovery to these specific accounts. Omission leads to auto-discovery. |
providers | list[str] | Matches the full connector prefix. Matches are case-insensitive. |
actions | list[str] | Matches specific tool names using glob patterns. Matches are case-sensitive. |
Sources: README.md:105-115, CLAUDE.md:155-160
Account Scoping
The account_ids filter limits tools to specific linked SaaS accounts. If you provide an empty list, the SDK treats this as "no filter" rather than "no accounts." The SDK skips individual failing accounts and logs warnings instead of terminating the entire fetch process.
Sources: README.md:116-117, tests/test_fetch_tools.py:456-465
Provider Matching
Provider filters match the full connector prefix. A connector name containing an underscore requires the full spelling (e.g., browser_linkedin). The matching logic is case-insensitive, meaning linear and LINEAR yield identical results.
Sources: README.md:118-120, CLAUDE.md:155-156
Action Globbing
Action filters use glob patterns to match tool names. This supports exact matches, prefixes, infixes, and character classes.
- Exact:
linear_get_issue - Prefix:
linear_* - Infix:
*_list_* - Character Class:
linear_[lg]*
Note: A leading ! character does not indicate exclusion. It acts as a literal character in the pattern. Sources: README.md:121-125, CLAUDE.md:157-158
Caching Behavior
The StackOneToolSet maintains an internal _catalog_cache to optimize performance. Filtering operations are applied in-memory to the cached catalog.
The cache ensures that sequential calls with different filters do not incur additional network latency. Re-ordering account IDs in the filter list still results in cache hits. Sources: tests/test_fetch_tools.py:387-410, tests/test_fetch_tools.py:428-435
Filtering Examples
Filtering allows for precise control over the tools bound to a model.
# Match exactly one tool
tools = toolset.fetch_tools(actions=["linear_get_issue"])
# Match all list actions for a specific provider
tools = toolset.fetch_tools(
providers=["linear"],
actions=["*_list_*"]
)
# Match multiple patterns (OR logic within actions)
tools = toolset.fetch_tools(actions=["*_list_*", "*_get_*"])
Sources: README.md:110-115, tests/test_fetch_tools.py:175-190
Conclusion
Advanced Tool Filtering provides the necessary controls to manage large SaaS integrations within AI applications. By combining account, provider, and action filters with a robust caching layer, the SDK enables efficient, context-aware tool discovery that minimizes token usage and improves LLM reliability.