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 TypeScript SDK provides three methods for tool discovery:
  • searchTools(): search by intent, returns a Tools collection ready for any framework
  • searchActionNames(): lightweight search returning action names and scores without fetching full tool definitions
  • getSearchTool(): returns a reusable SearchTool for agent loops

​
Constructor Configuration

You can set default search options at the constructor level using SearchConfig. These defaults apply to all search calls unless overridden per-call. 
import { StackOneToolSet, type SearchConfig } 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();

​
SearchConfig Options

OptionTypeDescription
method'auto' | 'semantic' | 'local'Search mode (default: 'auto')
topKnumberMaximum number of tools to return
minSimilaritynumberMinimum relevance score threshold (0-1)
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 });

​
Search Tools

searchTools() is the recommended method for agent frameworks. It fetches tools from your linked accounts, searches each connector in parallel via the semantic search API, and returns a Tools collection sorted by relevance. 
import { StackOneToolSet } from '@stackone/ai';

const toolset = new StackOneToolSet();

// Search for tools by intent
const tools = await toolset.searchTools('manage employee records and time off', {
  topK: 5,
  search: 'auto', // tries semantic API first, falls back to local search
});

console.log(`Found ${tools.length} tools`);

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

​
Search Modes

// Auto (default): tries semantic API first, falls back to local search on failure
const tools = await toolset.searchTools('manage employees', { search: 'auto' });

// Semantic only: uses the semantic API, throws SemanticSearchError if unavailable
const tools = await toolset.searchTools('manage employees', { search: 'semantic' });

// Local only: hybrid BM25+TF-IDF search, no network call to the semantic endpoint
const tools = await toolset.searchTools('manage employees', { search: 'local' });
  • auto: Recommended for production. Searches each connector in parallel via the semantic API. If the API call fails, automatically falls back to local search and logs a warning.
  • semantic: Strict mode. Same parallel per-connector search, but raises SemanticSearchError on failure instead of falling back.
  • local: Runs a hybrid BM25 + TF-IDF search entirely in-process (powered by Orama for BM25). No network call. Useful for offline or low-latency scenarios.

​
Options

ParameterTypeDescription
topKnumberMaximum number of tools to return
search'auto' | 'semantic' | 'local'Search mode (default: 'auto')
connectorstringFilter to a specific provider (e.g., 'bamboohr')
minSimilaritynumberMinimum relevance score threshold (0-1)
accountIdsstring[]Override account IDs for this search

​
Search Action Names

searchActionNames() queries the semantic API directly and returns metadata without fetching full tool definitions. Use it to preview results before committing to a full fetch. 
const results = await toolset.searchActionNames('manage employees', {
  topK: 5,
});

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

// Then fetch specific tools based on results
const topActions = results
  .filter((r) => r.similarityScore > 0.7)
  .map((r) => r.actionName);

const tools = await toolset.fetchTools({ actions: topActions });
searchActionNames() works with just STACKONE_API_KEY, no account ID needed. When called without accountIds, results come from the full StackOne catalog.

​
Search Tool (Agent Loops)

getSearchTool() 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(', ')}`);
}

​
Framework Integration

Tool search returns a Tools collection with built-in framework converters. See the framework guides for full examples:

​
Next Steps