Add retry hint on empty search results; warn on unrecognized shape

Author: richardbenedikt

CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.0] - 2026-04-26
+### Added
+- `web_search` now returns a retry hint on empty results, instructing the model to broaden/simplify the query before declining to answer. Closes the failure mode where the model interpreted "0 results" as "I cannot search" and gave up.
+- Diagnostic warning event when the search backend returns an unrecognized response shape (previously silently coerced to `[]`).
+### Changed
+- `web_search` docstring strengthened with explicit guidance on retrying after empty results.
+
+## [2.1.0] - 2026-04-26
+### Added
+- Per-URL citation events for every page that gets fetched (both via auto-fetch and explicit `fetch_url`). Open WebUI now displays each fetched page as its own clickable source in the chat instead of a single generic `websearch/web_search` entry.
+
 ## [2.0.0] - 2026-04-26
 ### Added
 - `auto_fetch_enabled` valve (default `true`). Dedicated master switch for the post-search auto-fetch step; when `false`, `web_search` returns snippets only but the model can still call `fetch_url` itself.

README.md

@@ -14,6 +14,7 @@ A small [Open WebUI](https://github.com/open-webui/open-webui) tool that lets th
 - **Domain allow/block lists** applied to both search results and `fetch_url` targets.
 - **Auto-fetches every result page by default** in parallel after every search, so answers are based on real page bodies rather than short snippets — even if the model wouldn't have called `fetch_url` itself. Configurable to a top-N cap.
 - **Status events** for visible progress in the chat UI.
+- **Per-URL citations** — every fetched page is emitted as its own clickable source in the chat, not a single generic tool entry.
 - **Single-file deployment** — copy `websearch.py` into Workspace → Tools.
 
 ## Requirements
@@ -67,7 +68,7 @@ Both methods return a JSON-encoded string with a stable shape:
 {"error": "human-readable reason"}
 ```
 
-`content` is present on every returned result by default (`auto_fetch_top=0`) when both `enable_fetch_url` and `auto_fetch_enabled` are on; set a positive `N` to cap pre-fetching to the top `N`, or set `auto_fetch_enabled=false` to skip pre-fetching entirely while keeping `fetch_url` available to the model. On a fetch failure the entry gets `"fetch_error": "..."` instead. The `hint` is omitted when there are no results or when `enable_fetch_url` is off.
+`content` is present on every returned result by default (`auto_fetch_top=0`) when both `enable_fetch_url` and `auto_fetch_enabled` are on; set a positive `N` to cap pre-fetching to the top `N`, or set `auto_fetch_enabled=false` to skip pre-fetching entirely while keeping `fetch_url` available to the model. On a fetch failure the entry gets `"fetch_error": "..."` instead. The `hint` is always present on empty results (instructs the model to retry with a broader query) and on results when `enable_fetch_url` is on; it is omitted only on results when `enable_fetch_url` is off.
 
 ## Development
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "openwebui-tool-websearch"
-version = "2.0.0"
+version = "2.2.0"
 description = "OpenWebUI tool that exposes web_search and fetch_url to the model, reusing OpenWebUI's configured search backend."
 readme = "README.md"
 requires-python = ">=3.11"

tests/test_normalize.py

@@ -2,7 +2,7 @@
 
 import json
 
-from websearch import _normalize
+from websearch import _looks_empty, _normalize
 
 
 def test_normalize_json_string_list() -> None:
@@ -40,3 +40,24 @@ def test_normalize_none_returns_empty() -> None:
 
 def test_normalize_drops_non_dict_entries() -> None:
     assert _normalize(["string", 42, {"title": "T"}]) == [{"title": "T", "link": "", "snippet": ""}]
+
+
+def test_looks_empty_recognizes_known_empty_shapes() -> None:
+    assert _looks_empty(None)
+    assert _looks_empty("")
+    assert _looks_empty("   ")
+    assert _looks_empty([])
+    assert _looks_empty({})
+    assert _looks_empty({"results": []})
+    assert _looks_empty("[]")
+    assert _looks_empty("{}")
+    assert _looks_empty('{"results": []}')
+
+
+def test_looks_empty_flags_unrecognized_or_non_empty_shapes() -> None:
+    assert not _looks_empty({"data": [{"title": "x"}]})
+    assert not _looks_empty({"web": {"results": []}})
+    assert not _looks_empty('{"data":[{"title":"x"}]}')
+    assert not _looks_empty([{"title": "x"}])
+    assert not _looks_empty("not json")
+    assert not _looks_empty(42)

tests/test_tool.py

@@ -37,16 +37,33 @@ async def test_web_search_returns_json_results(patch_builtins, fake_request, fak
     assert "fetch_url" in payload["hint"]
     assert search_calls and search_calls[0]["query"] == "openwebui"
     assert search_calls[0]["count"] == tool.valves.result_count
-    assert any(e["data"]["done"] for e in emitted)
+    assert any(e["data"].get("done") for e in emitted if e.get("type") == "status")
 
 
-async def test_web_search_omits_hint_when_no_results(patch_builtins, fake_request, fake_user) -> None:
+async def test_web_search_warns_on_unrecognized_response_shape(
+    patch_builtins, fake_request, fake_user, emitter, emitted
+) -> None:
+    patch_builtins(search_result={"data": [{"title": "x", "link": "https://x/1"}]})
+    tool = _make_tool()
+    out = await tool.web_search("q", __request__=fake_request, __user__=fake_user, __event_emitter__=emitter)
+    payload = json.loads(out)
+    assert payload["results"] == []
+    statuses = [e for e in emitted if e.get("type") == "status"]
+    assert any(
+        e["data"].get("status") == "warning" and "unrecognized" in e["data"].get("description", "").lower()
+        for e in statuses
+    )
+
+
+async def test_web_search_emits_retry_hint_when_no_results(patch_builtins, fake_request, fake_user) -> None:
     patch_builtins(search_result=[])
     tool = _make_tool()
     out = await tool.web_search("q", __request__=fake_request, __user__=fake_user)
     payload = json.loads(out)
     assert payload["results"] == []
-    assert "hint" not in payload
+    hint = payload["hint"].lower()
+    assert "broader" in hint or "shorter" in hint
+    assert "web_search" in hint
 
 
 async def test_web_search_omits_hint_when_fetch_url_disabled(patch_builtins, fake_request, fake_user) -> None:
@@ -131,6 +148,55 @@ async def test_web_search_auto_fetch_top_inactive_when_fetch_url_disabled(
     assert "hint" not in payload
 
 
+async def test_web_search_auto_fetch_emits_citation_per_page(
+    patch_builtins, fake_request, fake_user, emitter, emitted
+) -> None:
+    patch_builtins(
+        search_result=[
+            {"title": "T1", "link": "https://a.test/1", "snippet": "s1"},
+            {"title": "T2", "link": "https://b.test/2", "snippet": "s2"},
+        ],
+        fetch_result="body",
+    )
+    tool = _make_tool()
+    await tool.web_search("q", __request__=fake_request, __user__=fake_user, __event_emitter__=emitter)
+    citations = [e for e in emitted if e.get("type") == "citation"]
+    assert len(citations) == 2
+    urls = {c["data"]["source"]["url"] for c in citations}
+    assert urls == {"https://a.test/1", "https://b.test/2"}
+    assert all(c["data"]["document"] == ["body"] for c in citations)
+    names = {c["data"]["source"]["name"] for c in citations}
+    assert names == {"T1", "T2"}
+
+
+async def test_web_search_auto_fetch_skips_citation_on_empty_body(
+    patch_builtins, fake_request, fake_user, emitter, emitted
+) -> None:
+    patch_builtins(
+        search_result=[{"title": "T", "link": "https://a.test/1", "snippet": "s"}],
+        fetch_result="",
+    )
+    tool = _make_tool()
+    await tool.web_search("q", __request__=fake_request, __user__=fake_user, __event_emitter__=emitter)
+    citations = [e for e in emitted if e.get("type") == "citation"]
+    assert citations == []
+
+
+async def test_fetch_url_emits_citation(patch_builtins, fake_request, fake_user, emitter, emitted) -> None:
+    patch_builtins(fetch_result="hello")
+    tool = _make_tool()
+    await tool.fetch_url(
+        "https://example.com/x",
+        __request__=fake_request,
+        __user__=fake_user,
+        __event_emitter__=emitter,
+    )
+    citations = [e for e in emitted if e.get("type") == "citation"]
+    assert len(citations) == 1
+    assert citations[0]["data"]["source"]["url"] == "https://example.com/x"
+    assert citations[0]["data"]["document"] == ["hello"]
+
+
 async def test_web_search_auto_fetch_records_errors(patch_builtins, fake_request, fake_user) -> None:
     patch_builtins(
         search_result=[{"title": "A", "link": "https://a.test/1", "snippet": "sa"}],

websearch.py

@@ -6,7 +6,7 @@
 description: Search the web and fetch pages on demand, via OpenWebUI's configured backend.
 required_open_webui_version: 0.6.0
 requirements: pydantic>=2
-version: 2.0.0
+version: 2.2.0
 license: MIT
 """
 
@@ -81,6 +81,32 @@ def _filter_results(results: list[dict[str, Any]], allow: list[str], block: list
     return filtered
 
 
+def _looks_empty(raw: Any) -> bool:
+    """True if `raw` plausibly represents an empty result set in a recognized shape.
+
+    Used to distinguish a backend that genuinely returned nothing from one whose
+    response shape we failed to parse — the latter deserves a diagnostic warning,
+    the former does not.
+    """
+    if raw is None:
+        return True
+    if isinstance(raw, str):
+        if not raw.strip():
+            return True
+        try:
+            return _looks_empty(json.loads(raw))
+        except json.JSONDecodeError:
+            return False
+    if isinstance(raw, list):
+        return len(raw) == 0
+    if isinstance(raw, dict):
+        if not raw:
+            return True
+        results = raw.get("results")
+        return isinstance(results, list) and len(results) == 0
+    return False
+
+
 def _normalize(raw: Any) -> list[dict[str, Any]]:
     if raw is None:
         return []
@@ -123,6 +149,21 @@ async def _emit(emitter: EmitFn | None, description: str, *, done: bool = False,
     )
 
 
+async def _emit_citation(emitter: EmitFn | None, *, url: str, title: str, content: str) -> None:
+    if emitter is None or not content:
+        return
+    await emitter(
+        {
+            "type": "citation",
+            "data": {
+                "document": [content],
+                "metadata": [{"source": url}],
+                "source": {"name": title or url, "url": url},
+            },
+        }
+    )
+
+
 def _error(message: str) -> str:
     return json.dumps({"error": message})
 
@@ -190,12 +231,15 @@ async def web_search(
         Search the web when the user's question requires current, recent,
         or post-training-cutoff information, or specific facts you do not
         reliably know. Call multiple times with refined queries if the first
-        results are insufficient. After results come back, call fetch_url
-        on one or more of the most relevant links to read the full page
-        before answering — snippets are short and frequently misleading,
-        especially for lists, comparisons, dates, prices, or specifications.
-        Do not call for general knowledge, math, or topics fully covered
-        by your training data.
+        results are insufficient. If a call returns no results, retry with a
+        broader query (drop the year, drop adjectives, keep 2-4 core terms)
+        before declining to answer — search engines frequently miss long,
+        over-specified phrases. After results come back, call fetch_url on
+        one or more of the most relevant links to read the full page before
+        answering — snippets are short and frequently misleading, especially
+        for lists, comparisons, dates, prices, or specifications. Do not
+        call for general knowledge, math, or topics fully covered by your
+        training data.
 
         :param query: A focused search query in natural language.
         :param count: Optional override for number of results (1-20). 0 uses the configured default.
@@ -232,6 +276,12 @@ async def web_search(
             return _error(message)
 
         results = _normalize(raw)
+        if not results and not _looks_empty(raw):
+            await _emit(
+                __event_emitter__,
+                "Search backend returned an unrecognized response shape; treating as empty.",
+                status="warning",
+            )
         results = _filter_results(
             results,
             allow=_split_csv(self.valves.allow_domains),
@@ -253,7 +303,14 @@ async def web_search(
             status="success" if results else "warning",
         )
         payload: dict[str, Any] = {"results": results}
-        if results and self.valves.enable_fetch_url:
+        if not results:
+            payload["hint"] = (
+                "No results returned. The search engine often misses long, "
+                "over-specified queries. Call web_search again with a shorter, "
+                "broader query — drop the year, drop adjectives, keep 2-4 core "
+                "terms — before telling the user you don't know."
+            )
+        elif self.valves.enable_fetch_url:
             if fetched_count:
                 payload["hint"] = (
                     f"The top {fetched_count} page(s) have already been fetched and are "
@@ -296,7 +353,9 @@ async def _one(entry: dict[str, Any]) -> None:
                 return
             try:
                 content = await fetch_url(url=link, __request__=__request__, __user__=__user__)
-                entry["content"] = content if isinstance(content, str) else ""
+                text = content if isinstance(content, str) else ""
+                entry["content"] = text
+                await _emit_citation(emitter, url=link, title=str(entry.get("title") or ""), content=text)
             except Exception as exc:
                 entry["fetch_error"] = str(exc)
 
@@ -363,6 +422,7 @@ async def fetch_url(
             return _error(message)
 
         text = content if isinstance(content, str) else ""
+        await _emit_citation(__event_emitter__, url=cleaned_url, title=cleaned_url, content=text)
         await _emit(
             __event_emitter__,
             f"Fetched {len(text)} character(s) from {host}",