Tools Container Collection
Relevant source files
The following files were used as context for generating this wiki page:
The Tools class manages a collection of StackOneTool instances. It provides a centralized interface for tool lookup, iteration, and transformation into framework-specific formats such as OpenAI, LangChain, and Pydantic AI.
Sources: stackone_ai/tools.py:1001-1002, CLAUDE.md:20-25
Core Container Logic
The Tools container stores a list of tools and maintains an internal mapping for efficient lookup.
Tool Storage and Lookup
When you initialize the Tools class, it builds an internal _tool_map. This map uses the tool name as the key for $O(1)$ access. If multiple accounts serve tools with identical names, the container logs a warning and retains only the last tool listed in the map.
The diagram shows the relationship where the Tools container holds multiple StackOneTool instances and provides methods to manage them.
__getitem__(index): Returns a tool by its position in the list.__len__(): Returns the total number of tools in the collection.get_tool(name): Retrieves a specific tool by its name or returnsNoneif the tool does not exist.
Sources: stackone_ai/tools.py:1004-1033, tests/test_models.py:97-109
Account Scoping
The container manages account context for its entire collection. If you set an account ID at the container level, the container propagates that ID to every tool it holds.
set_account_id(account_id): Updates the_account_idfor every tool in the collection.get_account_id(): Iterates through the collection and returns the first non-null account ID it finds.
Sources: stackone_ai/tools.py:1043-1056, tests/test_fetch_tools.py:65-75
Framework Integrations
The Tools collection converts internal tool definitions into formats required by various AI orchestration frameworks.
OpenAI Integration
The container provides methods to interface directly with OpenAI's Chat Completions API.
to_openai(): Returns a list of JSON objects representing OpenAI function tools.execute_openai_tool_calls(tool_calls): Processes a list of tool calls returned by a model. It runs each tool, handles potential errors (like unknown tools or API failures), and returns a list of "tool" role messages formatted for the OpenAI message history.
The sequence diagram illustrates how the Tools container orchestrates the execution of multiple model-requested tool calls.
Sources: stackone_ai/tools.py:1062-1089, README.md:58-75
LangChain and Pydantic AI
The container facilitates native integration with LangChain and Pydantic AI through specialized conversion methods.
| Method | Output Type | Dependency |
|---|---|---|
to_langchain() | Sequence[BaseTool] | stackone-ai[langchain] |
to_pydantic_ai() | list[Tool] | stackone-ai[pydantic-ai] |
These methods import the required framework libraries lazily to avoid dragging in unnecessary dependencies if the adapters are not used.
Sources: stackone_ai/tools.py:1091-1100, pyproject.toml:39-45, README.md:88-105
Data Structures and Types
The Tools container operates primarily on these structures:
| Field | Type | Description |
|---|---|---|
tools | list[StackOneTool] | The underlying list of tool instances. |
_tool_map | dict[str, StackOneTool] | Internal name-to-tool lookup table. |
Sources: stackone_ai/tools.py:1004-1006
Tool Schema Pass-through
A key property of the collection is that it preserves the served catalog schema. When converting to OpenAI or other frameworks, the container ensures that constraints like format, pattern, enum, and oneOf reach the model intact. It strips the SDK's internal nullable marker and converts it into the standard JSON Schema required list during the conversion process.
Sources: stackone_ai/tools.py:873-888, tests/test_models.py:348-356
Summary
The Tools container collection serves as the bridge between fetched SaaS actions and AI model interfaces. It encapsulates the complexity of O(1) tool lookups, multi-account scoping, and framework-specific transformations. By maintaining a faithful mirror of the server-provided schema, it ensures that models receive accurate instructions for executing actions across linkable SaaS accounts.
Sources: stackone_ai/tools.py:1-12, README.md:160-170