feat(discovery): add get_node_details; deprecate the 8 get_*_details tools (#825)

# Why

The dbt Discovery toolset currently has 8 near-identical detail tools —
`get_model_details`, `get_source_details`, and 6 others — that are thin
wrappers around a single shared dispatcher keyed by resource type.
Having 8 separate tools means 8 separate descriptions in the MCP tool
list, increasing per-turn context overhead. A single
`get_node_details(resource_type, ...)` tool carries equivalent
functionality in one description slot.

# What

- Adds a new `get_node_details(resource_type, name, unique_id)` tool
that dispatches to the existing `ResourceDetailsFetcher.fetch_details`
based on `resource_type`. Supports all 8 resource types: model, source,
exposure, test, seed, snapshot, macro, semantic_model. (Named
`get_node_details` rather than `get_details` — `node` is the canonical
term dbt uses for a model, snapshot, etc., and `get_details` alone was
too generic.)
- Marks the 8 existing `get_*_details` tools as deprecated using the
`deprecated_description()` and `deprecation_meta()` helpers introduced
in the parent PR. All 8 remain fully registered and callable, but their
descriptions are now replaced with a short, blunt DEPRECATED line
pointing to `get_node_details` (rather than a banner prepended to the
full original description — a shorter description makes a model less
likely to pick the tool, speeding the usage soak), and their
`Tool._meta` carries `{"deprecated": true, "replacement":
"get_node_details"}`.
- The generated README now marks all 8 tools as deprecated
automatically, via #834's meta-driven `generate_docs.py` (merged to main
and picked up by rebasing this branch onto #824's latest state) — no
manual mapping needed on this end.

The underlying `ResourceDetailsFetcher` and its GraphQL queries are
unchanged — `get_node_details` uses the same data path.

# Notes

Stacked on #824 (enrich `get_lineage` + deprecate
`get_model_parents`/`get_model_children`). Merge #824 first, then
retarget this PR to `main`.

Drafted by claude-sonnet-4-6 and claude-opus-4-8 under the direction of
@theyostalservice

Author: theyostalservice

.changes/unreleased/Enhancement or New Feature-20260629-113020.yaml

@@ -0,0 +1,3 @@
+kind: Enhancement or New Feature
+body: Add get_node_details tool for fetching details of any dbt resource type; deprecate the 8 type-specific get_*_details tools in favor of get_node_details
+time: 2026-06-29T11:30:20.511624-07:00

README.md

@@ -45,22 +45,23 @@ To learn more about the dbt Discovery API, click [here](https://docs.getdbt.com/
 - `get_all_macros`: Retrieves macros; option to filter by package or return package names only.
 - `get_all_models`: Retrieves name and description of all models.
 - `get_all_sources`: Gets all sources with freshness status; option to filter by source name.
-- `get_exposure_details`: Gets exposure details including owner, parents, and freshness status.
+- `get_exposure_details`: *(deprecated — use `get_node_details` instead)*
 - `get_exposures`: Gets all exposures (downstream dashboards, apps, or analyses).
 - `get_lineage`: Gets full lineage graph (ancestors and descendants) with type and depth filtering.
-- `get_macro_details`: Gets details for a specific macro.
+- `get_macro_details`: *(deprecated — use `get_node_details` instead)*
 - `get_mart_models`: Retrieves all mart models.
 - `get_model_children`: *(deprecated — use `get_lineage` instead)*
-- `get_model_details`: Gets model details including compiled SQL, columns, and schema.
+- `get_model_details`: *(deprecated — use `get_node_details` instead)*
 - `get_model_health`: Gets health signals: run status, test results, and upstream source freshness.
 - `get_model_parents`: *(deprecated — use `get_lineage` instead)*
 - `get_model_performance`: Gets execution history for a model; option to include test results.
+- `get_node_details`: Gets full details for any dbt resource type (model, source, exposure, test, seed, snapshot, macro, semantic_model).
 - `get_related_models`: Finds similar models using semantic search.
-- `get_seed_details`: Gets details for a specific seed.
-- `get_semantic_model_details`: Gets details for a specific semantic model.
-- `get_snapshot_details`: Gets details for a specific snapshot.
-- `get_source_details`: Gets source details including columns and freshness.
-- `get_test_details`: Gets details for a specific test.
+- `get_seed_details`: *(deprecated — use `get_node_details` instead)*
+- `get_semantic_model_details`: *(deprecated — use `get_node_details` instead)*
+- `get_snapshot_details`: *(deprecated — use `get_node_details` instead)*
+- `get_source_details`: *(deprecated — use `get_node_details` instead)*
+- `get_test_details`: *(deprecated — use `get_node_details` instead)*
 - `search`: [Alpha] Searches for resources across the dbt project (not generally available).
 
 ### dbt CLI

src/dbt_mcp/discovery/param_descriptions.py

@@ -4,6 +4,13 @@
 
 DISCOVERY_PROJECT_ID_DESCRIPTION = MULTI_PROJECT_PROJECT_ID_DESCRIPTION
 
+RESOURCE_TYPE_DESCRIPTION = (
+    "The type of dbt resource to fetch details for. "
+    "One of: model, source, exposure, test, seed, snapshot, macro, semantic_model. "
+    "Tip: the resource_type is encoded in the unique_id prefix "
+    "(e.g. `model.my_project.orders` → model)."
+)
+
 SOURCE_NAMES_FILTER = (
     "Filter by top-level source names from the project `sources:` YAML "
     "(e.g. `raw_data`, `external_api`)"

src/dbt_mcp/discovery/tools.py

@@ -25,6 +25,7 @@
     MACRO_RETURN_PACKAGE_NAMES_ONLY,
     MODEL_PERF_INCLUDE_TESTS,
     MODEL_PERF_NUM_RUNS,
+    RESOURCE_TYPE_DESCRIPTION,
     SOURCE_NAMES_FILTER,
     SOURCE_UNIQUE_IDS_FILTER,
 )
@@ -145,11 +146,36 @@ async def get_all_models(
 
 
 @dbt_mcp_tool(
-    description=get_prompt("discovery/get_model_details"),
+    description=get_prompt("discovery/get_node_details"),
+    title="Get Details",
+    read_only_hint=True,
+    destructive_hint=False,
+    idempotent_hint=True,
+)
+async def get_node_details(
+    context: DiscoveryToolContext,
+    resource_type: Annotated[
+        AppliedResourceType, Field(description=RESOURCE_TYPE_DESCRIPTION)
+    ],
+    name: str | None = NAME_FIELD,
+    unique_id: str | None = UNIQUE_ID_FIELD,
+) -> list[dict]:
+    config = await context.config_provider.get_config()
+    return await context.resource_details_fetcher.fetch_details(
+        resource_type=resource_type,
+        unique_id=unique_id,
+        name=name,
+        config=config,
+    )
+
+
+@dbt_mcp_tool(
+    description=deprecated_description(replacement="get_node_details"),
     title="Get Model Details",
     read_only_hint=True,
     destructive_hint=False,
     idempotent_hint=True,
+    meta=deprecation_meta(replacement="get_node_details"),
 )
 async def get_model_details(
     context: DiscoveryToolContext,
@@ -297,11 +323,12 @@ async def get_exposures(
 
 
 @dbt_mcp_tool(
-    description=get_prompt("discovery/get_exposure_details"),
+    description=deprecated_description(replacement="get_node_details"),
     title="Get Exposure Details",
     read_only_hint=True,
     destructive_hint=False,
     idempotent_hint=True,
+    meta=deprecation_meta(replacement="get_node_details"),
 )
 async def get_exposure_details(
     context: DiscoveryToolContext,
@@ -340,11 +367,12 @@ async def get_all_sources(
 
 
 @dbt_mcp_tool(
-    description=get_prompt("discovery/get_source_details"),
+    description=deprecated_description(replacement="get_node_details"),
     title="Get Source Details",
     read_only_hint=True,
     destructive_hint=False,
     idempotent_hint=True,
+    meta=deprecation_meta(replacement="get_node_details"),
 )
 async def get_source_details(
     context: DiscoveryToolContext,
@@ -389,11 +417,12 @@ async def get_all_macros(
 
 
 @dbt_mcp_tool(
-    description=get_prompt("discovery/get_macro_details"),
+    description=deprecated_description(replacement="get_node_details"),
     title="Get Macro Details",
     read_only_hint=True,
     destructive_hint=False,
     idempotent_hint=True,
+    meta=deprecation_meta(replacement="get_node_details"),
 )
 async def get_macro_details(
     context: DiscoveryToolContext,
@@ -410,11 +439,12 @@ async def get_macro_details(
 
 
 @dbt_mcp_tool(
-    description=get_prompt("discovery/get_seed_details"),
+    description=deprecated_description(replacement="get_node_details"),
     title="Get Seed Details",
     read_only_hint=True,
     destructive_hint=False,
     idempotent_hint=True,
+    meta=deprecation_meta(replacement="get_node_details"),
 )
 async def get_seed_details(
     context: DiscoveryToolContext,
@@ -431,11 +461,12 @@ async def get_seed_details(
 
 
 @dbt_mcp_tool(
-    description=get_prompt("discovery/get_semantic_model_details"),
+    description=deprecated_description(replacement="get_node_details"),
     title="Get Semantic Model Details",
     read_only_hint=True,
     destructive_hint=False,
     idempotent_hint=True,
+    meta=deprecation_meta(replacement="get_node_details"),
 )
 async def get_semantic_model_details(
     context: DiscoveryToolContext,
@@ -452,11 +483,12 @@ async def get_semantic_model_details(
 
 
 @dbt_mcp_tool(
-    description=get_prompt("discovery/get_snapshot_details"),
+    description=deprecated_description(replacement="get_node_details"),
     title="Get Snapshot Details",
     read_only_hint=True,
     destructive_hint=False,
     idempotent_hint=True,
+    meta=deprecation_meta(replacement="get_node_details"),
 )
 async def get_snapshot_details(
     context: DiscoveryToolContext,
@@ -473,11 +505,12 @@ async def get_snapshot_details(
 
 
 @dbt_mcp_tool(
-    description=get_prompt("discovery/get_test_details"),
+    description=deprecated_description(replacement="get_node_details"),
     title="Get Test Details",
     read_only_hint=True,
     destructive_hint=False,
     idempotent_hint=True,
+    meta=deprecation_meta(replacement="get_node_details"),
 )
 async def get_test_details(
     context: DiscoveryToolContext,
@@ -496,6 +529,7 @@ async def get_test_details(
 DISCOVERY_TOOLS = [
     get_mart_models,
     get_all_models,
+    get_node_details,
     get_model_details,
     get_model_parents,
     get_model_children,

src/dbt_mcp/discovery/tools_multiproject.py

@@ -30,6 +30,7 @@
     MACRO_RETURN_PACKAGE_NAMES_ONLY,
     MODEL_PERF_INCLUDE_TESTS,
     MODEL_PERF_NUM_RUNS,
+    RESOURCE_TYPE_DESCRIPTION,
     SOURCE_NAMES_FILTER,
     SOURCE_UNIQUE_IDS_FILTER,
 )
@@ -156,11 +157,37 @@ async def get_all_models(
 
 
 @dbt_mcp_tool(
-    description=get_prompt("discovery/get_model_details"),
+    description=get_prompt("discovery/get_node_details"),
+    title="Get Details",
+    read_only_hint=True,
+    destructive_hint=False,
+    idempotent_hint=True,
+)
+async def get_node_details(
+    context: MultiProjectDiscoveryToolContext,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
+    resource_type: Annotated[
+        AppliedResourceType, Field(description=RESOURCE_TYPE_DESCRIPTION)
+    ],
+    name: str | None = NAME_FIELD,
+    unique_id: str | None = UNIQUE_ID_FIELD,
+) -> list[dict]:
+    config = await context.config_provider.get_config(project_id=project_id)
+    return await context.resource_details_fetcher.fetch_details(
+        resource_type=resource_type,
+        unique_id=unique_id,
+        name=name,
+        config=config,
+    )
+
+
+@dbt_mcp_tool(
+    description=deprecated_description(replacement="get_node_details"),
     title="Get Model Details",
     read_only_hint=True,
     destructive_hint=False,
     idempotent_hint=True,
+    meta=deprecation_meta(replacement="get_node_details"),
 )
 async def get_model_details(
     context: MultiProjectDiscoveryToolContext,
@@ -316,11 +343,12 @@ async def get_exposures(
 
 
 @dbt_mcp_tool(
-    description=get_prompt("discovery/get_exposure_details"),
+    description=deprecated_description(replacement="get_node_details"),
     title="Get Exposure Details",
     read_only_hint=True,
     destructive_hint=False,
     idempotent_hint=True,
+    meta=deprecation_meta(replacement="get_node_details"),
 )
 async def get_exposure_details(
     context: MultiProjectDiscoveryToolContext,
@@ -361,11 +389,12 @@ async def get_all_sources(
 
 
 @dbt_mcp_tool(
-    description=get_prompt("discovery/get_source_details"),
+    description=deprecated_description(replacement="get_node_details"),
     title="Get Source Details",
     read_only_hint=True,
     destructive_hint=False,
     idempotent_hint=True,
+    meta=deprecation_meta(replacement="get_node_details"),
 )
 async def get_source_details(
     context: MultiProjectDiscoveryToolContext,
@@ -412,11 +441,12 @@ async def get_all_macros(
 
 
 @dbt_mcp_tool(
-    description=get_prompt("discovery/get_macro_details"),
+    description=deprecated_description(replacement="get_node_details"),
     title="Get Macro Details",
     read_only_hint=True,
     destructive_hint=False,
     idempotent_hint=True,
+    meta=deprecation_meta(replacement="get_node_details"),
 )
 async def get_macro_details(
     context: MultiProjectDiscoveryToolContext,
@@ -434,11 +464,12 @@ async def get_macro_details(
 
 
 @dbt_mcp_tool(
-    description=get_prompt("discovery/get_seed_details"),
+    description=deprecated_description(replacement="get_node_details"),
     title="Get Seed Details",
     read_only_hint=True,
     destructive_hint=False,
     idempotent_hint=True,
+    meta=deprecation_meta(replacement="get_node_details"),
 )
 async def get_seed_details(
     context: MultiProjectDiscoveryToolContext,
@@ -456,11 +487,12 @@ async def get_seed_details(
 
 
 @dbt_mcp_tool(
-    description=get_prompt("discovery/get_semantic_model_details"),
+    description=deprecated_description(replacement="get_node_details"),
     title="Get Semantic Model Details",
     read_only_hint=True,
     destructive_hint=False,
     idempotent_hint=True,
+    meta=deprecation_meta(replacement="get_node_details"),
 )
 async def get_semantic_model_details(
     context: MultiProjectDiscoveryToolContext,
@@ -478,11 +510,12 @@ async def get_semantic_model_details(
 
 
 @dbt_mcp_tool(
-    description=get_prompt("discovery/get_snapshot_details"),
+    description=deprecated_description(replacement="get_node_details"),
     title="Get Snapshot Details",
     read_only_hint=True,
     destructive_hint=False,
     idempotent_hint=True,
+    meta=deprecation_meta(replacement="get_node_details"),
 )
 async def get_snapshot_details(
     context: MultiProjectDiscoveryToolContext,
@@ -500,11 +533,12 @@ async def get_snapshot_details(
 
 
 @dbt_mcp_tool(
-    description=get_prompt("discovery/get_test_details"),
+    description=deprecated_description(replacement="get_node_details"),
     title="Get Test Details",
     read_only_hint=True,
     destructive_hint=False,
     idempotent_hint=True,
+    meta=deprecation_meta(replacement="get_node_details"),
 )
 async def get_test_details(
     context: MultiProjectDiscoveryToolContext,
@@ -524,6 +558,7 @@ async def get_test_details(
 MULTIPROJECT_DISCOVERY_TOOLS = [
     get_mart_models,
     get_all_models,
+    get_node_details,
     get_model_details,
     get_model_parents,
     get_model_children,

src/dbt_mcp/prompts/discovery/get_node_details.md

@@ -0,0 +1,20 @@
+Retrieves full details for a dbt resource by type and name or unique ID.
+
+Use this tool when you need the full schema, definition, or metadata for a specific dbt resource. The `resource_type` determines what fields are returned.
+
+**Parameters:**
+- `resource_type`: The type of dbt resource. One of: `model`, `source`, `exposure`, `test`, `seed`, `snapshot`, `macro`, `semantic_model`. The resource type is also encoded in the `unique_id` prefix (e.g. `model.my_project.orders` → `model`).
+- `name`: The resource's short name (e.g. `orders`). Provide `name` or `unique_id`, not both.
+- `unique_id`: The resource's fully qualified unique ID (e.g. `model.my_project.orders`). Preferred when available — avoids ambiguity when multiple resources share a name.
+
+**Usage examples:**
+```python
+# Get details for a model by unique_id
+get_node_details(resource_type="model", unique_id="model.analytics.orders")
+
+# Get details for a source by name
+get_node_details(resource_type="source", name="raw_users")
+
+# Get details for a semantic model
+get_node_details(resource_type="semantic_model", unique_id="semantic_model.analytics.orders")
+```

src/dbt_mcp/tools/readme_mappings.py

@@ -27,6 +27,7 @@
     # Discovery tools
     ToolName.GET_MART_MODELS: "Retrieves all mart models.",
     ToolName.GET_ALL_MODELS: "Retrieves name and description of all models.",
+    ToolName.GET_NODE_DETAILS: "Gets full details for any dbt resource type (model, source, exposure, test, seed, snapshot, macro, semantic_model).",
     ToolName.GET_MODEL_DETAILS: "Gets model details including compiled SQL, columns, and schema.",
     ToolName.GET_MODEL_PARENTS: "Gets upstream dependencies of a model.",
     ToolName.GET_MODEL_CHILDREN: "Gets downstream dependents of a model.",

src/dbt_mcp/tools/tool_names.py

@@ -29,6 +29,7 @@ class ToolName(Enum):
     # Discovery tools
     GET_MART_MODELS = "get_mart_models"
     GET_ALL_MODELS = "get_all_models"
+    GET_NODE_DETAILS = "get_node_details"
     GET_MODEL_DETAILS = "get_model_details"
     GET_MODEL_PARENTS = "get_model_parents"
     GET_MODEL_CHILDREN = "get_model_children"

src/dbt_mcp/tools/toolsets.py

@@ -60,6 +60,7 @@ class Toolset(Enum):
     Toolset.DISCOVERY: {
         ToolName.GET_MART_MODELS,
         ToolName.GET_ALL_MODELS,
+        ToolName.GET_NODE_DETAILS,
         ToolName.GET_MODEL_DETAILS,
         ToolName.GET_MODEL_PARENTS,
         ToolName.GET_MODEL_CHILDREN,