toolcue Join the waitlist

Vercel AI SDK: only the tools each turn needs

The AI SDK sends every tool in tools to the model on every step. Its prepareStep hook can narrow that with activeTools, but something has to decide which tools a turn needs. Toolcue decides in about 35 ms, before the first step, including the lookups the chosen tools depend on.

Verified on 2026-11-02 with ai 7.0.162, with 6 end-to-end tests. Toolcue is in early access: join the waitlist.

Install#

bash
npm install toolcue ai zod

Set TOOLCUE_URL, TOOLCUE_TOKEN and TOOLCUE_ADMIN_TOKEN on your server. The integration is the toolcue/ai-sdk entry point; the client in toolcue has no dependencies.

Use it#

ts
import { generateText, stepCountIs } from "ai";
import { findToolsTool, selectTurn, toolcuePrepareStep } from "toolcue/ai-sdk";

const turn = await selectTurn("acme-billing", messages, { user: { roles: session.roles } });   // once per turn
const tools = { ...TOOLS, find_tools: findToolsTool(turn) };

const result = await generateText({
  model,
  tools,
  messages,
  stopWhen: stepCountIs(10),
  prepareStep: toolcuePrepareStep(turn, tools),      // sets activeTools on every step
});

streamText and ToolLoopAgent take the same prepareStep option (the tests use generateText). Publish your catalog once at deploy time, as in Publish your tools: AI SDK tools describe their input with zod, so convert each one to JSON Schema first (z.toJSONSchema in zod 4).

What happens#

  • selectTurn sends the newest user message and the conversation before it, with tool calls and their results, to Toolcue. For "Refund the last invoice for Globex" it returns the refund tool, the invoice list (the refund needs an invoice id) and the customer search (the list needs a customer id).
  • toolcuePrepareStep returns the same activeTools before every step of the turn. Tools that aren't in your Toolcue catalog always stay active.
  • find_tools searches your whole catalog when the model is missing a tool; what it finds is active from the next step.
  • A tool that isn't active doesn't run even if the model names it: the SDK answers the model with a tool error.
  • If Toolcue fails, selectTurn returns a turn with every tool, so your agent keeps working.

Compared with toolSearch()#

AI SDK v7 also ships toolSearch() with deferLoading tools: the model calls a search tool when it realises a tool is missing, and keyword scoring over names and descriptions picks candidates. Toolcue works before the model starts, reads the conversation, and adds dependent lookups, so most turns need no search step at all. They combine well: Toolcue for the turn's tools, and find_tools (or toolSearch with a Toolcue-backed search function) for the rare miss.