fix: map depth/unique_id args in get_lineage deprecation banner

Per Copilot review feedback: get_lineage isn't a drop-in for
get_model_parents/get_model_children — it requires unique_id (these
tools accept name alone) and defaults to depth=5 (these tools only
ever return immediate parents/children). Without this mapping, a
caller following 'use get_lineage instead' silently gets a 5-level
graph instead of the old immediate-neighbor behavior.

Adds GET_LINEAGE_ARG_MAPPING as a shared constant in
param_descriptions.py, reused at all 4 call sites (2 tools x 2 files)
via deprecated_description()'s arg_mapping parameter.

Author: theyostalservice

src/dbt_mcp/discovery/param_descriptions.py

@@ -33,3 +33,12 @@
 MACRO_INCLUDE_DEFAULT_DBT_PACKAGES = (
     "When true, include default dbt Labs core/adapter macro packages"
 )
+
+# Not a JSON Schema param description — used as the `arg_mapping` for the
+# get_model_parents/get_model_children deprecation banner. get_lineage isn't a
+# drop-in: it requires unique_id (these tools accept name alone) and defaults
+# to depth=5 (these tools only ever return immediate parents/children).
+GET_LINEAGE_ARG_MAPPING = (
+    "Call get_lineage(unique_id=..., depth=1) to match this tool's behavior — "
+    "get_lineage requires unique_id (not name) and defaults to depth=5."
+)

src/dbt_mcp/discovery/tools.py

@@ -18,6 +18,7 @@
     SourcesFetcher,
 )
 from dbt_mcp.discovery.param_descriptions import (
+    GET_LINEAGE_ARG_MAPPING,
     MACRO_INCLUDE_DEFAULT_DBT_PACKAGES,
     MACRO_PACKAGE_NAMES,
     MACRO_RETURN_PACKAGE_NAMES_ONLY,
@@ -161,7 +162,9 @@ async def get_model_details(
 
 
 @dbt_mcp_tool(
-    description=deprecated_description(replacement="get_lineage"),
+    description=deprecated_description(
+        replacement="get_lineage", arg_mapping=GET_LINEAGE_ARG_MAPPING
+    ),
     meta=deprecation_meta(replacement="get_lineage"),
     title="Get Model Parents",
     read_only_hint=True,
@@ -180,7 +183,9 @@ async def get_model_parents(
 
 
 @dbt_mcp_tool(
-    description=deprecated_description(replacement="get_lineage"),
+    description=deprecated_description(
+        replacement="get_lineage", arg_mapping=GET_LINEAGE_ARG_MAPPING
+    ),
     meta=deprecation_meta(replacement="get_lineage"),
     title="Get Model Children",
     read_only_hint=True,

src/dbt_mcp/discovery/tools_multiproject.py

@@ -23,6 +23,7 @@
 )
 from dbt_mcp.discovery.param_descriptions import (
     DISCOVERY_PROJECT_ID_DESCRIPTION,
+    GET_LINEAGE_ARG_MAPPING,
     MACRO_INCLUDE_DEFAULT_DBT_PACKAGES,
     MACRO_PACKAGE_NAMES,
     MACRO_RETURN_PACKAGE_NAMES_ONLY,
@@ -173,7 +174,9 @@ async def get_model_details(
 
 
 @dbt_mcp_tool(
-    description=deprecated_description(replacement="get_lineage"),
+    description=deprecated_description(
+        replacement="get_lineage", arg_mapping=GET_LINEAGE_ARG_MAPPING
+    ),
     meta=deprecation_meta(replacement="get_lineage"),
     title="Get Model Parents",
     read_only_hint=True,
@@ -193,7 +196,9 @@ async def get_model_parents(
 
 
 @dbt_mcp_tool(
-    description=deprecated_description(replacement="get_lineage"),
+    description=deprecated_description(
+        replacement="get_lineage", arg_mapping=GET_LINEAGE_ARG_MAPPING
+    ),
     meta=deprecation_meta(replacement="get_lineage"),
     title="Get Model Children",
     read_only_hint=True,

tests/unit/contract/contract_snapshot.json

@@ -1169,7 +1169,7 @@
         "readOnlyHint": true,
         "title": "Get Model Children"
       },
-      "description": "**DEPRECATED \u2014 use `get_lineage` instead.** This tool will be removed in a future release.",
+      "description": "**DEPRECATED \u2014 use `get_lineage` instead.** This tool will be removed in a future release.\n\nCall get_lineage(unique_id=..., depth=1) to match this tool's behavior \u2014 get_lineage requires unique_id (not name) and defaults to depth=5.",
       "input_schema": {
         "properties": {
           "name": {
@@ -1361,7 +1361,7 @@
         "readOnlyHint": true,
         "title": "Get Model Parents"
       },
-      "description": "**DEPRECATED \u2014 use `get_lineage` instead.** This tool will be removed in a future release.",
+      "description": "**DEPRECATED \u2014 use `get_lineage` instead.** This tool will be removed in a future release.\n\nCall get_lineage(unique_id=..., depth=1) to match this tool's behavior \u2014 get_lineage requires unique_id (not name) and defaults to depth=5.",
       "input_schema": {
         "properties": {
           "name": {

tests/unit/discovery/test_deprecated_tools.py

@@ -82,4 +82,21 @@ def test_deprecated_tool_description_is_trimmed(mock_fastmcp):
     fastmcp = _register_single_project(mock_fastmcp)
     description = fastmcp.tool_kwargs["get_model_parents"]["description"]
     assert "Retrieves the parent models" not in description
-    assert len(description) < 200
+    # Banner + a one-line arg mapping should stay well under the original
+    # prompt's length (which runs to several hundred characters).
+    assert len(description) < 300
+
+
+def test_deprecated_tool_description_maps_args_to_replacement(mock_fastmcp):
+    """get_lineage isn't a drop-in for get_model_parents/children: it requires
+
+    unique_id (these tools accept name alone) and defaults to depth=5 (these
+    tools only ever return immediate parents/children). The deprecation
+    description must spell out the mapping so callers reproduce the old
+    behavior instead of silently getting a 5-level graph.
+    """
+    fastmcp = _register_single_project(mock_fastmcp)
+    for tool_name in DEPRECATED_TOOLS:
+        description = fastmcp.tool_kwargs[tool_name]["description"]
+        assert "depth=1" in description
+        assert "unique_id" in description