feat: switch list_metrics response from JSON to CSV (#709)

Closes #708

## Summary

Switches the `list_metrics` tool response from JSON to CSV format. This
is unconventional, but for this use case — tabular data with potentially
many rows — CSV offers substantial benefits over JSON as LLM context:

- **67% smaller response**: 24,855 chars (JSON) → 8,139 chars (CSV)
- **Up to 33% lower cost** to answer a question end-to-end vs JSON
baseline
- Null/empty fields are omitted dynamically: columns only appear when at
least one metric has a value, keeping output compact by default
- When the CSV still exceeds `DBT_MCP_SL_MAX_RESPONSE_CHARS`, optional
columns (`description`, `metadata`) are stripped as a fallback

### Also included

**Prompt improvements** — guide agents to skip unnecessary
`get_dimensions` calls when `metric_time` is the only dimension needed,
compounding the token savings from the smaller response.

**Where clause fix** — strip surrounding double-quotes that LLMs
sometimes add to the `where` parameter string, preventing `Invalid {{
delimiter` errors from the dbt Semantic Layer's Jinja parser.

Author: b-per

.changes/unreleased/Enhancement or New Feature-20260410-list-metrics-csv.yaml

@@ -0,0 +1,3 @@
+kind: Enhancement or New Feature
+body: Reduce list_metrics response size by switching from JSON to CSV format, cutting response size by ~67% and reducing agent cost by up to 33% per query
+time: 2026-04-10T13:30:00.000000-07:00

src/dbt_mcp/config/config.py

@@ -147,6 +147,7 @@ def load_config(enable_proxied_tools: bool = True) -> Config:
                 credentials_provider=credentials_provider,
                 admin_client=admin_client,
                 metrics_related_max=settings.sl_metrics_related_max,
+                max_response_chars=settings.sl_metrics_max_response_chars,
             )
         )
 
@@ -181,6 +182,7 @@ def load_config(enable_proxied_tools: bool = True) -> Config:
         semantic_layer_config_provider = DefaultSemanticLayerConfigProvider(
             credentials_provider=credentials_provider,
             metrics_related_max=settings.sl_metrics_related_max,
+            max_response_chars=settings.sl_metrics_max_response_chars,
         )
 
     lsp_config = None

src/dbt_mcp/config/config_providers/base.py

@@ -58,3 +58,4 @@ class SemanticLayerConfig:
     token_provider: TokenProvider
     headers_provider: HeadersProvider
     metrics_related_max: int = 10
+    max_response_chars: int = 16000

src/dbt_mcp/config/config_providers/semantic_layer.py

@@ -14,9 +14,11 @@ def __init__(
         credentials_provider: CredentialsProvider,
         *,
         metrics_related_max: int = 10,
+        max_response_chars: int = 16000,
     ):
         self.credentials_provider = credentials_provider
         self.metrics_related_max = metrics_related_max
+        self.max_response_chars = max_response_chars
 
     async def get_config(self) -> SemanticLayerConfig:
         settings, token_provider = await self.credentials_provider.get_credentials()
@@ -39,6 +41,7 @@ async def get_config(self) -> SemanticLayerConfig:
                 token_provider=token_provider
             ),
             metrics_related_max=self.metrics_related_max,
+            max_response_chars=self.max_response_chars,
         )
 
 
@@ -51,10 +54,12 @@ def __init__(
         admin_client: DbtAdminAPIClient,
         *,
         metrics_related_max: int = 10,
+        max_response_chars: int = 16000,
     ):
         self.credentials_provider = credentials_provider
         self.admin_client = admin_client
         self.metrics_related_max = metrics_related_max
+        self.max_response_chars = max_response_chars
 
     async def get_config(self, project_id: int) -> SemanticLayerConfig:
         settings, token_provider = await self.credentials_provider.get_credentials()
@@ -86,4 +91,5 @@ async def get_config(self, project_id: int) -> SemanticLayerConfig:
                 token_provider=token_provider
             ),
             metrics_related_max=self.metrics_related_max,
+            max_response_chars=self.max_response_chars,
         )

src/dbt_mcp/config/settings.py

@@ -108,6 +108,9 @@ class DbtMcpSettings(BaseSettings):
     sl_metrics_related_max: int = Field(
         10, alias="DBT_MCP_SL_METRICS_RELATED_MAX", ge=0
     )
+    sl_metrics_max_response_chars: int = Field(
+        16000, alias="DBT_MCP_SL_MAX_RESPONSE_CHARS", ge=0
+    )
 
     def __repr__(self):
         """Custom repr to bring most important settings to front. Redact sensitive info."""

src/dbt_mcp/prompts/semantic_layer/get_dimensions.md

@@ -1,6 +1,8 @@
 <instructions>
 Get the dimensions for specified metrics
 
+Note: `metric_time` is a standard time dimension available on most metrics. You do not need to call this tool just to confirm time dimensions exist — call it only when you need categorical dimensions or specific granularity details. If this tool returns no results, proceed to query directly using `metric_time`.
+
 Dimensions are the attributes, features, or characteristics
 that describe or categorize data.
 

src/dbt_mcp/prompts/semantic_layer/list_metrics.md

@@ -1,8 +1,10 @@
 List metrics from the dbt Semantic Layer.
 
+The response is a CSV string with a header row. Columns are dynamic: a column is only present if at least one metric has a non-empty value for it. `name` and `type` are always present; `label`, `description`, `metadata`, `dimensions`, and `entities` are included only when at least one metric has a value. The `dimensions` and `entities` cells contain comma-separated lists of names.
+
 When the number of metrics is below the configured threshold (default: 10), each metric includes the names of its available dimensions and entities. Use get_dimensions or get_entities for full details (types, granularities, descriptions) on specific metrics.
 
-When above the threshold, only metrics are returned. Use get_dimensions and get_entities with the specific metrics you need.
+When above the threshold, only metrics are returned. `metric_time` is a standard time dimension available on most metrics — you can often query directly without calling `get_dimensions` first. Call `get_dimensions` only when you need non-time dimensions or specific granularity details.
 
 If the user is asking a data-related or business-related question, use this tool as a first step.
 

src/dbt_mcp/prompts/semantic_layer/query_metrics.md

@@ -18,7 +18,8 @@ and entity are referenced differently. For categorical dimensions,
 use `{{ Dimension('<name>') }}` and for time dimensions add the grain
 like `{{ TimeDimension('<name>', '<grain>') }}`. For entities,
 use `{{ Entity('<name>') }}`. When referencing dates in the `where`
-parameter, only use the format `yyyy-mm-dd`.
+parameter, only use the format `yyyy-mm-dd`. Pass the `where` value as a
+plain string — do not wrap it in additional quotes.
 
 Don't call this tool if the user's question cannot be answered with the provided
 metrics, dimensions, and entities. Instead, clarify what metrics, dimensions,

src/dbt_mcp/semantic_layer/client.py

@@ -296,6 +296,19 @@ def _format_get_metrics_compiled_sql_error(
             error=self._format_semantic_layer_error(compile_error)
         )
 
+    def _normalize_where(self, where: str | None) -> str | None:
+        """Strip surrounding quotes that LLMs sometimes add to where clause strings.
+
+        Returns None if the input is None or becomes empty/whitespace-only after
+        stripping quotes — the caller should treat this as "no where clause".
+        """
+        if where is None:
+            return None
+        where = where.strip()
+        if len(where) >= 2 and where[0] == '"' and where[-1] == '"':
+            where = where[1:-1]
+        return where.strip() or None
+
     # TODO: move this to the SDK
     def _format_query_failed_error(self, query_error: Exception) -> QueryMetricsError:
         if isinstance(query_error, QueryFailedError):
@@ -369,7 +382,9 @@ async def get_metrics_compiled_sql(
                     metrics=metrics,
                     group_by=group_by,  # type: ignore
                     order_by=parsed_order_by,  # type: ignore
-                    where=[where] if where else None,
+                    where=[normalized_where]
+                    if (normalized_where := self._normalize_where(where))
+                    else None,
                     limit=limit,
                     read_cache=True,
                 )
@@ -406,7 +421,9 @@ async def query_metrics(
                         metrics=metrics,
                         group_by=group_by,  # type: ignore
                         order_by=parsed_order_by,  # type: ignore
-                        where=[where] if where else None,
+                        where=[normalized_where]
+                        if (normalized_where := self._normalize_where(where))
+                        else None,
                         limit=limit,
                     )
                 except RetryTimeoutError as e:

src/dbt_mcp/semantic_layer/tools.py

@@ -1,3 +1,6 @@
+import csv
+import io
+import json
 import logging
 from dataclasses import dataclass
 
@@ -14,10 +17,11 @@
     DimensionToolResponse,
     EntityToolResponse,
     GetMetricsCompiledSqlSuccess,
+    ListMetricsResponse,
+    MetricToolResponse,
     OrderByParam,
     QueryMetricsSuccess,
     SavedQueryToolResponse,
-    ListMetricsResponse,
 )
 from dbt_mcp.tools.definitions import dbt_mcp_tool
 from dbt_mcp.tools.register import register_tools
@@ -27,6 +31,48 @@
 logger = logging.getLogger(__name__)
 
 
+def _build_csv(metrics: list[MetricToolResponse], columns: list[str]) -> str:
+    def _cell(m: MetricToolResponse, col: str) -> str:
+        val = getattr(m, col)
+        if val is None:
+            return ""
+        if isinstance(val, list):
+            return ",".join(str(v) for v in val)
+        if isinstance(val, dict):
+            return json.dumps(val, separators=(",", ":"), sort_keys=True)
+        return str(val)
+
+    output = io.StringIO()
+    writer = csv.writer(output, lineterminator="\n")
+    writer.writerow(columns)
+    for m in metrics:
+        writer.writerow([_cell(m, col) for col in columns])
+    return output.getvalue().rstrip("\n")
+
+
+def metrics_to_csv(response: ListMetricsResponse, max_response_chars: int = 0) -> str:
+    metrics = response.metrics
+    if not metrics:
+        return ""
+
+    def _has_any(field: str) -> bool:
+        # Skip columns where every value is None/empty — empty lists/dicts/strings
+        # count as "no data" so the column is omitted entirely.
+        return any(getattr(m, field) for m in metrics)
+
+    columns: list[str] = ["name", "type"]
+    for col in ("label", "description", "metadata", "dimensions", "entities"):
+        if _has_any(col):
+            columns.append(col)
+
+    result = _build_csv(metrics, columns)
+    if max_response_chars > 0 and len(result) > max_response_chars:
+        # Strip optional fields and rebuild
+        columns = [c for c in columns if c not in ("description", "metadata")]
+        result = _build_csv(metrics, columns)
+    return result
+
+
 @dataclass
 class SemanticLayerToolContext:
     config_provider: ConfigProvider[SemanticLayerConfig]
@@ -53,11 +99,12 @@ def __init__(
 async def list_metrics(
     context: SemanticLayerToolContext,
     search: str | None = None,
-) -> ListMetricsResponse:
+) -> str:
     config = await context.config_provider.get_config()
-    return await context.semantic_layer_fetcher.list_metrics(
+    response = await context.semantic_layer_fetcher.list_metrics(
         config=config, search=search
     )
+    return metrics_to_csv(response, max_response_chars=config.max_response_chars)
 
 
 @dbt_mcp_tool(