Skip to content
Source
Sign inSign up
TanStack/ai

fix(ai): return tools already offered from lazy discovery instead of "Unknown tool" #2174

OpenHugoPerard(GitHub profile, opens in a new tab)wants to merge 1 commit intomain fromrefs/pull/2174/headopened View on GitHub

When 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 tools with its schema. It does not start a tool-list refresh.
  • Docs: one paragraph in docs/tools/lazy-tool-discovery.md.
  • Changeset: @tanstack/ai patch.

✅ 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 eagerTools instead 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 alreadyAvailable instead of the schema. This changes the type of the result for no gain. Returning the schema in tools is 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, block discovery 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.
  • 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.
  • nx run @tanstack/ai:test:lib,test:types,test:oxlint: pass (2713 tests).
  • pnpm test:docs: pass.
  • pnpm test:pr on 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 clean main on this machine.
    • @tanstack/ai-sandbox-cloudflare, container-checkpoint.test.ts: chmod: --: No such file or directory. The macOS chmod does not accept --. It also fails on clean main on this machine.

Manual test

  1. On main, run pnpm --filter @tanstack/ai-e2e test:e2e tests/lazy-tools.spec.ts. The new test fails with Unknown tool: 'get_weather'.
  2. 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

    2. 🦋 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
      NameType
      @tanstack/aiPatch

      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

    3. Explain Change →

      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 tool error.

      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.json
      The 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.ts
      Unit tests cover eager, middleware-added, and middleware-removed tools. The end-to-end scenario checks discovery of get_weather and its subsequent tool call.

      Estimated code review effort: 2 (Simple) | ~12 minutes

      Change: Bug fix

      Suggested reviewers: alemtuzlak, season179

      Merge Risk: Minimal · up to 7f38b

      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: Passed 4

      Check nameStatusExplanation
      Title checkPassedThe 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 checkPassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes checkPassedCheck skipped because no linked issues were found for this pull request.
      Description checkPassedThe 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.

      Share

      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.md
      • docs/config.json
      • docs/tools/lazy-tool-discovery.md
      • packages/ai/src/activities/chat/tools/lazy-tool-manager.ts
      • packages/ai/tests/lazy-tool-manager.test.ts
      • testing/e2e/fixtures/tools-test/lazy-tool-discovery-offered.json
      • testing/e2e/src/lib/tools-test-tools.ts
      • testing/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.

    4. 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
      Automated triage — a human review follows.
    5. github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: maintainer

    6. tanstack-sourceBotcommented

      This change is useful. No open pull request does the same work. Related closed work is #788 and #795. This pull request does not link an issue.

      TanStack Source bot, value agent

    7. AlemTuzlak approved these changes

    8. View your CI Pipeline Execution ↗ for commit 7f38b550341986daa3cb3bcf5d7b3f3a9bb0a0c7

      CommandStatusDurationResult
      nx run-many --targets=build --exclude=examples/...✅ Succeeded2m 6sView ↗

      💡 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:10 UTC

    9. Open in StackBlitz

      @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@2174

      commit: 7f38b55

    10. tanstack-sourceBotcommented

      This change is useful. No open pull request does the same work. Related closed work is #788 and #795. This pull request does not link an issue.

      TanStack Source bot, value agent

    11. github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: author

    12. github-actions[bot](GitHub profile, opens in a new tab) removed labelswaiting-on: maintainer

    13. I believe the waiting-on: author label was applied automatically, so this is still ready for review.

    14. github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: maintainer

    15. github-actions[bot](GitHub profile, opens in a new tab) removed labelswaiting-on: author

Sign in to join this conversation.