docs: add smaller/local-LLM tool-search guidance (#1654)

Open WebUI + Ollama users hit a silent failure (#1651): the client
connects and "tests OK", but the model never calls a tool, so chats answer
from memory with no Home Assistant data. Smaller local models get handed
ha-mcp's full tool catalog at once and don't cope.

- README: add a "Smaller or local LLMs (Ollama, etc.)" subsection in Tool
  Discovery — enable tool search (defers the catalog behind an on-demand
  search interface) and raise the model's context window above the default.
- Setup wizard: add an amber callout to the Open WebUI step pointing
  local-model users to the same two fixes, linking the new section.
- Drop the unverified idle-context token figures from the README Tool
  Discovery section and the add-on DOCS (kept the tool counts).
- Fix the stale tool count in the README prose (86 -> 84, matching the
  badge/DOCS/tools.json) and a trailing-comma typo on the same line.
- Sync uv.lock to pyproject 7.8.1 (left at 7.8.0 after #1650) so the
  lockfile check passes.

Refs #1651

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kingpanther13

README.md

@@ -288,9 +288,16 @@ Skills can still be installed manually for clients that prefer local skill files
 
 ## 🔍 Tool Discovery for AI Agents
 
-By default, the full tool catalog (~86 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 Sonnet, Claude Opus) 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 86 tools eats ~46K tokens of idle context. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
+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.
+
+### Smaller or local LLMs (Ollama, etc.)
+
+If your model can't see the tools or your Home Assistant, it may be getting handed the whole tool catalog at once and struggling with it. It's recommended to try the following to see if it helps:
+
+- **Enable tool search** (`ENABLE_TOOL_SEARCH=true`, or the add-on option below). Instead of listing every tool up front, the server defers the catalog behind a search interface so the model pulls in only the tools it needs, when it needs them.
+- **Raise the model's context window above the default.** Local runtimes ship with small defaults (Ollama's `num_ctx` is one example) that can't hold a large tool set plus the conversation — increase it well beyond the default.
 
 ### Enable search-based discovery
 
@@ -307,14 +314,14 @@ The proxy split lets MCP clients apply different permission policies per categor
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| `ENABLE_TOOL_SEARCH` | `false` | Replace full tool catalog with search-based discovery (~46K → ~5K idle tokens). |
+| `ENABLE_TOOL_SEARCH` | `false` | Replace full tool catalog with search-based discovery (tools deferred behind on-demand search). |
 | `TOOL_SEARCH_MAX_RESULTS` | `5` | Max results returned by `ha_search_tools` (range 2–10). |
 | `PINNED_TOOLS` | empty | Comma-separated tool names to keep always visible. The web settings UI is the primary way to manage this. |
 
 ### When to enable
 
 - **Claude Haiku, OpenAI-compatible local models, Gemini, ChatGPT or any model without native deferred tool support** — large idle-context savings.
-- MCP clients that cap total tool count (some cap at 100) — surfaces a minimal set (~10 tools) instead of 86.
+- 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.

homeassistant-addon/DOCS.md

@@ -285,7 +285,7 @@ Requires add-on restart to take effect.
 
 **Default:** `false`
 
-Replaces the full tool catalog (~84 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).
+Replaces the full tool catalog (~84 tools) with search-based discovery (~4 proxy tools). 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.
 

site/src/pages/setup.astro

@@ -2250,6 +2250,15 @@ Authorization = "Bearer YOUR_TOKEN"</pre>
             <p class="mt-1">For stdio-based servers, use <a href="https://github.com/open-webui/mcpo" class="text-blue-400 hover:underline" target="_blank" rel="noopener">mcpo</a> proxy to bridge stdio to HTTP.</p>
             <p><a href="https://docs.openwebui.com/features/mcp/" class="text-blue-400 hover:underline" target="_blank" rel="noopener">Open WebUI MCP docs →</a></p>
           </div>
+          <div class="bg-amber-900/20 border border-amber-700/50 rounded-lg p-3 mt-4">
+            <p class="text-amber-300 text-sm font-medium">Using a smaller or local LLM (Ollama, etc.)?</p>
+            <p class="text-amber-200/80 text-xs mt-1">If the model can't see the tools or your Home Assistant, it may be getting handed all 80+ tools at once. It's recommended to try the following to see if it helps:</p>
+            <ul class="text-amber-200/80 text-xs mt-1 space-y-1 list-disc list-inside">
+              <li>Enable tool search (add-on option <code class="bg-amber-900/30 px-1 rounded">enable_tool_search</code>, or <code class="bg-amber-900/30 px-1 rounded">ENABLE_TOOL_SEARCH=true</code>): the full catalog is deferred behind a search interface so tools load on demand instead of all at once.</li>
+              <li>Raise your model's context window above the default (in Ollama, <code class="bg-amber-900/30 px-1 rounded">num_ctx</code>) so the tool definitions and your conversation fit.</li>
+            </ul>
+            <p class="text-amber-200/80 text-xs mt-1"><a href="https://github.com/homeassistant-ai/ha-mcp#smaller-or-local-llms-ollama-etc" target="_blank" rel="noopener" class="text-amber-300 hover:underline">Smaller or local LLM setup →</a></p>
+          </div>
         </div>`;
       } else if (state.client.id === 'copilot-cli') {
         if (isStdio) {