refine find page-full hints and cap tie-break order

Over-fetch one row in find_v2 so page-full hints skip the last page;
cap same-priority hints by emission order; add symbol fqn_prefix resolve test.

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

Author: HumanBean17

README.md

@@ -261,7 +261,7 @@ Example:
 {"kind":"symbol","filter":{"microservice":"chat-core","symbol_kind":"interface"}}
 ```
 
-**MCP v2 response extras (`hints`, pagination echo):** On success, `search`, `find`, `describe`, and `neighbors` return a `hints` field (`list[str]`, capped at five unique strings) with short, templated suggestions for likely next tool calls; hints are advisory. `hints` is always empty when `success` is false. `search` and `find` additionally echo the request’s `limit` and `offset` on success; on failure those echoed fields are omitted (`null` in JSON). `neighbors` echoes `requested_edge_types` (deduped edge labels from the request) on success for empty-result hints and diagnostics. See [`propose/HINTS-ROAD-SIGNS-PROPOSE.md`](./propose/HINTS-ROAD-SIGNS-PROPOSE.md) Appendix A for the locked v1 template catalog.
+**MCP v2 response extras (`hints`, pagination echo):** On success, `search`, `find`, `describe`, and `neighbors` return a `hints` field (`list[str]`, capped at five unique strings) with short, templated suggestions for likely next tool calls; hints are advisory. `hints` is always empty when `success` is false. `search` and `find` additionally echo the request’s `limit` and `offset` on success; on failure those echoed fields are omitted (`null` in JSON). The find page-full hint fires only when another page may exist (handler over-fetches by one row; not exposed on the output model). `neighbors` echoes `requested_edge_types` (deduped edge labels from the request) on success for empty-result hints and diagnostics. See [`propose/HINTS-ROAD-SIGNS-PROPOSE.md`](./propose/HINTS-ROAD-SIGNS-PROPOSE.md) Appendix A for the locked v1 template catalog.
 
 ---
 

mcp_hints.py

@@ -93,15 +93,20 @@ def _find_has_identifier_shaped_filter(kind: str, flt: dict[str, Any]) -> bool:
 
 
 def finalize_hint_list(scored: list[tuple[int, str]]) -> list[str]:
-    """Dedupe identical rendered strings keeping the highest priority; cap to 5 (drop lowest)."""
-    best_pri: dict[str, int] = {}
-    for pri, text in scored:
+    """Dedupe identical rendered strings keeping the highest priority; cap to 5 (drop lowest).
+
+    Within the same priority tier, keep hints in emission order (first scored wins the cap).
+    """
+    best: dict[str, tuple[int, int]] = {}
+    for idx, (pri, text) in enumerate(scored):
         if not text:
             continue
-        prev = best_pri.get(text)
-        if prev is None or pri > prev:
-            best_pri[text] = pri
-    ordered = sorted(best_pri.items(), key=lambda kv: (-kv[1], kv[0]))
+        prev = best.get(text)
+        if prev is None or pri > prev[0]:
+            best[text] = (pri, idx)
+        elif pri == prev[0]:
+            best[text] = (pri, min(prev[1], idx))
+    ordered = sorted(best.items(), key=lambda kv: (-kv[1][0], kv[1][1]))
     return [text for text, _pri in ordered[:5]]
 
 
@@ -137,7 +142,11 @@ 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):
+        if (
+            lim is not None
+            and len(results) >= int(lim)
+            and payload.get("has_more_results") is True
+        ):
             pairs.append((PRIORITY_META, TPL_FIND_PAGE_FULL.format(limit=int(lim))))
         return finalize_hint_list(pairs)
 

mcp_v2.py

@@ -756,36 +756,36 @@ def find_v2(
         if err := _validate_no_wildcards(nf):
             _log_fail_loud("wildcard")
             return FindOutput(success=False, message=err, hints=[], limit=None, offset=None)
+        fetch_cap = int(limit) + int(offset) + 1
         if kind == "symbol":
             where, params = _symbol_where_from_filter(nf)
-            params["lim"] = int(limit) + int(offset)
+            params["lim"] = fetch_cap
             rows = g._rows(  # noqa: SLF001
                 f"MATCH (s:Symbol) {where} RETURN s.id AS id, s.fqn AS fqn, s.microservice AS microservice, "
                 "s.module AS module, s.role AS role, s.kind AS symbol_kind ORDER BY s.fqn LIMIT $lim",
                 params,
             )
-            rows = rows[offset : offset + limit]
         elif kind == "route":
             rows = g.list_routes(
                 microservice=nf.microservice,
                 framework=nf.framework,
                 path_prefix=nf.path_prefix,
                 method=nf.http_method,
-                limit=max(500, limit + offset),
+                limit=max(500, fetch_cap),
             )
             rows = [r for r in rows if _node_matches_filter("route", r, nf)]
-            rows = rows[offset : offset + limit]
         else:
             rows = g.list_clients(
                 microservice=nf.microservice,
                 client_kind=nf.client_kind,
                 target_service=nf.target_service,
                 path_prefix=nf.target_path_prefix,
                 method=nf.http_method,
-                limit=max(500, limit + offset),
+                limit=max(500, fetch_cap),
             )
             rows = [r for r in rows if _node_matches_filter("client", r, nf)]
-            rows = rows[offset : offset + limit]
+        has_more_results = len(rows) > int(offset) + int(limit)
+        rows = rows[offset : offset + limit]
         refs = [_node_ref_from_row(kind, r) for r in rows]
         filter_dump = nf.model_dump(exclude_none=True)
         hint_payload: dict[str, Any] = {
@@ -795,6 +795,7 @@ def find_v2(
             "limit": limit,
             "offset": offset,
             "filter": filter_dump,
+            "has_more_results": has_more_results,
         }
         return FindOutput(
             success=True,

tests/test_mcp_hints.py

@@ -203,13 +203,34 @@ def test_hints_find_empty_identifier_filter_suggests_resolve(kuzu_graph) -> None
     assert any("resolve(identifier" in h and "hint_kind='client'" in h for h in out.hints)
 
 
+def test_hints_find_empty_symbol_fqn_prefix_suggests_resolve(kuzu_graph) -> None:
+    out = find_v2("symbol", {"fqn_prefix": "__no_such_prefix__"}, graph=kuzu_graph)
+    assert out.success is True
+    assert out.results == []
+    assert any("resolve(identifier" in h and "hint_kind='symbol'" in h for h in out.hints)
+
+
 def test_hints_find_page_full_emits_narrow_or_paginate(kuzu_graph) -> None:
     out = find_v2("symbol", {"role": "CONTROLLER"}, graph=kuzu_graph, limit=1, offset=0)
     assert out.success is True
     assert len(out.results) >= 1
     assert mcp_hints.TPL_FIND_PAGE_FULL.format(limit=1) in out.hints
 
 
+def test_hints_find_page_full_skips_when_last_page(kuzu_graph) -> None:
+    full = find_v2("symbol", {"role": "CONTROLLER"}, graph=kuzu_graph, limit=500, offset=0)
+    assert full.success and full.results
+    last = find_v2(
+        "symbol",
+        {"role": "CONTROLLER"},
+        graph=kuzu_graph,
+        limit=1,
+        offset=len(full.results) - 1,
+    )
+    assert last.success and len(last.results) == 1
+    assert mcp_hints.TPL_FIND_PAGE_FULL.format(limit=1) not in last.hints
+
+
 def test_hints_neighbors_empty_with_edge_types_emits_kind_check(kuzu_graph) -> None:
     class_id = _class_symbol_id(kuzu_graph)
     out = neighbors_v2(class_id, direction="out", edge_types=["DECLARES_CLIENT"], graph=kuzu_graph)
@@ -313,6 +334,36 @@ def test_hints_cap_drops_lowest_priority_over_five() -> None:
     assert "d1" in got and "o1" in got
 
 
+def test_hints_cap_same_priority_keeps_emission_order() -> None:
+    scored = [
+        (PRIORITY_META, "z-meta"),
+        (PRIORITY_META, "a-meta"),
+        (PRIORITY_META, "b-meta"),
+        (PRIORITY_META, "c-meta"),
+        (PRIORITY_META, "d-meta"),
+        (PRIORITY_META, "e-meta"),
+    ]
+    got = finalize_hint_list(scored)
+    assert len(got) == 5
+    assert "z-meta" in got
+    assert "e-meta" not in got
+
+
+def test_hints_find_page_full_requires_has_more_results_flag() -> None:
+    full_page = {
+        "success": True,
+        "kind": "symbol",
+        "results": [{"id": "sym:a"}],
+        "limit": 1,
+        "offset": 0,
+        "filter": {},
+    }
+    assert mcp_hints.TPL_FIND_PAGE_FULL.format(limit=1) not in generate_hints("find", full_page)
+    assert mcp_hints.TPL_FIND_PAGE_FULL.format(limit=1) in generate_hints(
+        "find", {**full_page, "has_more_results": True}
+    )
+
+
 def test_hints_kind_gate_method_payload_ignores_type_only_rollups() -> None:
     node_id = "sym:com.example.T#m()"
     rec = {