docs(session-search): document source-first retrieval limits

tests/tools/test_session_search.py

@@ -98,6 +98,14 @@ def test_no_llm_promise_in_description(self):
         desc = SESSION_SEARCH_SCHEMA["description"].lower()
         assert "no llm" in desc
 
+    def test_schema_description_enforces_source_first_limit(self):
+        desc = SESSION_SEARCH_SCHEMA["description"].lower()
+        assert "source-first limit" in desc
+        assert "conversation history only" in desc
+        assert "direct source" in desc
+        assert "session_search as secondary" in desc
+        assert "not found" in desc
+
 
 class TestHiddenSources:
     def test_tool_source_hidden(self):

tools/session_search_tool.py

@@ -631,6 +631,17 @@ def check_session_search_requirements() -> bool:
         "Search past sessions stored in the local session DB, or scroll inside one. "
         "FTS5-backed retrieval over the SQLite message store. No LLM calls — every "
         "shape returns actual messages from the DB.\n\n"
+        "SOURCE-FIRST LIMIT\n\n"
+        "  This tool searches Hermes conversation history only. It is not evidence "
+        "about the current contents of external sources. If the user provided a "
+        "direct source such as a URL, phone number/contact, app/thread, file path, "
+        "account, website, or live system, inspect that original source before or "
+        "instead of session_search when accessible. Use session_search as secondary "
+        "context for what was previously said, not as primary proof of what the "
+        "source currently contains. If the original source is inaccessible, say so "
+        "and why before falling back to session history. Do not conclude 'not found' "
+        "or 'no prior correspondence' from session_search alone when a direct source "
+        "was provided.\n\n"
         "FOUR CALLING SHAPES\n\n"
         "  1) DISCOVERY — pass `query`:\n"
         "     session_search(query=\"auth refactor\", limit=3)\n"
@@ -673,10 +684,12 @@ def check_session_search_requirements() -> bool:
         "(`\"docker networking\"`), boolean (`python NOT java`), or prefix wildcards "
         "(`deploy*`).\n\n"
         "WHEN TO USE\n\n"
-        "  Reach for this on any \"what did we do about X\" / \"where did we leave Y\" / "
-        "\"find the session where Z\" question — before gh, web search, or filesystem "
-        "inspection. The session DB carries what was said when; external tools show "
-        "current world state."
+        "  Reach for this on questions about Hermes conversation history itself, such "
+        "as \"what did we do about X\", \"where did we leave Y\", or \"find the "
+        "session where Z\". If the user provided a direct source identifier, inspect "
+        "that source first when accessible; session_search can then supply historical "
+        "context. The session DB carries what was said when; external tools show "
+        "current source/world state."
     ),
     "parameters": {
         "type": "object",