add v4 find success-path hints (F1–F3)

Emit handler/HTTP/async neighbors follow-ups on non-page-full find
results; document v4 dot-key reversal in HINTS-ROAD-SIGNS appendix.
S1 search single-hit describe deferred per plan.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: HumanBean17

mcp_hints.py

@@ -58,6 +58,11 @@
 
 TPL_FIND_EMPTY_RESOLVE = "no matches — try resolve(identifier, hint_kind='{kind}') for canonical lookup"
 TPL_FIND_PAGE_FULL = "result page full at {limit} — narrow filter or paginate"
+TPL_FIND_SUCCESS_HANDLER = "handler: neighbors(['{id}'],'in',['EXPOSES'])"
+TPL_FIND_SUCCESS_HTTP_TARGETS = "HTTP targets: neighbors(['{id}'],'out',['HTTP_CALLS'])"
+TPL_FIND_SUCCESS_ASYNC_TARGETS = "async targets: neighbors(['{id}'],'out',['ASYNC_CALLS'])"
+
+_FIND_SUCCESS_MAX_CHARS = 120
 
 TPL_NEIGHBORS_WRONG_SUBJECT_KIND = (
     "0 results — '{edge}' connects {src_kind} → {dst_kind}; "
@@ -394,6 +399,41 @@ def neighbors_success_hints(payload: dict[str, Any]) -> list[tuple[int, str]]:
     return pairs
 
 
+def _find_is_page_full(payload: dict[str, Any], results: list[dict[str, Any]]) -> bool:
+    lim = payload.get("limit")
+    return (
+        lim is not None
+        and len(results) >= int(lim)
+        and payload.get("has_more_results") is True
+    )
+
+
+def _append_find_success_hint(pairs: list[tuple[int, str]], text: str) -> None:
+    if text and len(text) <= _FIND_SUCCESS_MAX_CHARS:
+        pairs.append((PRIORITY_LEAF_FOLLOWUP, text))
+
+
+def find_success_hints(payload: dict[str, Any]) -> list[tuple[int, str]]:
+    """v4 non-empty find follow-ups (F1–F3); no graph I/O."""
+    if not payload.get("success"):
+        return []
+    results = list(payload.get("results") or [])
+    if not results or _find_is_page_full(payload, results):
+        return []
+    node_id = str(results[0].get("id") or "")
+    if not node_id:
+        return []
+    kind = str(payload.get("kind") or "")
+    pairs: list[tuple[int, str]] = []
+    if kind == "route":
+        _append_find_success_hint(pairs, TPL_FIND_SUCCESS_HANDLER.format(id=node_id))
+    elif kind == "client":
+        _append_find_success_hint(pairs, TPL_FIND_SUCCESS_HTTP_TARGETS.format(id=node_id))
+    elif kind == "producer":
+        _append_find_success_hint(pairs, TPL_FIND_SUCCESS_ASYNC_TARGETS.format(id=node_id))
+    return pairs
+
+
 def _any_fuzzy_strategy(edges: list[dict[str, Any]]) -> bool:
     for e in edges:
         attrs = e.get("attrs") if isinstance(e.get("attrs"), dict) else {}
@@ -503,12 +543,9 @@ def generate_hints(
         lim = payload.get("limit")
         if not results and _find_has_identifier_shaped_filter(kind, flt):
             pairs.append((PRIORITY_META, TPL_FIND_EMPTY_RESOLVE.format(kind=kind)))
-        if (
-            lim is not None
-            and len(results) >= int(lim)
-            and payload.get("has_more_results") is True
-        ):
+        if _find_is_page_full(payload, results) and lim is not None:
             pairs.append((PRIORITY_META, TPL_FIND_PAGE_FULL.format(limit=int(lim))))
+        pairs.extend(find_success_hints(payload))
         return finalize_hint_list(pairs)
 
     if output_kind == "neighbors":

propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md

@@ -280,6 +280,8 @@ File placement (`mcp_hints.py`), function decomposition, integration points in `
 
 **Amendment (2026-05-16, issue #161 / PR #164)** — five describe templates for the producer axis and override-route rollup, symmetric with the client/route rows above: `DECLARES.DECLARES_PRODUCER`, `DECLARES_PRODUCER`, `OVERRIDDEN_BY.DECLARES_PRODUCER`, `OVERRIDDEN_BY.EXPOSES`, and `kind == producer` declaring-method hint. No ontology or re-index change.
 
+**Amendment (v4 success-path, issue #163)** — second partial dot-key emission reversal: non-empty `neighbors` success hints on type Symbol origins may recommend `DECLARES.DECLARES_CLIENT`, `DECLARES.DECLARES_PRODUCER`, and `DECLARES.EXPOSES` (matching describe rollups). v3 empty structural `neighbors` hints still never use dot-keys (`_filter_neighbors_dotkey_hints` applies to the empty branch only). `OVERRIDDEN_BY.*` dot-keys remain describe-only. No ontology or re-index change.
+
 **What stayed unchanged from the first draft**
 
 - §1 frame statement; §2 principles 1–8; §3.1 field shape; §3.2 generation contract; §5 "deliberately does NOT do" table; §8 risks table.

tests/test_mcp_hints.py

@@ -1026,6 +1026,9 @@ def test_hints_neighbors_v2_declares_success_emits_dot_key_clients(kuzu_graph) -
             mcp_hints.TPL_DESCRIBE_TYPE_ROUTES_VIA_MEMBERS,
             {"id": "sym:com.example.bank.chat.Controller"},
         ),
+        (mcp_hints.TPL_FIND_SUCCESS_HANDLER, {"id": "route:svc:GET:/api/v1/chat"}),
+        (mcp_hints.TPL_FIND_SUCCESS_HTTP_TARGETS, {"id": "client:svc:feign:target:GET:/p"}),
+        (mcp_hints.TPL_FIND_SUCCESS_ASYNC_TARGETS, {"id": "producer:svc:kafka:topic:t"}),
     ],
 )
 def test_hints_all_v4_templates_under_120_chars(template: str, substitutions: dict[str, str]) -> None:
@@ -1159,6 +1162,69 @@ def test_hints_cap_same_priority_keeps_emission_order() -> None:
     assert "e-meta" not in got
 
 
+def _find_success_payload(
+    kind: str,
+    node_id: str,
+    *,
+    limit: int | None = None,
+    has_more_results: bool = False,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "success": True,
+        "kind": kind,
+        "results": [{"id": node_id, "kind": kind}],
+        "filter": {},
+        "offset": 0,
+    }
+    if limit is not None:
+        payload["limit"] = limit
+        payload["has_more_results"] = has_more_results
+    return payload
+
+
+def test_hints_find_route_success_emits_handler() -> None:
+    rid = "route:svc:GET:/api/v1/chat"
+    payload = _find_success_payload("route", rid)
+    want = mcp_hints.TPL_FIND_SUCCESS_HANDLER.format(id=rid)
+    assert want in generate_hints("find", payload)
+
+
+def test_hints_find_client_success_emits_http_calls() -> None:
+    cid = "client:svc:feign:target:GET:/p"
+    payload = _find_success_payload("client", cid)
+    want = mcp_hints.TPL_FIND_SUCCESS_HTTP_TARGETS.format(id=cid)
+    assert want in generate_hints("find", payload)
+
+
+def test_hints_find_producer_success_emits_async_calls() -> None:
+    pid = "producer:svc:kafka:topic:t"
+    payload = _find_success_payload("producer", pid)
+    want = mcp_hints.TPL_FIND_SUCCESS_ASYNC_TARGETS.format(id=pid)
+    assert want in generate_hints("find", payload)
+
+
+def test_hints_find_success_suppressed_when_page_full() -> None:
+    rid = "route:svc:GET:/api/v1/chat"
+    payload = _find_success_payload("route", rid, limit=1, has_more_results=True)
+    hints = generate_hints("find", payload)
+    assert mcp_hints.TPL_FIND_PAGE_FULL.format(limit=1) in hints
+    assert mcp_hints.TPL_FIND_SUCCESS_HANDLER.format(id=rid) not in hints
+
+
+def test_hints_find_success_uses_first_result_id_when_multiple() -> None:
+    first = "route:svc:GET:/first"
+    second = "route:svc:GET:/second"
+    payload = _find_success_payload("route", first)
+    payload["results"] = [
+        {"id": first, "kind": "route"},
+        {"id": second, "kind": "route"},
+    ]
+    want = mcp_hints.TPL_FIND_SUCCESS_HANDLER.format(id=first)
+    hints = generate_hints("find", payload)
+    assert want in hints
+    assert mcp_hints.TPL_FIND_SUCCESS_HANDLER.format(id=second) not in hints
+
+
 def test_hints_find_page_full_requires_has_more_results_flag() -> None:
     full_page = {
         "success": True,