Align MCP relationship guidance with agent profiles

Author: rodion-m

src/tests/test_artifact_relationships.py

@@ -38,6 +38,13 @@ def test_found_with_grouped_relationships(self):
             "sourceIdentifier": "org/repo::path::Symbol",
             "profile": "CallsOnly",
             "found": True,
+            "availableRelationshipCounts": {
+                "outgoingCalls": 57,
+                "incomingCalls": 3,
+                "ancestors": 0,
+                "descendants": 2,
+                "references": 11,
+            },
             "relationships": [
                 {
                     "relationType": "OutgoingCalls",
@@ -73,6 +80,10 @@ def test_found_with_grouped_relationships(self):
         assert parsed["sourceIdentifier"] == "org/repo::path::Symbol"
         assert parsed["profile"] == "callsOnly"
         assert parsed["found"] is True
+        assert parsed["availableRelationshipCounts"]["outgoingCalls"] == 57
+        assert parsed["availableRelationshipCounts"]["references"] == 11
+        assert "truncated" in parsed["hint"]
+        assert "higher max_count_per_type" in parsed["hint"]
 
         outgoing = parsed["relationships"][0]
         assert outgoing["type"] == "outgoing_calls"
@@ -100,6 +111,8 @@ def test_not_found_omits_relationships(self):
         parsed = _build_relationships_dict(data)
         assert parsed["found"] is False
         assert "relationships" not in parsed
+        assert "availableRelationshipCounts" not in parsed
+        assert "fresh identifier" in parsed["hint"]
 
     def test_empty_groups_still_rendered(self):
         data = {
@@ -130,6 +143,7 @@ def test_empty_groups_still_rendered(self):
         for g in parsed["relationships"]:
             assert g["totalCount"] == 0
             assert g["items"] == []
+        assert "No relationships were found for this profile" in parsed["hint"]
 
     def test_optional_fields_omitted_when_null(self):
         data = {
@@ -159,6 +173,92 @@ def test_optional_fields_omitted_when_null(self):
         assert "startLine" not in item
         assert "shortSummary" not in item
 
+    def test_empty_profile_hint_uses_available_counts(self):
+        data = {
+            "sourceIdentifier": "org/repo::path::Command",
+            "profile": "CallsOnly",
+            "found": True,
+            "availableRelationshipCounts": {
+                "outgoingCalls": 0,
+                "incomingCalls": 0,
+                "ancestors": 0,
+                "descendants": 0,
+                "references": 7,
+            },
+            "relationships": [
+                {
+                    "relationType": "OutgoingCalls",
+                    "totalCount": 0,
+                    "returnedCount": 0,
+                    "truncated": False,
+                    "items": [],
+                },
+                {
+                    "relationType": "IncomingCalls",
+                    "totalCount": 0,
+                    "returnedCount": 0,
+                    "truncated": False,
+                    "items": [],
+                },
+            ],
+        }
+
+        parsed = _build_relationships_dict(data)
+
+        assert parsed["availableRelationshipCounts"]["references"] == 7
+        assert "referencesOnly" in parsed["hint"]
+        assert "where-used" in parsed["hint"]
+
+    def test_all_relevant_empty_profile_hint_says_references_are_excluded(self):
+        data = {
+            "sourceIdentifier": "org/repo::path::Message",
+            "profile": "AllRelevant",
+            "found": True,
+            "availableRelationshipCounts": {
+                "outgoingCalls": 0,
+                "incomingCalls": 0,
+                "ancestors": 0,
+                "descendants": 0,
+                "references": 4,
+            },
+            "relationships": [
+                {
+                    "relationType": "OutgoingCalls",
+                    "totalCount": 0,
+                    "returnedCount": 0,
+                    "truncated": False,
+                    "items": [],
+                },
+                {
+                    "relationType": "IncomingCalls",
+                    "totalCount": 0,
+                    "returnedCount": 0,
+                    "truncated": False,
+                    "items": [],
+                },
+                {
+                    "relationType": "Ancestors",
+                    "totalCount": 0,
+                    "returnedCount": 0,
+                    "truncated": False,
+                    "items": [],
+                },
+                {
+                    "relationType": "Descendants",
+                    "totalCount": 0,
+                    "returnedCount": 0,
+                    "truncated": False,
+                    "items": [],
+                },
+            ],
+        }
+
+        parsed = _build_relationships_dict(data)
+
+        assert parsed["profile"] == "allRelevant"
+        assert "excludes references" in parsed["hint"]
+        assert "referencesOnly" in parsed["hint"]
+
     def test_quotes_and_specials_pass_through_unchanged(self):
         """Special chars (<, >, &, ") are preserved as-is in the dict — no HTML encoding."""
         data = {

src/tests/test_e2e_tools.py

@@ -1118,6 +1118,13 @@ class TestGetArtifactRelationshipsE2E:
         "sourceIdentifier": "org/repo::src/svc.py::Service",
         "profile": "CallsOnly",
         "found": True,
+        "availableRelationshipCounts": {
+            "outgoingCalls": 3,
+            "incomingCalls": 1,
+            "ancestors": 0,
+            "descendants": 0,
+            "references": 2,
+        },
         "relationships": [
             {
                 "relationType": "OutgoingCalls",
@@ -1162,6 +1169,8 @@ def handler(req):
         # FastMCP serializes via pydantic_core.to_json — compact, UTF-8.
         assert text == json.dumps(data, separators=(",", ":"), ensure_ascii=False)
         assert data["found"] is True
+        assert data["availableRelationshipCounts"]["references"] == 2
+        assert "Fetch promising related artifacts" in data["hint"]
         types = [g["type"] for g in data["relationships"]]
         assert "outgoing_calls" in types
         assert "incoming_calls" in types

src/tests/test_tool_metadata.py

@@ -41,3 +41,5 @@ async def test_all_tools_are_marked_read_only_with_titles():
     assert "exact artifact identifier" in relationships_description
     assert "not a search tool" in relationships_description
     assert "fetch_artifacts" in relationships_description
+    assert "excludes references" in relationships_description
+    assert "Mediated or dynamic frameworks" in relationships_description

src/tools/artifact_relationships.py

@@ -61,6 +61,17 @@ async def get_artifact_relationships(
         - The response contains relationship metadata and short summaries, not
           full source code. Use `fetch_artifacts` on returned identifiers when
           exact source content is needed.
+        - Choose `profile` by artifact shape: `callsOnly` for function/method
+          callers and callees; `inheritanceOnly` for hierarchy; `allRelevant`
+          for calls plus inheritance only (it excludes references);
+          `referencesOnly` for where-used checks on types, containers, fields,
+          commands, events, interfaces, and other non-call usage.
+        - Mediated or dynamic frameworks such as command buses, event buses,
+          dependency injection, reflection, route binding, subscriptions,
+          schedulers, or generated dispatch may not expose a direct call edge.
+          When graph context is missing or insufficient, use targeted
+          `grep_search` for construction, registration, dispatch, route,
+          subscription, or scheduler text surfaced by source you've already read.
         - If any relationship group has `truncated=true`, increase
           `max_count_per_type` up to 1000 or narrow the investigation with a
           more specific `profile`.
@@ -69,9 +80,9 @@ async def get_artifact_relationships(
         identifier: Fully qualified artifact identifier from search or fetch results.
         profile: Relationship profile to expand. One of:
                  - "callsOnly" (default): outgoing and incoming calls
-                 - "inheritanceOnly": ancestors and descendants
-                 - "allRelevant": calls + inheritance (4 groups)
-                 - "referencesOnly": symbol references
+                 - "inheritanceOnly": ancestors, descendants, implementations, and derived types
+                 - "allRelevant": calls + inheritance only; references are excluded
+                 - "referencesOnly": where-used LSP references for non-call usage
         max_count_per_type: Maximum related artifacts per relationship type (1–1000, default 50).
 
     Returns:
@@ -191,7 +202,15 @@ def _build_relationships_dict(data: dict) -> Dict[str, Any]:
 
     if found:
         relationships = data.get("relationships") or []
-        payload["relationships"] = [_build_group(group) for group in relationships]
+        groups = [_build_group(group) for group in relationships]
+        payload["relationships"] = groups
+
+        counts = _build_counts(data.get("availableRelationshipCounts"))
+        if counts is not None:
+            payload["availableRelationshipCounts"] = counts
+        payload["hint"] = _build_relationship_hint(found, mcp_profile, groups, counts)
+    else:
+        payload["hint"] = _build_relationship_hint(found, mcp_profile, [], None)
 
     return payload
 
@@ -226,3 +245,113 @@ def _build_group(group: dict) -> Dict[str, Any]:
         "truncated": bool(group.get("truncated")),
         "items": items,
     }
+
+
+def _build_counts(counts: Any) -> Dict[str, int] | None:
+    """Preserve backend relationship counts that guide profile recovery."""
+    if not isinstance(counts, dict):
+        return None
+
+    return {
+        "outgoingCalls": int(counts.get("outgoingCalls") or counts.get("OutgoingCalls") or 0),
+        "incomingCalls": int(counts.get("incomingCalls") or counts.get("IncomingCalls") or 0),
+        "ancestors": int(counts.get("ancestors") or counts.get("Ancestors") or 0),
+        "descendants": int(counts.get("descendants") or counts.get("Descendants") or 0),
+        "references": int(counts.get("references") or counts.get("References") or 0),
+    }
+
+
+def _build_relationship_hint(
+    found: bool,
+    profile: str,
+    groups: List[Dict[str, Any]],
+    counts: Dict[str, int] | None,
+) -> str:
+    """Give model-facing next-step guidance for graph traversal results."""
+    if not found:
+        return (
+            "No relationship data was found for this identifier. Verify that the identifier came from "
+            "a recent search/fetch result and points to a symbol-level artifact; otherwise re-run "
+            "semantic_search or grep_search to get a fresh identifier."
+        )
+
+    if any(group["truncated"] for group in groups):
+        return (
+            "Some relationship groups are truncated. If the user asked for all usages or full graph "
+            "scope, call get_artifact_relationships again with a higher max_count_per_type, then "
+            "fetch promising related artifacts before making broad claims."
+        )
+
+    if all(group["totalCount"] == 0 for group in groups):
+        return _build_empty_profile_hint(profile, counts)
+
+    return (
+        "Fetch promising related artifacts before making claims about behavior, concrete applications, "
+        "or how broadly this mechanism is used."
+    )
+
+
+def _build_empty_profile_hint(profile: str, counts: Dict[str, int] | None) -> str:
+    has_calls = (counts or {}).get("outgoingCalls", 0) > 0 or (counts or {}).get("incomingCalls", 0) > 0
+    has_inheritance = (counts or {}).get("ancestors", 0) > 0 or (counts or {}).get("descendants", 0) > 0
+    has_references = (counts or {}).get("references", 0) > 0
+
+    if profile == "referencesOnly" and has_calls and has_inheritance:
+        return (
+            "No references were found for this profile, but call and inheritance relationships exist. "
+            "Use callsOnly for function/method callers or callees, or inheritanceOnly for base classes, "
+            "interfaces, overrides, implementations, or derived types."
+        )
+    if profile == "referencesOnly" and has_calls:
+        return (
+            "No references were found for this profile, but call relationships exist. Use callsOnly "
+            "for function/method callers or callees. Use referencesOnly for where-used checks on "
+            "types, containers, fields, commands, events, interfaces, and other non-call usage."
+        )
+    if profile == "referencesOnly" and has_inheritance:
+        return (
+            "No references were found for this profile, but inheritance relationships exist. Use "
+            "inheritanceOnly for base classes, interfaces, overrides, implementations, or derived types."
+        )
+    if profile == "callsOnly" and has_references and has_inheritance:
+        return (
+            "No call relationships were found for this profile, but references and inheritance "
+            "relationships exist. Try referencesOnly for where-used checks or inheritanceOnly for hierarchy."
+        )
+    if profile == "callsOnly" and has_references:
+        return (
+            "No call relationships were found for this profile, but references exist. Use referencesOnly "
+            "for where-used checks on types, containers, fields, commands, events, interfaces, or mediated dispatch symbols."
+        )
+    if profile == "callsOnly" and has_inheritance:
+        return (
+            "No call relationships were found for this profile, but inheritance relationships exist. "
+            "Use inheritanceOnly for base classes, interfaces, overrides, implementations, or derived types."
+        )
+    if profile == "allRelevant" and has_references:
+        return (
+            "No calls or inheritance relationships were found for allRelevant. allRelevant excludes "
+            "references by design; use referencesOnly for where-used checks."
+        )
+    if profile == "inheritanceOnly" and has_calls and has_references:
+        return (
+            "No inheritance relationships were found for this profile. Use callsOnly for function "
+            "callers/callees, or referencesOnly for where-used checks on types, commands, events, fields, containers, or interfaces."
+        )
+    if profile == "inheritanceOnly" and has_calls:
+        return (
+            "No inheritance relationships were found for this profile, but call relationships exist. "
+            "Use callsOnly for function/method callers or callees."
+        )
+    if profile == "inheritanceOnly" and has_references:
+        return (
+            "No inheritance relationships were found for this profile, but references exist. Use "
+            "referencesOnly for where-used checks on types, containers, fields, commands, events, interfaces, or mediated dispatch symbols."
+        )
+
+    return (
+        "No relationships were found for this profile. Empty profile results do not mean the artifact "
+        "has no graph data. Use callsOnly for function/method callers and callees, inheritanceOnly for "
+        "hierarchy, allRelevant for calls plus inheritance, and referencesOnly for where-used checks on "
+        "types, containers, fields, commands, events, interfaces, and other non-call usage."
+    )