StackOneToolSet Component

Relevant source files

The following files were used as context for generating this wiki page:

• stackone_ai/tools.py
• stackone_ai/types.py
• README.md
• CLAUDE.md
• tests/test_fetch_tools.py

The StackOneToolSet acts as the primary entry point for the StackOne AI SDK. It manages account discovery, maintains a cached catalog of SaaS tools, and provides interfaces for natural-language search and tool execution.

StackOneToolSet communicates with a Model Context Protocol (MCP) server to fetch tool schemas at runtime. This architecture ensures that the schema presented to an AI model matches the server-side definitions exactly, without client-side modifications.

Sources: CLAUDE.md:16-25, README.md:20-25

Account Discovery and Scoping

The component manages access to multiple SaaS connectors through linked accounts. If you provide only an API key, the toolset calls GET /accounts to discover all active accounts. You can narrow the scope of discovery and execution by providing specific account IDs during initialization or through the set_accounts() method.

Sources: CLAUDE.md:27-30, README.md:65-70, tests/test_fetch_tools.py:20-30

Account Discovery Flow

The following diagram illustrates how the toolset identifies target accounts for tool fetching:

The discovery process ensures that only valid, active integrations are exposed to the AI model.

Sources: CLAUDE.md:27-31, tests/test_fetch_tools.py:465-480

Tool Catalog Management

The toolset maintains an internal cache of the tool catalog to optimize performance. Fetches across multiple accounts occur in parallel to minimize latency.

Sources: tests/test_fetch_tools.py:382-398, tests/test_fetch_tools.py:315-330

Tool Modes

The toolset operates in two distinct modes that determine how the catalog is structured and presented to models:

Mode	Description	Key Characteristic
individual	Lists one tool per action for every account.	Can produce hundreds of tools.
search_execute	Lists two meta-tools per connector (search and execute).	Keeps context window small.

Sources: stackone_ai/types.py:25-33, CLAUDE.md:32-37

Fetch and Filter Logic

The fetch_tools() method retrieves a Tools container. It supports three types of local filtering which are applied to the cached catalog:

• Account Filtering: Restricts tools to specific account_ids.
• Provider Filtering: Matches connector prefixes case-insensitively (e.g., "linear").
• Action Filtering: Uses case-sensitive glob patterns (e.g., *_list_*).

Sources: README.md:110-135, tests/test_fetch_tools.py:90-130

Calling Surfaces

StackOneToolSet provides two different surfaces for executing actions. These surfaces require different argument shapes to match their respective schemas.

Comparison of Calling Methods

Feature	Search & Execute	Fetch Tools & Tool Execute
Primary Method	toolset.search() + toolset.execute()	toolset.fetch_tools() + tool.execute()
Argument Shape	Nested Envelope: {"body": {"variables": {...}}}	Flat-Prefixed: body_variables, path_id
Discovery	Dynamic at runtime.	Pre-bound filtered set.
Context Usage	Low (Meta-tools only).	High (Per-action schemas).

Sources: README.md:140-155, CLAUDE.md:32-45

Execution Sequence

The sequence below describes the recommended flow for dynamic action discovery and execution:

Error Handling and Configuration

The component uses a specific hierarchy for exceptions. All SDK errors derive from StackOneError.

• ToolsetConfigError: Raised for invalid configuration, such as out-of-range top_k values in search.
• ToolsetLoadError: Raised when MCP fetching fails for all accounts.
• StackOneAPIError: Raised when the server returns an error, including status codes and response bodies.

Sources: stackone_ai/types.py:36-65, tests/test_fetch_tools.py:415-425

Configuration Parameters

Parameter	Type	Default	Description
api_key	str	N/A	StackOne API Key (Basic Auth).
base_url	str	https://api.stackone.com	The target API endpoint.
timeout	float	60.0	Timeout for all network requests.
tool_mode	ToolMode	individual	Structural style of served tools.

Sources: stackone_ai/types.py:22, stackone_ai/tools.py:68, stackone_ai/tools.py:100

Summary

The StackOneToolSet component centralizes the management of SaaS actions by bridging the local SDK with remote MCP services. It prioritizes technical accuracy by serving the catalog exactly as defined by the server. By supporting both dynamic meta-tool discovery and static tool binding, it provides flexibility for different AI agent architectures while maintaining strict security through header sanitization and account scoping.

Sources: CLAUDE.md:16-25, stackone_ai/tools.py:10-15