From d66af4a8d55b2fb614929f9461f6662510047a71 Mon Sep 17 00:00:00 2001
From: Tom Dobson <127199900+dobsontom@users.noreply.github.com>
Date: Wed, 14 Oct 2026 13:40:13 +0100
Subject: [PATCH 1/2] feat(alerts): use the meta description in source
 freshness alerts

---
 .../guides/alerts-code-configuration.mdx      | 11 ++++++++
 .../fetchers/alerts/schema/alert_data.py      |  2 +-
 .../alerts/schemas/test_alert_data_schema.py  | 25 +++++++++++++++++++
 3 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/docs/_snippets/guides/alerts-code-configuration.mdx b/docs/_snippets/guides/alerts-code-configuration.mdx
index db9d3721e..3018eb877 100644
--- a/docs/_snippets/guides/alerts-code-configuration.mdx
+++ b/docs/_snippets/guides/alerts-code-configuration.mdx
@@ -172,6 +172,17 @@ tests:
 
 </CodeGroup>
 
+Source freshness alerts read the same `description` key from the source's `meta`, and fall back to the default freshness description when it isn't set.
+
+```yml source
+sources:
+  - name: my_source
+    tables:
+      - name: my_table
+        meta:
+          description: "This is the source freshness description"
+```
+
 #### Tags
 
 You can use [tags](https://docs.getdbt.com/reference/resource-configs/tags) to provide context to your alerts.
diff --git a/elementary/monitor/fetchers/alerts/schema/alert_data.py b/elementary/monitor/fetchers/alerts/schema/alert_data.py
index 8d8e62689..9dd11437d 100644
--- a/elementary/monitor/fetchers/alerts/schema/alert_data.py
+++ b/elementary/monitor/fetchers/alerts/schema/alert_data.py
@@ -350,7 +350,7 @@ def format_alert(
             max_loaded_at=self.max_loaded_at,
             max_loaded_at_time_ago_in_s=self.max_loaded_at_time_ago_in_s,
             filter=self.filter,
-            freshness_description=self.freshness_description,
+            freshness_description=self.description or self.freshness_description,
             alert_class_id=self.alert_class_id,
             model_unique_id=self.model_unique_id,
             detected_at=self.detected_at,
diff --git a/tests/unit/monitor/fetchers/alerts/schemas/test_alert_data_schema.py b/tests/unit/monitor/fetchers/alerts/schemas/test_alert_data_schema.py
index aeff6cdc7..8a2ae65e3 100644
--- a/tests/unit/monitor/fetchers/alerts/schemas/test_alert_data_schema.py
+++ b/tests/unit/monitor/fetchers/alerts/schemas/test_alert_data_schema.py
@@ -5,6 +5,7 @@
 
 from elementary.monitor.fetchers.alerts.schema.alert_data import (
     BaseAlertDataSchema,
+    SourceFreshnessAlertDataSchema,
     TestAlertDataSchema,
 )
 from elementary.utils.time import DATETIME_FORMAT
@@ -37,6 +38,15 @@
     test_meta=dict(),
     elementary_unique_id="e_id_1"
 )
+SOURCE_FRESHNESS_ALERT = dict(
+    **BASE_ALERT,
+    source_freshness_execution_id="sfe_id_1",
+    source_name="source_1",
+    identifier="table_1",
+    original_status="error",
+    path="models/sources.yml",
+    freshness_description="default"
+)
 
 
 def test_flatten_meta():
@@ -119,3 +129,18 @@ def test_tags():
 
     base_alert = BaseAlertDataSchema(**{**BASE_ALERT, "tags": "a"})
     assert sorted(base_alert.tags) == sorted(["a"])
+
+
+@pytest.mark.parametrize(
+    "model_meta,expected",
+    [
+        (dict(), "default"),
+        (dict(description="custom"), "custom"),
+        (dict(alerts_config=dict(description="custom")), "custom"),
+    ],
+)
+def test_source_freshness_alert_description(model_meta, expected):
+    alert_data = SourceFreshnessAlertDataSchema(
+        **{**SOURCE_FRESHNESS_ALERT, "model_meta": model_meta}
+    )
+    assert alert_data.format_alert().freshness_description == expected

From 6165afdbf470f7c2323a62986c4ef566a4c640c2 Mon Sep 17 00:00:00 2001
From: Tom Dobson <127199900+dobsontom@users.noreply.github.com>
Date: Wed, 14 Oct 2026 13:44:51 +0100
Subject: [PATCH 2/2] docs(alerts): move the source freshness example into the
 description tabs

---
 docs/_snippets/guides/alerts-code-configuration.mdx | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/docs/_snippets/guides/alerts-code-configuration.mdx b/docs/_snippets/guides/alerts-code-configuration.mdx
index 3018eb877..6da606c5b 100644
--- a/docs/_snippets/guides/alerts-code-configuration.mdx
+++ b/docs/_snippets/guides/alerts-code-configuration.mdx
@@ -141,7 +141,7 @@ tests:
 
 #### Test description
 
-Elementary supports configuring description for tests that are included in alerts.
+Elementary supports configuring description for tests and source freshness checks that are included in alerts.
 It's recommended to add an explanation of what does it mean if this test fails, so alert will include this context.
 
 <CodeGroup>
@@ -170,10 +170,6 @@ tests:
         description: "This is the test description"
 ```
 
-</CodeGroup>
-
-Source freshness alerts read the same `description` key from the source's `meta`, and fall back to the default freshness description when it isn't set.
-
 ```yml source
 sources:
   - name: my_source
@@ -183,6 +179,8 @@ sources:
           description: "This is the source freshness description"
 ```
 
+</CodeGroup>
+
 #### Tags
 
 You can use [tags](https://docs.getdbt.com/reference/resource-configs/tags) to provide context to your alerts.