fix: Reword tool search warnings to target clients, not Claude models (#2077)

* fix: Reword tool search warnings to target clients, not Claude models

The enable_tool_search warnings blamed Sonnet/Opus models for a conflict
that belongs to clients with built-in deferred tool search (claude.ai,
Claude Desktop, Claude Code). Deferred tools are a client feature, not a
model feature: clients that inline all tool schemas (e.g. GitHub Copilot
CLI) benefit from ha-mcp's tool search regardless of model. Claude
clients should keep using their built-in tool search instead of ha-mcp's.

Updated on every surface carrying the warning: settings UI locales (all
languages), both add-on flavors' translations and DOCS.md, README, and
the locale source baseline.

Closes #2059

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: Update settings.js fallback copy of the tool search warning

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: Drop the exact full-catalog token figure from tool search help

The ~46K number drifts as the catalog grows; state the reduction as a
percentage and keep only the post-enable idle figure.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: Frame deferred-tools guidance around the client/model combination

The absolute 'client feature, not a model feature' claim contradicted the
model-based examples beside it (Codex review). The deciding question is
whether the current client/model combination loads the full catalog up
front.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: kingpanther13

README.md

@@ -324,9 +324,9 @@ Skills can still be installed manually for clients that prefer local skill files
 
 ## 🔍 Tool Discovery for AI Agents
 
-By default, the full tool catalog (~84 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (Claude Sonnet, Claude Opus) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
+By default, the full tool catalog (~84 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (claude.ai, Claude Desktop, Claude Code) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
 
-For models *without* deferred tool support — Claude Haiku, Gemini, ChatGPT OpenAI-compatible local models, smaller open-weights models — listing the full tool catalog up front adds a lot of idle context and can overwhelm smaller models. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
+For setups *without* deferred tool support — models like Claude Haiku, Gemini, OpenAI-compatible local models and smaller open-weights models, or clients that inline all tool schemas regardless of model (e.g. GitHub Copilot CLI) — listing the full tool catalog up front adds a lot of idle context and can overwhelm smaller models. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
 
 ### Smaller or local LLMs (Ollama, etc.)
 
@@ -356,11 +356,11 @@ The proxy split lets MCP clients apply different permission policies per categor
 
 ### When to enable
 
-- **Claude Haiku, OpenAI-compatible local models, Gemini, ChatGPT or any model without native deferred tool support** — large idle-context savings.
+- **Claude Haiku, OpenAI-compatible local models, Gemini, or any model without native deferred tool support** — large idle-context savings. The same applies to clients that inline all tool schemas regardless of model (e.g. GitHub Copilot CLI, even when running Claude Sonnet/Opus).
 - MCP clients that cap total tool count (some cap at 100) — surfaces a minimal set (~10 tools) instead of 84.
 - **Cost-sensitive deployments** — fewer idle tokens per turn.
 
-Leave it off when using Claude Sonnet/Opus or any client with deferred tool loading; the full catalog has no idle cost there and direct calls skip the search step. If you choose to use our toolsearch then you should disable the native Claude Opus/Sonnet toolsearch, which is called deferred tools in the settings.
+Leave it off in clients with deferred tool loading (claude.ai, Claude Desktop, Claude Code); the full catalog has no idle cost there, direct calls skip the search step, and the client's built-in tool search is the better choice — there is no benefit to running ha-mcp's on top of it. Whether tools are deferred depends on the client and model combination: the same model can behave differently per client — GitHub Copilot CLI running Claude Sonnet/Opus inlines the full catalog and still benefits from tool search here. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily.
 
 > 🔄 **Refresh your client's tool list after changing this (or any) setting.** Toggling `ENABLE_TOOL_SEARCH` (or changing pinned/disabled tools, Read Only Mode, etc.) changes the tools the server exposes, but your AI client keeps serving its **cached** tool list until it re-fetches. Restarting the add-on or Home Assistant does **not** refresh the client — reconnect or refresh the MCP server in your client (e.g. re-add/refresh the connector in ChatGPT, or close and reopen Claude Desktop). If you skip this, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but return `Unknown tool` when called. ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after re-adding, delete the connector and create a new one with a **different name**.
 

homeassistant-addon-dev/DOCS.md

@@ -14,7 +14,7 @@ The dev add-on uses the same configuration as the stable version. See the main a
 |--------|-------------|---------|
 | `backup_hint` | Backup strength preference | `normal` |
 | `secret_path` | Custom secret path (optional) | auto-generated |
-| `enable_tool_search` | Replace full tool catalog with search-based discovery (~46K → ~5K tokens). ⚠️ Do NOT enable for Claude Sonnet/Opus — their built-in tool search conflicts with ha-mcp's. Disable one or the other. | `false` |
+| `enable_tool_search` | Replace full tool catalog with search-based discovery (cuts idle context by ~90%, to ~5K tokens). ⚠️ Do NOT enable in clients with built-in tool search / deferred tools (claude.ai, Claude Desktop, Claude Code) — the layers conflict; use the client's built-in search instead. | `false` |
 | `enable_tool_security_policies` | Gate high-stakes tool calls (lock/alarm control, automation writes, etc.) behind user approval. Guarded calls block until the user clicks Approve in the Tool Security Policies tab of the web UI. Per-tool rules with optional argument conditions are configured in that same tab. | `false` |
 | `read_only_mode` | Toggles all write tools off, and removes ability for tools to make any write or destructive calls. Mixed read/write tools (backups, add-ons, energy preferences, voice pipelines, and code mode when enabled) stay available with their write operations blocked. Same toggle as the web UI Tools tab. | `false` |
 | `enable_beta_features` *(master)* | Master gate for the beta sub-flags below. Sub-flags are ignored at runtime while this is off — even when explicitly set to true. Mirrored to the web settings UI under "Beta features (dangerous)". | `true` |

homeassistant-addon-dev/translations/de.yaml

@@ -20,16 +20,22 @@ configuration:
     name: Tool-Suche aktivieren
     description: >-
       Ersetzt den vollständigen Tool-Katalog durch suchbasierte Entdeckung.
-      Reduziert den Leerlauf-Kontext von ~46K auf ~5K Tokens. ⚠️ Aktiviere dies
-      NICHT, wenn du Claude im Sonnet- oder Opus-Modus verwendest – diese
-      Modelle haben ihre eigene integrierte Tool-Suche / aufgeschobene Tools,
-      die mit unserer kollidiert. Um die Tool-Suche von ha-mcp mit Claude zu
-      verwenden, deaktiviere zuerst Claudes integrierte Tool-Suche; lasse dies
-      andernfalls ausgeschaltet. Verwende dies nur mit LLMs, denen native
-      aufgeschobene Tools fehlen (z. B. Claude Haiku, lokale OpenAI-kompatible
-      Modelle) oder mit kleineren Kontextfenstern. Tools werden über
-      ha_search_tools gefunden und über kategorisierte Proxys
-      (read/write/delete) ausgeführt. Erfordert Neustart, um wirksam zu werden.
+      Reduziert den Leerlauf-Kontext um rund 90 % auf etwa 5K Tokens. ⚠️
+      Aktiviere dies NICHT in Clients mit eigener integrierter Tool-Suche /
+      aufgeschobenen Tools (claude.ai, Claude Desktop, Claude Code) – die
+      beiden Suchebenen kollidieren, und die integrierte Tool-Suche des
+      Clients ist dort die bessere Wahl; lasse dies ausgeschaltet. Ob Tools
+      aufgeschoben werden, hängt von der Kombination aus Client und Modell ab:
+      Verwende dies, wenn dein Setup den vollständigen Katalog von Anfang an
+      lädt – Modelle ohne native aufgeschobene Tools (z. B. Gemini, lokale
+      OpenAI-kompatible Modelle, Claude Haiku), Clients, die alle
+      Tool-Schemata unabhängig vom Modell direkt einbetten (z. B. GitHub
+      Copilot CLI), oder kleinere Kontextfenster. Auch einige Codex-Modelle
+      und ChatGPT haben aufgeschobene Tools – prüfe direkt bei deinem
+      Client/Modell, welche Features er hat, damit du dies nicht unnötig
+      aktiviert lässt. Tools werden über ha_search_tools gefunden und über
+      kategorisierte Proxys (read/write/delete) ausgeführt. Erfordert
+      Neustart, um wirksam zu werden.
   enable_tool_security_policies:
     name: Tool-Sicherheitsrichtlinien aktivieren (erweitert)
     description: >-

homeassistant-addon-dev/translations/en.yaml

@@ -18,16 +18,21 @@ configuration:
   enable_tool_search:
     name: Enable tool search
     description: >-
-      Replace the full tool catalog with search-based discovery. Reduces
-      idle context from ~46K to ~5K tokens. ⚠️ Do NOT enable this if you
-      use Claude in Sonnet or Opus modes — those models have their own
-      built-in tool search / deferred tools, which conflicts with ours.
-      To use ha-mcp's tool search with Claude, disable Claude's built-in
-      tool search first; otherwise leave this off. Use this only with
-      LLMs that lack native deferred tools (e.g. Claude Haiku, local
-      OpenAI-compatible models) or with smaller context windows. Tools
-      are found via ha_search_tools and executed via categorized proxies
-      (read/write/delete). Requires restart to take effect.
+      Replace the full tool catalog with search-based discovery. Reduces idle
+      context by roughly 90%, to about 5K tokens. ⚠️ Do NOT enable this in
+      clients with their own built-in tool search / deferred tools (claude.ai,
+      Claude Desktop, Claude Code) — the two search layers conflict, and the
+      client's built-in tool search is the better choice there; leave this
+      off. Whether tools are deferred depends on your client and model
+      combination: use this when your setup loads the full catalog up front —
+      models without native deferred tools (e.g. Gemini, OpenAI-compatible
+      local models, Claude Haiku), clients that inline all tool schemas
+      regardless of model (e.g. GitHub Copilot CLI), or smaller context
+      windows. Some Codex models and ChatGPT include deferred tools too —
+      check your client/model directly to confirm its features so you don't
+      leave this enabled unnecessarily. Tools are found via ha_search_tools
+      and executed via categorized proxies (read/write/delete). Requires
+      restart to take effect.
   enable_tool_security_policies:
     name: Enable Tool Security Policies (advanced)
     description: >-

homeassistant-addon-dev/translations/es.yaml

@@ -20,17 +20,23 @@ configuration:
     name: Activar la búsqueda de herramientas
     description: >-
       Sustituye el catálogo completo de herramientas por un descubrimiento
-      basado en búsqueda. Reduce el contexto en reposo de unos 46K a unos 5K tokens.
-      ⚠️ NO actives esto si usas Claude en modo Sonnet u Opus: esos modelos
-      tienen su propia búsqueda de herramientas / herramientas diferidas
-      integrada, que entra en conflicto con la nuestra. Para usar la búsqueda de
-      herramientas de ha-mcp con Claude, desactiva primero la búsqueda integrada
-      de Claude; si no, deja esto desactivado. Úsalo solo con LLM que carezcan de
-      herramientas diferidas nativas (p. ej. Claude Haiku, modelos locales
-      compatibles con OpenAI) o con ventanas de contexto más pequeñas. Las
-      herramientas se localizan mediante ha_search_tools y se ejecutan a través
-      de proxies por categoría (lectura/escritura/borrado). Requiere reiniciar
-      para que surta efecto.
+      basado en búsqueda. Reduce el contexto en reposo en torno a un 90 %,
+      hasta unos 5K tokens. ⚠️ NO actives esto en clientes con su propia
+      búsqueda de herramientas / herramientas diferidas integrada (claude.ai,
+      Claude Desktop, Claude Code): las dos capas de búsqueda entran en
+      conflicto y la búsqueda integrada del cliente es allí la mejor opción;
+      deja esto desactivado. Que las herramientas se difieran depende de la
+      combinación de cliente y modelo: usa esto cuando tu configuración carga
+      el catálogo completo de entrada — modelos sin herramientas diferidas
+      nativas (p. ej. Gemini, modelos locales compatibles con OpenAI, Claude
+      Haiku), clientes que insertan todos los esquemas de herramientas sea
+      cual sea el modelo (p. ej. GitHub Copilot CLI) o ventanas de contexto
+      más pequeñas. Algunos modelos Codex y ChatGPT también incluyen
+      herramientas diferidas: comprueba directamente con tu cliente/modelo qué
+      características tiene para no dejar esto activado innecesariamente. Las
+      herramientas se localizan mediante ha_search_tools y se ejecutan a
+      través de proxies por categoría (lectura/escritura/borrado). Requiere
+      reiniciar para que surta efecto.
   enable_tool_security_policies:
     name: Activar las políticas de seguridad de herramientas (avanzado)
     description: >-

homeassistant-addon-dev/translations/fr.yaml

@@ -20,17 +20,23 @@ configuration:
     name: Activer la recherche d'outils
     description: >-
       Remplace le catalogue complet d'outils par une découverte basée sur la
-      recherche. Réduit le contexte inactif d'environ 46K à 5K tokens. ⚠️
-      N'active PAS ceci si tu utilises Claude en modes Sonnet ou Opus — ces
-      modèles ont leur propre recherche d'outils intégrée / outils différés, qui
-      entre en conflit avec la nôtre. Pour utiliser la recherche d'outils de
-      ha-mcp avec Claude, désactive d'abord la recherche d'outils intégrée de
-      Claude ; sinon, laisse ceci désactivé. Utilise ceci uniquement avec des
-      LLM qui n'ont pas d'outils différés natifs (p. ex. Claude Haiku, modèles
-      locaux compatibles OpenAI) ou avec des fenêtres de contexte plus petites.
-      Les outils sont trouvés via ha_search_tools et exécutés via des proxys
-      catégorisés (lecture/écriture/suppression). Nécessite un redémarrage pour
-      prendre effet.
+      recherche. Réduit le contexte inactif d'environ 90 %, à près de 5K
+      tokens. ⚠️ N'active PAS ceci dans les clients qui ont leur propre
+      recherche d'outils intégrée / outils différés (claude.ai, Claude
+      Desktop, Claude Code) — les deux couches de recherche entrent en
+      conflit, et la recherche d'outils intégrée du client y est le meilleur
+      choix ; laisse ceci désactivé. Le report des outils dépend de la
+      combinaison client/modèle : utilise ceci lorsque ta configuration charge
+      le catalogue complet d'emblée — modèles sans outils différés natifs (p.
+      ex. Gemini, modèles locaux compatibles OpenAI, Claude Haiku), clients
+      qui intègrent tous les schémas d'outils quel que soit le modèle (p. ex.
+      GitHub Copilot CLI), ou fenêtres de contexte plus petites. Certains
+      modèles Codex et ChatGPT incluent aussi des outils différés — vérifie
+      directement auprès de ton client/modèle quelles fonctionnalités il
+      possède pour ne pas laisser ceci activé inutilement. Les outils sont
+      trouvés via ha_search_tools et exécutés via des proxys catégorisés
+      (lecture/écriture/suppression). Nécessite un redémarrage pour prendre
+      effet.
   enable_tool_security_policies:
     name: Activer les politiques de sécurité des outils (avancé)
     description: >-

homeassistant-addon-dev/translations/ru.yaml

@@ -20,15 +20,21 @@ configuration:
     name: Включить поиск инструментов
     description: >-
       Заменяет полный каталог инструментов поиском по запросу. Уменьшает
-      неиспользуемый контекст примерно с 46 тыс. до 5 тыс. токенов. ⚠️ НЕ
-      включайте этот параметр, если используете Claude в режимах Sonnet или
-      Opus: у этих моделей есть собственный встроенный поиск инструментов и
-      отложенные инструменты, которые конфликтуют с нашими. Чтобы использовать
-      поиск инструментов ha-mcp с Claude, сначала отключите встроенный поиск
-      инструментов Claude; в противном случае оставьте этот параметр выключенным.
-      Используйте его только с LLM без собственных отложенных инструментов
-      (например, Claude Haiku или локальными OpenAI-совместимыми моделями) либо
-      с небольшими контекстными окнами. Инструменты находятся через
+      неиспользуемый контекст примерно на 90 % — до порядка 5 тыс. токенов. ⚠️
+      НЕ включайте этот параметр в клиентах с собственным встроенным поиском
+      инструментов и отложенными инструментами (claude.ai, Claude Desktop,
+      Claude Code): два слоя поиска конфликтуют, а встроенный поиск
+      инструментов клиента там — лучший выбор; оставьте этот параметр
+      выключенным. Будут ли инструменты отложенными, зависит от сочетания
+      клиента и модели: используйте этот параметр, когда ваша конфигурация
+      загружает полный каталог сразу — модели без собственных отложенных
+      инструментов (например, Gemini, локальные OpenAI-совместимые модели,
+      Claude Haiku), клиенты, которые встраивают все схемы инструментов
+      независимо от модели (например, GitHub Copilot CLI), или небольшие
+      контекстные окна. Некоторые модели Codex и ChatGPT тоже включают
+      отложенные инструменты — уточните непосредственно у своего
+      клиента/модели, какие функции он поддерживает, чтобы не оставлять этот
+      параметр включённым без необходимости. Инструменты находятся через
       ha_search_tools и выполняются через распределённые по категориям прокси
       (чтение, запись, удаление). Для применения требуется перезапуск.
   enable_tool_security_policies: