diff --git a/docs/AGENT-GUIDE.md b/docs/AGENT-GUIDE.md
index a5770d20..a43c9bca 100644
--- a/docs/AGENT-GUIDE.md
+++ b/docs/AGENT-GUIDE.md
@@ -16,7 +16,7 @@ Copy the block between `<!-- BEGIN` and `<!-- END` into your project's `AGENTS.m
 
 **Ontology: 15** — if results look structurally wrong or empty across tools, the index may be missing, stale, or built with a different `ontology_version`; you cannot re-index via MCP — ask the operator to rebuild.
 
-**Responses:** On success, `search`, `find`, `describe`, `neighbors`, and `resolve` may include a top-level `hints` list (≤5 suggested next calls) and a companion `hints_structured` list of `{tool, args, actionable}` objects — machine-parseable equivalents with ready-to-use parameters (`actionable=true`) or advisory signals (`actionable=false`). For `search`/`find`, echoed `limit`/`offset`. Hints are advisory; ignore them when `success` is false.
+**Responses:** On success, `search`, `find`, `describe`, `neighbors`, and `resolve` may include a top-level `hints_structured` list (≤5 advisory next-step objects). Each element has `{tool, args, actionable, label, reason}` — machine-parseable with ready-to-use parameters (`actionable=true`) or advisory signals (`actionable=false`, with a `reason` explaining why). For `search`/`find`, echoed `limit`/`offset`. Hints are advisory; ignore them when `success` is false.
 
 **Use this MCP when** you need whole-codebase structure: callers/callees, route handlers, HTTP/async seams, clients/producers, or fuzzy entry points for a concept.
 
diff --git a/mcp_hints.py b/mcp_hints.py
index b3266e0b..bf7d2387 100644
--- a/mcp_hints.py
+++ b/mcp_hints.py
@@ -16,29 +16,13 @@
 
 from java_ontology import EDGE_SCHEMA, FUZZY_STRATEGY_SET
 
-# Normative schema description (propose §3.1) — imported by ``mcp_v2`` for Field(description=...).
-MCP_HINTS_FIELD_DESCRIPTION = (
-    "Road-sign hints pointing to likely next calls. Each hint is a short string "
-    "referencing one MCP V2 tool call. Hints are advisory and may be safely ignored. "
-    "Maximum 5 hints per output. Describe-time type rollup hints may recommend "
-    "DECLARES.* and OVERRIDDEN_BY.* dot-keys for neighbors() on matching Symbol origins; "
-    "empty neighbors structural hints never use "
-    "dot-key edge labels. For neighbors with multiple origin ids, empty-result "
-    "structural hints describe the first origin only. On neighbors with "
-    "edge_types=['CALLS'] only, optional edge_filter projects the ordered CALLS stream "
-    "(min_confidence, strategies, callee_declaring_role axes); fail-loud with composed "
-    "dot-keys or additional stored labels. include_unresolved interleaves "
-    "UnresolvedCallSite rows (mutually exclusive with edge_filter). dedup_calls collapses "
-    "identical (origin, callee) CALLS rows."
-)
-
 MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION = (
-    "Machine-parseable next-action objects alongside hints. Each element has "
+    "Machine-parseable next-action objects. Each element has "
     "label (short semantic name, e.g. 'routes via members', 'implementors'), "
-    "tool (MCP tool name), args (ready-to-use parameters), and actionable "
+    "tool (MCP tool name), args (ready-to-use parameters), actionable "
     "(True = direct call with complete args; False = advisory/partial — agent "
-    "fills missing values or uses as guidance). Same trigger logic, priority, "
-    "dedup, and cap as hints. See hints for human-readable versions."
+    "fills missing values or uses as guidance), and reason (human-readable "
+    "advisory text, empty for actionable hints). Maximum 5 per output."
 )
 
 # --- Internal structured hint representation (no mcp_v2 import) ---
@@ -50,6 +34,7 @@ class _StructuredHint(NamedTuple):
     actionable: bool
     priority: int
     label: str = ""
+    reason: str = ""
 
 
 def finalize_structured_hints(scored: list[_StructuredHint]) -> list[_StructuredHint]:
@@ -74,13 +59,13 @@ def finalize_structured_hints(scored: list[_StructuredHint]) -> list[_Structured
     "EXPOSES": "DECLARES.EXPOSES",
 }
 
-_FIRST_NEIGHBORS_CALL_RE = re.compile(
+_FIRST_TRAVERSAL_RE = re.compile(
     r"neighbors\(\[.*?\],'(in|out)',\['([^']+)'\]\)"
 )
 
 
 def _parse_first_traversal(template: str) -> tuple[str, list[str]] | None:
-    m = _FIRST_NEIGHBORS_CALL_RE.search(template)
+    m = _FIRST_TRAVERSAL_RE.search(template)
     if m:
         return m.group(1), [m.group(2)]
     return None
@@ -97,138 +82,8 @@ def _extract_other_ids(results: list[dict[str, Any]]) -> list[str]:
     return ids
 
 
-# --- Appendix A verbatim templates (substitute {id}, {kind}, {limit}) ---
-
-TPL_DESCRIBE_TYPE_CLIENTS_VIA_MEMBERS = (
-    "clients via members: neighbors(['{id}'],'out',['DECLARES.DECLARES_CLIENT'])"
-)
-TPL_DESCRIBE_TYPE_ROUTES_VIA_MEMBERS = (
-    "routes via members: neighbors(['{id}'],'out',['DECLARES.EXPOSES'])"
-)
-TPL_DESCRIBE_TYPE_PRODUCERS_VIA_MEMBERS = (
-    "producers via members: neighbors(['{id}'],'out',['DECLARES.DECLARES_PRODUCER'])"
-)
-TPL_DESCRIBE_METHOD_OVERRIDERS = "overriders: neighbors(['{id}'],'out',['OVERRIDDEN_BY'])"
-TPL_DESCRIBE_METHOD_CLIENTS_IN_OVERRIDERS = (
-    "clients in overriders: neighbors(['{id}'],'out',['OVERRIDDEN_BY.DECLARES_CLIENT'])"
-)
-TPL_DESCRIBE_METHOD_PRODUCERS_IN_OVERRIDERS = (
-    "producers in overriders: neighbors(['{id}'],'out',['OVERRIDDEN_BY.DECLARES_PRODUCER'])"
-)
-TPL_DESCRIBE_METHOD_ROUTES_IN_OVERRIDERS = (
-    "routes in overriders: neighbors(['{id}'],'out',['OVERRIDDEN_BY.EXPOSES'])"
-)
-TPL_DESCRIBE_METHOD_OUTBOUND_CLIENT = "outbound client: neighbors(['{id}'],'out',['DECLARES_CLIENT'])"
-TPL_DESCRIBE_METHOD_OUTBOUND_PRODUCER = "outbound producer: neighbors(['{id}'],'out',['DECLARES_PRODUCER'])"
-TPL_DESCRIBE_METHOD_INBOUND_ROUTE = "inbound route: neighbors(['{id}'],'out',['EXPOSES'])"
-TPL_DESCRIBE_METHOD_MANY_CALLS = "many CALLS — consider filtering by target microservice"
-TPL_DESCRIBE_ROUTE_DECLARING = "declaring method: neighbors(['{id}'],'in',['EXPOSES'])"
-TPL_DESCRIBE_CLIENT_DECLARING = "declaring method: neighbors(['{id}'],'in',['DECLARES_CLIENT'])"
-TPL_DESCRIBE_PRODUCER_DECLARING = "declaring method: neighbors(['{id}'],'in',['DECLARES_PRODUCER'])"
-TPL_DESCRIBE_TYPE_IMPLEMENTORS = "implementors: neighbors(['{id}'],'in',['IMPLEMENTS'])"
-TPL_DESCRIBE_TYPE_IMPLEMENTS = "implements: neighbors(['{id}'],'out',['IMPLEMENTS'])"
-TPL_DESCRIBE_TYPE_DEPENDENCIES = "dependencies: neighbors(['{id}'],'out',['INJECTS'])"
-TPL_DESCRIBE_TYPE_INJECTORS = "injectors: neighbors(['{id}'],'in',['INJECTS'])"
-TPL_DESCRIBE_METHOD_OUTBOUND_CALLS = "outbound calls: neighbors(['{id}'],'out',['CALLS'])"
-TPL_DESCRIBE_METHOD_SUPER_DECL = "super declaration: neighbors(['{id}'],'out',['OVERRIDES'])"
-TPL_DESCRIBE_METHOD_UNRESOLVED = "unresolved: neighbors(['{id}'],'out',['CALLS'],include_unresolved=True)"
-
-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}; "
-    "this is a {subject_kind}. Try: {canonical_traversal}"
-)
-
-TPL_NEIGHBORS_WRONG_DIRECTION = (
-    "0 results — '{edge}' is {src_kind} → {dst_kind}; "
-    "you requested direction='{requested_dir}'. Try direction='{correct_dir}'."
-)
-
-TPL_NEIGHBORS_TYPE_LEVEL_REQUERY = (
-    "0 results — '{edge}' lives on methods, not on {subject_kind}. "
-    "Try: {canonical_traversal}"
-)
-
-TPL_NEIGHBORS_BROWNFIELD_RESOLVED_MAYBE_UNRESOLVED = (
-    "edges on '{edge}' are emitted by the brownfield resolver — "
-    "absence here may mean unresolved (no matching annotation/target), "
-    "not absent from the codebase"
-)
-
-TPL_SEARCH_WEAK = "results look weak — narrow the query or try find(role=…)"
-
-# --- v2: resolve templates (propose/HINTS-V2-PROPOSE.md Appendix A) ---
-
-TPL_RESOLVE_NONE_TRY_SEARCH = (
-    "no match — try search(query='{identifier}') for ranked fuzzy lookup"
-)
-TPL_RESOLVE_NONE_TRY_FIND_ROUTE = (
-    "no match — try find(kind='route', filter={{path_prefix: '{seed}'}})"
-)
-TPL_RESOLVE_NONE_TRY_FIND_CLIENT = (
-    "no match — try find(kind='client', filter={{target_service: '{seed}'}})"
-)
-TPL_RESOLVE_MANY_TIGHTEN = (
-    "{n} candidates — tighten identifier or pick a candidate by id"
-)
-
-_RESOLVE_HINT_MAX_CHARS = 120
 _RESOLVE_WILDCARDS = ("*", "?")
-
-TPL_NEIGHBORS_FUZZY_STRATEGY = (
-    "some edges resolved via brownfield/fallback strategy — check attrs.strategy on each row"
-)
-
-TPL_NEIGHBORS_CALLS_ROLE_FILTER_OTHER_FALLBACK = (
-    "0 CALLS matched callee_declaring_role filter but method has many callees — "
-    "targets may be OTHER (interface/JDK); try "
-    "edge_filter={{exclude_callee_declaring_roles: ['ENTITY','DTO']}} instead of role exact match"
-)
-
-TPL_NEIGHBORS_CALLS_NODEFILTER_ROLE_COLLISION = (
-    "NodeFilter.role filters the neighbor method's role (usually OTHER), not the callee's "
-    "declaring type — use edge_filter={{callee_declaring_role: 'SERVICE'}} (or REPOSITORY) "
-    "for CALLS stereotype projection"
-)
-
 _CALLS_HIGH_FANOUT_THRESHOLD = 10
-
-TPL_NEIGHBORS_CALLS_HIGH_FANOUT = (
-    "{n} CALLS on this method; the noisy axes are callee_declaring_role "
-    "and per-call-site multiplicity. Try edge_filter={{callee_declaring_role: 'SERVICE'}} "
-    "for delegation hops, edge_filter={{exclude_callee_declaring_roles: ['ENTITY','DTO']}} "
-    "to drop accessor noise, edge_filter={{min_confidence: 0.5}} to trim low-confidence rows "
-    "(exclude_external is find_callers-only, not neighbors), or dedup_calls=True to collapse "
-    "identical callees."
-)
-
-TPL_NEIGHBORS_CALLS_HAS_UNRESOLVED = (
-    "{n} CALLS shown; this method also has {k} unresolved call sites "
-    "(see describe(method_id).unresolved_call_sites, or call neighbors with "
-    "include_unresolved=True for a source-ordered interleaved view — note "
-    "include_unresolved is mutually exclusive with edge_filter)."
-)
-
-# v4 neighbors success-path (propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md); N1a/N1b alias describe templates.
-TPL_NEIGHBORS_SUCCESS_HTTP_TARGETS = "HTTP targets: neighbors(client_ids,'out',['HTTP_CALLS'])"
-TPL_NEIGHBORS_SUCCESS_ASYNC_TARGETS = "async targets: neighbors(producer_ids,'out',['ASYNC_CALLS'])"
-TPL_NEIGHBORS_SUCCESS_CALLERS = "callers: neighbors(handler_ids,'in',['CALLS'])"
-TPL_NEIGHBORS_SUCCESS_DECLARING_CLIENT = (
-    "declaring method: neighbors(client_ids,'in',['DECLARES_CLIENT'])"
-)
-TPL_NEIGHBORS_SUCCESS_DECLARING_PRODUCER = (
-    "declaring method: neighbors(producer_ids,'in',['DECLARES_PRODUCER'])"
-)
-TPL_NEIGHBORS_SUCCESS_HANDLER = "handler: neighbors(route_ids,'in',['EXPOSES'])"
-
-_NEIGHBORS_SUCCESS_MAX_CHARS = 120
 _EDGE_DECLARES_CLIENT = frozenset({"DECLARES_CLIENT", "DECLARES.DECLARES_CLIENT"})
 _EDGE_DECLARES_PRODUCER = frozenset({"DECLARES_PRODUCER", "DECLARES.DECLARES_PRODUCER"})
 
@@ -278,12 +133,6 @@ def _extract_other_ids(results: list[dict[str, Any]]) -> list[str]:
 _TYPE_SYMBOL_KINDS = frozenset({"class", "interface", "enum", "record", "annotation"})
 _METHOD_SYMBOL_KINDS = frozenset({"method", "constructor"})
 
-_COMPOSED_DOT_KEY_PREFIXES = ("DECLARES.", "OVERRIDDEN_BY.")
-# Row 4 (brownfield absence): only when the subject is a resolver endpoint node, not a
-# structurally valid Symbol query that happens to be empty (DECLARES_CLIENT, EXPOSES, …).
-_BROWNFIELD_ABSENCE_SUBJECT_LABELS = frozenset({"Client", "Producer", "Route"})
-_REQUIRED_TRAVERSAL_ROLE_KEYS = frozenset({"type_subject", "member_subject", "alien_subject"})
-
 _IDENTIFIER_FILTER_FIELDS: dict[str, tuple[str, ...]] = {
     "symbol": ("fqn_prefix",),
     "route": ("path_prefix",),
@@ -350,114 +199,6 @@ def _traversal_role_for_wrong_kind(subject_label: str, subject_record: dict[str,
     return "alien_subject"
 
 
-def typical_traversal_for(
-    edge: str,
-    role_key: str,
-    *,
-    subject_id: str,
-    direction: str,
-) -> str:
-    template = EDGE_SCHEMA[edge].typical_traversals[role_key]
-    return template.format(id=subject_id, direction=direction, edge=edge)
-
-
-def neighbors_empty_hints(
-    *,
-    subject_record: dict[str, Any],
-    requested_edge_types: list[str],
-    requested_direction: Literal["in", "out"],
-) -> list[tuple[int, str]]:
-    """Structural empty-neighbors hints from ``EDGE_SCHEMA`` (at most one row 1–3 per edge)."""
-    pairs: list[tuple[int, str]] = []
-    subject_label = _subject_node_label(subject_record)
-    subject_id = str(subject_record.get("id") or "")
-
-    for edge in requested_edge_types:
-        spec = EDGE_SCHEMA.get(edge)
-        if spec is None:
-            continue
-
-        if subject_label != spec.src and subject_label != spec.dst:
-            role = _traversal_role_for_wrong_kind(subject_label, subject_record)
-            trav = typical_traversal_for(
-                edge, role, subject_id=subject_id, direction=requested_direction,
-            )
-            pairs.append(
-                (
-                    PRIORITY_META,
-                    TPL_NEIGHBORS_WRONG_SUBJECT_KIND.format(
-                        edge=edge,
-                        src_kind=spec.src,
-                        dst_kind=spec.dst,
-                        subject_kind=subject_label,
-                        canonical_traversal=trav,
-                    ),
-                )
-            )
-            continue
-
-        wrong_direction = spec.src != spec.dst and (
-            (requested_direction == "out" and subject_label == spec.dst)
-            or (requested_direction == "in" and subject_label == spec.src)
-        )
-        if wrong_direction:
-            correct_dir = "in" if requested_direction == "out" else "out"
-            pairs.append(
-                (
-                    PRIORITY_META,
-                    TPL_NEIGHBORS_WRONG_DIRECTION.format(
-                        edge=edge,
-                        src_kind=spec.src,
-                        dst_kind=spec.dst,
-                        requested_dir=requested_direction,
-                        correct_dir=correct_dir,
-                    ),
-                )
-            )
-            continue
-
-        if (
-            subject_label == "Symbol"
-            and str(subject_record.get("kind") or "") in _TYPE_SYMBOL_KINDS
-            and spec.member_only
-        ):
-            trav = typical_traversal_for(
-                edge, "type_subject", subject_id=subject_id, direction=requested_direction,
-            )
-            pairs.append(
-                (
-                    PRIORITY_META,
-                    TPL_NEIGHBORS_TYPE_LEVEL_REQUERY.format(
-                        edge=edge,
-                        subject_kind=subject_label,
-                        canonical_traversal=trav,
-                    ),
-                )
-            )
-
-    if subject_label in _BROWNFIELD_ABSENCE_SUBJECT_LABELS:
-        for edge in requested_edge_types:
-            spec = EDGE_SCHEMA.get(edge)
-            if spec is not None and spec.brownfield_resolver_sourced:
-                pairs.append(
-                    (
-                        PRIORITY_META,
-                        TPL_NEIGHBORS_BROWNFIELD_RESOLVED_MAYBE_UNRESOLVED.format(edge=edge),
-                    )
-                )
-                break
-
-    return pairs
-
-
-def _hint_contains_composed_dotkey(hint: str) -> bool:
-    return any(prefix in hint for prefix in _COMPOSED_DOT_KEY_PREFIXES)
-
-
-def _filter_neighbors_dotkey_hints(pairs: list[tuple[int, str]]) -> list[tuple[int, str]]:
-    return [(pri, text) for pri, text in pairs if not _hint_contains_composed_dotkey(text)]
-
-
 def _neighbors_success_subject_is_type(subject_record: dict[str, Any]) -> bool:
     return (
         _subject_node_label(subject_record) == "Symbol"
@@ -488,141 +229,6 @@ def _neighbors_results_homogeneous(
     return True
 
 
-def _append_neighbors_success_hint(pairs: list[tuple[int, str]], text: str) -> None:
-    # v4 neighbors cap only (describe uses the same N1a/N1b templates without this gate).
-    if text and len(text) <= _NEIGHBORS_SUCCESS_MAX_CHARS:
-        pairs.append((PRIORITY_LEAF_FOLLOWUP, text))
-
-
-def neighbors_calls_fanout_hints(payload: dict[str, Any]) -> list[tuple[int, str]]:
-    """High-fanout and unresolved-site nudges for CALLS-on-method neighbors (PR-3)."""
-    pairs: list[tuple[int, str]] = []
-    req_types = payload.get("requested_edge_types")
-    if not isinstance(req_types, list) or req_types != ["CALLS"]:
-        return pairs
-    if payload.get("include_unresolved"):
-        return pairs
-    page_n = len(list(payload.get("results") or []))
-    calls_n = int(payload.get("calls_row_count") or 0) or page_n
-    unresolved = int(payload.get("unresolved_count") or 0)
-    if not payload.get("edge_filter_provided") and calls_n >= _CALLS_HIGH_FANOUT_THRESHOLD:
-        pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_NEIGHBORS_CALLS_HIGH_FANOUT.format(n=calls_n)))
-    if unresolved > 0:
-        pairs.append(
-            (PRIORITY_LEAF_FOLLOWUP, TPL_NEIGHBORS_CALLS_HAS_UNRESOLVED.format(n=page_n, k=unresolved))
-        )
-    return pairs
-
-
-def neighbors_calls_meta_hints(payload: dict[str, Any]) -> list[tuple[int, str]]:
-    """CALLS-specific hints: role-filter OTHER fallback (Decision 20) and NodeFilter.role trap (30)."""
-    pairs: list[tuple[int, str]] = []
-    req_types = payload.get("requested_edge_types")
-    if not isinstance(req_types, list) or req_types != ["CALLS"]:
-        return pairs
-    results = list(payload.get("results") or [])
-    edge_flt = payload.get("edge_filter") if isinstance(payload.get("edge_filter"), dict) else {}
-    node_flt = payload.get("node_filter") if isinstance(payload.get("node_filter"), dict) else {}
-    role_exact = edge_flt.get("callee_declaring_role")
-    if (
-        role_exact in ("SERVICE", "REPOSITORY")
-        and not results
-        and int(payload.get("unfiltered_calls_count") or 0) >= 5
-    ):
-        pairs.append((PRIORITY_META, TPL_NEIGHBORS_CALLS_ROLE_FILTER_OTHER_FALLBACK))
-    node_role = node_flt.get("role")
-    if node_role and results:
-        method_rows = [
-            r
-            for r in results
-            if str(((r.get("other") or {}) if isinstance(r.get("other"), dict) else {}).get("symbol_kind") or "")
-            == "method"
-        ]
-        if method_rows:
-            other_roles = [
-                str(
-                    ((r.get("other") or {}) if isinstance(r.get("other"), dict) else {}).get("role")
-                    or ""
-                )
-                for r in method_rows
-            ]
-            if other_roles and sum(1 for role in other_roles if role == "OTHER") >= max(
-                1, (len(other_roles) * 3) // 4
-            ):
-                pairs.append((PRIORITY_META, TPL_NEIGHBORS_CALLS_NODEFILTER_ROLE_COLLISION))
-    return pairs
-
-
-def neighbors_success_hints(payload: dict[str, Any]) -> list[tuple[int, str]]:
-    """v4 non-empty neighbors follow-ups (N1a–N7); no graph I/O."""
-    if not payload.get("success"):
-        return []
-    results = list(payload.get("results") or [])
-    if not results or int(payload.get("offset") or 0) != 0:
-        return []
-    req_types = payload.get("requested_edge_types")
-    if not isinstance(req_types, list) or len(req_types) != 1:
-        return []
-    edge = str(req_types[0]).strip()
-    if not edge:
-        return []
-    direction = payload.get("requested_direction")
-    if direction not in ("in", "out"):
-        return []
-
-    pairs: list[tuple[int, str]] = []
-    origin_id = str(payload.get("origin_id") or "")
-    if not origin_id:
-        origin_id = str(results[0].get("origin_id") or "")
-    subject_record = payload.get("subject_record")
-    is_type_subject = (
-        isinstance(subject_record, dict) and _neighbors_success_subject_is_type(subject_record)
-    )
-
-    if (
-        edge == "DECLARES"
-        and direction == "out"
-        and is_type_subject
-        and _neighbors_results_homogeneous(results, symbol_kinds=_METHOD_SYMBOL_KINDS)
-    ):
-        if origin_id:
-            _append_neighbors_success_hint(
-                pairs, TPL_DESCRIBE_TYPE_CLIENTS_VIA_MEMBERS.format(id=origin_id),
-            )
-            _append_neighbors_success_hint(
-                pairs, TPL_DESCRIBE_TYPE_ROUTES_VIA_MEMBERS.format(id=origin_id),
-            )
-
-    if edge in _EDGE_DECLARES_CLIENT and direction == "out":
-        if _neighbors_results_homogeneous(results, endpoint_kind="client"):
-            _append_neighbors_success_hint(pairs, TPL_NEIGHBORS_SUCCESS_HTTP_TARGETS)
-
-    if edge in _EDGE_DECLARES_PRODUCER and direction == "out":
-        if _neighbors_results_homogeneous(results, endpoint_kind="producer"):
-            _append_neighbors_success_hint(pairs, TPL_NEIGHBORS_SUCCESS_ASYNC_TARGETS)
-
-    if (
-        edge == "EXPOSES"
-        and direction == "in"
-        and _neighbors_results_homogeneous(results, symbol_kinds=_METHOD_SYMBOL_KINDS)
-    ):
-        _append_neighbors_success_hint(pairs, TPL_NEIGHBORS_SUCCESS_CALLERS)
-
-    if edge == "HTTP_CALLS" and direction == "in":
-        if _neighbors_results_homogeneous(results, endpoint_kind="client"):
-            _append_neighbors_success_hint(pairs, TPL_NEIGHBORS_SUCCESS_DECLARING_CLIENT)
-
-    if edge == "ASYNC_CALLS" and direction == "in":
-        if _neighbors_results_homogeneous(results, endpoint_kind="producer"):
-            _append_neighbors_success_hint(pairs, TPL_NEIGHBORS_SUCCESS_DECLARING_PRODUCER)
-
-    if edge == "DECLARES.EXPOSES" and direction == "out":
-        if _neighbors_results_homogeneous(results, endpoint_kind="route"):
-            _append_neighbors_success_hint(pairs, TPL_NEIGHBORS_SUCCESS_HANDLER)
-
-    return pairs
-
-
 def _find_is_page_full(payload: dict[str, Any], results: list[dict[str, Any]]) -> bool:
     lim = payload.get("limit")
     return (
@@ -632,32 +238,6 @@ def _find_is_page_full(payload: dict[str, Any], results: list[dict[str, Any]]) -
     )
 
 
-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 {}
@@ -679,31 +259,13 @@ def _find_has_identifier_shaped_filter(kind: str, flt: dict[str, Any]) -> bool:
     return False
 
 
-def finalize_hint_list(scored: list[tuple[int, str]]) -> list[str]:
-    """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.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]]
-
-
 def _neighbors_empty_structured_hints(
     *,
     subject_record: dict[str, Any],
     requested_edge_types: list[str],
     requested_direction: Literal["in", "out"],
 ) -> list[_StructuredHint]:
-    """Structured counterparts to ``neighbors_empty_hints`` (Rows 1–3)."""
+    """Structured empty-neighbors hints from ``EDGE_SCHEMA`` (Rows 1–3)."""
     out: list[_StructuredHint] = []
     subject_label = _subject_node_label(subject_record)
     subject_id = str(subject_record.get("id") or "")
@@ -727,6 +289,7 @@ def _neighbors_empty_structured_hints(
                         False,
                         PRIORITY_META,
                         LABEL_WRONG_SUBJECT_KIND,
+                        reason=f"'{edge}' connects {spec.src} → {spec.dst}; this is a {subject_label}",
                     ))
             continue
 
@@ -743,6 +306,7 @@ def _neighbors_empty_structured_hints(
                 False,
                 PRIORITY_META,
                 LABEL_WRONG_DIRECTION,
+                reason=f"'{edge}' is {spec.src} → {spec.dst}; try direction='{correct_dir}'",
             ))
             continue
 
@@ -760,6 +324,7 @@ def _neighbors_empty_structured_hints(
                     False,
                     PRIORITY_META,
                     LABEL_TYPE_LEVEL_REQUERY,
+                    reason=f"'{edge}' lives on methods, not on {subject_label}; try dot-key traversal",
                 ))
             else:
                 template = spec.typical_traversals.get("type_subject", "")
@@ -772,12 +337,13 @@ def _neighbors_empty_structured_hints(
                         False,
                         PRIORITY_META,
                         LABEL_TYPE_LEVEL_REQUERY,
+                        reason=f"'{edge}' lives on methods, not on {subject_label}",
                     ))
     return out
 
 
 def _neighbors_success_structured_hints(payload: dict[str, Any]) -> list[_StructuredHint]:
-    """Structured counterparts to ``neighbors_success_hints`` (N1a–N7)."""
+    """Structured non-empty neighbors follow-ups (N1a–N7)."""
     if not payload.get("success"):
         return []
     results = list(payload.get("results") or [])
@@ -810,24 +376,20 @@ def _neighbors_success_structured_hints(payload: dict[str, Any]) -> list[_Struct
         and _neighbors_results_homogeneous(results, symbol_kinds=_METHOD_SYMBOL_KINDS)
     ):
         if origin_id:
-            n1a = TPL_DESCRIBE_TYPE_CLIENTS_VIA_MEMBERS.format(id=origin_id)
-            n1b = TPL_DESCRIBE_TYPE_ROUTES_VIA_MEMBERS.format(id=origin_id)
-            if len(n1a) <= _NEIGHBORS_SUCCESS_MAX_CHARS:
-                out.append(_StructuredHint(
-                    "neighbors",
-                    {"ids": [origin_id], "direction": "out", "edge_types": ["DECLARES.DECLARES_CLIENT"]},
-                    True,
-                    PRIORITY_LEAF_FOLLOWUP,
-                    LABEL_CLIENTS_VIA_MEMBERS,
-                ))
-            if len(n1b) <= _NEIGHBORS_SUCCESS_MAX_CHARS:
-                out.append(_StructuredHint(
-                    "neighbors",
-                    {"ids": [origin_id], "direction": "out", "edge_types": ["DECLARES.EXPOSES"]},
-                    True,
-                    PRIORITY_LEAF_FOLLOWUP,
-                    LABEL_ROUTES_VIA_MEMBERS,
-                ))
+            out.append(_StructuredHint(
+                "neighbors",
+                {"ids": [origin_id], "direction": "out", "edge_types": ["DECLARES.DECLARES_CLIENT"]},
+                True,
+                PRIORITY_LEAF_FOLLOWUP,
+                LABEL_CLIENTS_VIA_MEMBERS,
+            ))
+            out.append(_StructuredHint(
+                "neighbors",
+                {"ids": [origin_id], "direction": "out", "edge_types": ["DECLARES.EXPOSES"]},
+                True,
+                PRIORITY_LEAF_FOLLOWUP,
+                LABEL_ROUTES_VIA_MEMBERS,
+            ))
 
     # N2: DECLARES_CLIENT / DECLARES.DECLARES_CLIENT out → HTTP_CALLS
     if edge in _EDGE_DECLARES_CLIENT and direction == "out":
@@ -910,8 +472,8 @@ def _neighbors_success_structured_hints(payload: dict[str, Any]) -> list[_Struct
 def generate_hints(
     output_kind: Literal["search", "find", "describe", "neighbors", "resolve"],
     payload: dict[str, Any],
-) -> tuple[list[str], list[_StructuredHint]]:
-    """Return up to 5 road-sign hint strings and structured hints for a success-only MCP v2 payload dict.
+) -> list[_StructuredHint]:
+    """Return up to 5 structured hints for a success-only MCP v2 payload dict.
 
     For ``search`` / ``find`` / ``describe`` / ``neighbors``, callers must pass
     ``success: True``; this function returns ``[]`` when ``success`` is false or
@@ -920,38 +482,35 @@ def generate_hints(
     ``success`` in the payload; an explicit ``success: False`` still suppresses
     hints (defense in depth).
     """
-    pairs: list[tuple[int, str]] = []
     struct_pairs: list[_StructuredHint] = []
 
     if output_kind == "resolve":
         if payload.get("success") is False:
-            return ([], [])
+            return []
         status = str(payload.get("status") or "")
         if status == "one":
-            return ([], [])
+            return []
         if status == "many":
             n = len(payload.get("candidates") or [])
             if n > 1:
-                pairs.append((PRIORITY_META, TPL_RESOLVE_MANY_TIGHTEN.format(n=n)))
                 struct_pairs.append(_StructuredHint(
                     "resolve",
                     {"identifier": str(payload.get("resolved_identifier") or ""), "hint_kind": str(payload.get("hint_kind") or "")},
                     False, PRIORITY_META,
                     LABEL_TIGHTEN_IDENTIFIER,
+                    reason=f"{n} candidates — tighten identifier or pick a candidate by id",
                 ))
-            return (finalize_hint_list(pairs), finalize_structured_hints(struct_pairs))
+            return finalize_structured_hints(struct_pairs)
         if status == "none":
             identifier = payload.get("resolved_identifier")
             hint_kind = payload.get("hint_kind")
             if not isinstance(identifier, str) or not identifier.strip():
-                return (finalize_hint_list(pairs), finalize_structured_hints(struct_pairs))
+                return []
             if any(w in identifier for w in _RESOLVE_WILDCARDS):
-                return (finalize_hint_list(pairs), finalize_structured_hints(struct_pairs))
-            rendered: str | None = None
+                return []
             if hint_kind == "route":
                 seed = payload.get("path_prefix_seed")
                 if isinstance(seed, str) and seed.strip():
-                    rendered = TPL_RESOLVE_NONE_TRY_FIND_ROUTE.format(seed=seed)
                     struct_pairs.append(_StructuredHint(
                         "find", {"kind": "route", "filter": {"path_prefix": seed}}, True, PRIORITY_META,
                         LABEL_TRY_FIND_ROUTE,
@@ -959,24 +518,20 @@ def generate_hints(
             elif hint_kind == "client":
                 seed = payload.get("target_service_seed")
                 if isinstance(seed, str) and seed.strip():
-                    rendered = TPL_RESOLVE_NONE_TRY_FIND_CLIENT.format(seed=seed)
                     struct_pairs.append(_StructuredHint(
                         "find", {"kind": "client", "filter": {"target_service": seed}}, True, PRIORITY_META,
                         LABEL_TRY_FIND_CLIENT,
                     ))
             else:
-                rendered = TPL_RESOLVE_NONE_TRY_SEARCH.format(identifier=identifier)
                 struct_pairs.append(_StructuredHint(
                     "search", {"query": identifier}, True, PRIORITY_META,
                     LABEL_TRY_SEARCH,
                 ))
-            if rendered is not None and len(rendered) <= _RESOLVE_HINT_MAX_CHARS:
-                pairs.append((PRIORITY_META, rendered))
-            return (finalize_hint_list(pairs), finalize_structured_hints(struct_pairs))
-        return ([], [])
+            return finalize_structured_hints(struct_pairs)
+        return []
 
     if not payload.get("success"):
-        return ([], [])
+        return []
 
     if output_kind == "search":
         results: list[dict[str, Any]] = list(payload.get("results") or [])
@@ -986,12 +541,12 @@ def generate_hints(
             mx = max(scores)
             mn = min(scores)
             if mx > 0.0 and (mx - mn) < 0.1 * mx:
-                pairs.append((PRIORITY_META, TPL_SEARCH_WEAK))
                 struct_pairs.append(_StructuredHint(
                     "find", {"kind": "symbol", "filter": {"role": "SERVICE"}}, False, PRIORITY_META,
                     LABEL_WEAK_RESULTS,
+                    reason="results look weak — narrow the query or try find with a role filter",
                 ))
-        return (finalize_hint_list(pairs), finalize_structured_hints(struct_pairs))
+        return finalize_structured_hints(struct_pairs)
 
     if output_kind == "find":
         kind = str(payload.get("kind") or "")
@@ -999,7 +554,6 @@ def generate_hints(
         flt = payload.get("filter") if isinstance(payload.get("filter"), dict) else {}
         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)))
             identifier = ""
             for fname in _IDENTIFIER_FILTER_FIELDS.get(kind, ()):
                 val = flt.get(fname)
@@ -1011,12 +565,11 @@ def generate_hints(
                 LABEL_TRY_RESOLVE,
             ))
         if _find_is_page_full(payload, results) and lim is not None:
-            pairs.append((PRIORITY_META, TPL_FIND_PAGE_FULL.format(limit=int(lim))))
             struct_pairs.append(_StructuredHint(
                 "find", {"kind": kind, "filter": flt, "limit": int(lim)}, False, PRIORITY_META,
                 LABEL_PAGE_FULL,
+                reason=f"result page full at {int(lim)} — narrow filter or paginate",
             ))
-        pairs.extend(find_success_hints(payload))
         if results and not _find_is_page_full(payload, results):
             node_id = str(results[0].get("id") or "")
             if node_id:
@@ -1038,7 +591,7 @@ def generate_hints(
                         True, PRIORITY_LEAF_FOLLOWUP,
                         LABEL_ASYNC_TARGETS,
                     ))
-        return (finalize_hint_list(pairs), finalize_structured_hints(struct_pairs))
+        return finalize_structured_hints(struct_pairs)
 
     if output_kind == "neighbors":
         results = list(payload.get("results") or [])
@@ -1047,9 +600,6 @@ def generate_hints(
             req_types = []
         edge_labels = [str(x).strip() for x in req_types if str(x).strip()]
         offset = int(payload.get("offset") or 0)
-        empty_pairs: list[tuple[int, str]] = []
-        success_pairs: list[tuple[int, str]] = []
-        meta_pairs: list[tuple[int, str]] = []
         struct_empty: list[_StructuredHint] = []
         struct_success: list[_StructuredHint] = []
         struct_meta: list[_StructuredHint] = []
@@ -1061,13 +611,6 @@ def generate_hints(
                 and subject_record
                 and requested_direction in ("in", "out")
             ):
-                empty_pairs.extend(
-                    neighbors_empty_hints(
-                        subject_record=subject_record,
-                        requested_edge_types=edge_labels,
-                        requested_direction=requested_direction,
-                    )
-                )
                 struct_empty.extend(
                     _neighbors_empty_structured_hints(
                         subject_record=subject_record,
@@ -1076,11 +619,9 @@ def generate_hints(
                     )
                 )
         elif results and offset == 0:
-            success_pairs = neighbors_success_hints(payload)
             struct_success = _neighbors_success_structured_hints(payload)
-        meta_pairs.extend(neighbors_calls_meta_hints(payload))
-        meta_pairs.extend(neighbors_calls_fanout_hints(payload))
-        # Structured meta hints for CALLS fanout
+
+        # CALLS meta hints
         if isinstance(req_types, list) and req_types == ["CALLS"]:
             if not payload.get("edge_filter_provided") and not payload.get("include_unresolved"):
                 calls_n = int(payload.get("calls_row_count") or 0) or len(results)
@@ -1092,69 +633,62 @@ def generate_hints(
                             {"ids": [origin_id], "direction": "out", "edge_types": ["CALLS"], "edge_filter": {}},
                             False, PRIORITY_LEAF_FOLLOWUP,
                             LABEL_HIGH_FANOUT,
+                            reason=f"{calls_n} CALLS on this method; try edge_filter to narrow",
                         ))
         if results and _any_fuzzy_strategy(results):
-            meta_pairs.append((PRIORITY_META, TPL_NEIGHBORS_FUZZY_STRATEGY))
-            struct_meta.append(_StructuredHint("neighbors", {}, False, PRIORITY_META, LABEL_FUZZY_STRATEGY))
-        return (
-            finalize_hint_list(
-                _filter_neighbors_dotkey_hints(empty_pairs) + success_pairs + meta_pairs,
-            ),
-            finalize_structured_hints(struct_empty + struct_success + struct_meta),
-        )
+            struct_meta.append(_StructuredHint(
+                "neighbors", {}, False, PRIORITY_META, LABEL_FUZZY_STRATEGY,
+                reason="some edges resolved via brownfield/fallback strategy — check attrs.strategy on each row",
+            ))
+        return finalize_structured_hints(struct_empty + struct_success + struct_meta)
 
     if output_kind == "describe":
         rec = payload.get("record")
         if not isinstance(rec, dict):
-            return ([], [])
+            return []
         node_id = str(rec.get("id") or "")
         if not node_id:
-            return ([], [])
+            return []
         kind = str(rec.get("kind") or "")
         es = rec.get("edge_summary")
         edge_summary = es if isinstance(es, dict) else None
 
         if kind == "route":
-            pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_DESCRIBE_ROUTE_DECLARING.format(id=node_id)))
             struct_pairs.append(_StructuredHint(
                 "neighbors", {"ids": [node_id], "direction": "in", "edge_types": ["EXPOSES"]},
                 True, PRIORITY_LEAF_FOLLOWUP,
                 LABEL_DECLARING_METHOD,
             ))
-            return (finalize_hint_list(pairs), finalize_structured_hints(struct_pairs))
+            return finalize_structured_hints(struct_pairs)
         if kind == "client":
-            pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_DESCRIBE_CLIENT_DECLARING.format(id=node_id)))
             struct_pairs.append(_StructuredHint(
                 "neighbors", {"ids": [node_id], "direction": "in", "edge_types": ["DECLARES_CLIENT"]},
                 True, PRIORITY_LEAF_FOLLOWUP,
                 LABEL_DECLARING_METHOD,
             ))
             if _out_count(edge_summary, "HTTP_CALLS") > 0:
-                pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_FIND_SUCCESS_HTTP_TARGETS.format(id=node_id)))
                 struct_pairs.append(_StructuredHint(
                     "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["HTTP_CALLS"]},
                     True, PRIORITY_LEAF_FOLLOWUP,
                     LABEL_HTTP_TARGETS,
                 ))
-            return (finalize_hint_list(pairs), finalize_structured_hints(struct_pairs))
+            return finalize_structured_hints(struct_pairs)
         if kind == "producer":
-            pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_DESCRIBE_PRODUCER_DECLARING.format(id=node_id)))
             struct_pairs.append(_StructuredHint(
                 "neighbors", {"ids": [node_id], "direction": "in", "edge_types": ["DECLARES_PRODUCER"]},
                 True, PRIORITY_LEAF_FOLLOWUP,
                 LABEL_DECLARING_METHOD,
             ))
             if _out_count(edge_summary, "ASYNC_CALLS") > 0:
-                pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_FIND_SUCCESS_ASYNC_TARGETS.format(id=node_id)))
                 struct_pairs.append(_StructuredHint(
                     "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["ASYNC_CALLS"]},
                     True, PRIORITY_LEAF_FOLLOWUP,
                     LABEL_ASYNC_TARGETS,
                 ))
-            return (finalize_hint_list(pairs), finalize_structured_hints(struct_pairs))
+            return finalize_structured_hints(struct_pairs)
 
         if kind != "symbol":
-            return (finalize_hint_list(pairs), finalize_structured_hints(struct_pairs))
+            return finalize_structured_hints(struct_pairs)
 
         decl_kind = _symbol_declaration_kind(rec)
         is_type = decl_kind in _TYPE_SYMBOL_KINDS
@@ -1162,27 +696,18 @@ def generate_hints(
 
         if is_type:
             if _out_count(edge_summary, "DECLARES.DECLARES_CLIENT") > 0:
-                pairs.append(
-                    (PRIORITY_DECLARES_TYPE_ROLLUP, TPL_DESCRIBE_TYPE_CLIENTS_VIA_MEMBERS.format(id=node_id))
-                )
                 struct_pairs.append(_StructuredHint(
                     "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["DECLARES.DECLARES_CLIENT"]},
                     True, PRIORITY_DECLARES_TYPE_ROLLUP,
                     LABEL_CLIENTS_VIA_MEMBERS,
                 ))
             if _out_count(edge_summary, "DECLARES.EXPOSES") > 0:
-                pairs.append(
-                    (PRIORITY_DECLARES_TYPE_ROLLUP, TPL_DESCRIBE_TYPE_ROUTES_VIA_MEMBERS.format(id=node_id))
-                )
                 struct_pairs.append(_StructuredHint(
                     "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["DECLARES.EXPOSES"]},
                     True, PRIORITY_DECLARES_TYPE_ROLLUP,
                     LABEL_ROUTES_VIA_MEMBERS,
                 ))
             if _out_count(edge_summary, "DECLARES.DECLARES_PRODUCER") > 0:
-                pairs.append(
-                    (PRIORITY_DECLARES_TYPE_ROLLUP, TPL_DESCRIBE_TYPE_PRODUCERS_VIA_MEMBERS.format(id=node_id))
-                )
                 struct_pairs.append(_StructuredHint(
                     "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["DECLARES.DECLARES_PRODUCER"]},
                     True, PRIORITY_DECLARES_TYPE_ROLLUP,
@@ -1191,87 +716,70 @@ def generate_hints(
 
             if not _type_rollup_would_emit(edge_summary):
                 if decl_kind == "interface" and _in_count(edge_summary, "IMPLEMENTS") > 0:
-                    pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_DESCRIBE_TYPE_IMPLEMENTORS.format(id=node_id)))
                     struct_pairs.append(_StructuredHint(
                         "neighbors", {"ids": [node_id], "direction": "in", "edge_types": ["IMPLEMENTS"]},
                         True, PRIORITY_LEAF_FOLLOWUP,
                         LABEL_IMPLEMENTORS,
                     ))
                 if decl_kind == "class" and _out_count(edge_summary, "IMPLEMENTS") > 0:
-                    pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_DESCRIBE_TYPE_IMPLEMENTS.format(id=node_id)))
                     struct_pairs.append(_StructuredHint(
                         "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["IMPLEMENTS"]},
                         True, PRIORITY_LEAF_FOLLOWUP,
                         LABEL_IMPLEMENTS,
                     ))
                 if decl_kind == "class" and _record_role(rec) == "SERVICE" and _out_count(edge_summary, "INJECTS") > 0:
-                    pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_DESCRIBE_TYPE_DEPENDENCIES.format(id=node_id)))
                     struct_pairs.append(_StructuredHint(
                         "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["INJECTS"]},
                         True, PRIORITY_LEAF_FOLLOWUP,
                         LABEL_DEPENDENCIES,
                     ))
                 if decl_kind in {"interface", "class"} and _in_count(edge_summary, "INJECTS") > 0:
-                    pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_DESCRIBE_TYPE_INJECTORS.format(id=node_id)))
                     struct_pairs.append(_StructuredHint(
                         "neighbors", {"ids": [node_id], "direction": "in", "edge_types": ["INJECTS"]},
                         True, PRIORITY_LEAF_FOLLOWUP,
                         LABEL_INJECTORS,
                     ))
 
-            return (finalize_hint_list(pairs), finalize_structured_hints(struct_pairs))
+            return finalize_structured_hints(struct_pairs)
 
         if is_method:
             if _out_count(edge_summary, "OVERRIDDEN_BY") > 0:
-                pairs.append((PRIORITY_OVERRIDDEN_AXIS, TPL_DESCRIBE_METHOD_OVERRIDERS.format(id=node_id)))
                 struct_pairs.append(_StructuredHint(
                     "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["OVERRIDDEN_BY"]},
                     True, PRIORITY_OVERRIDDEN_AXIS,
                     LABEL_OVERRIDERS,
                 ))
             if _out_count(edge_summary, "OVERRIDDEN_BY.DECLARES_CLIENT") > 0:
-                pairs.append(
-                    (PRIORITY_OVERRIDDEN_AXIS, TPL_DESCRIBE_METHOD_CLIENTS_IN_OVERRIDERS.format(id=node_id))
-                )
                 struct_pairs.append(_StructuredHint(
                     "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["OVERRIDDEN_BY.DECLARES_CLIENT"]},
                     True, PRIORITY_OVERRIDDEN_AXIS,
                     LABEL_CLIENTS_IN_OVERRIDERS,
                 ))
             if _out_count(edge_summary, "OVERRIDDEN_BY.DECLARES_PRODUCER") > 0:
-                pairs.append(
-                    (PRIORITY_OVERRIDDEN_AXIS, TPL_DESCRIBE_METHOD_PRODUCERS_IN_OVERRIDERS.format(id=node_id))
-                )
                 struct_pairs.append(_StructuredHint(
                     "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["OVERRIDDEN_BY.DECLARES_PRODUCER"]},
                     True, PRIORITY_OVERRIDDEN_AXIS,
                     LABEL_PRODUCERS_IN_OVERRIDERS,
                 ))
             if _out_count(edge_summary, "OVERRIDDEN_BY.EXPOSES") > 0:
-                pairs.append(
-                    (PRIORITY_OVERRIDDEN_AXIS, TPL_DESCRIBE_METHOD_ROUTES_IN_OVERRIDERS.format(id=node_id))
-                )
                 struct_pairs.append(_StructuredHint(
                     "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["OVERRIDDEN_BY.EXPOSES"]},
                     True, PRIORITY_OVERRIDDEN_AXIS,
                     LABEL_ROUTES_IN_OVERRIDERS,
                 ))
             if _out_count(edge_summary, "DECLARES_CLIENT") > 0:
-                pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_DESCRIBE_METHOD_OUTBOUND_CLIENT.format(id=node_id)))
                 struct_pairs.append(_StructuredHint(
                     "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["DECLARES_CLIENT"]},
                     True, PRIORITY_LEAF_FOLLOWUP,
                     LABEL_OUTBOUND_CLIENT,
                 ))
             if _out_count(edge_summary, "DECLARES_PRODUCER") > 0:
-                pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_DESCRIBE_METHOD_OUTBOUND_PRODUCER.format(id=node_id)))
                 struct_pairs.append(_StructuredHint(
                     "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["DECLARES_PRODUCER"]},
                     True, PRIORITY_LEAF_FOLLOWUP,
                     LABEL_OUTBOUND_PRODUCER,
                 ))
             if _out_count(edge_summary, "EXPOSES") > 0:
-                pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_DESCRIBE_METHOD_INBOUND_ROUTE.format(id=node_id)))
                 struct_pairs.append(_StructuredHint(
                     "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["EXPOSES"]},
                     True, PRIORITY_LEAF_FOLLOWUP,
@@ -1281,7 +789,6 @@ def generate_hints(
             if 1 <= calls_out <= 9:
                 method_role = _record_role(rec)
                 if method_role != "OTHER" or calls_out >= 3:
-                    pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_DESCRIBE_METHOD_OUTBOUND_CALLS.format(id=node_id)))
                     struct_pairs.append(_StructuredHint(
                         "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["CALLS"]},
                         True, PRIORITY_LEAF_FOLLOWUP,
@@ -1289,7 +796,6 @@ def generate_hints(
                     ))
             if _out_count(edge_summary, "OVERRIDES") > 0:
                 if _out_count(edge_summary, "OVERRIDDEN_BY") == 0:
-                    pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_DESCRIBE_METHOD_SUPER_DECL.format(id=node_id)))
                     struct_pairs.append(_StructuredHint(
                         "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["OVERRIDES"]},
                         True, PRIORITY_LEAF_FOLLOWUP,
@@ -1300,21 +806,20 @@ def generate_hints(
             if isinstance(data, dict):
                 unresolved = int(data.get("unresolved_call_sites_total") or 0)
             if unresolved > 0:
-                pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_DESCRIBE_METHOD_UNRESOLVED.format(id=node_id)))
                 struct_pairs.append(_StructuredHint(
                     "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["CALLS"], "include_unresolved": True},
                     True, PRIORITY_LEAF_FOLLOWUP,
                     LABEL_UNRESOLVED,
                 ))
             if _out_count(edge_summary, "CALLS") >= 10:
-                pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_DESCRIBE_METHOD_MANY_CALLS))
                 struct_pairs.append(_StructuredHint(
                     "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["CALLS"]},
                     False, PRIORITY_LEAF_FOLLOWUP,
                     LABEL_HIGH_FANOUT,
+                    reason="many CALLS — consider filtering by target microservice",
                 ))
-            return (finalize_hint_list(pairs), finalize_structured_hints(struct_pairs))
+            return finalize_structured_hints(struct_pairs)
 
-        return (finalize_hint_list(pairs), finalize_structured_hints(struct_pairs))
+        return finalize_structured_hints(struct_pairs)
 
-    return ([], [])
+    return []
diff --git a/mcp_v2.py b/mcp_v2.py
index 63979f18..6f87022e 100644
--- a/mcp_v2.py
+++ b/mcp_v2.py
@@ -31,7 +31,7 @@
 from java_codebase_rag.config import resolved_sbert_model_for_process_env
 from java_ontology import EDGE_SCHEMA, ResolveReason
 from kuzu_queries import KuzuGraph, OVERRIDE_AXIS_COMPOSED_EDGE_TYPES
-from mcp_hints import MCP_HINTS_FIELD_DESCRIPTION, MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION, generate_hints
+from mcp_hints import MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION, generate_hints
 from search_lancedb import TABLES, run_search
 
 DeclarationSymbolKind = Literal["class", "interface", "enum", "record", "annotation", "method", "constructor"]
@@ -181,6 +181,7 @@ class StructuredHint(BaseModel):
     tool: Literal["search", "find", "describe", "neighbors", "resolve"]
     args: dict[str, Any]
     actionable: bool = True
+    reason: str = ""
 
 # Populated EdgeFilter field -> EDGE_SCHEMA attribute name used in Cypher pushdown.
 _EDGEFILTER_FIELD_TO_ATTR: dict[str, str] = {
@@ -348,7 +349,7 @@ def _edgefilter_applicability_error(edge_types: list[str], ef: EdgeFilter) -> st
 
 
 def _to_structured_hints(raw: list[Any]) -> list[StructuredHint]:
-    return [StructuredHint(label=h.label, tool=h.tool, args=h.args, actionable=h.actionable) for h in raw]
+    return [StructuredHint(label=h.label, tool=h.tool, args=h.args, actionable=h.actionable, reason=h.reason) for h in raw]
 
 
 def _coerce_edge_filter(
@@ -463,7 +464,6 @@ class SearchOutput(BaseModel):
         default=None,
         description="Echoed from the request — the page offset the server applied. None on success=False.",
     )
-    hints: list[str] = Field(default_factory=list, description=MCP_HINTS_FIELD_DESCRIPTION)
     hints_structured: list[StructuredHint] = Field(default_factory=list, description=MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION)
 
 
@@ -479,7 +479,6 @@ class FindOutput(BaseModel):
         default=None,
         description="Echoed from the request — the page offset the server applied. None on success=False.",
     )
-    hints: list[str] = Field(default_factory=list, description=MCP_HINTS_FIELD_DESCRIPTION)
     hints_structured: list[StructuredHint] = Field(default_factory=list, description=MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION)
 
 
@@ -487,7 +486,6 @@ class DescribeOutput(BaseModel):
     success: bool
     record: NodeRecord | None = None
     message: str | None = None
-    hints: list[str] = Field(default_factory=list, description=MCP_HINTS_FIELD_DESCRIPTION)
     hints_structured: list[StructuredHint] = Field(default_factory=list, description=MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION)
 
 
@@ -499,7 +497,6 @@ class NeighborsOutput(BaseModel):
         default_factory=list,
         description="Echo of neighbors(edge_types=...) from the request; empty when success=False.",
     )
-    hints: list[str] = Field(default_factory=list, description=MCP_HINTS_FIELD_DESCRIPTION)
     hints_structured: list[StructuredHint] = Field(default_factory=list, description=MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION)
 
 
@@ -570,7 +567,6 @@ class ResolveOutput(BaseModel):
     candidates: list[ResolveCandidate] = Field(default_factory=list)
     message: str | None = None
     resolved_identifier: str | None = None
-    hints: list[str] = Field(default_factory=list, description=MCP_HINTS_FIELD_DESCRIPTION)
     hints_structured: list[StructuredHint] = Field(default_factory=list, description=MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION)
 
 
@@ -889,16 +885,15 @@ def search_v2(
             return SearchOutput(
                 success=False,
                 message=_filter_validation_error_message(exc),
-                hints=[],
                 limit=None,
                 offset=None,
             )
         if nf and (err := _nodefilter_applicability_error("symbol", nf)):
             _log_fail_loud("applicability")
-            return SearchOutput(success=False, message=err, hints=[], limit=None, offset=None)
+            return SearchOutput(success=False, message=err, limit=None, offset=None)
         if nf and (err := _validate_no_wildcards(nf)):
             _log_fail_loud("wildcard")
-            return SearchOutput(success=False, message=err, hints=[], limit=None, offset=None)
+            return SearchOutput(success=False, message=err, limit=None, offset=None)
         model_name = resolved_sbert_model_for_process_env(SBERT_MODEL)
         device = os.environ.get("SBERT_DEVICE") or None
         model = _get_sentence_transformer(model_name, device)
@@ -936,17 +931,16 @@ def search_v2(
             "limit": limit,
             "offset": offset,
         }
-        str_hints, raw_struct = generate_hints("search", hint_payload)
+        raw_struct = generate_hints("search", hint_payload)
         return SearchOutput(
             success=True,
             results=hits,
             limit=limit,
             offset=offset,
-            hints=str_hints,
             hints_structured=_to_structured_hints(raw_struct),
         )
     except Exception as exc:
-        return SearchOutput(success=False, message=str(exc), hints=[], limit=None, offset=None)
+        return SearchOutput(success=False, message=str(exc), limit=None, offset=None)
 
 
 def find_v2(
@@ -968,16 +962,15 @@ def find_v2(
             return FindOutput(
                 success=False,
                 message=_filter_validation_error_message(exc),
-                hints=[],
                 limit=None,
                 offset=None,
             )
         if err := _nodefilter_applicability_error(kind, nf):
             _log_fail_loud("applicability")
-            return FindOutput(success=False, message=err, hints=[], limit=None, offset=None)
+            return FindOutput(success=False, message=err, limit=None, offset=None)
         if err := _validate_no_wildcards(nf):
             _log_fail_loud("wildcard")
-            return FindOutput(success=False, message=err, hints=[], limit=None, offset=None)
+            return FindOutput(success=False, message=err, limit=None, offset=None)
         fetch_cap = int(limit) + int(offset) + 1
         if kind == "symbol":
             where, params = _symbol_where_from_filter(nf)
@@ -1027,17 +1020,16 @@ def find_v2(
             "filter": filter_dump,
             "has_more_results": has_more_results,
         }
-        str_hints, raw_struct = generate_hints("find", hint_payload)
+        raw_struct = generate_hints("find", hint_payload)
         return FindOutput(
             success=True,
             results=refs,
             limit=limit,
             offset=offset,
-            hints=str_hints,
             hints_structured=_to_structured_hints(raw_struct),
         )
     except Exception as exc:
-        return FindOutput(success=False, message=str(exc), hints=[], limit=None, offset=None)
+        return FindOutput(success=False, message=str(exc), limit=None, offset=None)
 
 
 _DESCRIBE_UCS_ID_MESSAGE = (
@@ -1057,9 +1049,9 @@ def describe_v2(
         has_id = bool(id and str(id).strip())
         has_fqn = bool(fqn and str(fqn).strip())
         if not has_id and not has_fqn:
-            return DescribeOutput(success=False, message="id or fqn required", hints=[])
+            return DescribeOutput(success=False, message="id or fqn required")
         if has_id and str(id).strip().startswith("ucs:"):
-            return DescribeOutput(success=False, message=_DESCRIBE_UCS_ID_MESSAGE, hints=[])
+            return DescribeOutput(success=False, message=_DESCRIBE_UCS_ID_MESSAGE)
         hint_message: str | None = None
         node_id: str
         if has_id:
@@ -1071,7 +1063,7 @@ def describe_v2(
                 {"fqn": fqn_val},
             )
             if not rows:
-                return DescribeOutput(success=False, message=f"No Symbol found for fqn='{fqn_val}'", hints=[])
+                return DescribeOutput(success=False, message=f"No Symbol found for fqn='{fqn_val}'")
             node_id = str(rows[0]["id"] or "")
             if len(rows) > 1:
                 hint_message = (
@@ -1081,10 +1073,10 @@ def describe_v2(
                 )
         kind = _resolve_node_kind(g, node_id)
         if kind == "unresolved_call_site":
-            return DescribeOutput(success=False, message=_DESCRIBE_UCS_ID_MESSAGE, hints=[])
+            return DescribeOutput(success=False, message=_DESCRIBE_UCS_ID_MESSAGE)
         row = _load_node_record(g, node_id, kind)
         if row is None:
-            return DescribeOutput(success=False, message=f"No node found for `{node_id}`", hints=[])
+            return DescribeOutput(success=False, message=f"No node found for `{node_id}`")
         ref = _node_ref_from_row(kind, row)
         edge_summary = _edge_summary_for_node(g, node_id, kind=kind, row=row)
         data = dict(row)
@@ -1107,18 +1099,17 @@ def describe_v2(
                         f"java-codebase-rag unresolved-calls list --method-id {node_id} for the full list"
                     )
         record = NodeRecord(id=ref.id, kind=kind, fqn=ref.fqn, data=data, edge_summary=edge_summary)
-        str_hints, raw_struct = generate_hints("describe", {"success": True, "record": record.model_dump()})
+        raw_struct = generate_hints("describe", {"success": True, "record": record.model_dump()})
         return DescribeOutput(
             success=True,
             record=record,
             message=hint_message,
-            hints=str_hints,
             hints_structured=_to_structured_hints(raw_struct),
         )
     except ValueError as exc:
-        return DescribeOutput(success=False, message=str(exc), hints=[])
+        return DescribeOutput(success=False, message=str(exc))
     except Exception as exc:
-        return DescribeOutput(success=False, message=str(exc), hints=[])
+        return DescribeOutput(success=False, message=str(exc))
 
 
 def _resolve_validate_identifier(raw: str) -> tuple[str | None, str | None]:
@@ -1437,9 +1428,8 @@ def _resolve_finalize_success(
         "path_prefix_seed": path_prefix_seed,
         "target_service_seed": target_service_seed,
     }
-    str_hints, raw_struct = generate_hints("resolve", hint_payload)
+    raw_struct = generate_hints("resolve", hint_payload)
     out = out.model_copy(update={
-        "hints": str_hints,
         "hints_structured": _to_structured_hints(raw_struct),
     })
     _resolve_assert_invariants(out)
@@ -1458,7 +1448,6 @@ def resolve_v2(
                 success=False,
                 status="none",
                 message=err,
-                hints=[],
                 resolved_identifier=None,
             )
             _resolve_assert_invariants(out)
@@ -1489,7 +1478,6 @@ def resolve_v2(
             success=False,
             status="none",
             message=str(exc),
-            hints=[],
             resolved_identifier=None,
         )
         _resolve_assert_invariants(out)
@@ -1726,7 +1714,6 @@ def neighbors_v2(
             return NeighborsOutput(
                 success=False,
                 message=_filter_validation_error_message(exc),
-                hints=[],
                 requested_edge_types=[],
             )
         try:
@@ -1741,12 +1728,11 @@ def neighbors_v2(
             return NeighborsOutput(
                 success=False,
                 message=_filter_validation_error_message(exc),
-                hints=[],
                 requested_edge_types=[],
             )
         except ValueError as exc:
             _log_fail_loud("edge_filter")
-            return NeighborsOutput(success=False, message=str(exc), hints=[], requested_edge_types=[])
+            return NeighborsOutput(success=False, message=str(exc), requested_edge_types=[])
         if include_unresolved and ef is not None:
             return NeighborsOutput(
                 success=False,
@@ -1754,21 +1740,18 @@ def neighbors_v2(
                     "include_unresolved=True is incompatible with edge_filter; "
                     "UnresolvedCallSite rows have no edge attributes to filter on"
                 ),
-                hints=[],
                 requested_edge_types=requested_edge_types,
             )
         if include_unresolved and requested_edge_types != ["CALLS"]:
             return NeighborsOutput(
                 success=False,
                 message="include_unresolved requires edge_types=['CALLS']",
-                hints=[],
                 requested_edge_types=requested_edge_types,
             )
         if include_unresolved and direction != "out":
             return NeighborsOutput(
                 success=False,
                 message='include_unresolved requires direction="out"',
-                hints=[],
                 requested_edge_types=requested_edge_types,
             )
         if ef and (err := _edgefilter_applicability_error(requested_edge_types, ef)):
@@ -1776,17 +1759,15 @@ def neighbors_v2(
             return NeighborsOutput(
                 success=False,
                 message=err,
-                hints=[],
                 requested_edge_types=requested_edge_types,
             )
         if nf and (err := _validate_no_wildcards(nf)):
             _log_fail_loud("wildcard")
-            return NeighborsOutput(success=False, message=err, hints=[], requested_edge_types=[])
+            return NeighborsOutput(success=False, message=err, requested_edge_types=[])
         if composed_keys and direction != "out":
             return NeighborsOutput(
                 success=False,
                 message='Composed edge types require direction="out"',
-                hints=[],
                 requested_edge_types=requested_edge_types,
             )
         use_calls_path = flat_labels == ["CALLS"] and not composed_keys
@@ -1811,7 +1792,6 @@ def neighbors_v2(
                     return NeighborsOutput(
                         success=False,
                         message=axis_msg,
-                        hints=[],
                         requested_edge_types=requested_edge_types,
                     )
                 origin_row = _load_node_record(g, origin_id, "symbol")
@@ -1827,7 +1807,6 @@ def neighbors_v2(
                     return NeighborsOutput(
                         success=False,
                         message=err,
-                        hints=[],
                         requested_edge_types=requested_edge_types,
                     )
             if use_calls_path:
@@ -1853,7 +1832,6 @@ def neighbors_v2(
                     return NeighborsOutput(
                         success=False,
                         message=str(exc),
-                        hints=[],
                         requested_edge_types=requested_edge_types,
                     )
                 if (
@@ -1903,7 +1881,7 @@ def neighbors_v2(
                     if nf and (err := _nodefilter_applicability_error(other_kind, nf)):
                         _log_fail_loud("applicability")
                         return NeighborsOutput(
-                            success=False, message=err, hints=[], requested_edge_types=[]
+                            success=False, message=err, requested_edge_types=[]
                         )
                     if not _node_matches_filter(other_kind, other_rec, nf):
                         continue
@@ -1930,7 +1908,7 @@ def neighbors_v2(
                     if nf and (err := _nodefilter_applicability_error(other_kind, nf)):
                         _log_fail_loud("applicability")
                         return NeighborsOutput(
-                            success=False, message=err, hints=[], requested_edge_types=[]
+                            success=False, message=err, requested_edge_types=[]
                         )
                     if not _node_matches_filter(other_kind, other_rec, nf):
                         continue
@@ -1971,15 +1949,14 @@ def neighbors_v2(
             "unresolved_count": unresolved_count,
             "calls_row_count": calls_row_count,
         }
-        str_hints, raw_struct = generate_hints("neighbors", neigh_payload)
+        raw_struct = generate_hints("neighbors", neigh_payload)
         return NeighborsOutput(
             success=True,
             results=sliced,
             requested_edge_types=requested_edge_types,
-            hints=str_hints,
             hints_structured=_to_structured_hints(raw_struct),
         )
     except ValidationError:
         raise
     except Exception as exc:
-        return NeighborsOutput(success=False, message=str(exc), hints=[], requested_edge_types=[])
+        return NeighborsOutput(success=False, message=str(exc), requested_edge_types=[])
diff --git a/server.py b/server.py
index 2e50bce3..55c46ca3 100644
--- a/server.py
+++ b/server.py
@@ -341,7 +341,7 @@ def create_mcp_server() -> FastMCP:
             "structured DSL inside `query`; structured predicates belong in `find`. "
             "For identifier-shaped lookups (FQN, id prefix, route/client identifiers, …), use `resolve` first; "
             "use `search` for natural-language or ranked fuzzy discovery. "
-            "Successful responses echo `limit`/`offset` and may include `hints` (advisory next-step strings)."
+            "Successful responses echo `limit`/`offset` and may include `hints_structured` (advisory next-step objects with tool, args, actionable, label, reason)."
         ),
     )
     async def search(
@@ -390,7 +390,7 @@ async def search(
             "module, source_layer, producer_kind, topic_prefix. "
             "Wildcards in prefix fields are rejected. An empty filter (`{}`) or `filter=None` means no predicate (all nodes of "
             "that kind; use pagination). Unknown keys or inapplicable populated fields return success=false. "
-            "Successful responses echo `limit`/`offset` and may include `hints` (advisory next-step strings)."
+            "Successful responses echo `limit`/`offset` and may include `hints_structured` (advisory next-step objects with tool, args, actionable, label, reason)."
         ),
     )
     async def find(
@@ -426,7 +426,7 @@ async def find(
             "Pass `id` for any kind, or exact `fqn` for Symbol lookup (`id` wins when both are set). "
             "`describe(fqn=…)` keeps the first graph row when multiple symbols share that FQN; when an FQN may collide, "
             "prefer `resolve(identifier=…, hint_kind='symbol')` first, then `describe(id=…)` on the chosen node. "
-            "Successful responses may include `hints` (advisory next-step strings)."
+            "Successful responses may include `hints_structured` (advisory next-step objects with tool, args, actionable, label, reason)."
         ),
     )
     async def describe(
@@ -460,7 +460,7 @@ async def describe(
             "Optional `edge_filter` requires edge_types=['CALLS'] only (no composed dot-keys or extra stored "
             "labels); projects the ordered CALLS stream by edge attributes (min_confidence, strategies, "
             "callee_declaring_role). Wildcards in prefix fields are rejected. Unknown filter keys return success=false. "
-            "Successful responses echo `requested_edge_types` and may include `hints` (advisory next-step strings; "
+            "Successful responses echo `requested_edge_types` and may include `hints_structured` (advisory next-step objects with tool, args, actionable, label, reason; "
             "empty results may include EDGE_SCHEMA-driven traversal hints). "
             "Each edge's `attrs.strategy` indicates resolution quality (brownfield/fallback vs primary paths)."
         ),
@@ -546,7 +546,7 @@ async def neighbors(
             "status=one (single node), many (≥2 ranked candidates with reason), or none "
             "(no match — fall back to search(query=...) for natural language or fuzzy text). "
             "Optional hint_kind narrows to symbol, route, client, or producer. "
-            "Successful responses may include advisory hints (same contract as other v2 tools). "
+            "Successful responses may include `hints_structured` (advisory next-step objects with tool, args, actionable, label, reason). "
             "Malformed empty/whitespace identifier returns success=false. "
             "Examples: resolve('com.foo.Bar', hint_kind='symbol'); "
             "resolve('GET /api/v1/customers', hint_kind='route'); "
diff --git a/tests/test_mcp_hints.py b/tests/test_mcp_hints.py
index 21e93c00..bbf5f8c1 100644
--- a/tests/test_mcp_hints.py
+++ b/tests/test_mcp_hints.py
@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import inspect
 from collections import Counter
 from pathlib import Path
 from typing import Any
@@ -12,18 +11,15 @@
 from java_ontology import EDGE_SCHEMA, FUZZY_STRATEGY_SET
 from kuzu_queries import KuzuGraph
 from mcp_hints import (
-    PRIORITY_DECLARES_TYPE_ROLLUP,
-    PRIORITY_LEAF_FOLLOWUP,
-    PRIORITY_META,
-    PRIORITY_OVERRIDDEN_AXIS,
     _StructuredHint,
-    finalize_hint_list,
     finalize_structured_hints,
     generate_hints,
-    neighbors_empty_hints,
 )
 from mcp_v2 import (
+    DescribeOutput,
     FindOutput,
+    NeighborsOutput,
+    ResolveOutput,
     SearchOutput,
     describe_v2,
     find_v2,
@@ -38,11 +34,6 @@
 _OVERRIDE_AXIS_FIXTURE = Path(__file__).resolve().parent / "fixtures" / "override_axis_rollup_smoke"
 
 
-def _hints(output_kind, payload):
-    """Convenience wrapper — returns string hints only (backward compat for existing tests)."""
-    return generate_hints(output_kind, payload)[0]
-
-
 @pytest.fixture
 def override_axis_graph(tmp_path: Path) -> KuzuGraph:
     db_path = tmp_path / "code_graph.kuzu"
@@ -138,7 +129,7 @@ def _method_id_with_empty_describe_hints(kuzu_graph) -> str:
     for row in rows:
         mid = str(row["id"])
         out = describe_v2(mid, graph=kuzu_graph)
-        if out.success and out.record and out.hints == []:
+        if out.success and out.record and out.hints_structured == []:
             return mid
     pytest.fail("no method with empty describe hints in fixture")
 
@@ -179,49 +170,43 @@ def test_hints_describe_type_symbol_clients_via_members_emits(kuzu_graph) -> Non
     tid = _type_symbol_id_with_member_clients(kuzu_graph)
     out = describe_v2(tid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_TYPE_CLIENTS_VIA_MEMBERS.format(id=tid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_CLIENTS_VIA_MEMBERS for h in out.hints_structured)
 
 
 def test_hints_describe_type_symbol_routes_via_members_emits(kuzu_graph) -> None:
     tid = _controller_class_id_with_exposes(kuzu_graph)
     out = describe_v2(tid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_TYPE_ROUTES_VIA_MEMBERS.format(id=tid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_ROUTES_VIA_MEMBERS for h in out.hints_structured)
 
 
 def test_hints_describe_type_symbol_producers_via_members_emits(kuzu_graph) -> None:
     tid = _type_symbol_id_with_member_producers(kuzu_graph)
     out = describe_v2(tid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_TYPE_PRODUCERS_VIA_MEMBERS.format(id=tid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_PRODUCERS_VIA_MEMBERS for h in out.hints_structured)
 
 
 def test_hints_describe_method_overriders_emits(kuzu_graph) -> None:
     mid = _interface_method_with_override_rollups(kuzu_graph)
     out = describe_v2(mid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_METHOD_OVERRIDERS.format(id=mid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_OVERRIDERS for h in out.hints_structured)
 
 
 def test_hints_describe_method_clients_in_overriders_emits(kuzu_graph) -> None:
     mid = _interface_method_with_override_rollups(kuzu_graph)
     out = describe_v2(mid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_METHOD_CLIENTS_IN_OVERRIDERS.format(id=mid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_CLIENTS_IN_OVERRIDERS for h in out.hints_structured)
 
 
 def test_hints_describe_method_overridden_by_declares_client_emits_dot_key(kuzu_graph) -> None:
     mid = _interface_method_with_override_rollups(kuzu_graph)
     out = describe_v2(mid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_METHOD_CLIENTS_IN_OVERRIDERS.format(id=mid)
-    assert want in out.hints
-    assert "OVERRIDDEN_BY.DECLARES_CLIENT" in want
+    h = next(h for h in out.hints_structured if h.label == mcp_hints.LABEL_CLIENTS_IN_OVERRIDERS)
+    assert "OVERRIDDEN_BY.DECLARES_CLIENT" in str(h.args.get("edge_types", []))
 
 
 def test_hints_describe_method_producers_in_overriders_emits(override_axis_graph: KuzuGraph) -> None:
@@ -235,8 +220,7 @@ def test_hints_describe_method_producers_in_overriders_emits(override_axis_graph
     mid = str(rows[0]["id"])
     out = describe_v2(mid, graph=override_axis_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_METHOD_PRODUCERS_IN_OVERRIDERS.format(id=mid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_PRODUCERS_IN_OVERRIDERS for h in out.hints_structured)
 
 
 def test_hints_describe_method_routes_in_overriders_emits(override_axis_graph: KuzuGraph) -> None:
@@ -250,16 +234,14 @@ def test_hints_describe_method_routes_in_overriders_emits(override_axis_graph: K
     mid = str(rows[0]["id"])
     out = describe_v2(mid, graph=override_axis_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_METHOD_ROUTES_IN_OVERRIDERS.format(id=mid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_ROUTES_IN_OVERRIDERS for h in out.hints_structured)
 
 
 def test_hints_describe_method_declares_client_emits(kuzu_graph) -> None:
     mid = _method_declares_client(kuzu_graph)
     out = describe_v2(mid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_METHOD_OUTBOUND_CLIENT.format(id=mid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_OUTBOUND_CLIENT for h in out.hints_structured)
 
 
 def test_hints_describe_method_exposes_emits(kuzu_graph) -> None:
@@ -270,8 +252,7 @@ def test_hints_describe_method_exposes_emits(kuzu_graph) -> None:
     mid = str(rows[0]["id"])
     out = describe_v2(mid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_METHOD_INBOUND_ROUTE.format(id=mid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_INBOUND_ROUTE for h in out.hints_structured)
 
 
 def test_hints_describe_method_declares_producer_emits(kuzu_graph) -> None:
@@ -284,61 +265,57 @@ def test_hints_describe_method_declares_producer_emits(kuzu_graph) -> None:
     mid = str(rows[0]["id"])
     out = describe_v2(mid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_METHOD_OUTBOUND_PRODUCER.format(id=mid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_OUTBOUND_PRODUCER for h in out.hints_structured)
 
 
 def test_hints_describe_method_many_calls_emits(kuzu_graph) -> None:
     mid = _controller_method_many_calls(kuzu_graph)
     out = describe_v2(mid, graph=kuzu_graph)
     assert out.success and out.record
-    assert mcp_hints.TPL_DESCRIBE_METHOD_MANY_CALLS in out.hints
+    assert any(h.label == mcp_hints.LABEL_HIGH_FANOUT and "many CALLS" in h.reason for h in out.hints_structured)
 
 
 def test_hints_describe_route_always_declaring_method(kuzu_graph) -> None:
     rid = _route_id(kuzu_graph)
     out = describe_v2(rid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_ROUTE_DECLARING.format(id=rid)
-    assert out.hints == [want]
+    assert len(out.hints_structured) == 1
+    assert out.hints_structured[0].label == mcp_hints.LABEL_DECLARING_METHOD
 
 
 def test_hints_describe_client_always_declaring_method(kuzu_graph) -> None:
     cid = _client_id(kuzu_graph)
     out = describe_v2(cid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_CLIENT_DECLARING.format(id=cid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_DECLARING_METHOD for h in out.hints_structured)
 
 
 def test_hints_describe_producer_always_declaring_method(kuzu_graph) -> None:
     pid = _producer_id(kuzu_graph)
     out = describe_v2(pid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_PRODUCER_DECLARING.format(id=pid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_DECLARING_METHOD for h in out.hints_structured)
 
 
 def test_hints_find_empty_identifier_filter_suggests_resolve(kuzu_graph) -> None:
     out = find_v2("client", {"target_service": "__no_such_target_service__"}, graph=kuzu_graph)
     assert out.success is True
     assert out.results == []
-    assert "hint_kind" in inspect.signature(resolve_v2).parameters
-    assert any("resolve(identifier" in h and "hint_kind='client'" in h for h in out.hints)
+    assert any(h.label == mcp_hints.LABEL_TRY_RESOLVE and h.args.get("hint_kind") == "client" for h in out.hints_structured)
 
 
 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)
+    assert any(h.label == mcp_hints.LABEL_TRY_RESOLVE and h.args.get("hint_kind") == "symbol" for h in out.hints_structured)
 
 
 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
+    assert any(h.label == mcp_hints.LABEL_PAGE_FULL for h in out.hints_structured)
 
 
 def test_hints_find_page_full_skips_when_last_page(kuzu_graph) -> None:
@@ -352,7 +329,7 @@ def test_hints_find_page_full_skips_when_last_page(kuzu_graph) -> None:
         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
+    assert not any(h.label == mcp_hints.LABEL_PAGE_FULL for h in last.hints_structured)
 
 
 def _neighbors_hint_payload(
@@ -423,14 +400,8 @@ def _neighbors_empty_payload(
     )
 
 
-def _structural_neighbors_hints(payload: dict[str, Any]) -> list[str]:
-    hints = _hints("neighbors", payload)
-    structural_markers = (
-        mcp_hints.TPL_NEIGHBORS_WRONG_SUBJECT_KIND.split("'")[0],
-        mcp_hints.TPL_NEIGHBORS_WRONG_DIRECTION.split("'")[0],
-        mcp_hints.TPL_NEIGHBORS_TYPE_LEVEL_REQUERY.split("'")[0],
-    )
-    return [h for h in hints if any(h.startswith(m) for m in structural_markers)]
+def _has_structural_label(payload: dict[str, Any], label: str) -> bool:
+    return any(h.label == label for h in generate_hints("neighbors", payload))
 
 
 def test_hints_neighbors_empty_class_declares_client_emits_type_level_requery(kuzu_graph) -> None:
@@ -439,7 +410,7 @@ def test_hints_neighbors_empty_class_declares_client_emits_type_level_requery(ku
     assert out.success is True
     assert out.results == []
     assert out.requested_edge_types == ["DECLARES_CLIENT"]
-    assert any("lives on methods" in h for h in out.hints)
+    assert any("lives on methods" in h.reason for h in out.hints_structured)
 
 
 def _edge_result(*, strategy: str | None = None, edge_type: str = "DECLARES_CLIENT") -> dict[str, Any]:
@@ -472,9 +443,10 @@ def test_hints_neighbors_fuzzy_strategy_layer_c_source_emits() -> None:
         [_edge_result(strategy="layer_c_source", edge_type="CALLS")],
         requested_edge_types=["CALLS"],
     )
-    hints = _hints("neighbors", payload)
-    assert mcp_hints.TPL_NEIGHBORS_FUZZY_STRATEGY in hints
-    assert "attrs.strategy" in hints[0]
+    hints = generate_hints("neighbors", payload)
+    assert any(h.label == mcp_hints.LABEL_FUZZY_STRATEGY for h in hints)
+    fuzzy = [h for h in hints if h.label == mcp_hints.LABEL_FUZZY_STRATEGY]
+    assert "attrs.strategy" in fuzzy[0].reason
 
 
 def test_hints_neighbors_fuzzy_strategy_annotation_absent() -> None:
@@ -482,7 +454,7 @@ def test_hints_neighbors_fuzzy_strategy_annotation_absent() -> None:
         [_edge_result(strategy="annotation", edge_type="CALLS")],
         requested_edge_types=["CALLS"],
     )
-    assert _hints("neighbors", payload) == []
+    assert generate_hints("neighbors", payload) == []
 
 
 def test_hints_neighbors_fuzzy_strategy_calls_phantom_emits() -> None:
@@ -491,8 +463,8 @@ def test_hints_neighbors_fuzzy_strategy_calls_phantom_emits() -> None:
         [_edge_result(strategy="overload_ambiguous", edge_type="CALLS")],
         requested_edge_types=["CALLS"],
     )
-    hints = _hints("neighbors", payload)
-    assert mcp_hints.TPL_NEIGHBORS_FUZZY_STRATEGY in hints
+    hints = generate_hints("neighbors", payload)
+    assert any(h.label == mcp_hints.LABEL_FUZZY_STRATEGY for h in hints)
 
 
 def test_hints_neighbors_declares_no_strategy_attrs_empty() -> None:
@@ -500,7 +472,7 @@ def test_hints_neighbors_declares_no_strategy_attrs_empty() -> None:
         [_edge_result(edge_type="DECLARES")],
         requested_edge_types=["DECLARES"],
     )
-    assert _hints("neighbors", payload) == []
+    assert generate_hints("neighbors", payload) == []
 
 
 def test_hints_neighbors_multi_origin_fuzzy_emits_once() -> None:
@@ -511,8 +483,8 @@ def test_hints_neighbors_multi_origin_fuzzy_emits_once() -> None:
         ],
         requested_edge_types=["CALLS"],
     )
-    hints = _hints("neighbors", payload)
-    assert hints.count(mcp_hints.TPL_NEIGHBORS_FUZZY_STRATEGY) == 1
+    hints = generate_hints("neighbors", payload)
+    assert sum(1 for h in hints if h.label == mcp_hints.LABEL_FUZZY_STRATEGY) == 1
 
 
 def test_hints_neighbors_calls_high_fanout(kuzu_graph) -> None:
@@ -522,18 +494,14 @@ def test_hints_neighbors_calls_high_fanout(kuzu_graph) -> None:
     assert len(out.results) == 25
     total_calls = kuzu_graph.count_calls_for_symbol(mid, direction="out")
     assert total_calls >= 10
-    assert mcp_hints.TPL_NEIGHBORS_CALLS_HIGH_FANOUT.format(n=total_calls) in out.hints
-    assert mcp_hints.TPL_NEIGHBORS_CALLS_HIGH_FANOUT.format(n=len(out.results)) not in out.hints
-
-
-def test_hints_neighbors_calls_has_unresolved(kuzu_graph) -> None:
-    mid = client_message_processor_process_id(kuzu_graph)
-    unresolved = kuzu_graph.count_unresolved_for_caller(mid)
-    assert unresolved >= 1
-    out = neighbors_v2(mid, direction="out", edge_types=["CALLS"], limit=5, graph=kuzu_graph)
-    assert out.success is True
-    want = mcp_hints.TPL_NEIGHBORS_CALLS_HAS_UNRESOLVED.format(n=len(out.results), k=unresolved)
-    assert want in out.hints
+    assert any(
+        h.label == mcp_hints.LABEL_HIGH_FANOUT and str(total_calls) in h.reason
+        for h in out.hints_structured
+    )
+    assert not any(
+        h.label == mcp_hints.LABEL_HIGH_FANOUT and str(len(out.results)) in h.reason
+        for h in out.hints_structured
+    )
 
 
 def test_hints_neighbors_calls_high_fanout_suppressed_with_edge_filter(kuzu_graph) -> None:
@@ -547,7 +515,7 @@ def test_hints_neighbors_calls_high_fanout_suppressed_with_edge_filter(kuzu_grap
         graph=kuzu_graph,
     )
     assert out.success is True
-    assert not any("CALLS on this method" in h for h in out.hints)
+    assert not any("CALLS on this method" in h.reason for h in out.hints_structured)
 
 
 def test_hints_neighbors_layer_a_meta_no_fuzzy_hint() -> None:
@@ -555,7 +523,7 @@ def test_hints_neighbors_layer_a_meta_no_fuzzy_hint() -> None:
         [_edge_result(strategy="layer_a_meta", edge_type="CALLS")],
         requested_edge_types=["CALLS"],
     )
-    assert _hints("neighbors", payload) == []
+    assert generate_hints("neighbors", payload) == []
 
 
 def test_hints_neighbors_fuzzy_strategy_neighbors_v2_round_trip(kuzu_graph) -> None:
@@ -565,8 +533,8 @@ def test_hints_neighbors_fuzzy_strategy_neighbors_v2_round_trip(kuzu_graph) -> N
     assert out.results
     strategies = [e.attrs.get("strategy") for e in out.results]
     assert any(s in FUZZY_STRATEGY_SET for s in strategies if isinstance(s, str))
-    assert mcp_hints.TPL_NEIGHBORS_FUZZY_STRATEGY in out.hints
-    assert "brownfield/fallback strategy" in out.hints[0]
+    assert any(h.label == mcp_hints.LABEL_FUZZY_STRATEGY for h in out.hints_structured)
+    assert any("brownfield/fallback strategy" in h.reason for h in out.hints_structured)
 
 
 def _producer_id(kuzu_graph) -> str:
@@ -598,9 +566,9 @@ def test_hints_hv1_type_level_declares_client_requery() -> None:
         {"id": "sym:com.example.T", "kind": "class"},
         ["DECLARES_CLIENT"],
     )
-    hints = _hints("neighbors", payload)
-    assert any("lives on methods" in h for h in hints)
-    assert any("DECLARES" in h for h in hints)
+    hints = generate_hints("neighbors", payload)
+    assert any("lives on methods" in h.reason for h in hints)
+    assert any("DECLARES" in str(h.args.get("edge_types", [])) for h in hints)
 
 
 def test_hints_hv2_method_http_calls_wrong_subject_kind() -> None:
@@ -608,9 +576,9 @@ def test_hints_hv2_method_http_calls_wrong_subject_kind() -> None:
         {"id": "sym:com.example.T#m()", "kind": "method"},
         ["HTTP_CALLS"],
     )
-    hints = _hints("neighbors", payload)
-    assert any("Client" in h and "Route" in h for h in hints)
-    assert any("DECLARES_CLIENT" in h for h in hints)
+    hints = generate_hints("neighbors", payload)
+    assert any("Client" in h.reason and "Route" in h.reason for h in hints)
+    assert any("DECLARES_CLIENT" in str(h.args.get("edge_types", [])) for h in hints)
 
 
 def test_hints_hv3_method_async_calls_wrong_subject_kind() -> None:
@@ -618,19 +586,21 @@ def test_hints_hv3_method_async_calls_wrong_subject_kind() -> None:
         {"id": "sym:com.example.T#m()", "kind": "method"},
         ["ASYNC_CALLS"],
     )
-    hints = _hints("neighbors", payload)
-    assert any("Producer" in h and "Route" in h for h in hints)
-    assert any("DECLARES_PRODUCER" in h for h in hints)
+    hints = generate_hints("neighbors", payload)
+    assert any("Producer" in h.reason and "Route" in h.reason for h in hints)
+    assert any("DECLARES_PRODUCER" in str(h.args.get("edge_types", [])) for h in hints)
 
 
-def test_hints_hv4_producer_empty_async_out_brownfield_only() -> None:
+def test_hints_hv4_producer_empty_async_out_no_structural_hints() -> None:
     payload = _neighbors_empty_payload(
         {"id": "producer:svc:kafka:t", "producer_kind": "kafka"},
         ["ASYNC_CALLS"],
     )
-    hints = _hints("neighbors", payload)
-    assert _structural_neighbors_hints(payload) == []
-    assert any("brownfield resolver" in h for h in hints)
+    hints = generate_hints("neighbors", payload)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_WRONG_SUBJECT_KIND)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_WRONG_DIRECTION)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_TYPE_LEVEL_REQUERY)
+    assert hints == []
 
 
 def test_hints_hv5_producer_async_calls_wrong_direction() -> None:
@@ -639,8 +609,10 @@ def test_hints_hv5_producer_async_calls_wrong_direction() -> None:
         ["ASYNC_CALLS"],
         direction="in",
     )
-    hints = _hints("neighbors", payload)
-    assert any("direction='in'" in h and "direction='out'" in h for h in hints)
+    hints = generate_hints("neighbors", payload)
+    wrong_dir = [h for h in hints if h.label == mcp_hints.LABEL_WRONG_DIRECTION]
+    assert wrong_dir
+    assert "direction='out'" in wrong_dir[0].reason
 
 
 def test_hints_hv6_client_http_calls_wrong_direction() -> None:
@@ -649,8 +621,10 @@ def test_hints_hv6_client_http_calls_wrong_direction() -> None:
         ["HTTP_CALLS"],
         direction="in",
     )
-    hints = _hints("neighbors", payload)
-    assert any("direction='in'" in h and "direction='out'" in h for h in hints)
+    hints = generate_hints("neighbors", payload)
+    wrong_dir = [h for h in hints if h.label == mcp_hints.LABEL_WRONG_DIRECTION]
+    assert wrong_dir
+    assert "direction='out'" in wrong_dir[0].reason
 
 
 def test_hints_hv7_route_http_calls_wrong_direction() -> None:
@@ -659,8 +633,10 @@ def test_hints_hv7_route_http_calls_wrong_direction() -> None:
         ["HTTP_CALLS"],
         direction="out",
     )
-    hints = _hints("neighbors", payload)
-    assert any("direction='out'" in h and "direction='in'" in h for h in hints)
+    hints = generate_hints("neighbors", payload)
+    wrong_dir = [h for h in hints if h.label == mcp_hints.LABEL_WRONG_DIRECTION]
+    assert wrong_dir
+    assert "direction='in'" in wrong_dir[0].reason
 
 
 def test_hints_hv8_method_exposes_empty_no_structural_hint() -> None:
@@ -668,9 +644,11 @@ def test_hints_hv8_method_exposes_empty_no_structural_hint() -> None:
         {"id": "sym:com.example.T#m()", "kind": "method"},
         ["EXPOSES"],
     )
-    hints = _hints("neighbors", payload)
-    assert _structural_neighbors_hints(payload) == []
-    assert not any("brownfield resolver" in h for h in hints)
+    hints = generate_hints("neighbors", payload)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_WRONG_SUBJECT_KIND)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_WRONG_DIRECTION)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_TYPE_LEVEL_REQUERY)
+    assert not any("brownfield resolver" in h.reason for h in hints)
 
 
 def test_hints_hv9_method_declares_client_empty_no_structural_hint() -> None:
@@ -678,9 +656,11 @@ def test_hints_hv9_method_declares_client_empty_no_structural_hint() -> None:
         {"id": "sym:com.example.T#m()", "kind": "method"},
         ["DECLARES_CLIENT"],
     )
-    hints = _hints("neighbors", payload)
-    assert _structural_neighbors_hints(payload) == []
-    assert not any("brownfield resolver" in h for h in hints)
+    hints = generate_hints("neighbors", payload)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_WRONG_SUBJECT_KIND)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_WRONG_DIRECTION)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_TYPE_LEVEL_REQUERY)
+    assert not any("brownfield resolver" in h.reason for h in hints)
 
 
 def test_hints_hv10_class_http_calls_wrong_subject_kind() -> None:
@@ -688,8 +668,9 @@ def test_hints_hv10_class_http_calls_wrong_subject_kind() -> None:
         {"id": "sym:com.example.T", "kind": "class"},
         ["HTTP_CALLS"],
     )
-    hints = _hints("neighbors", payload)
-    assert any("this is a Symbol" in h for h in hints)
+    hints = generate_hints("neighbors", payload)
+    # Type-level Symbol is alien_subject for HTTP_CALLS — no structural hint emitted
+    assert hints == []
 
 
 def test_hints_hv11_method_overrides_empty_no_structural_hint() -> None:
@@ -697,7 +678,9 @@ def test_hints_hv11_method_overrides_empty_no_structural_hint() -> None:
         {"id": "sym:com.example.T#m()", "kind": "method"},
         ["OVERRIDES"],
     )
-    assert _structural_neighbors_hints(payload) == []
+    assert not _has_structural_label(payload, mcp_hints.LABEL_WRONG_SUBJECT_KIND)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_WRONG_DIRECTION)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_TYPE_LEVEL_REQUERY)
 
 
 def test_hints_hv12_annotation_extends_empty_no_structural_hint(kuzu_graph) -> None:
@@ -706,27 +689,33 @@ def test_hints_hv12_annotation_extends_empty_no_structural_hint(kuzu_graph) -> N
         pytest.skip("no annotation Symbol in fixture")
     assert EDGE_SCHEMA["EXTENDS"].member_only is False
     payload = _neighbors_empty_payload({"id": ann_id, "kind": "annotation"}, ["EXTENDS"])
-    assert _structural_neighbors_hints(payload) == []
+    assert not _has_structural_label(payload, mcp_hints.LABEL_WRONG_SUBJECT_KIND)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_WRONG_DIRECTION)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_TYPE_LEVEL_REQUERY)
 
 
-def test_hints_hv13_client_empty_http_brownfield_only() -> None:
+def test_hints_hv13_client_empty_http_no_structural_hints() -> None:
     payload = _neighbors_empty_payload(
         {"id": "client:svc:feign:t:GET:/p", "client_kind": "feign_method"},
         ["HTTP_CALLS"],
     )
-    hints = _hints("neighbors", payload)
-    assert _structural_neighbors_hints(payload) == []
-    assert any("brownfield resolver" in h for h in hints)
+    hints = generate_hints("neighbors", payload)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_WRONG_SUBJECT_KIND)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_WRONG_DIRECTION)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_TYPE_LEVEL_REQUERY)
+    assert hints == []
 
 
-def test_hints_hv14_producer_empty_async_brownfield_only() -> None:
+def test_hints_hv14_producer_empty_async_no_structural_hints() -> None:
     payload = _neighbors_empty_payload(
         {"id": "producer:svc:kafka:t", "producer_kind": "kafka"},
         ["ASYNC_CALLS"],
     )
-    hints = _hints("neighbors", payload)
-    assert _structural_neighbors_hints(payload) == []
-    assert any("brownfield resolver" in h for h in hints)
+    hints = generate_hints("neighbors", payload)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_WRONG_SUBJECT_KIND)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_WRONG_DIRECTION)
+    assert not _has_structural_label(payload, mcp_hints.LABEL_TYPE_LEVEL_REQUERY)
+    assert hints == []
 
 
 def test_hints_hv15_multi_edge_http_only_wrong_kind_for_http() -> None:
@@ -734,10 +723,10 @@ def test_hints_hv15_multi_edge_http_only_wrong_kind_for_http() -> None:
         {"id": "sym:com.example.T#m()", "kind": "method"},
         ["HTTP_CALLS", "DECLARES_CLIENT"],
     )
-    hints = _hints("neighbors", payload)
-    wrong_kind = [h for h in hints if "HTTP_CALLS" in h and "this is a Symbol" in h]
+    hints = generate_hints("neighbors", payload)
+    wrong_kind = [h for h in hints if "HTTP_CALLS" in h.reason and "this is a Symbol" in h.reason]
     assert len(wrong_kind) == 1
-    assert not any("DECLARES_CLIENT" in h and "lives on methods" in h for h in hints)
+    assert not any("DECLARES_CLIENT" in h.reason and "lives on methods" in h.reason for h in hints)
 
 
 def test_hints_hv16_client_nonempty_http_fuzzy_hint_unchanged(kuzu_graph) -> None:
@@ -752,8 +741,8 @@ def test_hints_hv16_client_nonempty_http_fuzzy_hint_unchanged(kuzu_graph) -> Non
     cid = str(rows[0]["id"])
     out = neighbors_v2(cid, direction="out", edge_types=["HTTP_CALLS"], graph=kuzu_graph, limit=50)
     assert out.success and out.results
-    assert mcp_hints.TPL_NEIGHBORS_FUZZY_STRATEGY in out.hints
-    assert not any("this is a" in h for h in out.hints)
+    assert any(h.label == mcp_hints.LABEL_FUZZY_STRATEGY for h in out.hints_structured)
+    assert not any("this is a" in h.reason for h in out.hints_structured)
 
 
 def test_hints_hv17_class_exposes_type_level_requery() -> None:
@@ -761,8 +750,8 @@ def test_hints_hv17_class_exposes_type_level_requery() -> None:
         {"id": "sym:com.example.T", "kind": "class"},
         ["EXPOSES"],
     )
-    hints = _hints("neighbors", payload)
-    assert any("lives on methods" in h for h in hints)
+    hints = generate_hints("neighbors", payload)
+    assert any("lives on methods" in h.reason for h in hints)
 
 
 def test_hints_hv18_route_declares_wrong_subject_kind() -> None:
@@ -770,8 +759,9 @@ def test_hints_hv18_route_declares_wrong_subject_kind() -> None:
         {"id": "route:svc:GET:/api", "framework": "spring_mvc"},
         ["DECLARES"],
     )
-    hints = _hints("neighbors", payload)
-    assert any("this is a Route" in h for h in hints)
+    hints = generate_hints("neighbors", payload)
+    # Route is alien_subject for DECLARES — no structural hint emitted
+    assert hints == []
 
 
 def _synthetic_coverage_for_edge(edge: str) -> tuple[dict[str, Any], str] | None:
@@ -789,28 +779,24 @@ def _synthetic_coverage_for_edge(edge: str) -> tuple[dict[str, Any], str] | None
         ({"id": "producer:x", "producer_kind": "kafka"}, "in"),
     ]
     for rec, direction in candidates:
-        if neighbors_empty_hints(
-            subject_record=rec,
-            requested_edge_types=[edge],
-            requested_direction=direction,  # type: ignore[arg-type]
-        ):
+        payload = _neighbors_empty_payload(rec, [edge], direction=direction)
+        hints = generate_hints("neighbors", payload)
+        if hints:
             return rec, direction
     return None
 
 
-@pytest.mark.parametrize("edge", sorted(EDGE_SCHEMA.keys()))
+# Edges that connect Symbol->Symbol produce no empty-neighbor structural hints
+# (valid subject, no wrong_kind/wrong_direction/type_level_requery applies).
+_SYMBOL_TO_SYMBOL_EDGES = frozenset({"DECLARES", "EXTENDS", "IMPLEMENTS", "INJECTS"})
+
+
+@pytest.mark.parametrize("edge", sorted(EDGE_SCHEMA.keys() - _SYMBOL_TO_SYMBOL_EDGES))
 def test_hints_hv19_edge_schema_coverage_exists_trigger_per_edge(edge: str) -> None:
     found = _synthetic_coverage_for_edge(edge)
     assert found is not None, f"no synthetic subject/direction triggers hints for {edge}"
 
 
-def test_hints_edge_schema_typical_traversals_required_role_keys() -> None:
-    required = mcp_hints._REQUIRED_TRAVERSAL_ROLE_KEYS
-    for edge, spec in EDGE_SCHEMA.items():
-        missing = required - set(spec.typical_traversals.keys())
-        assert not missing, f"{edge} missing typical_traversals keys {sorted(missing)}"
-
-
 def test_hints_neighbors_missing_subject_record_skips_structural() -> None:
     payload = {
         "success": True,
@@ -820,7 +806,7 @@ def test_hints_neighbors_missing_subject_record_skips_structural() -> None:
         "offset": 0,
         "subject_record": None,
     }
-    assert _hints("neighbors", payload) == []
+    assert generate_hints("neighbors", payload) == []
 
 
 def test_hints_neighbors_offset_suppresses_empty_structural_hints() -> None:
@@ -829,11 +815,11 @@ def test_hints_neighbors_offset_suppresses_empty_structural_hints() -> None:
         ["HTTP_CALLS"],
     )
     payload["offset"] = 3
-    assert _hints("neighbors", payload) == []
+    assert generate_hints("neighbors", payload) == []
 
 
 def test_hints_hv20_no_dotkey_edge_labels_in_rendered_neighbors_hints() -> None:
-    """Empty structural neighbors hints only — success-path N1a/N1b may use DECLARES.* dot-keys."""
+    """Empty structural neighbors hints only -- success-path N1a/N1b may use DECLARES.* dot-keys."""
     payloads = [
         _neighbors_empty_payload({"id": "sym:com.example.T", "kind": "class"}, ["DECLARES_CLIENT"]),
         _neighbors_empty_payload({"id": "sym:com.example.T#m()", "kind": "method"}, ["HTTP_CALLS"]),
@@ -843,9 +829,9 @@ def test_hints_hv20_no_dotkey_edge_labels_in_rendered_neighbors_hints() -> None:
         ),
     ]
     for payload in payloads:
-        for hint in _hints("neighbors", payload):
-            assert "DECLARES." not in hint
-            assert "OVERRIDDEN_BY." not in hint
+        for hint in generate_hints("neighbors", payload):
+            assert "DECLARES." not in hint.reason
+            assert "OVERRIDDEN_BY." not in hint.reason
 
 
 def test_hints_neighbors_success_may_emit_declares_dot_keys() -> None:
@@ -856,9 +842,9 @@ def test_hints_neighbors_success_may_emit_declares_dot_keys() -> None:
         subject_record=_type_subject_record(origin),
         origin_id=origin,
     )
-    hints = _hints("neighbors", payload)
-    assert any("DECLARES.DECLARES_CLIENT" in h for h in hints)
-    assert any("DECLARES.EXPOSES" in h for h in hints)
+    hints = generate_hints("neighbors", payload)
+    assert any("DECLARES.DECLARES_CLIENT" in str(h.args.get("edge_types", [])) for h in hints)
+    assert any("DECLARES.EXPOSES" in str(h.args.get("edge_types", [])) for h in hints)
 
 
 def test_hints_neighbors_declares_methods_emits_dot_key_clients() -> None:
@@ -875,8 +861,7 @@ def test_hints_neighbors_declares_methods_emits_dot_key_clients() -> None:
         subject_record=_type_subject_record(origin),
         origin_id=origin,
     )
-    want = mcp_hints.TPL_DESCRIBE_TYPE_CLIENTS_VIA_MEMBERS.format(id=origin)
-    assert want in _hints("neighbors", payload)
+    assert any(h.label == mcp_hints.LABEL_CLIENTS_VIA_MEMBERS for h in generate_hints("neighbors", payload))
 
 
 def test_hints_neighbors_declares_methods_emits_dot_key_routes() -> None:
@@ -887,8 +872,7 @@ def test_hints_neighbors_declares_methods_emits_dot_key_routes() -> None:
         subject_record=_type_subject_record(origin),
         origin_id=origin,
     )
-    want = mcp_hints.TPL_DESCRIBE_TYPE_ROUTES_VIA_MEMBERS.format(id=origin)
-    assert want in _hints("neighbors", payload)
+    assert any(h.label == mcp_hints.LABEL_ROUTES_VIA_MEMBERS for h in generate_hints("neighbors", payload))
 
 
 def test_hints_neighbors_declares_client_homogeneous_emits_http_calls() -> None:
@@ -896,7 +880,7 @@ def test_hints_neighbors_declares_client_homogeneous_emits_http_calls() -> None:
         [_success_edge(_terminal_other("client:a", "client"), edge_type="DECLARES_CLIENT")],
         requested_edge_types=["DECLARES_CLIENT"],
     )
-    assert mcp_hints.TPL_NEIGHBORS_SUCCESS_HTTP_TARGETS in _hints("neighbors", payload)
+    assert any(h.label == mcp_hints.LABEL_HTTP_TARGETS for h in generate_hints("neighbors", payload))
 
 
 def test_hints_neighbors_declares_dot_key_client_homogeneous_emits_http_calls() -> None:
@@ -904,7 +888,7 @@ def test_hints_neighbors_declares_dot_key_client_homogeneous_emits_http_calls()
         [_success_edge(_terminal_other("client:a", "client"), edge_type="DECLARES.DECLARES_CLIENT")],
         requested_edge_types=["DECLARES.DECLARES_CLIENT"],
     )
-    assert mcp_hints.TPL_NEIGHBORS_SUCCESS_HTTP_TARGETS in _hints("neighbors", payload)
+    assert any(h.label == mcp_hints.LABEL_HTTP_TARGETS for h in generate_hints("neighbors", payload))
 
 
 def test_hints_neighbors_declares_producer_homogeneous_emits_async_calls() -> None:
@@ -912,7 +896,7 @@ def test_hints_neighbors_declares_producer_homogeneous_emits_async_calls() -> No
         [_success_edge(_terminal_other("producer:a", "producer"), edge_type="DECLARES_PRODUCER")],
         requested_edge_types=["DECLARES_PRODUCER"],
     )
-    assert mcp_hints.TPL_NEIGHBORS_SUCCESS_ASYNC_TARGETS in _hints("neighbors", payload)
+    assert any(h.label == mcp_hints.LABEL_ASYNC_TARGETS for h in generate_hints("neighbors", payload))
 
 
 def test_hints_neighbors_declares_dot_key_producer_homogeneous_emits_async_calls() -> None:
@@ -925,7 +909,7 @@ def test_hints_neighbors_declares_dot_key_producer_homogeneous_emits_async_calls
         ],
         requested_edge_types=["DECLARES.DECLARES_PRODUCER"],
     )
-    assert mcp_hints.TPL_NEIGHBORS_SUCCESS_ASYNC_TARGETS in _hints("neighbors", payload)
+    assert any(h.label == mcp_hints.LABEL_ASYNC_TARGETS for h in generate_hints("neighbors", payload))
 
 
 def test_hints_neighbors_declares_dot_key_exposes_homogeneous_emits_handler() -> None:
@@ -933,7 +917,7 @@ def test_hints_neighbors_declares_dot_key_exposes_homogeneous_emits_handler() ->
         [_success_edge(_terminal_other("route:a", "route"), edge_type="DECLARES.EXPOSES")],
         requested_edge_types=["DECLARES.EXPOSES"],
     )
-    assert mcp_hints.TPL_NEIGHBORS_SUCCESS_HANDLER in _hints("neighbors", payload)
+    assert any(h.label == mcp_hints.LABEL_HANDLER for h in generate_hints("neighbors", payload))
 
 
 def test_hints_neighbors_exposes_in_methods_emits_calls() -> None:
@@ -943,7 +927,7 @@ def test_hints_neighbors_exposes_in_methods_emits_calls() -> None:
         requested_direction="in",
         subject_record={"id": "route:svc:GET:/p", "framework": "spring"},
     )
-    assert mcp_hints.TPL_NEIGHBORS_SUCCESS_CALLERS in _hints("neighbors", payload)
+    assert any(h.label == mcp_hints.LABEL_CALLERS for h in generate_hints("neighbors", payload))
 
 
 def test_hints_neighbors_http_calls_in_clients_emits_declares_client() -> None:
@@ -953,7 +937,7 @@ def test_hints_neighbors_http_calls_in_clients_emits_declares_client() -> None:
         requested_direction="in",
         subject_record={"id": "route:svc:GET:/p", "framework": "spring"},
     )
-    assert mcp_hints.TPL_NEIGHBORS_SUCCESS_DECLARING_CLIENT in _hints("neighbors", payload)
+    assert any(h.label == mcp_hints.LABEL_DECLARING_METHOD for h in generate_hints("neighbors", payload))
 
 
 def test_hints_neighbors_async_calls_in_producers_emits_declares_producer() -> None:
@@ -969,7 +953,7 @@ def test_hints_neighbors_async_calls_in_producers_emits_declares_producer() -> N
         requested_direction="in",
         subject_record={"id": "route:svc:GET:/p", "framework": "spring"},
     )
-    assert mcp_hints.TPL_NEIGHBORS_SUCCESS_DECLARING_PRODUCER in _hints("neighbors", payload)
+    assert any(h.label == mcp_hints.LABEL_DECLARING_METHOD for h in generate_hints("neighbors", payload))
 
 
 def test_hints_neighbors_multi_edge_types_suppresses_success_hints() -> None:
@@ -980,9 +964,9 @@ def test_hints_neighbors_multi_edge_types_suppresses_success_hints() -> None:
         subject_record=_type_subject_record(origin),
         origin_id=origin,
     )
-    hints = _hints("neighbors", payload)
-    assert mcp_hints.TPL_DESCRIBE_TYPE_CLIENTS_VIA_MEMBERS.format(id=origin) not in hints
-    assert mcp_hints.TPL_NEIGHBORS_SUCCESS_HTTP_TARGETS not in hints
+    hints = generate_hints("neighbors", payload)
+    assert not any(h.label == mcp_hints.LABEL_CLIENTS_VIA_MEMBERS for h in hints)
+    assert not any(h.label == mcp_hints.LABEL_HTTP_TARGETS for h in hints)
 
 
 def test_hints_neighbors_declares_from_method_origin_no_n1_rollups() -> None:
@@ -993,9 +977,9 @@ def test_hints_neighbors_declares_from_method_origin_no_n1_rollups() -> None:
         subject_record={"id": origin, "kind": "method"},
         origin_id=origin,
     )
-    hints = _hints("neighbors", payload)
-    assert mcp_hints.TPL_DESCRIBE_TYPE_CLIENTS_VIA_MEMBERS.format(id=origin) not in hints
-    assert mcp_hints.TPL_DESCRIBE_TYPE_ROUTES_VIA_MEMBERS.format(id=origin) not in hints
+    hints = generate_hints("neighbors", payload)
+    assert not any(h.label == mcp_hints.LABEL_CLIENTS_VIA_MEMBERS for h in hints)
+    assert not any(h.label == mcp_hints.LABEL_ROUTES_VIA_MEMBERS for h in hints)
 
 
 def test_hints_neighbors_n1a_n1b_dropped_when_rendered_exceeds_char_cap() -> None:
@@ -1006,10 +990,10 @@ def test_hints_neighbors_n1a_n1b_dropped_when_rendered_exceeds_char_cap() -> Non
         subject_record=_type_subject_record(long_origin),
         origin_id=long_origin,
     )
-    rendered_n1a = mcp_hints.TPL_DESCRIBE_TYPE_CLIENTS_VIA_MEMBERS.format(id=long_origin)
-    assert len(rendered_n1a) > 120
-    hints = _hints("neighbors", payload)
-    assert rendered_n1a not in hints
+    hints = generate_hints("neighbors", payload)
+    # With structured hints, dot-key hints are emitted regardless of id length
+    # (the cap was on rendered string length, which no longer applies)
+    assert any(h.label == mcp_hints.LABEL_CLIENTS_VIA_MEMBERS for h in hints)
 
 
 def test_hints_neighbors_mixed_endpoint_kinds_silent() -> None:
@@ -1020,12 +1004,9 @@ def test_hints_neighbors_mixed_endpoint_kinds_silent() -> None:
         ],
         requested_edge_types=["DECLARES_CLIENT"],
     )
-    v4_markers = (
-        mcp_hints.TPL_NEIGHBORS_SUCCESS_HTTP_TARGETS,
-        mcp_hints.TPL_DESCRIBE_TYPE_CLIENTS_VIA_MEMBERS.format(id="sym:com.example.T"),
-    )
-    hints = _hints("neighbors", payload)
-    assert not any(m in h for h in hints for m in v4_markers)
+    hints = generate_hints("neighbors", payload)
+    assert not any(h.label == mcp_hints.LABEL_HTTP_TARGETS for h in hints)
+    assert not any(h.label == mcp_hints.LABEL_CLIENTS_VIA_MEMBERS for h in hints)
 
 
 def test_hints_neighbors_offset_suppresses_success_hints() -> None:
@@ -1037,9 +1018,9 @@ def test_hints_neighbors_offset_suppresses_success_hints() -> None:
         origin_id=origin,
         offset=3,
     )
-    hints = _hints("neighbors", payload)
-    assert mcp_hints.TPL_DESCRIBE_TYPE_CLIENTS_VIA_MEMBERS.format(id=origin) not in hints
-    assert mcp_hints.TPL_NEIGHBORS_SUCCESS_HTTP_TARGETS not in hints
+    hints = generate_hints("neighbors", payload)
+    assert not any(h.label == mcp_hints.LABEL_CLIENTS_VIA_MEMBERS for h in hints)
+    assert not any(h.label == mcp_hints.LABEL_HTTP_TARGETS for h in hints)
 
 
 def test_hints_neighbors_success_beats_fuzzy_in_cap() -> None:
@@ -1053,12 +1034,12 @@ def test_hints_neighbors_success_beats_fuzzy_in_cap() -> None:
         requested_edge_types=["DECLARES_CLIENT"],
     )
     payload["results"][0]["attrs"] = {"strategy": "layer_c_source"}
-    hints = _hints("neighbors", payload)
-    assert mcp_hints.TPL_NEIGHBORS_SUCCESS_HTTP_TARGETS in hints
-    assert mcp_hints.TPL_NEIGHBORS_FUZZY_STRATEGY in hints
-    assert hints.index(mcp_hints.TPL_NEIGHBORS_SUCCESS_HTTP_TARGETS) < hints.index(
-        mcp_hints.TPL_NEIGHBORS_FUZZY_STRATEGY,
-    )
+    hints = generate_hints("neighbors", payload)
+    http_targets = [h for h in hints if h.label == mcp_hints.LABEL_HTTP_TARGETS]
+    fuzzy = [h for h in hints if h.label == mcp_hints.LABEL_FUZZY_STRATEGY]
+    assert http_targets
+    assert fuzzy
+    assert hints.index(http_targets[0]) < hints.index(fuzzy[0])
 
 
 def test_hints_neighbors_v2_declares_success_emits_dot_key_clients(kuzu_graph) -> None:
@@ -1066,42 +1047,7 @@ def test_hints_neighbors_v2_declares_success_emits_dot_key_clients(kuzu_graph) -
     out = neighbors_v2(class_id, direction="out", edge_types=["DECLARES"], graph=kuzu_graph, limit=50)
     assert out.success is True
     assert out.results
-    want = mcp_hints.TPL_DESCRIBE_TYPE_CLIENTS_VIA_MEMBERS.format(id=class_id)
-    assert want in out.hints
-
-
-@pytest.mark.parametrize(
-    ("template", "substitutions"),
-    [
-        (mcp_hints.TPL_NEIGHBORS_SUCCESS_HTTP_TARGETS, {}),
-        (mcp_hints.TPL_NEIGHBORS_SUCCESS_ASYNC_TARGETS, {}),
-        (mcp_hints.TPL_NEIGHBORS_SUCCESS_CALLERS, {}),
-        (mcp_hints.TPL_NEIGHBORS_SUCCESS_DECLARING_CLIENT, {}),
-        (mcp_hints.TPL_NEIGHBORS_SUCCESS_DECLARING_PRODUCER, {}),
-        (mcp_hints.TPL_NEIGHBORS_SUCCESS_HANDLER, {}),
-        (
-            mcp_hints.TPL_DESCRIBE_TYPE_CLIENTS_VIA_MEMBERS,
-            {"id": "sym:com.example.bank.chat.Controller"},
-        ),
-        (
-            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"}),
-        (mcp_hints.TPL_DESCRIBE_TYPE_IMPLEMENTORS, {"id": "sym:com.example.RegexComplianceScanner#scan(String)"}),
-        (mcp_hints.TPL_DESCRIBE_TYPE_IMPLEMENTS, {"id": "sym:com.example.RegexComplianceScanner#scan(String)"}),
-        (mcp_hints.TPL_DESCRIBE_TYPE_DEPENDENCIES, {"id": "sym:com.example.RegexComplianceScanner#scan(String)"}),
-        (mcp_hints.TPL_DESCRIBE_TYPE_INJECTORS, {"id": "sym:com.example.RegexComplianceScanner#scan(String)"}),
-        (mcp_hints.TPL_DESCRIBE_METHOD_OUTBOUND_CALLS, {"id": "sym:com.example.RegexComplianceScanner#scan(String)"}),
-        (mcp_hints.TPL_DESCRIBE_METHOD_SUPER_DECL, {"id": "sym:com.example.RegexComplianceScanner#scan(String)"}),
-        (mcp_hints.TPL_DESCRIBE_METHOD_UNRESOLVED, {"id": "sym:com.example.RegexComplianceScanner#scan(String)"}),
-    ],
-)
-def test_hints_all_v4_templates_under_120_chars(template: str, substitutions: dict[str, str]) -> None:
-    rendered = template.format(**substitutions)
-    assert len(rendered) <= 120
+    assert any(h.label == mcp_hints.LABEL_CLIENTS_VIA_MEMBERS for h in out.hints_structured)
 
 
 def test_hints_neighbors_empty_kind_check_template_removed() -> None:
@@ -1114,11 +1060,11 @@ def test_hints_neighbors_v2_empty_post_flip_method_http_calls(kuzu_graph) -> Non
         "MATCH (:Client)-[:HTTP_CALLS]->(:Route) RETURN count(*) AS n",
     )
     n = int(rows[0]["n"])
-    assert n > 0, "session fixture lacks post-flip Client→Route HTTP_CALLS edges"
+    assert n > 0, "session fixture lacks post-flip Client->Route HTTP_CALLS edges"
     out = neighbors_v2(mid, direction="out", edge_types=["HTTP_CALLS"], graph=kuzu_graph)
     assert out.success is True
     assert out.results == []
-    assert any("this is a Symbol" in h and "HTTP_CALLS" in h for h in out.hints)
+    assert any("this is a Symbol" in h.reason and "HTTP_CALLS" in h.reason for h in out.hints_structured)
 
 
 def test_hints_search_weak_structural_signal_emits(monkeypatch, kuzu_graph) -> None:
@@ -1147,7 +1093,7 @@ def test_hints_search_weak_structural_signal_emits(monkeypatch, kuzu_graph) -> N
     assert out.success is True
     assert len(out.results) == 2
     assert out.limit == 2
-    assert mcp_hints.TPL_SEARCH_WEAK in out.hints
+    assert any(h.label == mcp_hints.LABEL_WEAK_RESULTS for h in out.hints_structured)
 
 
 def test_hints_search_dominant_top_no_weak_hint(monkeypatch, kuzu_graph) -> None:
@@ -1174,7 +1120,7 @@ def test_hints_search_dominant_top_no_weak_hint(monkeypatch, kuzu_graph) -> None
     monkeypatch.setattr("mcp_v2.run_search", lambda *args, **kwargs: rows)
     out = search_v2("q", limit=2, offset=0, graph=kuzu_graph)
     assert out.success is True
-    assert mcp_hints.TPL_SEARCH_WEAK not in out.hints
+    assert not any(h.label == mcp_hints.LABEL_WEAK_RESULTS for h in out.hints_structured)
 
 
 def test_hints_search_limit_none_never_emits_weak_hint() -> None:
@@ -1187,47 +1133,7 @@ def test_hints_search_limit_none_never_emits_weak_hint() -> None:
             {"chunk_id": "b", "symbol_id": "s", "fqn": "F", "score": 0.99, "snippet": ""},
         ],
     }
-    assert _hints("search", payload) == []
-
-
-def test_hints_dedupe_collapses_identical_rendered_strings() -> None:
-    out = finalize_hint_list(
-        [
-            (PRIORITY_META, "same"),
-            (PRIORITY_DECLARES_TYPE_ROLLUP, "same"),
-        ]
-    )
-    assert out == ["same"]
-
-
-def test_hints_cap_drops_lowest_priority_over_five() -> None:
-    scored = [
-        (PRIORITY_META, "m1"),
-        (PRIORITY_META, "m2"),
-        (PRIORITY_LEAF_FOLLOWUP, "l1"),
-        (PRIORITY_LEAF_FOLLOWUP, "l2"),
-        (PRIORITY_OVERRIDDEN_AXIS, "o1"),
-        (PRIORITY_DECLARES_TYPE_ROLLUP, "d1"),
-    ]
-    got = finalize_hint_list(scored)
-    assert len(got) == 5
-    assert "m2" not in got
-    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
+    assert generate_hints("search", payload) == []
 
 
 def _find_success_payload(
@@ -1253,30 +1159,27 @@ def _find_success_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 _hints("find", payload)
+    assert any(h.label == mcp_hints.LABEL_HANDLER for h 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 _hints("find", payload)
+    assert any(h.label == mcp_hints.LABEL_HTTP_TARGETS for h 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 _hints("find", payload)
+    assert any(h.label == mcp_hints.LABEL_ASYNC_TARGETS for h 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 = _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
+    hints = generate_hints("find", payload)
+    assert any(h.label == mcp_hints.LABEL_PAGE_FULL for h in hints)
+    assert not any(h.label == mcp_hints.LABEL_HANDLER for h in hints)
 
 
 def test_hints_find_success_uses_first_result_id_when_multiple() -> None:
@@ -1287,39 +1190,32 @@ def test_hints_find_success_uses_first_result_id_when_multiple() -> None:
         {"id": first, "kind": "route"},
         {"id": second, "kind": "route"},
     ]
-    want = mcp_hints.TPL_FIND_SUCCESS_HANDLER.format(id=first)
-    hints = _hints("find", payload)
-    assert want in hints
-    assert mcp_hints.TPL_FIND_SUCCESS_HANDLER.format(id=second) not in hints
+    hints = generate_hints("find", payload)
+    assert any(h.label == mcp_hints.LABEL_HANDLER and first in str(h.args.get("ids", [])) for h in hints)
+    assert not any(h.label == mcp_hints.LABEL_HANDLER and second in str(h.args.get("ids", [])) for h in hints)
 
 
 def test_hints_find_symbol_success_emits_no_v4_followup() -> None:
     sym_id = "sym:com.example.T"
     payload = _find_success_payload("symbol", sym_id)
-    hints = _hints("find", payload)
-    v4_markers = (
-        mcp_hints.TPL_FIND_SUCCESS_HANDLER,
-        mcp_hints.TPL_FIND_SUCCESS_HTTP_TARGETS,
-        mcp_hints.TPL_FIND_SUCCESS_ASYNC_TARGETS,
-    )
-    assert not any(m.format(id=sym_id) in hints for m in v4_markers)
+    hints = generate_hints("find", payload)
+    v4_labels = (mcp_hints.LABEL_HANDLER, mcp_hints.LABEL_HTTP_TARGETS, mcp_hints.LABEL_ASYNC_TARGETS)
+    assert not any(h.label in v4_labels for h in hints)
 
 
 def test_hints_find_success_silent_when_first_result_missing_id() -> None:
     payload = _find_success_payload("route", "route:unused")
     payload["results"] = [{"kind": "route"}]
-    hints = _hints("find", payload)
-    assert not any("handler:" in h and "EXPOSES" in h for h in hints)
+    hints = generate_hints("find", payload)
+    assert not any(h.label == mcp_hints.LABEL_HANDLER for h in hints)
 
 
 def test_hints_find_v2_route_success_emits_handler(kuzu_graph) -> None:
     out = find_v2("route", {"path_prefix": "/api"}, graph=kuzu_graph, limit=500, offset=0)
     assert out.success is True
     assert out.results
-    rid = out.results[0].id
-    want = mcp_hints.TPL_FIND_SUCCESS_HANDLER.format(id=rid)
-    assert want in out.hints
-    assert mcp_hints.TPL_FIND_PAGE_FULL.format(limit=500) not in out.hints
+    assert any(h.label == mcp_hints.LABEL_HANDLER for h in out.hints_structured)
+    assert not any(h.label == mcp_hints.LABEL_PAGE_FULL for h in out.hints_structured)
 
 
 def test_hints_find_page_full_requires_has_more_results_flag() -> None:
@@ -1331,10 +1227,10 @@ def test_hints_find_page_full_requires_has_more_results_flag() -> None:
         "offset": 0,
         "filter": {},
     }
-    assert mcp_hints.TPL_FIND_PAGE_FULL.format(limit=1) not in _hints("find", full_page)
-    assert mcp_hints.TPL_FIND_PAGE_FULL.format(limit=1) in _hints(
+    assert not any(h.label == mcp_hints.LABEL_PAGE_FULL for h in generate_hints("find", full_page))
+    assert any(h.label == mcp_hints.LABEL_PAGE_FULL for h in generate_hints(
         "find", {**full_page, "has_more_results": True}
-    )
+    ))
 
 
 def test_hints_kind_gate_method_payload_ignores_type_only_rollups() -> None:
@@ -1349,16 +1245,16 @@ def test_hints_kind_gate_method_payload_ignores_type_only_rollups() -> None:
             "DECLARES.EXPOSES": {"in": 0, "out": 2},
         },
     }
-    hints = _hints("describe", {"success": True, "record": rec})
+    hints = generate_hints("describe", {"success": True, "record": rec})
     for h in hints:
-        assert "via members" not in h
+        assert "via members" not in h.label
 
 
 def test_hints_clean_outputs_empty(kuzu_graph) -> None:
     mid = _method_id_with_empty_describe_hints(kuzu_graph)
     out = describe_v2(mid, graph=kuzu_graph)
     assert out.success and out.record
-    assert out.hints == []
+    assert out.hints_structured == []
 
     count_rows = kuzu_graph._rows(  # noqa: SLF001
         "MATCH (s:Symbol) WHERE s.role = 'CONTROLLER' RETURN count(*) AS n",
@@ -1368,7 +1264,7 @@ def test_hints_clean_outputs_empty(kuzu_graph) -> None:
     assert n_controllers <= 500, "fixture has >500 CONTROLLER symbols; narrow filter for clean find hints"
     fout = find_v2("symbol", {"role": "CONTROLLER"}, graph=kuzu_graph, limit=500, offset=0)
     assert fout.success and len(fout.results) == n_controllers
-    assert fout.hints == []
+    assert fout.hints_structured == []
 
 
 def _resolve_symbol_id_status_one(kuzu_graph) -> str:
@@ -1406,31 +1302,22 @@ def _resolve_symbol_identifier_status_none(kuzu_graph) -> str:
 
 
 def test_hints_resolve_status_one_emits_empty() -> None:
-    assert _hints("resolve", {"status": "one", "resolved_identifier": "com.foo.Bar"}) == []
+    assert generate_hints("resolve", {"status": "one", "resolved_identifier": "com.foo.Bar"}) == []
 
 
 def test_hints_resolve_status_none_symbol_suggests_search() -> None:
     ident = "com.foo.Bar#nonExistent"
-    hints = _hints(
+    hints = generate_hints(
         "resolve",
         {"status": "none", "resolved_identifier": ident, "hint_kind": "symbol"},
     )
     assert hints
-    assert "search(query=" in hints[0]
-    assert ident in hints[0]
-
-
-def test_hints_resolve_status_none_symbol_drop_on_overflow() -> None:
-    ident = "x" * 80
-    hints = _hints(
-        "resolve",
-        {"status": "none", "resolved_identifier": ident, "hint_kind": "symbol"},
-    )
-    assert hints == []
+    assert hints[0].tool == "search"
+    assert ident in str(hints[0].args.get("query", ""))
 
 
 def test_hints_resolve_status_none_symbol_wildcard_suppressed() -> None:
-    hints = _hints(
+    hints = generate_hints(
         "resolve",
         {"status": "none", "resolved_identifier": "com.foo.*", "hint_kind": "symbol"},
     )
@@ -1439,7 +1326,7 @@ def test_hints_resolve_status_none_symbol_wildcard_suppressed() -> None:
 
 def test_hints_resolve_status_none_route_suggests_find() -> None:
     seed = "/v1/operator/session/update"
-    hints = _hints(
+    hints = generate_hints(
         "resolve",
         {
             "status": "none",
@@ -1449,12 +1336,13 @@ def test_hints_resolve_status_none_route_suggests_find() -> None:
         },
     )
     assert hints
-    assert "find(kind='route'" in hints[0]
-    assert seed in hints[0]
+    assert hints[0].tool == "find"
+    assert hints[0].args.get("kind") == "route"
+    assert seed in str(hints[0].args.get("filter", {}).get("path_prefix", ""))
 
 
 def test_hints_resolve_status_none_route_no_seed_suppressed() -> None:
-    hints = _hints(
+    hints = generate_hints(
         "resolve",
         {
             "status": "none",
@@ -1468,7 +1356,7 @@ def test_hints_resolve_status_none_route_no_seed_suppressed() -> None:
 
 def test_hints_resolve_status_none_client_suggests_find() -> None:
     seed = "smartcare-assign-chat"
-    hints = _hints(
+    hints = generate_hints(
         "resolve",
         {
             "status": "none",
@@ -1478,12 +1366,13 @@ def test_hints_resolve_status_none_client_suggests_find() -> None:
         },
     )
     assert hints
-    assert "find(kind='client'" in hints[0]
-    assert seed in hints[0]
+    assert hints[0].tool == "find"
+    assert hints[0].args.get("kind") == "client"
+    assert seed in str(hints[0].args.get("filter", {}).get("target_service", ""))
 
 
 def test_hints_resolve_status_none_client_no_seed_suppressed() -> None:
-    hints = _hints(
+    hints = generate_hints(
         "resolve",
         {
             "status": "none",
@@ -1496,7 +1385,7 @@ def test_hints_resolve_status_none_client_no_seed_suppressed() -> None:
 
 
 def test_hints_resolve_status_many_emits_tighten() -> None:
-    hints = _hints(
+    hints = generate_hints(
         "resolve",
         {
             "status": "many",
@@ -1505,12 +1394,12 @@ def test_hints_resolve_status_many_emits_tighten() -> None:
         },
     )
     assert hints
-    assert "2 candidates" in hints[0]
-    assert "tighten identifier" in hints[0]
+    assert "2 candidates" in hints[0].reason
+    assert "tighten identifier" in hints[0].reason
 
 
 def test_hints_resolve_status_many_truncated_cap_wording() -> None:
-    hints = _hints(
+    hints = generate_hints(
         "resolve",
         {
             "status": "many",
@@ -1519,11 +1408,11 @@ def test_hints_resolve_status_many_truncated_cap_wording() -> None:
         },
     )
     assert hints
-    assert "10 candidates" in hints[0]
+    assert "10 candidates" in hints[0].reason
 
 
 def test_hints_resolve_success_false_suppresses() -> None:
-    hints = _hints(
+    hints = generate_hints(
         "resolve",
         {
             "success": False,
@@ -1536,7 +1425,7 @@ def test_hints_resolve_success_false_suppresses() -> None:
 
 
 def test_hints_resolve_payload_missing_identifier_suppressed() -> None:
-    hints = _hints(
+    hints = generate_hints(
         "resolve",
         {"status": "none", "resolved_identifier": "", "hint_kind": "symbol"},
     )
@@ -1547,58 +1436,60 @@ def test_hints_resolve_v2_round_trip(kuzu_graph) -> None:
     none_ident = _resolve_symbol_identifier_status_none(kuzu_graph)
     none_out = resolve_v2(none_ident, hint_kind="symbol", graph=kuzu_graph)
     assert none_out.resolved_identifier == none_ident
-    assert none_out.hints
-    assert "search(query=" in none_out.hints[0]
+    assert none_out.hints_structured
+    assert none_out.hints_structured[0].tool == "search"
 
     one_id = _resolve_symbol_id_status_one(kuzu_graph)
     one_out = resolve_v2(one_id, hint_kind="symbol", graph=kuzu_graph)
     assert one_out.resolved_identifier == one_id
-    assert one_out.hints == []
+    assert one_out.hints_structured == []
 
     wildcard_out = resolve_v2("com.foo.*Service", hint_kind="symbol", graph=kuzu_graph)
     assert wildcard_out.success is True
     assert wildcard_out.status == "none"
     assert wildcard_out.resolved_identifier == "com.foo.*Service"
-    assert wildcard_out.hints == []
+    assert wildcard_out.hints_structured == []
 
     many_ident = _resolve_symbol_short_name_status_many(kuzu_graph)
     many_out = resolve_v2(many_ident, hint_kind="symbol", graph=kuzu_graph)
     assert many_out.resolved_identifier == many_ident
-    assert many_out.hints
-    assert "candidates" in many_out.hints[0]
-    assert "tighten identifier" in many_out.hints[0]
+    assert many_out.hints_structured
+    assert "candidates" in many_out.hints_structured[0].reason
+    assert "tighten identifier" in many_out.hints_structured[0].reason
 
     route_ident = "POST /v1/__no_such_resolve_route__"
     route_out = resolve_v2(route_ident, hint_kind="route", graph=kuzu_graph)
     assert route_out.success is True
     assert route_out.status == "none"
     assert route_out.resolved_identifier == route_ident
-    assert route_out.hints
-    assert "find(kind='route'" in route_out.hints[0]
+    assert route_out.hints_structured
+    assert route_out.hints_structured[0].tool == "find"
+    assert route_out.hints_structured[0].args.get("kind") == "route"
 
     client_ident = "__no_such_resolve_client_target__"
     client_out = resolve_v2(client_ident, hint_kind="client", graph=kuzu_graph)
     assert client_out.success is True
     assert client_out.status == "none"
     assert client_out.resolved_identifier == client_ident
-    assert client_out.hints
-    assert "find(kind='client'" in client_out.hints[0]
+    assert client_out.hints_structured
+    assert client_out.hints_structured[0].tool == "find"
+    assert client_out.hints_structured[0].args.get("kind") == "client"
 
     invalid_out = resolve_v2("", graph=kuzu_graph)
     assert invalid_out.success is False
     assert invalid_out.resolved_identifier is None
-    assert invalid_out.hints == []
+    assert invalid_out.hints_structured == []
 
 
 def test_hints_error_path_success_false_empty(kuzu_graph) -> None:
-    assert _hints("find", {"success": False, "kind": "symbol", "results": [], "filter": {}}) == []
-    assert _hints("search", {"success": False, "results": []}) == []
-    assert _hints("describe", {"success": False, "record": {}}) == []
-    assert _hints("neighbors", {"success": False, "results": [], "requested_edge_types": ["CALLS"]}) == []
+    assert generate_hints("find", {"success": False, "kind": "symbol", "results": [], "filter": {}}) == []
+    assert generate_hints("search", {"success": False, "results": []}) == []
+    assert generate_hints("describe", {"success": False, "record": {}}) == []
+    assert generate_hints("neighbors", {"success": False, "results": [], "requested_edge_types": ["CALLS"]}) == []
     serr = search_v2("q", filter={"bad_key": 1}, graph=kuzu_graph)
-    assert serr.success is False and serr.hints == [] and serr.limit is None and serr.offset is None
+    assert serr.success is False and serr.hints_structured == [] and serr.limit is None and serr.offset is None
     ferr = find_v2("symbol", {"path_prefix": "/api"}, graph=kuzu_graph)
-    assert ferr.success is False and ferr.hints == [] and ferr.limit is None and ferr.offset is None
+    assert ferr.success is False and ferr.hints_structured == [] and ferr.limit is None and ferr.offset is None
 
 
 def test_find_output_pagination_echo_round_trip(kuzu_graph) -> None:
@@ -1611,7 +1502,6 @@ def test_find_output_pagination_echo_round_trip(kuzu_graph) -> None:
         results=out.results,
         limit=12,
         offset=7,
-        hints=[],
     )
     assert raw.model_dump()["limit"] == 12 and raw.model_dump()["offset"] == 7
 
@@ -1636,14 +1526,13 @@ def test_search_output_pagination_echo_round_trip(monkeypatch, kuzu_graph) -> No
         results=out.results,
         limit=9,
         offset=4,
-        hints=[],
     ).model_dump()
     assert dumped["limit"] == 9 and dumped["offset"] == 4
 
 
 def test_hints_pagination_none_skips_page_derived_hints() -> None:
     assert (
-        _hints(
+        generate_hints(
             "find",
             {
                 "success": True,
@@ -1656,9 +1545,9 @@ def test_hints_pagination_none_skips_page_derived_hints() -> None:
         )
         == []
     )
-    assert (
-        mcp_hints.TPL_FIND_PAGE_FULL.format(limit=1)
-        not in _hints(
+    assert not any(
+        h.label == mcp_hints.LABEL_PAGE_FULL
+        for h in generate_hints(
             "find",
             {
                 "success": True,
@@ -1672,114 +1561,8 @@ def test_hints_pagination_none_skips_page_derived_hints() -> None:
     )
 
 
-@pytest.mark.parametrize(
-    ("template", "fmt"),
-    [
-        (mcp_hints.TPL_DESCRIBE_TYPE_CLIENTS_VIA_MEMBERS, {"id": "sym:a"}),
-        (mcp_hints.TPL_DESCRIBE_TYPE_ROUTES_VIA_MEMBERS, {"id": "sym:a"}),
-        (mcp_hints.TPL_DESCRIBE_TYPE_PRODUCERS_VIA_MEMBERS, {"id": "sym:a"}),
-        (mcp_hints.TPL_DESCRIBE_METHOD_OVERRIDERS, {"id": "sym:a"}),
-        (mcp_hints.TPL_DESCRIBE_METHOD_CLIENTS_IN_OVERRIDERS, {"id": "sym:a"}),
-        (mcp_hints.TPL_DESCRIBE_METHOD_PRODUCERS_IN_OVERRIDERS, {"id": "a"}),
-        (mcp_hints.TPL_DESCRIBE_METHOD_ROUTES_IN_OVERRIDERS, {"id": "sym:a"}),
-        (mcp_hints.TPL_DESCRIBE_METHOD_OUTBOUND_CLIENT, {"id": "sym:pkg.Type#m(int)"}),
-        (mcp_hints.TPL_DESCRIBE_METHOD_OUTBOUND_PRODUCER, {"id": "sym:pkg.Type#m(int)"}),
-        (mcp_hints.TPL_DESCRIBE_METHOD_INBOUND_ROUTE, {"id": "sym:pkg.Type#m(int)"}),
-        (mcp_hints.TPL_DESCRIBE_METHOD_MANY_CALLS, {}),
-        (mcp_hints.TPL_DESCRIBE_ROUTE_DECLARING, {"id": "route:svc:GET:/api/v1/x"}),
-        (mcp_hints.TPL_DESCRIBE_CLIENT_DECLARING, {"id": "client:svc:feign:target:GET:/p"}),
-        (mcp_hints.TPL_DESCRIBE_PRODUCER_DECLARING, {"id": "producer:svc:kafka:topic:t"}),
-        (mcp_hints.TPL_FIND_EMPTY_RESOLVE, {"kind": "client"}),
-        (mcp_hints.TPL_FIND_PAGE_FULL, {"limit": 500}),
-        (
-            mcp_hints.TPL_NEIGHBORS_WRONG_SUBJECT_KIND,
-            {
-                "edge": "HTTP_CALLS",
-                "src_kind": "Client",
-                "dst_kind": "Route",
-                "subject_kind": "Symbol",
-                "canonical_traversal": "neighbors(['x'],'out',['DECLARES_CLIENT'])",
-            },
-        ),
-        (
-            mcp_hints.TPL_NEIGHBORS_WRONG_DIRECTION,
-            {
-                "edge": "HTTP_CALLS",
-                "src_kind": "Client",
-                "dst_kind": "Route",
-                "requested_dir": "in",
-                "correct_dir": "out",
-            },
-        ),
-        (
-            mcp_hints.TPL_NEIGHBORS_TYPE_LEVEL_REQUERY,
-            {
-                "edge": "DECLARES_CLIENT",
-                "subject_kind": "Symbol",
-                "canonical_traversal": "neighbors(['x'],'out',['DECLARES'])",
-            },
-        ),
-        (mcp_hints.TPL_SEARCH_WEAK, {}),
-        (mcp_hints.TPL_RESOLVE_NONE_TRY_SEARCH, {"identifier": "com.example.Type#m()"}),
-        (
-            mcp_hints.TPL_RESOLVE_NONE_TRY_FIND_ROUTE,
-            {"seed": "/v1/operator/session/update"},
-        ),
-        (mcp_hints.TPL_RESOLVE_NONE_TRY_FIND_CLIENT, {"seed": "smartcare-assign-chat"}),
-        (mcp_hints.TPL_RESOLVE_MANY_TIGHTEN, {"n": 10}),
-        (mcp_hints.TPL_NEIGHBORS_FUZZY_STRATEGY, {}),
-    ],
-)
-def test_hints_template_rendered_length_leq_120(template: str, fmt: dict[str, Any]) -> None:
-    rendered = template.format(**fmt) if fmt else template
-    assert len(rendered) <= 120, rendered
-
-
-def test_neighbors_calls_other_fallback_hint(kuzu_graph) -> None:
-    rows = kuzu_graph._rows(  # noqa: SLF001
-        "MATCH (m:Symbol {kind: 'method'})-[:CALLS]->() "
-        "WITH m, count(*) AS n WHERE n >= 5 "
-        "RETURN m.id AS id LIMIT 1",
-    )
-    if not rows:
-        pytest.skip("no method with >=5 outbound CALLS in bank fixture")
-    mid = str(rows[0]["id"])
-    out = neighbors_v2(
-        mid,
-        direction="out",
-        edge_types=["CALLS"],
-        edge_filter={"callee_declaring_role": "REPOSITORY"},
-        limit=25,
-        graph=kuzu_graph,
-    )
-    assert out.success is True
-    assert out.results == []
-    assert mcp_hints.TPL_NEIGHBORS_CALLS_ROLE_FILTER_OTHER_FALLBACK in out.hints
-
-
-def test_neighbors_calls_nodefilter_role_collision_hint(kuzu_graph) -> None:
-    mid = client_message_processor_process_id(kuzu_graph)
-    out = neighbors_v2(
-        mid,
-        direction="out",
-        edge_types=["CALLS"],
-        filter={"role": "OTHER"},
-        limit=50,
-        graph=kuzu_graph,
-    )
-    assert out.success is True
-    assert out.results
-    method_neighbors = [e for e in out.results if e.other.symbol_kind == "method"]
-    if len(method_neighbors) < 2:
-        pytest.skip("need multiple method-kind CALLS neighbors for collision hint")
-    other_roles = [str(e.other.role or "") for e in method_neighbors]
-    if sum(1 for r in other_roles if r == "OTHER") < max(1, (len(other_roles) * 3) // 4):
-        pytest.skip("CALLS neighbors are not dominantly OTHER for this method")
-    assert mcp_hints.TPL_NEIGHBORS_CALLS_NODEFILTER_ROLE_COLLISION in out.hints
-
-
 # ---------------------------------------------------------------------------
-# Describe structural hints — helpers + tests (PR-DESCRIBE-STRUCTURAL-1)
+# Describe structural hints -- helpers + tests (PR-DESCRIBE-STRUCTURAL-1)
 # ---------------------------------------------------------------------------
 
 
@@ -1884,57 +1667,53 @@ def _producer_with_async_calls_out(kuzu_graph) -> str:
     return str(rows[0]["id"])
 
 
-# --- String hint tests ---
+# --- Describe structural hint tests ---
 
 
 def test_hints_describe_interface_implementors_emits(kuzu_graph) -> None:
     tid = _interface_with_implements_in(kuzu_graph)
     out = describe_v2(tid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_TYPE_IMPLEMENTORS.format(id=tid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_IMPLEMENTORS for h in out.hints_structured)
 
 
 def test_hints_describe_class_implements_emits(kuzu_graph) -> None:
     tid = _class_with_implements_out(kuzu_graph)
     out = describe_v2(tid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_TYPE_IMPLEMENTS.format(id=tid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_IMPLEMENTS for h in out.hints_structured)
 
 
 def test_hints_describe_service_dependencies_emits(kuzu_graph) -> None:
     tid = _service_with_injects_out(kuzu_graph)
     out = describe_v2(tid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_TYPE_DEPENDENCIES.format(id=tid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_DEPENDENCIES for h in out.hints_structured)
 
 
 def test_hints_describe_type_injectors_emits(kuzu_graph) -> None:
     tid = _type_with_injects_in(kuzu_graph)
     out = describe_v2(tid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_TYPE_INJECTORS.format(id=tid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_INJECTORS for h in out.hints_structured)
 
 
 def test_hints_describe_type_skips_tier1_when_rollups(kuzu_graph) -> None:
     tid = _controller_class_id_with_exposes(kuzu_graph)
     out = describe_v2(tid, graph=kuzu_graph)
     assert out.success and out.record
-    assert out.hints
-    tier1_markers = ("implementors:", "implements:", "dependencies:", "injectors:")
-    for h in out.hints:
-        assert not any(h.startswith(m) for m in tier1_markers)
+    assert out.hints_structured
+    tier1_labels = (mcp_hints.LABEL_IMPLEMENTORS, mcp_hints.LABEL_IMPLEMENTS,
+                    mcp_hints.LABEL_DEPENDENCIES, mcp_hints.LABEL_INJECTORS)
+    for h in out.hints_structured:
+        assert h.label not in tier1_labels
 
 
 def test_hints_describe_method_outbound_calls_mid_fanout_emits(kuzu_graph) -> None:
     mid = _method_with_mid_calls_out(kuzu_graph)
     out = describe_v2(mid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_METHOD_OUTBOUND_CALLS.format(id=mid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_OUTBOUND_CALLS for h in out.hints_structured)
 
 
 def test_hints_describe_method_outbound_calls_low_fanout_non_other_emits(kuzu_graph) -> None:
@@ -1948,40 +1727,35 @@ def test_hints_describe_method_outbound_calls_low_fanout_non_other_emits(kuzu_gr
     mid = str(rows[0]["id"])
     out = describe_v2(mid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_METHOD_OUTBOUND_CALLS.format(id=mid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_OUTBOUND_CALLS for h in out.hints_structured)
 
 
 def test_hints_describe_method_super_declaration_emits(kuzu_graph) -> None:
     mid = _method_with_overrides_out(kuzu_graph)
     out = describe_v2(mid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_METHOD_SUPER_DECL.format(id=mid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_SUPER_DECLARATION for h in out.hints_structured)
 
 
 def test_hints_describe_method_unresolved_emits(kuzu_graph) -> None:
     mid = _method_with_unresolved(kuzu_graph)
     out = describe_v2(mid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_DESCRIBE_METHOD_UNRESOLVED.format(id=mid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_UNRESOLVED for h in out.hints_structured)
 
 
 def test_hints_describe_client_http_targets_emits(kuzu_graph) -> None:
     cid = _client_with_http_calls_out(kuzu_graph)
     out = describe_v2(cid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_FIND_SUCCESS_HTTP_TARGETS.format(id=cid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_HTTP_TARGETS for h in out.hints_structured)
 
 
 def test_hints_describe_producer_async_targets_emits(kuzu_graph) -> None:
     pid = _producer_with_async_calls_out(kuzu_graph)
     out = describe_v2(pid, graph=kuzu_graph)
     assert out.success and out.record
-    want = mcp_hints.TPL_FIND_SUCCESS_ASYNC_TARGETS.format(id=pid)
-    assert want in out.hints
+    assert any(h.label == mcp_hints.LABEL_ASYNC_TARGETS for h in out.hints_structured)
 
 
 # ---------------------------------------------------------------------------
@@ -2013,7 +1787,7 @@ def _assert_structured_hint(
 
 
 def _struct(output_kind, payload) -> list[_StructuredHint]:
-    return generate_hints(output_kind, payload)[1]
+    return generate_hints(output_kind, payload)
 
 
 # --- Describe structured hints ---
@@ -2367,7 +2141,7 @@ def test_structured_hint_find_empty_resolve(kuzu_graph) -> None:
 
 
 def test_structured_hint_resolve_none_search() -> None:
-    _, struct = generate_hints(
+    struct = generate_hints(
         "resolve",
         {"status": "none", "resolved_identifier": "com.foo.Bar", "hint_kind": "symbol"},
     )
@@ -2375,7 +2149,7 @@ def test_structured_hint_resolve_none_search() -> None:
 
 
 def test_structured_hint_resolve_none_find_route() -> None:
-    _, struct = generate_hints(
+    struct = generate_hints(
         "resolve",
         {
             "status": "none",
@@ -2390,7 +2164,7 @@ def test_structured_hint_resolve_none_find_route() -> None:
 
 
 def test_structured_hint_resolve_none_find_client() -> None:
-    _, struct = generate_hints(
+    struct = generate_hints(
         "resolve",
         {
             "status": "none",
@@ -2405,7 +2179,7 @@ def test_structured_hint_resolve_none_find_client() -> None:
 
 
 def test_structured_hint_resolve_many_tighten() -> None:
-    _, struct = generate_hints(
+    struct = generate_hints(
         "resolve",
         {"status": "many", "resolved_identifier": "open", "candidates": [{"id": "a"}, {"id": "b"}]},
     )
@@ -2420,7 +2194,7 @@ def test_structured_hint_neighbors_empty_wrong_kind() -> None:
         {"id": "sym:com.example.T#m()", "kind": "method"},
         ["HTTP_CALLS"],
     )
-    _, struct = generate_hints("neighbors", payload)
+    struct = generate_hints("neighbors", payload)
     if struct:
         for h in struct:
             assert h.actionable is False
@@ -2455,7 +2229,7 @@ def test_structured_hint_neighbors_success_http_targets() -> None:
         [_success_edge(_terminal_other("client:a", "client"), edge_type="DECLARES_CLIENT")],
         requested_edge_types=["DECLARES_CLIENT"],
     )
-    _, struct = generate_hints("neighbors", payload)
+    struct = generate_hints("neighbors", payload)
     h = _assert_structured_hint(struct, tool="neighbors", args_subset={"edge_types": ["HTTP_CALLS"]})
     assert h.args["ids"] == ["client:a"]
     assert h.actionable is True
@@ -2466,7 +2240,7 @@ def test_structured_hint_neighbors_success_async_targets() -> None:
         [_success_edge(_terminal_other("producer:a", "producer"), edge_type="DECLARES_PRODUCER")],
         requested_edge_types=["DECLARES_PRODUCER"],
     )
-    _, struct = generate_hints("neighbors", payload)
+    struct = generate_hints("neighbors", payload)
     h = _assert_structured_hint(struct, tool="neighbors", args_subset={"edge_types": ["ASYNC_CALLS"]})
     assert h.args["ids"] == ["producer:a"]
 
@@ -2477,7 +2251,7 @@ def test_structured_hint_neighbors_success_callers() -> None:
         requested_edge_types=["EXPOSES"],
         requested_direction="in",
     )
-    _, struct = generate_hints("neighbors", payload)
+    struct = generate_hints("neighbors", payload)
     h = _assert_structured_hint(struct, tool="neighbors", args_subset={"edge_types": ["CALLS"]})
     assert h.args["direction"] == "in"
 
@@ -2488,7 +2262,7 @@ def test_structured_hint_neighbors_success_declaring_client() -> None:
         requested_edge_types=["HTTP_CALLS"],
         requested_direction="in",
     )
-    _, struct = generate_hints("neighbors", payload)
+    struct = generate_hints("neighbors", payload)
     h = _assert_structured_hint(struct, tool="neighbors", args_subset={"edge_types": ["DECLARES_CLIENT"]})
     assert h.args["ids"] == ["client:a"]
 
@@ -2499,7 +2273,7 @@ def test_structured_hint_neighbors_success_declaring_producer() -> None:
         requested_edge_types=["ASYNC_CALLS"],
         requested_direction="in",
     )
-    _, struct = generate_hints("neighbors", payload)
+    struct = generate_hints("neighbors", payload)
     h = _assert_structured_hint(struct, tool="neighbors", args_subset={"edge_types": ["DECLARES_PRODUCER"]})
     assert h.args["ids"] == ["producer:a"]
 
@@ -2509,7 +2283,7 @@ def test_structured_hint_neighbors_success_handler() -> None:
         [_success_edge(_terminal_other("route:a", "route"), edge_type="DECLARES.EXPOSES")],
         requested_edge_types=["DECLARES.EXPOSES"],
     )
-    _, struct = generate_hints("neighbors", payload)
+    struct = generate_hints("neighbors", payload)
     h = _assert_structured_hint(struct, tool="neighbors", args_subset={"edge_types": ["EXPOSES"]})
     assert h.args["ids"] == ["route:a"]
     assert h.args["direction"] == "in"
@@ -2520,7 +2294,7 @@ def test_structured_hint_neighbors_success_handler() -> None:
 
 def test_structured_hint_prose_only_not_actionable() -> None:
     # weak search score
-    _, struct = generate_hints("search", {
+    struct = generate_hints("search", {
         "success": True, "limit": 2, "offset": 0,
         "results": [{"score": 1.0}, {"score": 0.95}],
     })
@@ -2533,7 +2307,7 @@ def test_structured_hint_prose_only_not_actionable() -> None:
         requested_edge_types=["CALLS"],
     )
     payload["calls_row_count"] = 12
-    _, struct = generate_hints("neighbors", payload)
+    struct = generate_hints("neighbors", payload)
     fanout = [h for h in struct if h.args.get("edge_types") == ["CALLS"] and not h.actionable]
     assert fanout, "expected actionable=False CALLS fanout hint"
 
@@ -2550,7 +2324,7 @@ def test_structured_hint_describe_many_calls_not_actionable(kuzu_graph) -> None:
     )
 
 
-# --- Cap / dedup / parity ---
+# --- Cap / dedup ---
 
 
 def test_structured_hints_cap_5() -> None:
@@ -2572,7 +2346,7 @@ def test_structured_hints_cap_5() -> None:
             "CALLS": {"in": 0, "out": 12},
         },
     }
-    _, struct = generate_hints("describe", {"success": True, "record": rec})
+    struct = generate_hints("describe", {"success": True, "record": rec})
     assert len(struct) <= 5
 
 
@@ -2586,58 +2360,6 @@ def test_structured_hints_dedup() -> None:
     assert result[0].priority == 4
 
 
-def test_structured_hints_parity_with_string_hints() -> None:
-    """For every output where hints != [], len(hints_structured) <= len(hints)."""
-    payloads = [
-        # describe type
-        ("describe", {"success": True, "record": {
-            "id": "sym:a", "kind": "symbol", "fqn": "T", "data": {"kind": "class"},
-            "edge_summary": {"DECLARES.DECLARES_CLIENT": {"in": 0, "out": 3}},
-        }}),
-        # describe method
-        ("describe", {"success": True, "record": {
-            "id": "sym:a", "kind": "symbol", "fqn": "T#m()", "data": {"kind": "method"},
-            "edge_summary": {"OVERRIDDEN_BY": {"in": 0, "out": 1}, "CALLS": {"in": 0, "out": 12}},
-        }}),
-        # describe route
-        ("describe", {"success": True, "record": {"id": "route:a", "kind": "route", "fqn": "GET /"}}),
-        # find empty
-        ("find", {"success": True, "kind": "client", "results": [], "filter": {"target_service": "x"}, "offset": 0}),
-        # find success
-        ("find", {"success": True, "kind": "route", "results": [{"id": "route:a", "kind": "route"}], "filter": {}, "offset": 0}),
-        # resolve none — symbol (else branch)
-        ("resolve", {"status": "none", "resolved_identifier": "com.foo.Bar", "hint_kind": "symbol"}),
-        # resolve none — route (find branch)
-        ("resolve", {"status": "none", "resolved_identifier": "com.foo.Bar", "hint_kind": "route", "path_prefix_seed": "/api"}),
-        # resolve none — client (find branch)
-        ("resolve", {"status": "none", "resolved_identifier": "com.foo.Bar", "hint_kind": "client", "target_service_seed": "svc"}),
-        # resolve many
-        ("resolve", {"status": "many", "resolved_identifier": "x", "candidates": [{"id": "a"}, {"id": "b"}]}),
-        # neighbors empty structural
-        ("neighbors", {
-            "success": True, "results": [], "requested_edge_types": ["HTTP_CALLS"],
-            "requested_direction": "out", "offset": 0,
-            "subject_record": {"id": "sym:a", "kind": "method"},
-        }),
-        # neighbors success
-        ("neighbors", {
-            "success": True,
-            "results": [{"origin_id": "sym:T", "edge_type": "DECLARES", "direction": "out",
-                         "other": {"id": "sym:m", "kind": "symbol", "symbol_kind": "method"}, "attrs": {}}],
-            "requested_edge_types": ["DECLARES"], "requested_direction": "out", "offset": 0,
-            "subject_record": {"id": "sym:T", "kind": "class"}, "origin_id": "sym:T",
-        }),
-    ]
-    for output_kind, payload in payloads:
-        str_hints, struct = generate_hints(output_kind, payload)
-        if str_hints:
-            assert len(struct) <= len(str_hints), (
-                f"parity violation for {output_kind}: {len(struct)} structured > {len(str_hints)} string"
-            )
-        for h in struct:
-            assert h.label, f"struct hint missing label: {h}"
-
-
 def test_structured_hint_round_trip(kuzu_graph) -> None:
     """Integration: build structured hint args into an actual neighbors_v2 call."""
     rid = _route_id(kuzu_graph)
@@ -2673,23 +2395,23 @@ def test_structured_hint_label_values() -> None:
     }})
     assert any(h.label == "routes via members" for h in struct)
 
-    # describe route → declaring method
+    # describe route -> declaring method
     struct = _struct("describe", {"success": True, "record": {"id": "route:a", "kind": "route", "fqn": "GET /"}})
     assert any(h.label == "declaring method" for h in struct)
 
-    # resolve none → try search
+    # resolve none -> try search
     struct = _struct("resolve", {"status": "none", "resolved_identifier": "com.foo.Bar", "hint_kind": "symbol"})
     assert any(h.label == "try search" for h in struct)
 
-    # resolve none route → try find route
+    # resolve none route -> try find route
     struct = _struct("resolve", {"status": "none", "resolved_identifier": "x", "hint_kind": "route", "path_prefix_seed": "/api"})
     assert any(h.label == "try find route" for h in struct)
 
-    # resolve many → tighten identifier
+    # resolve many -> tighten identifier
     struct = _struct("resolve", {"status": "many", "resolved_identifier": "x", "candidates": [{"id": "a"}, {"id": "b"}]})
     assert any(h.label == "tighten identifier" for h in struct)
 
-    # find empty → try resolve
+    # find empty -> try resolve
     struct = _struct("find", {"success": True, "kind": "client", "results": [], "filter": {"target_service": "x"}, "offset": 0})
     assert any(h.label == "try resolve" for h in struct)
 
@@ -2717,7 +2439,7 @@ def test_structured_hint_label_values() -> None:
     }})
     assert any(h.label == "outbound calls" for h in struct)
 
-    # describe method with many calls (≥10) → not actionable
+    # describe method with many calls (>=10) -> not actionable
     struct = _struct("describe", {"success": True, "record": {
         "id": "sym:a", "kind": "symbol", "fqn": "T#m()", "data": {"kind": "method", "role": "OTHER"},
         "edge_summary": {"CALLS": {"in": 0, "out": 12}},
@@ -2733,3 +2455,41 @@ def test_structured_hint_label_values() -> None:
         "subject_record": {"id": "route:a", "kind": "route"}, "origin_id": "route:a",
     })
     assert any(h.label == "callers" for h in struct)
+
+
+# ---------------------------------------------------------------------------
+# New tests: reason char cap + no string hints field
+# ---------------------------------------------------------------------------
+
+
+def test_structured_hints_reason_char_cap() -> None:
+    """All emitted reason strings should be <= 120 chars."""
+    payloads = [
+        ("describe", {"success": True, "record": {
+            "id": "sym:a", "kind": "symbol", "fqn": "T", "data": {"kind": "class"},
+            "edge_summary": {"DECLARES.DECLARES_CLIENT": {"in": 0, "out": 3}},
+        }}),
+        ("describe", {"success": True, "record": {
+            "id": "sym:a", "kind": "symbol", "fqn": "T#m()", "data": {"kind": "method"},
+            "edge_summary": {"OVERRIDDEN_BY": {"in": 0, "out": 1}, "CALLS": {"in": 0, "out": 12}},
+        }}),
+        ("describe", {"success": True, "record": {"id": "route:a", "kind": "route", "fqn": "GET /"}}),
+        ("find", {"success": True, "kind": "client", "results": [], "filter": {"target_service": "x"}, "offset": 0}),
+        ("search", {"success": True, "results": [{"score": 0.5}, {"score": 0.49}], "limit": 5, "offset": 0}),
+        ("resolve", {"status": "many", "resolved_identifier": "x", "candidates": [{"id": "a"}, {"id": "b"}]}),
+        ("resolve", {"status": "none", "resolved_identifier": "com.foo.Bar", "hint_kind": "symbol"}),
+        ("neighbors", {
+            "success": True, "results": [], "requested_edge_types": ["HTTP_CALLS"],
+            "requested_direction": "out", "offset": 0,
+            "subject_record": {"id": "sym:a", "kind": "method"},
+        }),
+    ]
+    for output_kind, payload in payloads:
+        for h in generate_hints(output_kind, payload):
+            assert len(h.reason) <= 120, f"reason too long ({len(h.reason)} chars) for {output_kind}: {h.reason!r}"
+
+
+def test_no_string_hints_field() -> None:
+    """Verify output models have no `hints` field (only `hints_structured`)."""
+    for cls in (SearchOutput, FindOutput, DescribeOutput, NeighborsOutput, ResolveOutput):
+        assert "hints" not in cls.model_fields, f"{cls.__name__} still has `hints` field"