Semantic Tool Search

Relevant source files

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

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

Semantic Tool Search enables agents to discover and execute SaaS actions using natural language queries. This system allows the SDK to handle catalogs containing hundreds of tools without exceeding an LLM's context window by providing a dynamic retrieval mechanism.

The search process utilizes specialized meta-tools served via the Model Context Protocol (MCP). Instead of listing every individual action to a model, the SDK provides *_search_actions and *_execute_action tools that rank actions based on similarity scores and execute them by ID.

Sources: README.md:14-17, CLAUDE.md:27-31, stackone_ai/types.py:23-31

Architecture and Components

The Semantic Tool Search architecture relies on three primary components: the StackOneToolSet container, the MCP endpoint, and specialized StackOneMcpTool instances.

System Interaction Flow

The following diagram illustrates the interaction between the SDK, the StackOne API, and the connected SaaS providers during a search and execution flow.

The SDK first discovers active accounts, then calls the meta-search tool on the MCP server, and finally routes the execution request back through the same protocol.
Sources: CLAUDE.md:33-39, stackone_ai/toolset.py:75-100, stackone_ai/tools.py:195-215

Core Classes and Modes

Component	Description
StackOneToolSet	The main entry point that manages account discovery, tool caching, and the high-level search() and execute() methods.
ToolMode	A literal type defining how tools are listed. Semantic search uses "search_execute" mode, which lists two meta-tools per connector.
StackOneMcpTool	A specialized tool class that communicates via the MCP tools/call endpoint instead of the standard RPC endpoint.

Sources: stackone_ai/types.py:23-31, stackone_ai/toolset.py:21-35, stackone_ai/tools.py:539-556

Search Logic

The search() method queries every linked connector for actions matching a natural language prompt.

Execution Process

1. Account Discovery: If no accounts are specified, the StackOneToolSet calls GET /accounts and uses every active account.
2. Meta-Tool Fetching: The SDK fetches tools from the /mcp endpoint with the parameter tool-mode=search_execute.
3. Parallel Execution: The SDK executes search requests across all connectors in parallel to minimize latency.
4. Result Ranking: Results are collected and ranked by their similarity_score across all connectors.

Sources: CLAUDE.md:33-39, stackone_ai/toolset.py:84-120, tests/test_fetch_tools.py:448-468

Result Structure

A search result (hit) provides the necessary metadata for an agent to construct an execution request.

# Example Search Hit
{
    "action_id": "linear_list_comments",
    "description": "Returns a page of Linear comments...",
    "similarity_score": 0.86,
    "example_request": {"query": {"page_size": 25}},
    "input_schema": {"type": "object", "properties": {"body": {...}}}
}

Sources: README.md:46-52, tests/test_fetch_tools.py:113-118

Execution Logic

Execution in semantic search mode uses the toolset.execute(action_id, args) method. This routes the request to the *_execute_action meta-tool for the connector associated with the action_id.

Argument Shaping

Unlike individual tools which use flat-prefixed arguments (e.g., body_variables), semantic execution requires a nested envelope shape. This shape typically includes body, query, path, and headers keys, matching the input_schema provided in the search hits.

Sources: CLAUDE.md:41-46, stackone_ai/tools.py:560-570, README.md:120-130

Security and Validation

The SDK performs the following validations during execution:

• Header Sanitization: The SDK drops headers not declared in the served schema to prevent prompt-injection attacks.
• Action ID Pinning: The action_id provided to the method is pinned, preventing models from overriding the target action via the arguments dictionary.
• Input Validation: The SDK verifies that arguments are provided as a JSON object before transmitting the request.

Sources: stackone_ai/tools.py:348-375, tests/test_fetch_tools.py:588-592

Configuration and Constraints

Semantic search behavior is influenced by several configuration parameters and environment settings.

Top_K Constraints

The top_k parameter controls the number of results returned per connector.

• Range: Must be between 1 and 50.
• Application: The limit is applied per connector, and results are subsequently merged and re-ranked.

Sources: CLAUDE.md:88-89, tests/test_fetch_tools.py:532-540

Error Handling

The search and execute flow utilizes a specific error hierarchy to ensure diagnosability.

Summary of Differences

Feature	Semantic Search (execute)	Individual Tool (tool.execute)
Discovery	Natural language query	Glob/Provider filtering
Argument Shape	Nested Envelope	Flat-Prefixed
Internal Tool	StackOneMcpTool	StackOneRpcTool
Protocol	MCP tools/call	StackOne RPC /actions/rpc

Sources: CLAUDE.md:41-48, README.md:120-130