Share multi-project project_id description for Discovery and Semantic layer (#758)

## Summary

Consolidated `project_id` description between multi-project semantic
layer and discovery usages.

## Checklist
- [x] I have performed a self-review of my code
- [x] I have made corresponding changes to the documentation (in
https://github.com/dbt-labs/docs.getdbt.com) if required -- Mention it
here
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes

Author: DevonFulcher

.changes/unreleased/Enhancement or New Feature-20260506-101233.yaml

@@ -0,0 +1,3 @@
+kind: Enhancement or New Feature
+body: Share multi-project project_id description for Discovery and Semantic layer
+time: 2026-05-06T10:12:33.706765-05:00

src/dbt_mcp/discovery/param_descriptions.py

@@ -1,13 +1,8 @@
-"""JSON Schema parameter descriptions and Field() defaults for Discovery MCP tools."""
+"""JSON Schema parameter descriptions for Discovery MCP tools."""
 
-from pydantic import Field
+from dbt_mcp.tools.multiproject_params import MULTI_PROJECT_PROJECT_ID_DESCRIPTION
 
-DISCOVERY_PROJECT_ID_DESCRIPTION = (
-    "The dbt Cloud project ID to query. "
-    "Use list_projects_and_environments to discover available project IDs."
-)
-
-PROJECT_ID_FIELD = Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)
+DISCOVERY_PROJECT_ID_DESCRIPTION = MULTI_PROJECT_PROJECT_ID_DESCRIPTION
 
 SOURCE_NAMES_FILTER = (
     "Filter by top-level source names from the project `sources:` YAML "

src/dbt_mcp/discovery/tools_multiproject.py

@@ -22,12 +22,12 @@
     SourcesFetcher,
 )
 from dbt_mcp.discovery.param_descriptions import (
+    DISCOVERY_PROJECT_ID_DESCRIPTION,
     MACRO_INCLUDE_DEFAULT_DBT_PACKAGES,
     MACRO_PACKAGE_NAMES,
     MACRO_RETURN_PACKAGE_NAMES_ONLY,
     MODEL_PERF_INCLUDE_TESTS,
     MODEL_PERF_NUM_RUNS,
-    PROJECT_ID_FIELD,
     SOURCE_NAMES_FILTER,
     SOURCE_UNIQUE_IDS_FILTER,
 )
@@ -123,7 +123,7 @@ def __init__(
 )
 async def get_mart_models(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
 ) -> list[dict]:
     config = await context.config_provider.get_config(project_id=project_id)
     mart_models = await context.models_fetcher.fetch_models(
@@ -142,7 +142,7 @@ async def get_mart_models(
 )
 async def get_all_models(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
 ) -> list[dict]:
     # TODO: push code into fetchers
     config = await context.config_provider.get_config(project_id=project_id)
@@ -158,7 +158,7 @@ async def get_all_models(
 )
 async def get_model_details(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
     name: str | None = NAME_FIELD,
     unique_id: str | None = UNIQUE_ID_FIELD,
 ) -> list[dict]:
@@ -180,7 +180,7 @@ async def get_model_details(
 )
 async def get_model_parents(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
     name: str | None = NAME_FIELD,
     unique_id: str | None = UNIQUE_ID_FIELD,
 ) -> list[dict]:
@@ -199,7 +199,7 @@ async def get_model_parents(
 )
 async def get_model_children(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
     name: str | None = NAME_FIELD,
     unique_id: str | None = UNIQUE_ID_FIELD,
 ) -> list[dict]:
@@ -218,7 +218,7 @@ async def get_model_children(
 )
 async def get_model_health(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
     name: str | None = NAME_FIELD,
     unique_id: str | None = UNIQUE_ID_FIELD,
 ) -> list[dict]:
@@ -239,7 +239,7 @@ async def get_model_health(
 )
 async def get_model_performance(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
     name: str | None = NAME_FIELD,
     unique_id: str | None = UNIQUE_ID_FIELD,
     num_runs: int = Field(
@@ -272,7 +272,7 @@ async def get_model_performance(
 )
 async def get_lineage(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
     unique_id: str = UNIQUE_ID_REQUIRED_FIELD,
     types: list[LineageResourceType] | None = TYPES_FIELD,
     depth: int = DEPTH_FIELD,
@@ -292,7 +292,7 @@ async def get_lineage(
 )
 async def get_exposures(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
 ) -> list[dict]:
     config = await context.config_provider.get_config(project_id=project_id)
     return await context.exposures_fetcher.fetch_exposures(config=config)
@@ -307,7 +307,7 @@ async def get_exposures(
 )
 async def get_exposure_details(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
     name: str | None = NAME_FIELD,
     unique_id: str | None = UNIQUE_ID_FIELD,
 ) -> list[dict]:
@@ -329,7 +329,7 @@ async def get_exposure_details(
 )
 async def get_all_sources(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
     source_names: Annotated[
         list[str] | None, Field(description=SOURCE_NAMES_FILTER)
     ] = None,
@@ -352,7 +352,7 @@ async def get_all_sources(
 )
 async def get_source_details(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
     name: str | None = NAME_FIELD,
     unique_id: str | None = UNIQUE_ID_FIELD,
 ) -> list[dict]:
@@ -374,7 +374,7 @@ async def get_source_details(
 )
 async def get_all_macros(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
     package_names: Annotated[
         list[str] | None, Field(description=MACRO_PACKAGE_NAMES)
     ] = None,
@@ -403,7 +403,7 @@ async def get_all_macros(
 )
 async def get_macro_details(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
     name: str | None = NAME_FIELD,
     unique_id: str | None = UNIQUE_ID_FIELD,
 ) -> list[dict]:
@@ -425,7 +425,7 @@ async def get_macro_details(
 )
 async def get_seed_details(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
     name: str | None = NAME_FIELD,
     unique_id: str | None = UNIQUE_ID_FIELD,
 ) -> list[dict]:
@@ -447,7 +447,7 @@ async def get_seed_details(
 )
 async def get_semantic_model_details(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
     name: str | None = NAME_FIELD,
     unique_id: str | None = UNIQUE_ID_FIELD,
 ) -> list[dict]:
@@ -469,7 +469,7 @@ async def get_semantic_model_details(
 )
 async def get_snapshot_details(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
     name: str | None = NAME_FIELD,
     unique_id: str | None = UNIQUE_ID_FIELD,
 ) -> list[dict]:
@@ -491,7 +491,7 @@ async def get_snapshot_details(
 )
 async def get_test_details(
     context: MultiProjectDiscoveryToolContext,
-    project_id: int = PROJECT_ID_FIELD,
+    project_id: Annotated[int, Field(description=DISCOVERY_PROJECT_ID_DESCRIPTION)],
     name: str | None = NAME_FIELD,
     unique_id: str | None = UNIQUE_ID_FIELD,
 ) -> list[dict]:

src/dbt_mcp/semantic_layer/param_descriptions.py

@@ -1,13 +1,12 @@
 """JSON Schema parameter descriptions for Semantic Layer MCP tools."""
 
 from dbt_mcp.dbt_admin.param_descriptions import PAGINATION_LIMIT
+from dbt_mcp.tools.multiproject_params import MULTI_PROJECT_PROJECT_ID_DESCRIPTION
 
 # Reuse Admin API wording for semantic query row limits (single source of truth).
 QUERY_RESULT_LIMIT = PAGINATION_LIMIT
 
-SEMANTIC_LAYER_PROJECT_ID = (
-    "Numeric dbt Cloud project ID to use for this Semantic Layer call"
-)
+SEMANTIC_LAYER_PROJECT_ID = MULTI_PROJECT_PROJECT_ID_DESCRIPTION
 
 SEMANTIC_SEARCH_METRICS = "Filter metrics by substring match against the metric name"
 

src/dbt_mcp/tools/multiproject_params.py

@@ -0,0 +1,6 @@
+"""Shared MCP parameter descriptions for multi-project (dbt Cloud) tool variants."""
+
+MULTI_PROJECT_PROJECT_ID_DESCRIPTION = (
+    "dbt Cloud numeric project ID for this call. "
+    "Use list_projects to discover valid project IDs."
+)