> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tool Search 101
> How StackOne's tool search finds the right tools from thousands of actions using natural language
Tool search enables AI agents to discover the right tools using natural language queries, without requiring exact action names.
**The Problem**: StackOne manages over 10,000 actions across connectors, with some containing 2,000+ actions. Loading all of them into an LLM's context window is not practical:
* **Token bloat**: every tool definition consumes tokens, leaving less room for reasoning
* **Accuracy drops**: LLMs make worse tool selections as the candidate set grows
* **Provider caps**: OpenAI caps function definitions at \~128 per request
**The Solution**: More tools does not mean more capability. Without structure, they become noise. Tool search finds only the relevant tools for each query, keeping agent prompts lean while expanding their capabilities.
**Search Flow**
1. **Search**: Your agent calls the search method with a natural language query
2. **Discover**: The SDK fetches available connectors and tool definitions from your linked accounts via MCP
3. **Match**: Each connector is searched in parallel via the semantic search API
4. **Rank**: Results are matched to MCP tool definitions, ranked by relevance, deduplicated
5. **Return**: A `Tools` collection is returned, ready for any framework
The agent only sees the tools it needs, not the entire catalog.
**Three Search Modes**
| Mode | Behavior | When to use |
| ---------------- | ------------------------------------------------------------------- | --------------------------------------------------------------- |
| `auto` (default) | Tries the semantic API first, falls back to local search on failure | Production use: best accuracy with built-in resilience |
| `semantic` | Semantic API only. Throws an error if the API is unavailable. | When you need strict control and want to handle errors yourself |
| `local` | Hybrid BM25 + TF-IDF search, entirely in-process. No network call. | Offline environments or when you need minimal latency |
**Local search** scores results with `0.2 * BM25 + 0.8 * TF-IDF` and runs with no network calls.
**Semantic search** uses enriched embeddings where action descriptions are expanded with related terms before embedding. For example, "Create Employee" is enriched with synonyms like "add new", "insert", "worker", "staff", "team member", so natural language queries match even when wording differs.
Tested across 103 semantically-challenging queries against 9,340 actions:
| Approach | Hit\@5 (all connectors) | Hit\@5 (per connector) |
| ------------------- | ----------------------- | ---------------------- |
| BM25 only | 21% | 65% |
| Enhanced Embeddings | 84% | 90% |
BM25 keyword matching works well for exact terms but fails on natural language. For example, searching "onboard new hire" won't match "Create Employee" with BM25 alone.
For comparison, Anthropic's built-in [tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) uses BM25 matching. StackOne's semantic mode uses enriched embeddings for higher accuracy on natural language queries.
**Real-World Use Cases**:
* **HR Agent**: "Approve Alice's time off request" finds `hibob_create_time_off` and executes in HiBob
* **Support Agent**: "Search for Jira ticket ABC-123" finds `ticketing_ticket_list` and returns details
* **Knowledge Agent**: "Find training docs on GDPR" finds `documents_file_search` and queries KB
**When to Use**:
Use tool search when your agent spans many SaaS systems (dozens to thousands of tools) and you need higher selection accuracy and scalability.
Skip tool search if you have a very small, static toolset where you can load all tools directly.
### Key Features
StackOne has 10,000+ actions. Search returns only the relevant ones for each query.
Only relevant tools exposed per request, reducing misfires and hallucinations.
Filters results to tools available for configured account IDs, respecting auth boundaries.
Returns a Tools collection with converters for OpenAI, LangChain, Vercel AI SDK, and more.
## Quick Example
```python theme={null}
from stackone_ai import StackOneToolSet
toolset = StackOneToolSet()
# Get search & execute tools. The LLM discovers and runs tools on demand
tools = toolset.openai(mode="search_and_execute")
# Pass these to your OpenAI agent
# The agent gets tool_search + tool_execute, only 2 tools regardless of catalog size
```
## Two Approaches
**Give the LLM 2 tools — it discovers and runs actions on demand.**
Instead of pre-filtering, you give the LLM `tool_search` and `tool_execute`. The LLM searches for relevant tools, reads their parameter schemas, and executes them within its own reasoning loop.
Best for:
* Open-ended assistants ("help me with any HR task")
* Large tool catalogs where pre-filtering is impractical
* When you don't know which tools will be needed upfront
* Minimal token overhead — always 2 tools regardless of catalog size
**You search first, LLM gets a focused set of tools.**
Your code calls `searchTools()` or `fetchTools()` with filters, gets back a `Tools` collection, and passes those to the LLM. The LLM only sees relevant tools.
Best for:
* Known tasks where you can predict which tools are needed
* Constrained agents with a focused scope
* When you want full control over which tools the LLM can access
| Aspect | Search & Execute | Pre-filtered |
| ----------------- | ----------------------------------------- | --------------------------- |
| Tools sent to LLM | Always 2 (`tool_search` + `tool_execute`) | Filtered set (5-20) |
| Token cost | Constant | Scales with number of tools |
| Discovery | LLM discovers on-demand | You search upfront |
| Use case | Open-ended, exploratory | Constrained, known tasks |
## Architecture Overview
```mermaid theme={null}
graph TB
User["User"] --> Agent["Your AI Agent"]
Agent --> SearchTools["Search Tools"]
Agent --> SearchActionNames["Search Action Names"]
SearchTools --> MCP["MCP Server"]
SearchTools --> SemanticAPI["Semantic Search API"]
SearchTools --> Agent
Agent --> Execute["Execute Tool"]
style User fill:#f3f4f6,stroke:#d1d5db,stroke-width:2px,color:#374151
style Agent fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style SearchTools fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#15803d
style SearchActionNames fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#15803d
style SemanticAPI fill:#16a34a,stroke:#15803d,stroke-width:2px,color:#fff
style MCP fill:#16a34a,stroke:#15803d,stroke-width:2px,color:#fff
style Execute fill:#16a34a,stroke:#15803d,stroke-width:2px,color:#fff
```
**Flow:**
1. User sends a natural language query to your AI agent
2. Agent calls **Search Tools** to find relevant actions
3. Search Tools discovers available connectors and tool schemas via **MCP**, then ranks actions via the **Semantic Search API**
4. Search results are matched to MCP tool definitions, sorted by relevance
5. Agent receives a ranked `Tools` collection
6. Agent calls `execute()` on the selected tool
## Next Steps
* [Tool Search](/agents/python/tool-search) for full API reference and all three methods
* [Basic Usage](/agents/python/basic-usage) for fetching and executing tools
* [Tool Filtering](/agents/python/tool-filtering) for glob pattern filtering