docs(skill): surface site:/operator search limitations instead of silently reformulating

[juniperbevensee]

Bug

[matilde-search-snippets] — Matilde site: queries don't return snippets, and Matilde silently reformulates the query when the backend returns no snippets, rather than surfacing the limitation. For a citations tool, silent degradation is the real bug: a clean-looking answer is built on a query the agent quietly changed.

Finding

Matilde owns no web-search code of its own — it delegates web search to the Hermes runtime's tools and only talks to structured scholarly APIs (Crossref, OpenAlex, DataCite). The "silent reformulation" is emergent LLM behavior: when a site:/operator query returns empty or snippet-less results, the agent drops the operator and re-queries without telling the user, and nothing in its skill instructions forbids it. So the self-contained fix is at the skill/prompt level, not in any search code.

Fix

hermes-skill/SKILL.md gains a Web-search honesty rule, integrated into the file's existing structure and voice:

• Phase 2 (Gather): when an operator query (site:, filetype:, exact-phrase, …) returns no results or no usable snippets, report it explicitly (e.g. "could not retrieve snippets for site:X — the search backend may not support that operator"), and treat any broaden/reformulate as a visible, stated step — never a silent swap.
• Quality and Ethics Floor: a "Never hide a search limitation" bullet tying it to Matilde's existing honesty principle (unknown is a valid answer).

Why it fits

Matilde's whole ethos is "never hide a limitation" — never fabricate, never inflate a verifiability score, never hide a retraction. A silently reformulated query is exactly that class of hidden limitation. This makes the rule explicit so the agent treats a snippet-less operator query as a finding to surface, not a problem to paper over.

Note

The filed bug attributed this to Matilde's search code, but Matilde delegates web search to the runtime; an optional secondary hardening is to annotate empty-snippet / operator-ignored results in hermes-agent-mt's tools/web_tools.py:784 web_search_tool — tracked separately.

Autonomous gardener PR — propose-only for review.

🤖 Generated with Claude Code