docs: warn against enable_tool_search on Claude Sonnet/Opus (#1088) (#1140)

* docs: warn against enable_tool_search on Claude Sonnet/Opus

Issue #1088 reports tool discovery breaking on claude.ai/Claude Desktop
when ENABLE_TOOL_SEARCH=true. The cause is collision between ha-mcp's
categorized search transform and Claude's own native deferred tool
loader: stacking the two layers double-defers and read tools (e.g.
ha_call_read_tool) silently fail to surface, leaving every read tool
unreachable.

The previous wording framed this as "you don't need it" rather than
"it actively breaks." Update DOCS.md and the addon UI toggle text on
both stable and dev addon variants to:

- Lead with an explicit "Do NOT enable" warning callout
- Note the failure mode (read tools become unreachable)
- Link to issue #1088
- Tell users they must disable Claude's own internal tool search /
  deferred tools first if they really want ha-mcp's search
- Repeat the warning in the "When to leave disabled" bullet so it is
  visible at every glance, not just in the callout

Toggle descriptions in translations/en.yaml are kept identical between
the stable and dev addons.

* docs: tighten enable_tool_search warning, drop issue link

Address review feedback:

- Soften the failure-mode wording from "actively breaks ... can fail to
  surface" (which was internally contradictory and stronger than the
  evidence) to "conflicts" / "running both at once does not work."
- Frame the choice plainly: Claude Sonnet/Opus run their own tool
  search, and the user must pick one — disable Claude's to use ha-mcp's,
  otherwise leave this off. Drops the speculative "must turn off in
  client settings" framing.
- Remove the issue #1088 link from all four user-facing locations; users
  reading the addon docs/UI don't need to chase a GitHub issue.
- Add the disable-Claude-first workaround to the addon UI toggle text
  (translations/en.yaml). Previously the workaround was only in DOCS.md
  so users adjusting the toggle in the UI never saw it.
- Reuse one canonical phrase across the blockquote, the "When to leave
  disabled" bullet, the dev-addon table row, and the toggle text so
  future edits don't have to chase four divergent copies.

---------

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>

Author: kingpanther13

homeassistant-addon-dev/DOCS.md

@@ -16,7 +16,7 @@ The dev add-on uses the same configuration as the stable version. See the main a
 | `secret_path` | Custom secret path (optional) | auto-generated |
 | `enable_skills` | Serve bundled HA best-practice skills as MCP resources | `true` |
 | `enable_skills_as_tools` | Expose skills via list_resources/read_resource tools | `true` |
-| `enable_tool_search` | Replace full tool catalog with search-based discovery (~46K → ~5K tokens) | `false` |
+| `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_yaml_config_editing` *(beta)* | Enables `ha_config_set_yaml` for editing `configuration.yaml` directly. Requires `ha_mcp_tools` custom component. | `false` |
 | `enable_filesystem_tools` *(beta)* | Enables file read/write tools (`ha_list_files`, `ha_read_file`, `ha_write_file`, `ha_delete_file`). Requires `ha_mcp_tools` custom component. | `false` |
 | `enable_custom_component_integration` *(beta)* | Enables `ha_install_mcp_tools` installer tool for the `ha_mcp_tools` custom component. | `false` |

homeassistant-addon-dev/translations/en.yaml

@@ -22,10 +22,15 @@ configuration:
     name: Enable tool search
     description: >-
       Replace the full tool catalog with search-based discovery. Reduces
-      idle context from ~46K to ~5K tokens. Use this if using an LLM without
-      deferred tools 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.
+      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.
   enable_yaml_config_editing:
     name: Enable YAML config editing (beta)
     description: >-

homeassistant-addon/DOCS.md

@@ -248,14 +248,17 @@ Requires add-on restart to take effect.
 
 Replaces the full tool catalog (~86 tools, ~46K tokens) with search-based discovery (~4 proxy tools, ~5K tokens). When enabled, tools are found via `ha_search_tools` and executed through categorized proxies (read/write/delete).
 
+> ⚠️ **Do NOT enable this if you use Claude in Sonnet or Opus modes.** Those models run their own built-in tool search / deferred tools, which conflicts with ha-mcp's — running both at once does not work. To use ha-mcp's tool search with Claude, disable Claude's built-in tool search first; otherwise leave this off.
+
 **When to enable:**
 - Models **without native deferred tool support** — this includes OpenAI-compatible local models, and also **Claude Haiku** which does not use Claude's built-in deferred tool loading. Haiku users will see significant token savings with this enabled.
 - Models with **limited context windows** (≤200K) or deployments where context cost is a concern
 - MCP clients that **cap total tools** (e.g. at 100) — reduces visible tool count to ~4
 
 **When to leave disabled (default):**
-- Claude Sonnet/Opus or other clients with deferred tool support — tools are loaded on demand, so the full catalog has no idle context cost
-- When you need direct tool access without the search step
+- **Claude in Sonnet or Opus modes** — their built-in tool search conflicts with ha-mcp's. Disable one or the other.
+- Other clients with native deferred tool support — tools are loaded on demand, so the full catalog has no idle context cost.
+- When you need direct tool access without the search step.
 
 Requires add-on restart to take effect.
 

homeassistant-addon/translations/en.yaml

@@ -22,10 +22,15 @@ configuration:
     name: Enable tool search
     description: >-
       Replace the full tool catalog with search-based discovery. Reduces
-      idle context from ~46K to ~5K tokens. Use this if using an LLM without
-      deferred tools 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.
+      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.
   verify_ssl:
     name: Verify TLS certificate
     description: >-