Tool Discovery - Stackone

Large action catalogs would overflow the model’s context if every tool were loaded up front. Search-based discovery lets the agent find the right action at runtime, keeping the token footprint flat as your catalog grows — see the overview for why it matters.

StackOne actions are exposed to agents as tools — an action in the catalog becomes a tool in your agent’s hands. The two terms describe the same operation from either side.

Overview

There are two levels of control over which tools an agent sees — the connector profile sets hard boundaries that everything inherits, then each protocol discovers or narrows within them.

Connector profile level — Scoping Connectors on the connector profile sets hard, admin-level boundaries that every protocol and caller inherits.
Protocol level — chosen per toolset or per call:

Method	What it does	Compatible protocols	When to use
Search & Execute (Recommended)	The agent is only given two tools: `tool_search` + `tool_execute`. Token cost stays flat however large the catalog	MCP, Agent SDK, A2A	Open-ended assistants, large catalogs, unknown tasks
Tool Filtering	Narrow what a fetch returns by provider or action glob patterns	Agent SDK	Constrained agents with a focused, predictable scope
Manual search	Your code searches the catalog by natural language upfront, then hands the matches to the agent	Agent SDK	Known tasks where your code assembles the toolset upfront

How Search works

Search — the agent (or your code) calls search with a natural language query.
Discover — available connectors and tool definitions are fetched for your linked accounts.
Match — each connector’s tools are searched in parallel via the semantic search API.
Rank — results are matched to tool definitions, ranked by relevance, and deduplicated.
Return — a ready-to-use tools collection, filtered to what the configured account IDs can access.

Search and Execute

MCP

StackOne’s MCP server exposes Search & Execute through the tool-mode query parameter. See MCP Tool modes for the parameters, client setup examples, and the search/execute tool reference. To use it in your agent’s client, follow the respective Agent Setup walkthroughs.

Agent SDK

Hand the agent tool_search and tool_execute — only two tools reach the LLM regardless of catalog size. For examples, see the framework guide for the framework you’re building with.

Actions API

Search directly over the catalog, then run the result via RPC. See Search connector actions and Make an RPC call.

Tool filtering

Tool Filtering is only available when using the Agent SDK protocol.

Tool filtering allows you to perform a primitive matching pattern against the tool names to reduce the tools exposed to the agent. Filter on either attribute, or combine both in one fetch:

Attribute	Accepts	Example
`providers`	Connector keys	`["hibob", "workday"]`
`actions`	Action names — exact or wildcard (`*`)	`["hibob_create_employee", "_list_"]`

Tool names follow the format provider_action. Use the wildcard * to match similarly named actions, for example:

Actions Attribute	Matches
`_list_`	`bamboohr_list_employees` `bamboohr_list_company_files`
`*_employees`	`bamboohr_list_employees` `bamboohr_get_changed_employees`
`_employees, employee*`	`bamboohr_list_employees` `bamboohr_get_changed_employees` `bamboohr_create_employee` `bamboohr_get_employee_photo`

// Filter by providers
const byProviders = await toolset.fetchTools({
  providers: ["hibob", "workday"],
  accountIds: ["your-account-id"],
});

// Filter by actions with exact match
const byActions = await toolset.fetchTools({
  actions: ["hibob_search_employees", "hibob_create_employee"],
  accountIds: ["your-account-id"],
});

// Filter by actions with glob patterns
const byGlob = await toolset.fetchTools({
  actions: ["*_list_*"],
  accountIds: ["your-account-id"],
});

// Combine multiple filters
const combined = await toolset.fetchTools({
  providers: ["hibob"],
  actions: ["*_list_*"],
  accountIds: ["your-account-id"],
});

# Filter by providers
tools = toolset.fetch_tools(
    providers=["hibob", "workday"],
    account_ids=["your-account-id"],
)

# Filter by actions with exact match
tools = toolset.fetch_tools(
    actions=["hibob_search_employees", "hibob_create_employee"],
    account_ids=["your-account-id"],
)

# Filter by actions with glob patterns
tools = toolset.fetch_tools(
    actions=["*_list_*"],
    account_ids=["your-account-id"],
)

# Combine multiple filters
tools = toolset.fetch_tools(
    providers=["hibob"],
    actions=["*_list_*"],
    account_ids=["your-account-id"],
)

More examples: stackone-ai-node (TypeScript) and stackone-ai-python (Python).

Manual search

Manual Search is only available when using the Agent SDK protocol.

When you need to find tools yourself before passing them to an agent:

import { StackOneToolSet } from '@stackone/ai';

const toolset = new StackOneToolSet();
const tools = await toolset.searchTools('manage employee records');

// Use with any framework
const openAITools = tools.toOpenAI();
const aiSdkTools = await tools.toAISDK();

from stackone_ai import StackOneToolSet

toolset = StackOneToolSet()
tools = toolset.search_tools("manage employee records")

# Use with any framework
openai_tools = tools.to_openai()
langchain_tools = tools.to_langchain()

No configuration needed. Defaults to auto mode with sensible defaults.

Write queries that describe the business task (“find employees hired this year”) rather than the technical operation (“list employees filtered by start date”). Search is semantic.

Search modes

Mode	Behavior
`auto`	Tries the semantic API first, falls back to local search on failure. Recommended for production.
`semantic`	Strict mode. Uses the semantic API only, and throws / raises `SemanticSearchError` on failure.
`local`	Hybrid BM25 + TF-IDF search entirely in-process. No network call. Useful for offline or low-latency scenarios.

Local search is powered by Orama in TypeScript and bm25s in Python.

// Auto (default)
const tools = await toolset.searchTools('manage employees', { search: 'auto' });

// Semantic only
const semantic = await toolset.searchTools('manage employees', { search: 'semantic' });

// Local only
const local = await toolset.searchTools('manage employees', { search: 'local' });

# Auto (default)
tools = toolset.search_tools("manage employees", search="auto")

# Semantic only
tools = toolset.search_tools("manage employees", search="semantic")

# Local only
tools = toolset.search_tools("manage employees", search="local")

Search Accuracy

Semantic search uses enriched embeddings: action descriptions are expanded with related terms before embedding, so “onboard new hire” matches “Create Employee” even though the wording differs. Local search relies on BM25 keyword matching, which works for exact terms but misses natural language phrasing. Tested across 103 semantically-challenging queries against 9,340 actions:

Approach	Hit@5 (all connectors)	Hit@5 (per connector)
BM25 only (`local`)	21%	65%
Enriched embeddings (`semantic`)	84%	90%

Search options

Constructor configuration

Set default search options at the constructor level. These apply to all search calls unless overridden per-call.SearchConfig options

Option	Type	Description
`method`	`'auto' \| 'semantic' \| 'local'`	Search mode (default: `'auto'`)
`topK` / `top_k`	`number` / `int`	Maximum number of tools to return
`minSimilarity` / `min_similarity`	`number` / `float`	Minimum relevance score threshold (0-1)

import { StackOneToolSet } from '@stackone/ai';

// Custom search config
const toolset = new StackOneToolSet({ search: { method: 'semantic', topK: 5 } });

// Disable search
const disabled = new StackOneToolSet({ search: null });

// Default: search enabled with method: 'auto'
const defaultToolset = new StackOneToolSet();

// Per-call overrides take precedence over constructor defaults:
// method stays 'semantic' from the constructor, topK overridden to 10
const more = await toolset.searchTools('manage employees', { topK: 10 });

from stackone_ai import StackOneToolSet

# Custom search config
toolset = StackOneToolSet(search={"method": "semantic", "top_k": 5})

# Disable search
disabled = StackOneToolSet(search=None)

# Default: search enabled with method="auto"
default_toolset = StackOneToolSet()

# Per-call overrides take precedence over constructor defaults:
# method stays "semantic" from the constructor, top_k overridden to 10
more = toolset.search_tools("manage employees", top_k=10)

Parameters reference

TypeScript

Parameter	Type	Description
`topK`	`number`	Maximum number of tools to return
`search`	`'auto' \| 'semantic' \| 'local'`	Search mode (default: `'auto'`)
`connector`	`string`	Filter to a specific provider (e.g., `'workday'`)
`minSimilarity`	`number`	Minimum relevance score threshold (0-1)
`accountIds`	`string[]`	Override account IDs for this search

Python

Parameter	Type	Description
`query`	`str`	Natural language description of what you want to do
`top_k`	`int \| None`	Maximum number of tools to return
`search`	`"auto" \| "semantic" \| "local"`	Search mode (default: `"auto"`)
`connector`	`str \| None`	Filter to a specific provider (e.g., `"workday"`)
`min_similarity`	`float \| None`	Minimum relevance score threshold (0-1)
`account_ids`	`list[str] \| None`	Override account IDs for this search

Advanced patterns

Lightweight preview (action names + scores)

Returns action names and similarity scores without fetching full tool definitions. Use it to inspect results before committing to a full fetch.

const results = await toolset.searchActionNames('manage employees', {
  topK: 5,
});

for (const result of results) {
  console.log(`${result.id}: ${result.similarityScore}`);
}

results = toolset.search_action_names("manage employees", top_k=5)

for r in results:
    print(f"{r.id}: {r.similarity_score:.2f}")

This works with just STACKONE_API_KEY, no account ID needed. When called without account IDs, results come from the full StackOne catalog.

Reusable search tool for custom agent loops

Returns a reusable SearchTool for agent loops where the LLM decides what to search for.

const searchTool = toolset.getSearchTool({ search: 'auto' });

// In an agent loop, search for tools as needed
const queries = [
  'create a new employee',
  'list job candidates',
  'send a message to a channel',
];

for (const query of queries) {
  const tools = await searchTool.search(query, { topK: 3 });
  const toolNames = tools.toArray().map((t) => t.name);
  console.log(`"${query}" -> ${toolNames.join(', ')}`);
}

search_tool = toolset.get_search_tool(search="auto")

# In an agent loop, call it with natural language queries
queries = [
    "create a new employee",
    "list job candidates",
    "send a message to a channel",
]

for query in queries:
    tools = search_tool(query, top_k=3)
    tool_names = [t.name for t in tools]
    print(f'"{query}" -> {", ".join(tool_names)}')

The returned Tools collection converts to OpenAI, Vercel AI SDK, LangChain, and more — see the framework guides under Agent SDK.

​Overview

​Search and Execute

​MCP

​Agent SDK

​Actions API

​Tool filtering

​Manual search

​Search modes

​Search options

​Advanced patterns

Overview

Search and Execute

MCP

Agent SDK

Actions API

Tool filtering

Manual search

Search modes

Search options

Advanced patterns