Tool Execution API
Relevant source files
The following files were used as context for generating this wiki page:
The Tool Execution API provides a unified interface for performing actions on SaaS platforms through the StackOne AI SDK. It allows developers to search for tools using natural language and execute them against connected SaaS accounts using a standardized request-response cycle.
The SDK translates model-generated arguments into specific HTTP requests directed at StackOne's /actions/rpc or Model Context Protocol (MCP) endpoints. The system ensures that the tool schemas presented to AI models match the served catalog exactly.
Sources: AGENTS.md:12-19, stackone_ai/toolset.py:28-32
Core Execution Architecture
The execution logic resides in two primary surfaces: the StackOneToolSet for discovery and routing, and the StackOneTool subclasses for direct HTTP execution.
Execution Components
The following diagram illustrates the relationship between the core classes responsible for tool execution.
The SDK uses StackOneRpcTool for per-action tools and StackOneMcpTool for meta-tools like search.
Sources: stackone_ai/tools.py:382-387, stackone_ai/tools.py:734-740, stackone_ai/toolset.py:35-40
Key Classes and Data Structures
| Class | Description |
|---|---|
StackOneToolSet | Main entry point for account discovery, tool searching, and execution routing. |
StackOneTool | Base class containing HTTP request preparation, header sanitization, and framework adapters. |
StackOneRpcTool | Implements execution against the /actions/rpc endpoint using flat-prefixed parameters. |
StackOneMcpTool | Implements execution for meta-tools over the MCP tools/call transport. |
ExecuteConfig | Defines the HTTP method, URL, and parameter locations for a specific tool. |
Sources: stackone_ai/types.py:165-175, stackone_ai/tools.py:382-390, stackone_ai/toolset.py:46-52
Execution Surfaces
The SDK exposes two distinct ways to call tools, each optimized for different agent behaviors.
Search and Execute API
This surface uses meta-tools (*_search_actions and *_execute_action) to rank and run actions. It accepts a nested argument envelope: {"body": {"variables": {...}}}. This approach keeps the tool catalog small by not loading every individual tool into the model's context window.
Individual Tool Execution
This surface uses per-action tools fetched via fetch_tools(). It uses the flat-prefixed parameter style: body_variables, path_id. It is best for binding a fixed, filtered set of tools to a model.
The diagram shows the decision flow between using natural language search versus direct tool execution.
Sources: AGENTS.md:21-36, README.md:143-157
Parameter Handling and Sanitization
The SDK manages how parameters are mapped to HTTP requests to prevent security vulnerabilities and ensure compatibility with various SaaS providers.
Parameter Mapping
The ParameterLocation enum defines where a parameter resides in the final API request.
| Location | Description |
|---|---|
HEADER | Parameter added to HTTP headers. |
QUERY | Parameter added to the URL query string. |
PATH | Parameter substituted into the URL path template. |
BODY | Parameter added to the JSON or Form request body. |
FILE | Indicates a file upload operation. |
Sources: stackone_ai/types.py:100-106
Request Preparation Logic
- Header Sanitization: The SDK drops any model-supplied headers that are not explicitly declared in the served schema to prevent header injection.
- Path Encoding: Path parameters are URL-encoded before substitution into the URL template to prevent SSRF attacks.
- Envelope Splitting: For RPC tools, the
_split_envelope_paramsmethod separates flat-prefixed keys (e.g.,path_id) into their respectivepath,query, orbodycontainers.
Sources: stackone_ai/tools.py:456-466, stackone_ai/tools.py:778-785
Error Handling
All SDK exceptions derive from StackOneError. The system handles API failures by surfacing the server's specific error message to allow models to retry with corrected arguments.
The diagram illustrates how API errors are caught and transformed into actionable exceptions.
Sources: stackone_ai/types.py:35-50, stackone_ai/tools.py:228-240
Common Exceptions
StackOneAPIError: Raised when the StackOne API returns a non-success status code. Includesstatus_codeandresponse_body.ToolsetLoadError: Raised when tools cannot be fetched from the MCP endpoint (e.g., network failure or dead account).ToolsetConfigError: Raised for missing API keys or invalidtop_kvalues in search.
Sources: stackone_ai/types.py:42-65, stackone_ai/toolset.py:246-250
Implementation Example: RPC Execution
The StackOneRpcTool prepares the payload for the unified execution endpoint.
# Sources: stackone_ai/tools.py:749-760
def execute(self, arguments: str | dict[str, Any] | None = None) -> dict[str, Any]:
parsed_arguments = self._parse_arguments(arguments)
envelope = self._split_envelope_params(parsed_arguments, set(self.parameters.properties) or None)
payload: dict[str, Any] = {
"action": self.name,
"body": envelope["body"],
"headers": self._build_action_headers(envelope["headers"] or None),
}
if envelope["path"]:
payload["path"] = envelope["path"]
if envelope["query"]:
payload["query"] = envelope["query"]
return super().execute(payload)
Sources: stackone_ai/tools.py:749-764
Summary
The Tool Execution API centralizes the logic for interacting with SaaS connectors. By providing two distinct calling surfaces—one for natural language discovery and one for direct binding—it accommodates both simple scripts and complex AI agents. The SDK enforces strict schema pass-through and header sanitization to maintain security and accuracy across diverse integrations.