Tool Search

New to tool search? Start with Tool Search 101 for an overview of why, how, and when to use it.

Agent-Driven Search (Recommended)

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);

import OpenAI from 'openai';
import { StackOneToolSet } from '@stackone/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 openaiTools = tools.toOpenAI();

const client = new OpenAI();
const messages = [
  {
    role: 'system' as const,
    content:
      'Use tool_search to find relevant tools, then tool_execute to run them. ' +
      'Read parameter schemas from tool_search results carefully.',
  },
  { role: 'user' as const, content: 'List my upcoming Calendly events for the next week.' },
];

for (let i = 0; i < 10; i++) {
  const response = await client.chat.completions.create({
    model: 'gpt-5.4',
    messages,
    tools: openaiTools,
    tool_choice: 'auto',
  });

  const choice = response.choices[0];
  if (!choice.message.tool_calls?.length) {
    console.log(choice.message.content);
    break;
  }

  messages.push(choice.message);
  for (const toolCall of choice.message.tool_calls) {
    const tool = tools.getTool(toolCall.function.name);
    const result = tool ? await tool.execute(toolCall.function.arguments) : { error: 'Unknown tool' };
    messages.push({ role: 'tool', tool_call_id: toolCall.id, content: JSON.stringify(result) });
  }
}

Manual Search

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.

Search modes (auto, semantic, local)

Mode	Behaviour
`auto`	Tries semantic API first, falls back to local search on failure. Recommended for production.
`semantic`	Strict mode. Uses semantic API only, throws `SemanticSearchError` on failure.
`local`	Hybrid 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' });

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`	`number`	Maximum number of tools to return
`minSimilarity`	`number`	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 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 });

Parameters reference

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

Advanced Patterns

searchActionNames(), lightweight preview

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.

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

Overview

Getting Started

Frameworks

API Behavior

Agent-Driven Search (Recommended)

Framework Examples

Manual Search

SearchConfig Options

Advanced Patterns

Next Steps

​Agent-Driven Search (Recommended)

​Framework Examples

​Manual Search

​SearchConfig Options

​Advanced Patterns

​Next Steps

Agent-Driven Search (Recommended)

Framework Examples

Manual Search

SearchConfig Options

Advanced Patterns

Next Steps