ai/docs/03-ai-sdk-core/19-tool-search.mdx

AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.

---
title: Tool Search
description: Let models discover tools on demand, with direct calling or cache-preserving code mode.
---

# Tool Search

`toolSearch()` lets a model find the tools it needs without loading every tool's
definition into its initial context. Register tools with `deferLoading: true`;
search matches their names and descriptions and makes them available on the
**next model step**.

Use it with `generateText`, `streamText`, `ToolLoopAgent`, or `WorkflowAgent` from
`@ai-sdk/workflow`. The model supplies a search query; the factory optionally
accepts an application-defined `search` callback and a `maxResults` limit.
`WorkflowAgent` supports direct tool calling; the other APIs also support
cache-preserving code mode.

## Direct Tool Calling

The model initially sees only `search`. After searching, matching definitions are
added to the provider's tool list and the model calls those tools directly. This
changes the tool definitions and can invalidate the cached prompt prefix.

```ts
import { generateText, isStepCount, tool, toolSearch } from 'ai';
import { z } from 'zod/v4';

const weather = tool({
  deferLoading: true,
  description: 'Get the weather forecast for a city.',
  inputSchema: z.object({ city: z.string() }),
  execute: async ({ city }) => ({ city, forecast: 'Rain tomorrow.' }),
});

const result = await generateText({
  model: __MODEL__,
  tools: { search: toolSearch(), weather },
  stopWhen: isStepCount(5),
  prompt: 'Will it rain in Bangalore tomorrow?',
});
```

## Code Mode

With [code mode](/docs/ai-sdk-core/code-mode), the model searches and calls tools
through generated code. Set `toolDiscovery: 'conversation'` to announce discovered
definitions in user messages while keeping the provider-visible code tool
unchanged. **This preserves the tool-definition cache as tools are discovered.**
Actual prompt-cache reuse depends on the provider.

Using the `weather` tool defined above:

```ts
import { experimental_codeModeTool as codeModeTool } from '@ai-sdk/code-mode';

const result = await generateText({
  model: __MODEL__,
  tools: {
    code: codeModeTool({ toolDiscovery: 'conversation' }),
    search: toolSearch(),
    weather,
  },
  experimental_toolCallers: {
    search: ['code'],
    weather: ['code'],
  },
  stopWhen: isStepCount(5),
  prompt: 'Will it rain in Bangalore tomorrow?',
});
```

The model first runs `tools.search({ query: 'weather forecast' })`. On the next
step, it receives the updated capability catalog and can call
`tools.weather({ city: 'Bangalore' })`.

In both modes, search loads up to five matches by default, respects `activeTools`
and caller routing, and keeps discovered tools available for the rest of the
generation.
MCP client tools work too: add `deferLoading: true` to the tools returned by
`client.tools()`.

Set `maxResults` to change the number of matching tools loaded per search:

```ts
const search = toolSearch({ maxResults: 10 });
```

`maxResults` must be a positive safe integer. A larger limit can load related
tools in one search, but also adds more tool definitions to the model context.
It does not change keyword matching or ranking.

## Custom Search

Provide a `search` callback when your application needs different matching or
ranking. It receives the query and all eligible deferred tool names and resolved
descriptions, and returns ranked names. It can be synchronous or asynchronous.

```ts
const search = toolSearch({
  search: ({ query, tools }) => {
    // Discover related Gmail actions together, in the application's preferred order.
    const preferred = /\bgmail\b/i.test(query)
      ? ['gmail_list_messages', 'gmail_get_message']
      : [];
    return preferred.filter(name => tools.some(tool => tool.name === name));
  },
});
```

The SDK filters unknown names and duplicates before keeping the first `maxResults`
valid results (five by default). Tools excluded by `activeTools` or caller routing
remain unavailable.
Discovery still takes effect on the next model step. Without a callback, search
keeps its default keyword matching and ranking.

See the [`toolSearch()` reference](/docs/reference/ai-sdk-core/tool-search) for
input, output, and matching details.