**USER PREFERENCE — CRITICAL:** ALL web searches MUST use `mcp_searxng_searxng_web_search`. The built-in `web_search` tool is NOT to be used under any circumstances. This is a hard preference — the user explicitly requires SearXNG MCP for all factual verification and research.
Use `mcp_searxng_searxng_web_search` with these defaults per query type. Never use `web_search`, `web_extract`, or curl — always route through MCP.
## Category Routing
| Query type | `categories` | `time_range` | `min_score` |
-`response_format`: `json` for programmatic, `text` for human reading
- **Global fallback**: `time_range=year`, `min_score=0.2` — apply to any query that doesn't match a specific category above
## Post-search
After search, use `mcp_searxng_web_url_read` on top 1-2 results for full content. Use `section` param to extract specific headings.
## Instance check
Run `mcp_searxng_searxng_instance_info` once per session to confirm engines are healthy. Flag any `unresponsive_engines` in results. Full engine inventory and known-broken engines documented in `references/searxng-instance.md`.
**PITFALL — Default engines may all be broken:** SearXNG uses server-side defaults. If all are broken, every search returns zero results with no error. Diagnose by hitting the SearXNG API directly:
If only Bing works, pass `engines=bing` in every `mcp_searxng_searxng_web_search` call until the server-side defaults are fixed. The MCP tool does NOT specify engines by default — it relies entirely on SearXNG's server-side defaults.
The `mcp_searxng_searxng_web_search` tool accepts an `engines` parameter (comma-separated engine names). This is the primary bias-reduction mechanism — different search engines have different indexes and ranking algorithms. Use it to get genuinely different results:
```bash
# Mainstream Western indexes
engines=bing,google
# Independent crawlers (different indexes, different ranking)
engines=mojeek,wiby
# Privacy-focused
engines=duckduckgo,startpage
```
**Engine health varies.** On the local Docker instance (localhost:8888, 279 engines), commonly broken engines include: brave (rate-limited), qwant (access denied), yahoo (HTTP error), sogou (CAPTCHA), fastbot/fireball (suspended). These show as `unresponsive_engines` in results — SearXNG handles them gracefully. Check `searxng_instance_info` periodically for current health.
-`references/telegram-bot-api-2026.md` — Telegram Bot API features relevant to Hermes integration (overlaps with `telegram-integration/references/bot-api-2026.md` — curator will consolidate)
## Disabling the built-in `web` toolset (SearXNG-only mode)
To force ALL web searches through SearXNG MCP and prevent the agent from ever using the built-in `web_search`/`web_extract` tools, two config changes are required:
**1. Disable the `web` toolset globally:**
```yaml
# ~/.hermes/config.yaml
agent:
disabled_toolsets: ["web"]
```
**2. Remove `web` from platform toolsets (CLI and any other active platforms):**
```yaml
# ~/.hermes/config.yaml
platform_toolsets:
cli:
- browser
- clarify
- code_execution
# ... all others ...
- vision
# web REMOVED from this list
```
**3. Verify SearXNG is the configured backend (already set if you followed the MCP setup):**
With both `disabled_toolsets` and `platform_toolsets` updated, the `web_search` and `web_extract` tools are completely unavailable. The agent must use `mcp_searxng_searxng_web_search` and `mcp_searxng_web_url_read` for all web access.
Full reference config snippet: `references/disable-builtin-web.md`
## Setup / Troubleshooting
### `SEARXNG_URL` — Two Separate Requirements
The built-in `web_search` tool and the MCP SearXNG tools read `SEARXNG_URL` from DIFFERENT sources. Both must be set independently:
**Critical pitfall — `config.yaml``web.searxng_url` does NOT feed the built-in tool:** The built-in `web_search` tool's availability check (`_has_env("SEARXNG_URL")` in `tools/web_tools.py`) calls `get_env_value()` which reads `os.environ` first, then `~/.hermes/.env`. It does NOT read `web.searxng_url` from `config.yaml`. If `SEARXNG_URL` is only in `config.yaml` and not in `.env`, the built-in `web_search` returns empty results with no error — the tool silently falls through to "no provider configured."
**Diagnostic:** `web_search` returning empty `{"data": {"web": []}}` with no error message = `SEARXNG_URL` missing from `.env`. The MCP tools working fine at the same time confirms the instance is healthy — the gap is only in the built-in tool's env source.
**Fix:** Add `SEARXNG_URL=http://localhost:8888` to `~/.hermes/.env` AND all profile `.env` files. The MCP server config in `config.yaml` already passes `SEARXNG_URL` via its `env` block:
But this only covers the MCP subprocess — the main Hermes process still needs it in `.env` for the built-in tool.
**Verification after fix:** Start a new session (`/reset`) — env vars are read at startup. Then `web_search("test")` should return results. The MCP tools should continue working as before.
**Bulk `.env` update:** When adding `SEARXNG_URL` to `.env`, update ALL profile `.env` files (base + all 15 profiles). Use `hermes-config-bulk-update` skill pattern — same 16-location rule applies to `.env` as to `config.yaml`. Check with: `for p in ~/.hermes/profiles/*/; do grep -l SEARXNG_URL "$p/.env" 2>/dev/null || echo "MISSING: $(basename $p)"; done`
- DuckDuckGo and Startpage are working on the local Docker instance (localhost:8888). Brave and Qwant are rate-limited. Check `searxng_instance_info` for current health.
-`time_range` only works with `news` and `general` categories
-`min_score` above 0.5 often returns zero results
-`categories` must be comma-separated, no spaces: `it,science` not `it, science`
-`web_extract` (Hermes built-in) does NOT work with SearXNG backend — it needs firecrawl/tavily/exa. Use `mcp_searxng_web_url_read` instead for URL content extraction. When the built-in `web` toolset is disabled, this is enforced automatically.
## References
-`references/mcp-server-config.md` — full MCP server setup, tool list, verification commands
-`references/searxng-mcp-only-policy.md` — USER PREFERENCE: ALL web searches must use SearXNG MCP, never built-in web_search
