fix(ai): return tools already offered from lazy discovery instead of "Unknown tool" #2174
main fromrefs/pull/2174/head·opened View on GitHubWhen a model asks the lazy discovery tool for a tool it can already call, discovery answers Unknown tool. Some models then stop using that tool. This PR makes discovery return the definition of every tool offered to the model in that step, the same way it already does for a lazy tool the model asks for again.
🎯 Changes#
LazyToolManager.getExecutableTools()keeps the tools offered in this step. The engine passes it the set after middleware, so this includes tools that a middleware added and leaves out tools that a middleware removed.- The discovery tool looks up a name in the lazy tools first, then in that offered set. An offered tool comes back in
toolswith its schema. It does not start a tool-list refresh. - Docs: one paragraph in
docs/tools/lazy-tool-discovery.md. - Changeset:
@tanstack/aipatch.
✅ Checklist#
- I have followed the steps in the Contributing guide.
- I have tested code changes locally with
pnpm run test:pr, or these tests do not apply to this pull request. (Node 24.22.1, no cache: 461 of 464 tasks pass. The 3 failures are macOS-only sandbox tests that this PR does not touch. See Testing.) - I fully understand the code in this pull request, including any code generated with AI assistance.
- Docs: I updated
docs/for this change, or this change is not user-facing. - Changeset: I added a changeset (
pnpm changeset), or this PR does not change a published package.
🚀 Release Impact#
- This change affects published code, and I have generated a changeset.
- This change is docs/CI/dev-only (no release).
Root cause#
Issue. An app sends eager and lazy tools to chat(), or a middleware adds tools in onConfig. The model calls __lazy__tool__discovery__ with the name of a tool it can already call. Discovery returns { tools: [], errors: ["Unknown tool: '<name>'. ..."] }. The model reads this as "the tool does not exist". We saw Claude Haiku stop a task for this reason.
Cause. The execute function of the discovery tool, in createDiscoveryTool() in lazy-tool-manager.ts, looks only in lazyToolMap. Each name that is not lazy becomes Unknown tool, even when the engine offered that tool to the model in this step.
Fix. getExecutableTools() gets the offered tools from the engine just before it runs the tool calls of each step. It now stores them. Discovery falls back to that set before it reports Unknown tool.
Possible alternatives#
- Look up
eagerToolsinstead of the offered set. This is a smaller change. It misses tools that a middleware adds, and it would announce eager tools that a middleware removed. - Return a new field such as
alreadyAvailableinstead of the schema. This changes the type of the result for no gain. Returning the schema intoolsis what discovery already does for a lazy tool that the model asks for again.
Testing#
Commands run
- Unit repro, written for this PR, in
packages/ai/tests/lazy-tool-manager.test.ts, blockdiscovery of tools that are already offered.- On
main(code unchanged):× returns an eager tool instead of "Unknown tool",× returns a tool that a middleware added to the offered set. Result:2 failed | 1 passed. - With this PR:
3 passed.
- On
- E2E
pnpm --filter @tanstack/ai-e2e test:e2e tests/lazy-tools.spec.ts.- On
main:✘ discovery of an already offered tool returns it, not "Unknown tool", received{"tools":[],"errors":["Unknown tool: 'get_weather'. Available tools: [search_inventory]"]}. - With this PR:
2 passed.
- On
nx run @tanstack/ai:test:lib,test:types,test:oxlint: pass (2713 tests).pnpm test:docs: pass.pnpm test:pron Node 24.22.1 (from.nvmrc), macOS, with--skip-nx-cache: 461 of 464 tasks pass. The 3 failures are in sandbox packages that this PR does not change:@tanstack/ai-sandbox-local-process: passes when run alone. It fails only under the load of the full parallel run.@tanstack/ai-sandbox,tool-bridge.test.ts"rejects when the listener cannot start": times out after 5 s. It also fails on cleanmainon this machine.@tanstack/ai-sandbox-cloudflare,container-checkpoint.test.ts:chmod: --: No such file or directory. The macOSchmoddoes not accept--. It also fails on cleanmainon this machine.
Manual test
- On
main, runpnpm --filter @tanstack/ai-e2e test:e2e tests/lazy-tools.spec.ts. The new test fails withUnknown tool: 'get_weather'. - On this branch, run the same command. Both tests pass.
How this PR makes testing easy
- 3 unit tests: an eager tool, a tool added by a middleware, and an eager tool removed by a middleware (still
Unknown tool). - A new E2E scenario,
lazy-tool-discovery-offered, in the tools-test page.
Risk / rollback#
Low. Only the result of a discovery call for a name that is not lazy changes. Revert the PR to undo.
Known limit, not changed here: a lazy tool that a middleware removes from the offered set is still returned by discovery, because discovery looks in lazyToolMap first. That was already the behavior before this PR.
🤖 Generated with Claude Code
- 1
tanstack-source added labelsbug
No actionable comments were generated in the recent review.
Walkthrough
-
Tool discovery now returns definitions for tools offered to the model in the current turn. Only newly discovered lazy tools update discovery state and trigger a tool-list refresh. Requests for names that are neither lazy nor offered still return an
Unknown toolerror.Changes: Lazy Tool Discovery
Layer / File(s) Summary Track and resolve offered tools
packages/ai/src/activities/chat/tools/lazy-tool-manager.ts,docs/tools/lazy-tool-discovery.md,.changeset/lazy-discovery-offered-tools.md,docs/config.jsonThe manager records post-middleware tools offered to the model, excluding the discovery tool. Discovery returns definitions for offered tools without marking them as newly discovered or triggering a refresh. The docs and changeset describe this behavior and the unknown-tool case. Validate offered-tool discovery
packages/ai/tests/lazy-tool-manager.test.ts,testing/e2e/src/lib/tools-test-tools.ts,testing/e2e/fixtures/tools-test/lazy-tool-discovery-offered.json,testing/e2e/tests/lazy-tools.spec.tsUnit tests cover eager, middleware-added, and middleware-removed tools. The end-to-end scenario checks discovery of get_weatherand its subsequent tool call.Estimated code review effort: 2 (Simple) | ~12 minutes
Change: Bug fix
Suggested reviewers:
alemtuzlak,season179
Merge Risk:
Minimal · up to7f38b-
Lazy tool discovery now returns definitions for tools the model can already call, instead of reporting them as unknown. The change is small, well covered by tests and documented. The only known limitation, that a lazy tool removed by middleware is still returned, is stated in the PR. No unresolved merge-blocking risk was found.
Pre-merge checks:
4-
Check name Status Explanation Title check The title names the main change: lazy tool discovery now returns tools already offered to the model instead of reporting them as "Unknown tool". The changeset, code, tests, docs, and e2e fixture all m… Linked Issues check Check skipped because no linked issues were found for this pull request. Out of Scope Changes check Check skipped because no linked issues were found for this pull request. Description check The description follows the repository template closely. It covers the change and root cause, the fix, alternatives, testing commands with results, a manual test, and risk/rollback. All checklist item… Full details: Title check
-
Explanation
The title names the main change: lazy tool discovery now returns tools already offered to the model instead of reporting them as "Unknown tool". The changeset, code, tests, docs, and e2e fixture all match this fix. The title is specific and uses the conventional fix(ai) prefix.
Full details: Description check
-
Explanation
The description follows the repository template closely. It covers the change and root cause, the fix, alternatives, testing commands with results, a manual test, and risk/rollback. All checklist items are marked and the release impact is stated. The description is thorough, and the stated test results are consistent with the PR objectives. Minor note: the description says the machine ran Node 24.22.1 from .nvmrc, while the objectives say Node 26; this discrepancy is worth confirming, but it does not affect the template structure.
-
Finishing Touches
-
Generate unit tests (beta)
-
- Create a new PR
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Recent review info-
Run configuration-
- Source mode: Auto
- Repository: TanStack/ai
- Branch: main
- File: .coderabbit.yaml
- Commit: 6484f08
- Layers: Repository YAML
- Review profile: CHILL
- Plan: Advanced
- Run ID:
fd523ae5-a84d-49f6-9f52-a2fe364c089a
Commits-
Reviewing files that changed from the base of the PR and between 6484f0864f3b6c4476aad0bbf2a79ef5e4e6a9e8 and 7f38b550341986daa3cb3bcf5d7b3f3a9bb0a0c7.
Files selected for processing: 8-
.changeset/lazy-discovery-offered-tools.mddocs/config.jsondocs/tools/lazy-tool-discovery.mdpackages/ai/src/activities/chat/tools/lazy-tool-manager.tspackages/ai/tests/lazy-tool-manager.test.tstesting/e2e/fixtures/tools-test/lazy-tool-discovery-offered.jsontesting/e2e/src/lib/tools-test-tools.tstesting/e2e/tests/lazy-tools.spec.ts
Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.
-
-
github-actions[bot](GitHub profile, opens in a new tab) assignedtombeckenham
Thanks for the PR, @HugoPerard! 🙌 @tombeckenham will take a look.
Automated pre-review checks
- ✅ CI passing
- ✅ No merge conflicts
- ✅ Changeset present
- ✅ E2E test changes included
github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: maintainer
AlemTuzlak approved these changes
View your CI Pipeline Execution ↗ for commit 7f38b550341986daa3cb3bcf5d7b3f3a9bb0a0c7
Command Status Duration Result nx run-many --targets=build --exclude=examples/...✅ Succeeded 2m 6s View ↗ 💡 With Ultracache enabled, Nx Cloud learns each task's file inputs in CI and uses them on later runs. Turn on Ultracache in workspace settings ↗ · Read docs ↗
☁️ Nx Cloud last updated this comment at
2026-11-19 11:21:10UTC@tanstack/ai
npm i https://pkg.pr.new/@tanstack/ai@2174@tanstack/ai-acp
npm i https://pkg.pr.new/@tanstack/ai-acp@2174@tanstack/ai-angular
npm i https://pkg.pr.new/@tanstack/ai-angular@2174@tanstack/ai-anthropic
npm i https://pkg.pr.new/@tanstack/ai-anthropic@2174@tanstack/ai-bedrock
npm i https://pkg.pr.new/@tanstack/ai-bedrock@2174@tanstack/ai-byteplus
npm i https://pkg.pr.new/@tanstack/ai-byteplus@2174@tanstack/ai-claude-code
npm i https://pkg.pr.new/@tanstack/ai-claude-code@2174@tanstack/ai-client
npm i https://pkg.pr.new/@tanstack/ai-client@2174@tanstack/ai-cloudflare
npm i https://pkg.pr.new/@tanstack/ai-cloudflare@2174@tanstack/ai-code-mode
npm i https://pkg.pr.new/@tanstack/ai-code-mode@2174@tanstack/ai-code-mode-snippets
npm i https://pkg.pr.new/@tanstack/ai-code-mode-snippets@2174@tanstack/ai-codex
npm i https://pkg.pr.new/@tanstack/ai-codex@2174@tanstack/ai-cohere
npm i https://pkg.pr.new/@tanstack/ai-cohere@2174@tanstack/ai-compaction
npm i https://pkg.pr.new/@tanstack/ai-compaction@2174@tanstack/ai-computer-local
npm i https://pkg.pr.new/@tanstack/ai-computer-local@2174@tanstack/ai-computer-playwright
npm i https://pkg.pr.new/@tanstack/ai-computer-playwright@2174@tanstack/ai-computer-sandbox
npm i https://pkg.pr.new/@tanstack/ai-computer-sandbox@2174@tanstack/ai-computer-use
npm i https://pkg.pr.new/@tanstack/ai-computer-use@2174@tanstack/ai-devtools-core
npm i https://pkg.pr.new/@tanstack/ai-devtools-core@2174@tanstack/ai-durable-stream
npm i https://pkg.pr.new/@tanstack/ai-durable-stream@2174@tanstack/ai-effect
npm i https://pkg.pr.new/@tanstack/ai-effect@2174@tanstack/ai-elevenlabs
npm i https://pkg.pr.new/@tanstack/ai-elevenlabs@2174@tanstack/ai-event-client
npm i https://pkg.pr.new/@tanstack/ai-event-client@2174@tanstack/ai-fal
npm i https://pkg.pr.new/@tanstack/ai-fal@2174@tanstack/ai-gemini
npm i https://pkg.pr.new/@tanstack/ai-gemini@2174@tanstack/ai-grok
npm i https://pkg.pr.new/@tanstack/ai-grok@2174@tanstack/ai-grok-build
npm i https://pkg.pr.new/@tanstack/ai-grok-build@2174@tanstack/ai-groq
npm i https://pkg.pr.new/@tanstack/ai-groq@2174@tanstack/ai-harness
npm i https://pkg.pr.new/@tanstack/ai-harness@2174@tanstack/ai-harness-cli
npm i https://pkg.pr.new/@tanstack/ai-harness-cli@2174@tanstack/ai-isolate-cloudflare
npm i https://pkg.pr.new/@tanstack/ai-isolate-cloudflare@2174@tanstack/ai-isolate-daytona
npm i https://pkg.pr.new/@tanstack/ai-isolate-daytona@2174@tanstack/ai-isolate-e2b
npm i https://pkg.pr.new/@tanstack/ai-isolate-e2b@2174@tanstack/ai-isolate-node
npm i https://pkg.pr.new/@tanstack/ai-isolate-node@2174@tanstack/ai-isolate-quickjs
npm i https://pkg.pr.new/@tanstack/ai-isolate-quickjs@2174@tanstack/ai-isolate-quickjs-bun
npm i https://pkg.pr.new/@tanstack/ai-isolate-quickjs-bun@2174@tanstack/ai-llmgateway
npm i https://pkg.pr.new/@tanstack/ai-llmgateway@2174@tanstack/ai-lovable
npm i https://pkg.pr.new/@tanstack/ai-lovable@2174@tanstack/ai-mcp
npm i https://pkg.pr.new/@tanstack/ai-mcp@2174@tanstack/ai-memory
npm i https://pkg.pr.new/@tanstack/ai-memory@2174@tanstack/ai-mistral
npm i https://pkg.pr.new/@tanstack/ai-mistral@2174@tanstack/ai-muse
npm i https://pkg.pr.new/@tanstack/ai-muse@2174@tanstack/ai-neon
npm i https://pkg.pr.new/@tanstack/ai-neon@2174@tanstack/ai-octane
npm i https://pkg.pr.new/@tanstack/ai-octane@2174@tanstack/ai-ollama
npm i https://pkg.pr.new/@tanstack/ai-ollama@2174@tanstack/ai-ollaya
npm i https://pkg.pr.new/@tanstack/ai-ollaya@2174@tanstack/ai-openai
npm i https://pkg.pr.new/@tanstack/ai-openai@2174@tanstack/ai-opencode
npm i https://pkg.pr.new/@tanstack/ai-opencode@2174@tanstack/ai-openrouter
npm i https://pkg.pr.new/@tanstack/ai-openrouter@2174@tanstack/ai-perplexity
npm i https://pkg.pr.new/@tanstack/ai-perplexity@2174@tanstack/ai-persistence
npm i https://pkg.pr.new/@tanstack/ai-persistence@2174@tanstack/ai-preact
npm i https://pkg.pr.new/@tanstack/ai-preact@2174@tanstack/ai-react
npm i https://pkg.pr.new/@tanstack/ai-react@2174@tanstack/ai-reactor
npm i https://pkg.pr.new/@tanstack/ai-reactor@2174@tanstack/ai-remix
npm i https://pkg.pr.new/@tanstack/ai-remix@2174@tanstack/ai-sandbox
npm i https://pkg.pr.new/@tanstack/ai-sandbox@2174@tanstack/ai-sandbox-blaxel
npm i https://pkg.pr.new/@tanstack/ai-sandbox-blaxel@2174@tanstack/ai-sandbox-boxd
npm i https://pkg.pr.new/@tanstack/ai-sandbox-boxd@2174@tanstack/ai-sandbox-cloudflare
npm i https://pkg.pr.new/@tanstack/ai-sandbox-cloudflare@2174@tanstack/ai-sandbox-daytona
npm i https://pkg.pr.new/@tanstack/ai-sandbox-daytona@2174@tanstack/ai-sandbox-docker
npm i https://pkg.pr.new/@tanstack/ai-sandbox-docker@2174@tanstack/ai-sandbox-e2b
npm i https://pkg.pr.new/@tanstack/ai-sandbox-e2b@2174@tanstack/ai-sandbox-local-process
npm i https://pkg.pr.new/@tanstack/ai-sandbox-local-process@2174@tanstack/ai-sandbox-railway
npm i https://pkg.pr.new/@tanstack/ai-sandbox-railway@2174@tanstack/ai-sandbox-sprites
npm i https://pkg.pr.new/@tanstack/ai-sandbox-sprites@2174@tanstack/ai-sandbox-upstash-box
npm i https://pkg.pr.new/@tanstack/ai-sandbox-upstash-box@2174@tanstack/ai-sandbox-vercel
npm i https://pkg.pr.new/@tanstack/ai-sandbox-vercel@2174@tanstack/ai-skills
npm i https://pkg.pr.new/@tanstack/ai-skills@2174@tanstack/ai-solid
npm i https://pkg.pr.new/@tanstack/ai-solid@2174@tanstack/ai-svelte
npm i https://pkg.pr.new/@tanstack/ai-svelte@2174@tanstack/ai-typesafe
npm i https://pkg.pr.new/@tanstack/ai-typesafe@2174@tanstack/ai-utils
npm i https://pkg.pr.new/@tanstack/ai-utils@2174@tanstack/ai-vercel-gateway
npm i https://pkg.pr.new/@tanstack/ai-vercel-gateway@2174@tanstack/ai-vertex
npm i https://pkg.pr.new/@tanstack/ai-vertex@2174@tanstack/ai-vue
npm i https://pkg.pr.new/@tanstack/ai-vue@2174@tanstack/ai-worldlabs
npm i https://pkg.pr.new/@tanstack/ai-worldlabs@2174@tanstack/openai-base
npm i https://pkg.pr.new/@tanstack/openai-base@2174@tanstack/preact-ai-devtools
npm i https://pkg.pr.new/@tanstack/preact-ai-devtools@2174@tanstack/react-ai-devtools
npm i https://pkg.pr.new/@tanstack/react-ai-devtools@2174@tanstack/solid-ai-devtools
npm i https://pkg.pr.new/@tanstack/solid-ai-devtools@2174@tanstack/svelte-ai-devtools
npm i https://pkg.pr.new/@tanstack/svelte-ai-devtools@2174commit:
7f38b55github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: author
github-actions[bot](GitHub profile, opens in a new tab) removed labelswaiting-on: maintainer
I believe the
waiting-on: authorlabel was applied automatically, so this is still ready for review.github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: maintainer
github-actions[bot](GitHub profile, opens in a new tab) removed labelswaiting-on: author
Sign in to join this conversation.
🦋 Changeset detected#
Latest commit: 7f38b550341986daa3cb3bcf5d7b3f3a9bb0a0c7
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are.
Click here if you're a maintainer who wants to add another changeset to this PR