Skip to main content
New to tool search? Start with Tool Search 101 for an overview of why, how, and when to use it.
The simplest way to use tool search: give your agent tool_search and tool_execute, and let it discover tools on demand. 
import { StackOneToolSet } from '@stackone/ai';

const toolset = new StackOneToolSet();

// LLM receives only 2 tools: tool_search + tool_execute
const tools = toolset.getTools();
const openaiTools = tools.toOpenAI();
Only 2 tools are sent to the LLM regardless of how many tools exist in your catalog. Token usage stays constant.

​
Framework Examples

import { openai } from '@ai-sdk/openai';
import { StackOneToolSet } from '@stackone/ai';
import { generateText, stepCountIs } from 'ai';

// Uses STACKONE_API_KEY and STACKONE_ACCOUNT_ID from environment
const toolset = new StackOneToolSet({
  search: { method: 'semantic', topK: 3 },
});

// LLM receives only 2 tools: tool_search + tool_execute
const tools = toolset.getTools();

const { text } = await generateText({
  model: openai('gpt-5.4'),
  tools: await tools.toAISDK(),
  prompt: 'List my upcoming Calendly events for the next week.',
  stopWhen: stepCountIs(10),
});

console.log(text);
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();
No configuration needed. Defaults to auto mode with sensible defaults.
ModeBehaviour
autoTries semantic API first, falls back to local search on failure. Recommended for production.
semanticStrict mode. Uses semantic API only, throws SemanticSearchError on failure.
localHybrid BM25 + TF-IDF search entirely in-process (powered by Orama). No network call. Useful for offline or low-latency scenarios.
// Auto (default)
const tools = await toolset.searchTools('manage employees', { search: 'auto' });

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

// Local only
const tools = await toolset.searchTools('manage employees', { search: 'local' });
Set default search options at the constructor level. These apply to all search calls unless overridden per-call.

​
SearchConfig Options

OptionTypeDescription
method'auto' | 'semantic' | 'local'Search mode (default: 'auto')
topKnumberMaximum number of tools to return
minSimilaritynumberMinimum 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 toolset = new StackOneToolSet({ search: null });

// Default: search enabled with method: 'auto'
const toolset = new StackOneToolSet();
Per-call overrides take precedence over constructor defaults:
// Constructor sets topK=5 for all search calls
const toolset = new StackOneToolSet({ search: { method: 'semantic', topK: 5 } });

// Uses constructor defaults: method='semantic', topK=5
const tools = await toolset.searchTools('manage employees');

// topK overridden to 10 for this call; method remains 'semantic'
const tools = await toolset.searchTools('manage employees', { topK: 10 });
ParameterTypeDescription
topKnumberMaximum number of tools to return
search'auto' | 'semantic' | 'local'Search mode (default: 'auto')
connectorstringFilter to a specific provider (e.g., 'workday')
minSimilaritynumberMinimum relevance score threshold (0-1)
accountIdsstring[]Override account IDs for this search

​
Advanced Patterns

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}`);
}
searchActionNames() works with just STACKONE_API_KEY, no account ID needed. When called without accountIds, results come from the full StackOne catalog.
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(', ')}`);
}

​
Next Steps