Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/lazy-discovery-offered-tools.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@tanstack/ai': patch
---

The lazy tool discovery tool no longer says `Unknown tool` for a tool that the model can already call. Before, it knew only the lazy tools. When a model asked it for an eager tool, or for a tool that a middleware added, it returned `Unknown tool`, and some models then stopped using that tool. Discovery now returns the definition of each tool offered to the model in that step. An eager tool that a middleware removed still gets `Unknown tool`. A lazy tool that a middleware removed still returns its definition.
2 changes: 1 addition & 1 deletion docs/config.json
Original file line number Diff line number Diff line change
Expand Up @@ -438,7 +438,7 @@
"label": "Lazy Tool Discovery",
"to": "tools/lazy-tool-discovery",
"addedAt": "2026-04-15",
"updatedAt": "2026-10-22"
"updatedAt": "2026-11-17"
},
{
"label": "Tool Architecture",
Expand Down
2 changes: 2 additions & 0 deletions docs/tools/lazy-tool-discovery.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,8 @@ The model can ask for one tool or for many in one call:
__lazy__tool__discovery__({ toolNames: ["compareProducts", "calculateFinancing"] })
```

The model can also ask for a tool that it can already call: an eager tool, a tool it found before, or a tool that a middleware added. The discovery tool returns the definition of that tool too, so the model can call it. A name that is not a lazy tool and that the model cannot call, such as an eager tool that a middleware removed, gets an `Unknown tool` error. A lazy tool always returns its definition, even when a middleware removed it.

## When to make a tool lazy

Make a tool lazy when:
Expand Down
16 changes: 14 additions & 2 deletions packages/ai/src/activities/chat/tools/lazy-tool-manager.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ export class LazyToolManager {
private hasNewDiscoveries: boolean
private readonly discoveryTool: Tool | null
private readonly lazyToolsConfig: LazyToolsConfig
/** Tools offered to the model this turn, set by `getExecutableTools()`. */
private offeredTools = new Map<string, AnyTool>()

constructor(
tools: ReadonlyArray<Tool>,
Expand Down Expand Up @@ -117,6 +119,13 @@ export class LazyToolManager {
activeTools: ReadonlyArray<AnyTool>,
pendingToolCallNames: ReadonlyArray<string>,
): ReadonlyArray<AnyTool> {
// `activeTools` is the set after middleware. The discovery tool reads it
// so it does not call an offered tool "Unknown".
this.offeredTools = new Map(
activeTools
.filter((t) => t.name !== DISCOVERY_TOOL_NAME)
.map((t) => [t.name, t]),
)
if (
this.discoveryTool &&
pendingToolCallNames.includes(DISCOVERY_TOOL_NAME) &&
Expand Down Expand Up @@ -263,13 +272,16 @@ export class LazyToolManager {
const errors: Array<string> = []

for (const name of args.toolNames) {
const tool = lazyToolMap.get(name)
const lazyTool = lazyToolMap.get(name)
// A tool already offered this turn (eager, discovered, or added by
// middleware) returns its schema like a re-discovered lazy tool.
const tool = lazyTool ?? manager.offeredTools.get(name)
if (tool) {
// Only flag a refresh for genuinely new discoveries. Re-requesting
// an already-discovered tool still returns its schema below (the
// model asked for it), but must not trigger a redundant tool-list
// refresh + continue in the agent loop.
if (!manager.discoveredTools.has(name)) {
if (lazyTool && !manager.discoveredTools.has(name)) {
manager.discoveredTools.add(name)
manager.hasNewDiscoveries = true
}
Expand Down
56 changes: 56 additions & 0 deletions packages/ai/tests/lazy-tool-manager.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -289,6 +289,62 @@ describe('LazyToolManager', () => {
})
})

describe('discovery of tools that are already offered', () => {
it('returns an eager tool instead of "Unknown tool"', async () => {
const manager = new LazyToolManager(
[makeTool('eagerA'), makeTool('lazyA', { lazy: true })],
[],
)
const active = manager.getActiveTools()
const exec = manager.getExecutableTools(active, [DISCOVERY_TOOL_NAME])
const discovery = exec.find((t) => t.name === DISCOVERY_TOOL_NAME)

const result = await discovery!.execute!({ toolNames: ['eagerA'] })

expect(result.tools).toEqual([
{ name: 'eagerA', description: 'Tool: eagerA' },
])
expect(result.errors).toBeUndefined()
expect(manager.hasNewlyDiscoveredTools()).toBe(false)
})

it('returns a tool that a middleware added to the offered set', async () => {
const manager = new LazyToolManager(
[makeTool('lazyA', { lazy: true })],
[],
)
const offered = [...manager.getActiveTools(), makeTool('fromMiddleware')]
const exec = manager.getExecutableTools(offered, [DISCOVERY_TOOL_NAME])
const discovery = exec.find((t) => t.name === DISCOVERY_TOOL_NAME)

const result = await discovery!.execute!({
toolNames: ['fromMiddleware'],
})

expect(result.tools.map((t: Tool) => t.name)).toEqual(['fromMiddleware'])
expect(result.errors).toBeUndefined()
})

it('still rejects an eager tool that a middleware filtered out', async () => {
const manager = new LazyToolManager(
[makeTool('eagerA'), makeTool('lazyA', { lazy: true })],
[],
)
const offered = manager
.getActiveTools()
.filter((t) => t.name !== 'eagerA')
const exec = manager.getExecutableTools(offered, [DISCOVERY_TOOL_NAME])
const discovery = exec.find((t) => t.name === DISCOVERY_TOOL_NAME)

const result = await discovery!.execute!({ toolNames: ['eagerA'] })

expect(result.tools).toEqual([])
expect(result.errors).toEqual([
"Unknown tool: 'eagerA'. Available tools: [lazyA]",
])
})
})

describe('idempotent discovery', () => {
it('re-discovering an already-discovered tool returns its schema but does not flag a new discovery', async () => {
const tools = [
Expand Down
41 changes: 41 additions & 0 deletions testing/e2e/fixtures/tools-test/lazy-tool-discovery-offered.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
{
"fixtures": [
{
"match": {
"userMessage": "[lazy-tool-discovery-offered] run test",
"sequenceIndex": 0
},
"response": {
"toolCalls": [
{
"name": "__lazy__tool__discovery__",
"arguments": "{\"toolNames\":[\"get_weather\"]}"
}
]
}
},
{
"match": {
"userMessage": "[lazy-tool-discovery-offered] run test",
"sequenceIndex": 1
},
"response": {
"toolCalls": [
{
"name": "get_weather",
"arguments": "{\"city\":\"Paris\"}"
}
]
}
},
{
"match": {
"userMessage": "[lazy-tool-discovery-offered] run test",
"sequenceIndex": 2
},
"response": {
"content": "It is sunny in Paris."
}
}
]
}
6 changes: 6 additions & 0 deletions testing/e2e/src/lib/tools-test-tools.ts
Original file line number Diff line number Diff line change
Expand Up @@ -282,6 +282,11 @@ export const SCENARIO_LIST = [
label: 'Lazy Tool Discovery',
category: 'basic',
},
{
id: 'lazy-tool-discovery-offered',
label: 'Lazy Discovery of an Offered Tool',
category: 'basic',
},
{ id: 'custom-events', label: 'Custom Event Emitting', category: 'basic' },
{
id: 'server-context',
Expand Down Expand Up @@ -472,6 +477,7 @@ export function getToolsForScenario(scenario: string) {
return [serverTools.get_weather]

case 'lazy-tool-discovery':
case 'lazy-tool-discovery-offered':
return [serverTools.get_weather, searchInventory]

case 'custom-events':
Expand Down
31 changes: 31 additions & 0 deletions testing/e2e/tests/lazy-tools.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import {
waitForTestComplete,
getMetadata,
getToolCalls,
getMessages,
} from './tools-test/helpers'

test.describe('Lazy Tool Discovery', () => {
Expand All @@ -21,4 +22,34 @@ test.describe('Lazy Tool Discovery', () => {
expect(toolNames).toContain('__lazy__tool__discovery__')
expect(toolNames).toContain('search_inventory')
})

test('discovery of an already offered tool returns it, not "Unknown tool"', async ({
page,
testId,
aimockPort,
}) => {
await selectScenario(
page,
'lazy-tool-discovery-offered',
testId,
aimockPort,
)
await runTest(page)
await waitForTestComplete(page, 20000, 2)

const toolCalls = await getToolCalls(page)
expect(toolCalls.map((tc: any) => tc.name)).toEqual([
'__lazy__tool__discovery__',
'get_weather',
])

const messages = await getMessages(page)
const discoveryResult = messages
.flatMap((m: any) => m.parts)
.find(
(p: any) =>
p.type === 'tool-result' && p.toolCallId === toolCalls[0].id,
)
expect(discoveryResult?.content).not.toContain('Unknown tool')
})
})
Loading