Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(error-tracking): return the issue summary from the MCP issue tool (#122534)

James Gill2807c64177bc
diff --git a/frontend/snapshots.yml b/frontend/snapshots.yml
index 7502462aab04..d5f50d344dae 100644
--- a/frontend/snapshots.yml
+++ b/frontend/snapshots.yml
@@ -6392,6 +6392,8 @@ snapshots:
hash: v1.k794b7964.1dd412a9421bb62e86ff964b3a0449375c9429b972a66fe3074db04bc7d7dd97.qWnA19cd9of2KGwgsVLoFh0yzOSwj8lWaSr2cDaW4_0
mcp-apps-error-tracking--with-external-links--light:
hash: v1.k794b7964.1c438b81ddecf6cd51016c53d57b3a80c7a60aab20f69a4629f52d9366452c72.alkUqUY-JcNO_PquFIaJSqBh0hBs4BbMf4NNbwjkHI4
+ mcp-apps-error-tracking--with-summary--light:
+ hash: v1.k794b7964.abc6286aac2c3c5d149186152dfe99f4f55211d22e1c5dcc7afdd660e7aee0a8._hUZDIukZAlhrPAG4jUp2qCJJpseLqP70Yft7dR0H6s
mcp-apps-experiments--completed--light:
hash: v1.k794b7964.2cd0548418687f103711826bcf66f9841ec296280045bcd908bb6faa71665fdd.kZS5bk6crHV7tw2advq5NZRhdwbDF5IrEkYNCnIvksE
mcp-apps-experiments--draft--light:
diff --git a/products/error_tracking/backend/presentation/views/query.py b/products/error_tracking/backend/presentation/views/query.py
index 2b24049ed356..a5b7bcf3002a 100644
--- a/products/error_tracking/backend/presentation/views/query.py
+++ b/products/error_tracking/backend/presentation/views/query.py
@@ -1,5 +1,6 @@
from __future__ import annotations
+import time
from typing import Literal, cast
from django.utils.timezone import now
@@ -25,14 +26,18 @@ from posthog.api.mixins import ValidatedRequest, validated_request
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.api.utils import action
from posthog.clickhouse.query_tagging import Feature, Product, tags_context
+from posthog.dataclasses import frozen
from posthog.event_usage import report_user_action
+from posthog.exceptions_capture import capture_exception
from posthog.hogql_queries.events_query_runner import EventsQueryRunner
from posthog.hogql_queries.query_runner import ExecutionMode
from posthog.models import User
from products.error_tracking.backend.facade import (
api as facade_api,
+ contracts,
queries as query_facade,
+ summaries as summaries_facade,
)
from products.error_tracking.backend.facade.query_utils import (
CONTEXT_EVENT_SELECTS,
@@ -75,10 +80,61 @@ from products.error_tracking.backend.presentation.views.query_serializers import
ErrorTrackingIssueQueryRequestSerializer,
ErrorTrackingIssuesListQueryRequestSerializer,
ErrorTrackingIssuesListResponseSerializer,
+ IssueSummaryStatus,
)
logger = structlog.get_logger(__name__)
+# The wait holds a web worker. A read that times out returns `generating`, and generation continues in the background.
+ISSUE_SUMMARY_WAIT_SECONDS = 6.0
+
+
+@frozen
+class IssueSummaryRead:
+ status: IssueSummaryStatus
+ summary: contracts.ErrorTrackingIssueSummary | None
+
+
+def read_issue_summary(team_id: int, issue_id: str, user: User) -> IssueSummaryRead:
+ """Return the stored summary, or wait a bounded time for a first one. A summary failure never fails the read."""
+ try:
+ # A stale stored summary returns at once while a newer one generates in the background.
+ summary = summaries_facade.get_issue_summary(team_id, issue_id, user=user)
+ started_at = now()
+ started = summaries_facade.start_issue_summary_generation(team_id, issue_id, user=user)
+ if summary is None and not started:
+ # A worker can save the first summary between the read above and the start, which then returns False.
+ summary = summaries_facade.get_issue_summary(team_id, issue_id, user=user)
+ if summary is None:
+ return IssueSummaryRead(status=IssueSummaryStatus.UNAVAILABLE, summary=None)
+ elif summary is None:
+ summary = summaries_facade.wait_for_issue_summary(
+ team_id,
+ issue_id,
+ user=user,
+ checked_after=started_at,
+ timeout_seconds=ISSUE_SUMMARY_WAIT_SECONDS,
+ )
+ except Exception as error:
+ capture_exception(error, {"team_id": team_id, "issue_id": issue_id})
+ return IssueSummaryRead(status=IssueSummaryStatus.UNAVAILABLE, summary=None)
+ if summary is None:
+ return IssueSummaryRead(status=IssueSummaryStatus.GENERATING, summary=None)
+ return IssueSummaryRead(status=IssueSummaryStatus.READY, summary=summary)
+
+
+def summary_payload(summary: contracts.ErrorTrackingIssueSummary) -> dict[str, object]:
+ return compact_dict(
+ {
+ "what_happened": summary.what_happened,
+ "likely_cause": summary.likely_cause,
+ "who_is_affected": summary.who_is_affected,
+ "suggested_next_step": summary.suggested_next_step,
+ "category": summary.category.value if summary.category is not None else None,
+ "generated_at": summary.generated_at.isoformat(),
+ }
+ )
+
class ErrorTrackingQueryViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):
scope_object = "error_tracking"
@@ -161,6 +217,7 @@ class ErrorTrackingQueryViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):
)
@action(methods=["POST"], detail=False, url_path="issue", required_scopes=["error_tracking:read"])
def issue(self, request: ValidatedRequest, **kwargs: object) -> Response:
+ started_at = time.monotonic()
params = dict(request.validated_data)
issue_id = str(params["issueId"])
date_range = build_date_range(params.get("dateRange"))
@@ -204,10 +261,14 @@ class ErrorTrackingQueryViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):
payload["impact"] = {}
if include_sparkline:
payload["sparkline"] = []
- self._report_issue_read(
- request, issue_id, "issue", include_breakdown=include_breakdown, include_sparkline=include_sparkline
+ return self._issue_response(
+ request,
+ issue_id,
+ payload,
+ started_at=started_at,
+ include_breakdown=include_breakdown,
+ include_sparkline=include_sparkline,
)
- return Response(payload)
issue = cast(dict[str, object], raw_results[0])
event_properties = self._issue_event_properties(
request,
@@ -243,8 +304,41 @@ class ErrorTrackingQueryViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):
)
if include_breakdown:
payload["breakdown"] = self._issue_breakdown(request, issue_id, date_range, filter_test_accounts)
+ return self._issue_response(
+ request,
+ issue_id,
+ payload,
+ started_at=started_at,
+ include_breakdown=include_breakdown,
+ include_sparkline=include_sparkline,
+ )
+
+ def _issue_response(
+ self,
+ request: ValidatedRequest,
+ issue_id: str,
+ payload: dict[str, object],
+ *,
+ started_at: float,
+ include_breakdown: bool,
+ include_sparkline: bool,
+ ) -> Response:
+ summary_started_at = time.monotonic()
+ summary_read = read_issue_summary(self.team.id, issue_id, cast(User, request.user))
+ summary_finished_at = time.monotonic()
+ if summary_read.summary is not None:
+ payload["summary"] = summary_payload(summary_read.summary)
+ payload["summary_status"] = summary_read.status.value
self._report_issue_read(
- request, issue_id, "issue", include_breakdown=include_breakdown, include_sparkline=include_sparkline
+ request,
+ issue_id,
+ "issue",
+ include_breakdown=include_breakdown,
+ include_sparkline=include_sparkline,
+ summary_status=summary_read.status.value,
+ # Shows whether starting generation before the ClickHouse queries would shorten first reads.
+ facts_ms=round((summary_started_at - started_at) * 1000),
+ summary_wait_ms=round((summary_finished_at - summary_started_at) * 1000),
)
return Response(payload)
diff --git a/products/error_tracking/backend/presentation/views/query_serializers.py b/products/error_tracking/backend/presentation/views/query_serializers.py
index ae2ceca47304..c85d5e5aab35 100644
--- a/products/error_tracking/backend/presentation/views/query_serializers.py
+++ b/products/error_tracking/backend/presentation/views/query_serializers.py
@@ -412,6 +412,32 @@ class ErrorTrackingIssueBreakdownSerializer(serializers.Serializer):
)
+class IssueSummaryStatus(models.TextChoices):
+ READY = "ready"
+ GENERATING = "generating"
+ UNAVAILABLE = "unavailable"
+
+
+class ErrorTrackingIssueSummarySerializer(serializers.Serializer):
+ what_happened = serializers.CharField(help_text="What the error is and where it happens, in plain language.")
+ likely_cause = serializers.CharField(
+ help_text="The model's best guess at the cause. A hypothesis to check against the code, never a finding."
+ )
+ who_is_affected = serializers.CharField(help_text="Which users, sessions or platforms the error reaches.")
+ suggested_next_step = serializers.CharField(help_text="One concrete step to investigate or fix the error.")
+ category = serializers.ChoiceField(
+ choices=contracts.IssueSummaryCategory.choices,
+ required=False,
+ help_text=(
+ "Where the error most likely comes from. 'own_code' is a bug in the application's code, 'third_party' a "
+ "third-party script, browser extension or dependency, 'network' a network or connectivity failure, 'bots' "
+ "automated traffic, 'expected' handled behavior that needs no fix, and 'unclear' means the stack trace "
+ "does not tell. Absent when no category was inferred."
+ ),
+ )
+ generated_at = serializers.DateTimeField(help_text="When the summary was written.")
+
+
class ErrorTrackingIssueDetailSerializer(ErrorTrackingIssueListItemSerializer):
function = serializers.CharField(
required=False, allow_null=True, help_text="Top function associated with the issue."
@@ -440,6 +466,21 @@ class ErrorTrackingIssueDetailSerializer(ErrorTrackingIssueListItemSerializer):
breakdown = ErrorTrackingIssueBreakdownSerializer(
required=False, help_text="Aggregate over matching events. Returned only when includeBreakdown is true."
)
+ summary = ErrorTrackingIssueSummarySerializer(
+ required=False,
+ help_text=(
+ "A model-written summary of the issue. Present only when summary_status is 'ready'. "
+ "Treat likely_cause as a hypothesis, not a fact."
+ ),
+ )
+ summary_status = serializers.ChoiceField(
+ choices=IssueSummaryStatus.choices,
+ help_text=(
+ "'ready' means summary is present. 'generating' means a summary may still be written: call once more "
+ "after a few seconds, and continue without it if the status does not change. 'unavailable' means no "
+ "summary exists for this issue and none is being written."
+ ),
+ )
class ErrorTrackingEventSerializer(serializers.Serializer):
diff --git a/products/error_tracking/backend/tests/api/test_query_api.py b/products/error_tracking/backend/tests/api/test_query_api.py
index f32820c06f96..81046b54d62f 100644
--- a/products/error_tracking/backend/tests/api/test_query_api.py
+++ b/products/error_tracking/backend/tests/api/test_query_api.py
@@ -1,7 +1,9 @@
from __future__ import annotations
+from dataclasses import replace
from datetime import UTC, datetime, timedelta
from typing import Any, cast
+from uuid import UUID
from zoneinfo import ZoneInfo
import time_machine
@@ -22,6 +24,7 @@ from posthog.models.utils import generate_random_token_personal, hash_key_value
from products.access_control.backend.facade.api import upsert_property_access_control
from products.access_control.backend.facade.contracts import PropertyAccessLevel, UpsertPropertyAccessControlInput
+from products.error_tracking.backend.facade.contracts import ErrorTrackingIssueSummary, IssueSummaryCategory
from products.error_tracking.backend.facade.query_utils import (
ISSUE_BREAKDOWN_TOP_VALUES,
MAX_STACK_FRAMES,
@@ -262,6 +265,28 @@ def test_breakdown_query_date_range(
assert breakdown_query_date_range(date_range, ZoneInfo("UTC"), BREAKDOWN_NOW) == (expected, expected_limited)
+SUMMARIES_FACADE = "products.error_tracking.backend.facade.summaries"
+STORED_SUMMARY = ErrorTrackingIssueSummary(
+ issue_id=UUID("01936e7f-d7ff-7314-b2d4-7627981e34f0"),
+ what_happened="Checkout throws a TypeError when the cart is empty.",
+ likely_cause="The cart total reads a property of an undefined line item.",
+ who_is_affected="Users who open checkout with an empty cart.",
+ suggested_next_step="Guard the line item lookup in the cart total.",
+ category=IssueSummaryCategory.OWN_CODE,
+ model="test-model",
+ generated_at=datetime(2026, 4, 24, 11, 0, tzinfo=UTC),
+ checked_at=datetime(2026, 4, 24, 11, 0, tzinfo=UTC),
+)
+STORED_SUMMARY_PAYLOAD = {
+ "what_happened": STORED_SUMMARY.what_happened,
+ "likely_cause": STORED_SUMMARY.likely_cause,
+ "who_is_affected": STORED_SUMMARY.who_is_affected,
+ "suggested_next_step": STORED_SUMMARY.suggested_next_step,
+ "category": "own_code",
+ "generated_at": "2026-04-24T11:00:00+00:00",
+}
+
+
class TestErrorTrackingQueryAPI(ClickhouseTestMixin, APIBaseTest):
issue_id = "01936e7f-d7ff-7314-b2d4-7627981e34f0"
fingerprint = "issue-fingerprint"
@@ -333,22 +358,25 @@ class TestErrorTrackingQueryAPI(ClickhouseTestMixin, APIBaseTest):
)
flush_persons_and_events()
- response = self.client.post(
- f"/api/environments/{self.team.id}/error_tracking/query/issues",
- data={
- "status": "all",
- "dateRange": {"date_from": "-1d", "date_to": "2026-04-25T00:00:00Z"},
- "library": "posthog-js",
- "release": "2026.04.24",
- "fingerprint": self.fingerprint,
- "url": "/checkout",
- "filterGroup": [{"key": "$browser", "type": "event", "operator": "exact", "value": ["Chrome"]}],
- },
- format="json",
- )
+ with patch(f"{SUMMARIES_FACADE}.start_issue_summary_generation") as start_generation:
+ response = self.client.post(
+ f"/api/environments/{self.team.id}/error_tracking/query/issues",
+ data={
+ "status": "all",
+ "dateRange": {"date_from": "-1d", "date_to": "2026-04-25T00:00:00Z"},
+ "library": "posthog-js",
+ "release": "2026.04.24",
+ "fingerprint": self.fingerprint,
+ "url": "/checkout",
+ "filterGroup": [{"key": "$browser", "type": "event", "operator": "exact", "value": ["Chrome"]}],
+ },
+ format="json",
+ )
assert response.status_code == 200
assert [row["id"] for row in response.json()["results"]] == [self.issue_id]
+ assert "summary" not in response.json()["results"][0]
+ start_generation.assert_not_called()
project_response = self.client.post(
f"/api/environments/{self.team.id}/error_tracking/query/issues",
@@ -818,8 +846,18 @@ class TestErrorTrackingQueryAPI(ClickhouseTestMixin, APIBaseTest):
@parameterized.expand(
[
- ("issue", True, {"includeSparkline": True}, {"include_breakdown": False, "include_sparkline": True}),
- ("issue", False, {"includeSparkline": True}, {"include_breakdown": False, "include_sparkline": True}),
+ (
+ "issue",
+ True,
+ {"includeSparkline": True},
+ {"include_breakdown": False, "include_sparkline": True, "summary_status": "unavailable"},
+ ),
+ (
+ "issue",
+ False,
+ {"includeSparkline": True},
+ {"include_breakdown": False, "include_sparkline": True, "summary_status": "unavailable"},
+ ),
("issue_events", True, {}, {}),
]
)
@@ -867,6 +905,91 @@ class TestErrorTrackingQueryAPI(ClickhouseTestMixin, APIBaseTest):
**expected_properties,
}
]
+ if endpoint == "issue":
+ assert isinstance(read_events[0]["facts_ms"], int)
+ assert isinstance(read_events[0]["summary_wait_ms"], int)
+
+ @parameterized.expand(
+ [
+ ("stored", STORED_SUMMARY, True, None, None, False, "ready", STORED_SUMMARY_PAYLOAD),
+ (
+ "stored_without_category",
+ replace(STORED_SUMMARY, category=None),
+ False,
+ None,
+ None,
+ False,
+ "ready",
+ {key: value for key, value in STORED_SUMMARY_PAYLOAD.items() if key != "category"},
+ ),
+ ("generated_within_the_wait", None, True, STORED_SUMMARY, None, True, "ready", STORED_SUMMARY_PAYLOAD),
+ ("wait_times_out", None, True, None, None, True, "generating", None),
+ ("gates_off", None, False, None, None, False, "unavailable", None),
+ (
+ "saved_before_the_start",
+ [None, STORED_SUMMARY],
+ False,
+ None,
+ None,
+ False,
+ "ready",
+ STORED_SUMMARY_PAYLOAD,
+ ),
+ ("facade_fails", None, None, None, RuntimeError("broker down"), False, "unavailable", None),
+ ]
+ )
+ @time_machine.travel("2026-04-24T12:00:00Z", tick=False)
+ def test_issue_detail_returns_the_summary(
+ self,
+ _name: str,
+ stored: ErrorTrackingIssueSummary | None | list[ErrorTrackingIssueSummary | None],
+ started: bool | None,
+ waited: ErrorTrackingIssueSummary | None,
+ start_error: Exception | None,
+ expect_wait: bool,
+ expected_status: str,
+ expected_summary: dict[str, object] | None,
+ ) -> None:
+ self.create_issue()
+ self.create_exception_event()
+ flush_persons_and_events()
+ clock = [100.0]
+
+ def wait(*_args: object, **_kwargs: object) -> ErrorTrackingIssueSummary | None:
+ clock[0] += 2.5
+ return waited
+
+ with (
+ patch("products.error_tracking.backend.presentation.views.query.time") as view_time,
+ patch(
+ f"{SUMMARIES_FACADE}.get_issue_summary",
+ side_effect=stored if isinstance(stored, list) else lambda *_args, **_kwargs: stored,
+ ),
+ patch(
+ f"{SUMMARIES_FACADE}.start_issue_summary_generation", return_value=started, side_effect=start_error
+ ) as start_generation,
+ patch(f"{SUMMARIES_FACADE}.wait_for_issue_summary", side_effect=wait) as wait_for_summary,
+ patch("posthog.event_usage.posthoganalytics.capture") as mock_capture,
+ ):
+ view_time.monotonic.side_effect = lambda: clock[0]
+ response = self.client.post(
+ f"/api/environments/{self.team.id}/error_tracking/query/issue",
+ data={"issueId": self.issue_id},
+ format="json",
+ )
+
+ assert response.status_code == 200
+ assert response.json()["summary_status"] == expected_status
+ assert response.json().get("summary") == expected_summary
+ assert response.json()["impact"]["occurrences"] == 1
+ start_generation.assert_called_once_with(self.team.id, self.issue_id, user=self.user)
+ assert wait_for_summary.called == expect_wait
+ [read_event] = [
+ call.kwargs["properties"]
+ for call in mock_capture.call_args_list
+ if call.kwargs.get("event") == "error_tracking_issue_read"
+ ]
+ assert (read_event["facts_ms"], read_event["summary_wait_ms"]) == (0, 2500 if expect_wait else 0)
def test_issue_read_succeeds_when_capture_fails(self) -> None:
self.create_issue()
diff --git a/products/error_tracking/frontend/generated/api.schemas.ts b/products/error_tracking/frontend/generated/api.schemas.ts
index 9e456e74f1c7..52f1d0296c00 100644
--- a/products/error_tracking/frontend/generated/api.schemas.ts
+++ b/products/error_tracking/frontend/generated/api.schemas.ts
@@ -1293,6 +1293,60 @@ export interface ErrorTrackingIssueBreakdownApi {
top_values: ErrorTrackingBreakdownTopValuesApi
}
+/**
+ * * `own_code` - Own Code
+ * * `third_party` - Third Party
+ * * `network` - Network
+ * * `bots` - Bots
+ * * `expected` - Expected
+ * * `unclear` - Unclear
+ */
+export type IssueSummaryCategoryEnumApi = (typeof IssueSummaryCategoryEnumApi)[keyof typeof IssueSummaryCategoryEnumApi]
+
+export const IssueSummaryCategoryEnumApi = {
+ OwnCode: 'own_code',
+ ThirdParty: 'third_party',
+ Network: 'network',
+ Bots: 'bots',
+ Expected: 'expected',
+ Unclear: 'unclear',
+} as const
+
+export interface ErrorTrackingIssueSummaryApi {
+ /** What the error is and where it happens, in plain language. */
+ what_happened: string
+ /** The model's best guess at the cause. A hypothesis to check against the code, never a finding. */
+ likely_cause: string
+ /** Which users, sessions or platforms the error reaches. */
+ who_is_affected: string
+ /** One concrete step to investigate or fix the error. */
+ suggested_next_step: string
+ /** Where the error most likely comes from. 'own_code' is a bug in the application's code, 'third_party' a third-party script, browser extension or dependency, 'network' a network or connectivity failure, 'bots' automated traffic, 'expected' handled behavior that needs no fix, and 'unclear' means the stack trace does not tell. Absent when no category was inferred.
+ *
+ * * `own_code` - Own Code
+ * * `third_party` - Third Party
+ * * `network` - Network
+ * * `bots` - Bots
+ * * `expected` - Expected
+ * * `unclear` - Unclear */
+ category?: IssueSummaryCategoryEnumApi
+ /** When the summary was written. */
+ generated_at: string
+}
+
+/**
+ * * `ready` - Ready
+ * * `generating` - Generating
+ * * `unavailable` - Unavailable
+ */
+export type IssueSummaryStatusEnumApi = (typeof IssueSummaryStatusEnumApi)[keyof typeof IssueSummaryStatusEnumApi]
+
+export const IssueSummaryStatusEnumApi = {
+ Ready: 'ready',
+ Generating: 'generating',
+ Unavailable: 'unavailable',
+} as const
+
export interface ErrorTrackingIssueDetailApi {
/** Error tracking issue ID. */
id: string
@@ -1353,6 +1407,14 @@ export interface ErrorTrackingIssueDetailApi {
sparkline?: number[]
/** Aggregate over matching events. Returned only when includeBreakdown is true. */
breakdown?: ErrorTrackingIssueBreakdownApi
+ /** A model-written summary of the issue. Present only when summary_status is 'ready'. Treat likely_cause as a hypothesis, not a fact. */
+ summary?: ErrorTrackingIssueSummaryApi
+ /** 'ready' means summary is present. 'generating' means a summary may still be written: call once more after a few seconds, and continue without it if the status does not change. 'unavailable' means no summary exists for this issue and none is being written.
+ *
+ * * `ready` - Ready
+ * * `generating` - Generating
+ * * `unavailable` - Unavailable */
+ summary_status: IssueSummaryStatusEnumApi
}
/**
diff --git a/products/error_tracking/mcp/apps/ErrorIssueView.test.tsx b/products/error_tracking/mcp/apps/ErrorIssueView.test.tsx
index a2cb2aef4958..760fbe56bc23 100644
--- a/products/error_tracking/mcp/apps/ErrorIssueView.test.tsx
+++ b/products/error_tracking/mcp/apps/ErrorIssueView.test.tsx
@@ -68,9 +68,33 @@ describe('ErrorIssueView', () => {
expect(screen.queryByText(/Browsers:/)).toBeNull()
})
- it('shows no breakdown when the response has none', () => {
+ it('shows no breakdown or summary when the response has none', () => {
render(<ErrorIssueView issue={{ id: 'issue-1', name: 'TypeError' }} />)
expect(screen.queryByText(/Breakdown of/)).toBeNull()
+ expect(screen.queryByText('Summary')).toBeNull()
+ })
+
+ it('labels the summary cause as a hypothesis', () => {
+ render(
+ <ErrorIssueView
+ issue={{
+ id: 'issue-1',
+ name: 'TypeError',
+ summary_status: 'ready',
+ summary: {
+ what_happened: 'Checkout throws on an empty cart.',
+ likely_cause: 'The cart total reads an undefined line item.',
+ who_is_affected: 'Users with an empty cart.',
+ suggested_next_step: 'Guard the line item lookup.',
+ category: 'own_code',
+ generated_at: '2026-04-24T11:00:00Z',
+ },
+ }}
+ />
+ )
+
+ expect(screen.getByText('Likely cause (hypothesis): The cart total reads an undefined line item.')).toBeTruthy()
+ expect(screen.getByText('Own code')).toBeTruthy()
})
})
diff --git a/products/error_tracking/mcp/apps/ErrorIssueView.tsx b/products/error_tracking/mcp/apps/ErrorIssueView.tsx
index 095295999761..acb8ebd95bbb 100644
--- a/products/error_tracking/mcp/apps/ErrorIssueView.tsx
+++ b/products/error_tracking/mcp/apps/ErrorIssueView.tsx
@@ -3,6 +3,12 @@ import type { ReactElement } from 'react'
import { DescriptionList, formatDate } from '@posthog/mcp-ui'
import { Badge, Button, Card, CardContent } from '@posthog/quill'
+import type {
+ ErrorTrackingIssueSummaryApi,
+ IssueSummaryCategoryEnumApi,
+ IssueSummaryStatusEnumApi,
+} from '../../frontend/generated/api.schemas'
+
export interface ExternalIssue {
external_url: string
integration?: { display_name?: string }
@@ -47,6 +53,15 @@ export function formatBreakdownValues(values: ErrorIssueBreakdownValue[] | undef
return (values ?? []).map(({ value, count }) => `${value} (${count})`).join(', ')
}
+const summaryCategoryLabels: Record<IssueSummaryCategoryEnumApi, string> = {
+ own_code: 'Own code',
+ third_party: 'Third party',
+ network: 'Network',
+ bots: 'Bots',
+ expected: 'Expected',
+ unclear: 'Unclear',
+}
+
export interface ErrorIssueData {
id: string
name: string
@@ -56,6 +71,8 @@ export interface ErrorIssueData {
assignee?: { id: string; type: string } | null
external_issues?: ExternalIssue[]
breakdown?: ErrorIssueBreakdown
+ summary?: ErrorTrackingIssueSummaryApi
+ summary_status?: IssueSummaryStatusEnumApi
_posthogUrl?: string
}
@@ -88,6 +105,32 @@ export function ErrorIssueView({ issue }: ErrorIssueViewProps): ReactElement {
{issue.description && <span className="text-sm text-muted-foreground">{issue.description}</span>}
</div>
+ {issue.summary && (
+ <Card>
+ <CardContent>
+ <div className="flex flex-col gap-2">
+ <div className="flex items-center gap-2 flex-wrap">
+ <span className="text-sm font-semibold">Summary</span>
+ {issue.summary.category && (
+ <Badge>{summaryCategoryLabels[issue.summary.category]}</Badge>
+ )}
+ </div>
+ <span className="text-xs text-muted-foreground">
+ Written by AI. Check it against the details below.
+ </span>
+ <DescriptionList
+ items={[
+ { label: 'What happened', value: issue.summary.what_happened },
+ { label: 'Likely cause (hypothesis)', value: issue.summary.likely_cause },
+ { label: 'Who is affected', value: issue.summary.who_is_affected },
+ { label: 'Next step', value: issue.summary.suggested_next_step },
+ ]}
+ />
+ </div>
+ </CardContent>
+ </Card>
+ )}
+
<Card>
<CardContent>
<DescriptionList
diff --git a/products/error_tracking/mcp/apps/ErrorTracking.stories.tsx b/products/error_tracking/mcp/apps/ErrorTracking.stories.tsx
index f24984a590d7..b6b3571d130d 100644
--- a/products/error_tracking/mcp/apps/ErrorTracking.stories.tsx
+++ b/products/error_tracking/mcp/apps/ErrorTracking.stories.tsx
@@ -115,6 +115,27 @@ export const WithBreakdown: Story = {
name: 'Issue with breakdown',
}
+const issueWithSummary: ErrorIssueData = {
+ ...activeIssue,
+ summary_status: 'ready',
+ summary: {
+ what_happened:
+ 'The dashboard grid throws a TypeError when it renders a dashboard whose items list is null. The page stays blank.',
+ likely_cause:
+ 'DashboardGrid.tsx calls map on dashboard items before the items request finishes, so the value is still null.',
+ who_is_affected: 'About 40 users in the last 7 days, mostly on Chrome, all on the dashboard page.',
+ suggested_next_step:
+ 'Default dashboard items to an empty list in DashboardGrid.tsx until the request finishes.',
+ category: 'own_code',
+ generated_at: '2025-12-11T09:00:00Z',
+ },
+}
+
+export const WithSummary: Story = {
+ render: () => <ErrorIssueView issue={issueWithSummary} />,
+ name: 'Issue with summary',
+}
+
const sampleListData: ErrorIssueListData = {
count: 4,
results: [activeIssue, resolvedIssue, issueWithLinks, suppressedIssue],
diff --git a/products/error_tracking/mcp/prompts/query-error-tracking-issue.md b/products/error_tracking/mcp/prompts/query-error-tracking-issue.md
index 3aa493a2673b..80df92da46d0 100644
--- a/products/error_tracking/mcp/prompts/query-error-tracking-issue.md
+++ b/products/error_tracking/mcp/prompts/query-error-tracking-issue.md
@@ -14,6 +14,8 @@ Defaults are intentionally useful: last 7 days, test accounts filtered out, aggr
# Response fields
+- `summary`: a model-written summary with `what_happened`, `likely_cause`, `who_is_affected`, `suggested_next_step` and `category`. Use it to answer quickly, and check it against the facts in the same response. `likely_cause` is a hypothesis. Report it as a possible cause, never as a fact, and check it against a stack trace from `query-error-tracking-issue-events` before you act on it.
+- `summary_status`: `ready` when `summary` is present. `generating` means a summary may still be written. If the user needs it, call this tool once more after a few seconds. If it is still `generating`, continue without it. `unavailable` means no summary is available for this issue. Do not mention a missing summary to the user.
- `first_release`: the release on the issue's first event, in the same shape as `latest_release`. It does not depend on `dateRange`. When the user asks which release caused the issue, compare it with `latest_release`. It is absent when the first event has no release metadata.
- `trend`: occurrences in the second half of `dateRange` against the first half. Read `direction` (`new`, `increasing`, `decreasing` or `stable`) and do not do the arithmetic again. `increasing` and `decreasing` mean a change of at least 25%. `new` means the issue was first seen in the second half. With small counts, check `current_occurrences` and `previous_occurrences` before you call a change significant. `trend` is absent when the issue has no occurrences in `dateRange`.
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index 1b7b674c584e..f93779bc844e 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -11252,7 +11252,7 @@
"reads_ingested_data": "events"
},
"query-error-tracking-issue": {
- "description": "Get compact details for one Error tracking issue.\n\nUse this after `query-error-tracking-issues-list` when you have an `issueId` and need issue status, severity, name/description, first/last seen timestamps, assignee, compact impact counts, trend, top in-app frame, and first and latest release metadata.\n\nDefaults are intentionally useful: last 7 days, test accounts filtered out, aggregate impact included, and no sparkline unless requested.\n\n# Parameters\n\n- `issueId`: required Error tracking issue UUID.\n- `dateRange`: time range for impact counts and latest-event metadata. Defaults to last 7 days.\n- `includeSparkline`: set true only if the shape of the volume over time helps answer the user. To ask whether the issue is getting worse or better, read `trend` instead. When true, `volumeResolution` defaults to 12 if not provided.\n- `volumeResolution`: integer count of equal-width buckets across `dateRange`, from 0 to 200, when sparkline data is needed. It is not a unit such as `hour` or `day`. For daily buckets over the default 7-day range, send `7`.\n- `includeBreakdown`: set true when the user asks where, for whom, or on which platforms the issue happens. It returns the same breakdowns as the issue page, over all matching events: the most common paths (or URLs, when events have no path, as with backend SDKs), screens, browsers, OS, libraries, library versions, and app versions, each with a count, and up to 5 `$session_id` values with the most events. It covers at most the last 30 days of `dateRange`; `range_limited` is true when it covers less than you asked for. Empty dimensions are left out.\n\n# Response fields\n\n- `first_release`: the release on the issue's first event, in the same shape as `latest_release`. It does not depend on `dateRange`. When the user asks which release caused the issue, compare it with `latest_release`. It is absent when the first event has no release metadata.\n- `trend`: occurrences in the second half of `dateRange` against the first half. Read `direction` (`new`, `increasing`, `decreasing` or `stable`) and do not do the arithmetic again. `increasing` and `decreasing` mean a change of at least 25%. `new` means the issue was first seen in the second half. With small counts, check `current_occurrences` and `previous_occurrences` before you call a change significant. `trend` is absent when the issue has no occurrences in `dateRange`.\n\n# Next steps\n\nUse `query-error-tracking-issue-events` with the same `issueId` only when the user needs a concrete event, a stack trace, code variables, OpenTelemetry trace IDs, or the handled flag. Do not fetch many events to count browsers, URLs, or versions; use `includeBreakdown` instead.\n\nWhen `sample_session_ids` is not empty and the user asks what happened before the error, call `query-session-recordings-list` with `session_ids`.",
+ "description": "Get compact details for one Error tracking issue.\n\nUse this after `query-error-tracking-issues-list` when you have an `issueId` and need issue status, severity, name/description, first/last seen timestamps, assignee, compact impact counts, trend, top in-app frame, and first and latest release metadata.\n\nDefaults are intentionally useful: last 7 days, test accounts filtered out, aggregate impact included, and no sparkline unless requested.\n\n# Parameters\n\n- `issueId`: required Error tracking issue UUID.\n- `dateRange`: time range for impact counts and latest-event metadata. Defaults to last 7 days.\n- `includeSparkline`: set true only if the shape of the volume over time helps answer the user. To ask whether the issue is getting worse or better, read `trend` instead. When true, `volumeResolution` defaults to 12 if not provided.\n- `volumeResolution`: integer count of equal-width buckets across `dateRange`, from 0 to 200, when sparkline data is needed. It is not a unit such as `hour` or `day`. For daily buckets over the default 7-day range, send `7`.\n- `includeBreakdown`: set true when the user asks where, for whom, or on which platforms the issue happens. It returns the same breakdowns as the issue page, over all matching events: the most common paths (or URLs, when events have no path, as with backend SDKs), screens, browsers, OS, libraries, library versions, and app versions, each with a count, and up to 5 `$session_id` values with the most events. It covers at most the last 30 days of `dateRange`; `range_limited` is true when it covers less than you asked for. Empty dimensions are left out.\n\n# Response fields\n\n- `summary`: a model-written summary with `what_happened`, `likely_cause`, `who_is_affected`, `suggested_next_step` and `category`. Use it to answer quickly, and check it against the facts in the same response. `likely_cause` is a hypothesis. Report it as a possible cause, never as a fact, and check it against a stack trace from `query-error-tracking-issue-events` before you act on it.\n- `summary_status`: `ready` when `summary` is present. `generating` means a summary may still be written. If the user needs it, call this tool once more after a few seconds. If it is still `generating`, continue without it. `unavailable` means no summary is available for this issue. Do not mention a missing summary to the user.\n- `first_release`: the release on the issue's first event, in the same shape as `latest_release`. It does not depend on `dateRange`. When the user asks which release caused the issue, compare it with `latest_release`. It is absent when the first event has no release metadata.\n- `trend`: occurrences in the second half of `dateRange` against the first half. Read `direction` (`new`, `increasing`, `decreasing` or `stable`) and do not do the arithmetic again. `increasing` and `decreasing` mean a change of at least 25%. `new` means the issue was first seen in the second half. With small counts, check `current_occurrences` and `previous_occurrences` before you call a change significant. `trend` is absent when the issue has no occurrences in `dateRange`.\n\n# Next steps\n\nUse `query-error-tracking-issue-events` with the same `issueId` only when the user needs a concrete event, a stack trace, code variables, OpenTelemetry trace IDs, or the handled flag. Do not fetch many events to count browsers, URLs, or versions; use `includeBreakdown` instead.\n\nWhen `sample_session_ids` is not empty and the user asks what happened before the error, call `query-session-recordings-list` with `session_ids`.",
"category": "Error tracking",
"feature": "error_tracking",
"summary": "Query error tracking issue",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index 65a737504591..0d7082d7dea5 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -11909,7 +11909,7 @@
"reads_ingested_data": "events"
},
"query-error-tracking-issue": {
- "description": "Get compact details for one Error tracking issue.\n\nUse this after `query-error-tracking-issues-list` when you have an `issueId` and need issue status, severity, name/description, first/last seen timestamps, assignee, compact impact counts, trend, top in-app frame, and first and latest release metadata.\n\nDefaults are intentionally useful: last 7 days, test accounts filtered out, aggregate impact included, and no sparkline unless requested.\n\n# Parameters\n\n- `issueId`: required Error tracking issue UUID.\n- `dateRange`: time range for impact counts and latest-event metadata. Defaults to last 7 days.\n- `includeSparkline`: set true only if the shape of the volume over time helps answer the user. To ask whether the issue is getting worse or better, read `trend` instead. When true, `volumeResolution` defaults to 12 if not provided.\n- `volumeResolution`: integer count of equal-width buckets across `dateRange`, from 0 to 200, when sparkline data is needed. It is not a unit such as `hour` or `day`. For daily buckets over the default 7-day range, send `7`.\n- `includeBreakdown`: set true when the user asks where, for whom, or on which platforms the issue happens. It returns the same breakdowns as the issue page, over all matching events: the most common paths (or URLs, when events have no path, as with backend SDKs), screens, browsers, OS, libraries, library versions, and app versions, each with a count, and up to 5 `$session_id` values with the most events. It covers at most the last 30 days of `dateRange`; `range_limited` is true when it covers less than you asked for. Empty dimensions are left out.\n\n# Response fields\n\n- `first_release`: the release on the issue's first event, in the same shape as `latest_release`. It does not depend on `dateRange`. When the user asks which release caused the issue, compare it with `latest_release`. It is absent when the first event has no release metadata.\n- `trend`: occurrences in the second half of `dateRange` against the first half. Read `direction` (`new`, `increasing`, `decreasing` or `stable`) and do not do the arithmetic again. `increasing` and `decreasing` mean a change of at least 25%. `new` means the issue was first seen in the second half. With small counts, check `current_occurrences` and `previous_occurrences` before you call a change significant. `trend` is absent when the issue has no occurrences in `dateRange`.\n\n# Next steps\n\nUse `query-error-tracking-issue-events` with the same `issueId` only when the user needs a concrete event, a stack trace, code variables, OpenTelemetry trace IDs, or the handled flag. Do not fetch many events to count browsers, URLs, or versions; use `includeBreakdown` instead.\n\nWhen `sample_session_ids` is not empty and the user asks what happened before the error, call `query-session-recordings-list` with `session_ids`.",
+ "description": "Get compact details for one Error tracking issue.\n\nUse this after `query-error-tracking-issues-list` when you have an `issueId` and need issue status, severity, name/description, first/last seen timestamps, assignee, compact impact counts, trend, top in-app frame, and first and latest release metadata.\n\nDefaults are intentionally useful: last 7 days, test accounts filtered out, aggregate impact included, and no sparkline unless requested.\n\n# Parameters\n\n- `issueId`: required Error tracking issue UUID.\n- `dateRange`: time range for impact counts and latest-event metadata. Defaults to last 7 days.\n- `includeSparkline`: set true only if the shape of the volume over time helps answer the user. To ask whether the issue is getting worse or better, read `trend` instead. When true, `volumeResolution` defaults to 12 if not provided.\n- `volumeResolution`: integer count of equal-width buckets across `dateRange`, from 0 to 200, when sparkline data is needed. It is not a unit such as `hour` or `day`. For daily buckets over the default 7-day range, send `7`.\n- `includeBreakdown`: set true when the user asks where, for whom, or on which platforms the issue happens. It returns the same breakdowns as the issue page, over all matching events: the most common paths (or URLs, when events have no path, as with backend SDKs), screens, browsers, OS, libraries, library versions, and app versions, each with a count, and up to 5 `$session_id` values with the most events. It covers at most the last 30 days of `dateRange`; `range_limited` is true when it covers less than you asked for. Empty dimensions are left out.\n\n# Response fields\n\n- `summary`: a model-written summary with `what_happened`, `likely_cause`, `who_is_affected`, `suggested_next_step` and `category`. Use it to answer quickly, and check it against the facts in the same response. `likely_cause` is a hypothesis. Report it as a possible cause, never as a fact, and check it against a stack trace from `query-error-tracking-issue-events` before you act on it.\n- `summary_status`: `ready` when `summary` is present. `generating` means a summary may still be written. If the user needs it, call this tool once more after a few seconds. If it is still `generating`, continue without it. `unavailable` means no summary is available for this issue. Do not mention a missing summary to the user.\n- `first_release`: the release on the issue's first event, in the same shape as `latest_release`. It does not depend on `dateRange`. When the user asks which release caused the issue, compare it with `latest_release`. It is absent when the first event has no release metadata.\n- `trend`: occurrences in the second half of `dateRange` against the first half. Read `direction` (`new`, `increasing`, `decreasing` or `stable`) and do not do the arithmetic again. `increasing` and `decreasing` mean a change of at least 25%. `new` means the issue was first seen in the second half. With small counts, check `current_occurrences` and `previous_occurrences` before you call a change significant. `trend` is absent when the issue has no occurrences in `dateRange`.\n\n# Next steps\n\nUse `query-error-tracking-issue-events` with the same `issueId` only when the user needs a concrete event, a stack trace, code variables, OpenTelemetry trace IDs, or the handled flag. Do not fetch many events to count browsers, URLs, or versions; use `includeBreakdown` instead.\n\nWhen `sample_session_ids` is not empty and the user asks what happened before the error, call `query-session-recordings-list` with `session_ids`.",
"category": "Error tracking",
"feature": "error_tracking",
"summary": "Query error tracking issue",
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 0aec156867b8..e82a25f04916 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -41849,6 +41849,62 @@ export namespace Schemas {
current_from: string;
}
+ /**
+ * * `own_code` - Own Code
+ * * `third_party` - Third Party
+ * * `network` - Network
+ * * `bots` - Bots
+ * * `expected` - Expected
+ * * `unclear` - Unclear
+ */
+ export type IssueSummaryCategoryEnum = typeof IssueSummaryCategoryEnum[keyof typeof IssueSummaryCategoryEnum];
+
+
+ export const IssueSummaryCategoryEnum = {
+ OwnCode: 'own_code',
+ ThirdParty: 'third_party',
+ Network: 'network',
+ Bots: 'bots',
+ Expected: 'expected',
+ Unclear: 'unclear',
+ } as const;
+
+ export interface ErrorTrackingIssueSummary {
+ /** What the error is and where it happens, in plain language. */
+ what_happened: string;
+ /** The model's best guess at the cause. A hypothesis to check against the code, never a finding. */
+ likely_cause: string;
+ /** Which users, sessions or platforms the error reaches. */
+ who_is_affected: string;
+ /** One concrete step to investigate or fix the error. */
+ suggested_next_step: string;
+ /** Where the error most likely comes from. 'own_code' is a bug in the application's code, 'third_party' a third-party script, browser extension or dependency, 'network' a network or connectivity failure, 'bots' automated traffic, 'expected' handled behavior that needs no fix, and 'unclear' means the stack trace does not tell. Absent when no category was inferred.
+ *
+ * * `own_code` - Own Code
+ * * `third_party` - Third Party
+ * * `network` - Network
+ * * `bots` - Bots
+ * * `expected` - Expected
+ * * `unclear` - Unclear */
+ category?: IssueSummaryCategoryEnum;
+ /** When the summary was written. */
+ generated_at: string;
+ }
+
+ /**
+ * * `ready` - Ready
+ * * `generating` - Generating
+ * * `unavailable` - Unavailable
+ */
+ export type IssueSummaryStatusEnum = typeof IssueSummaryStatusEnum[keyof typeof IssueSummaryStatusEnum];
+
+
+ export const IssueSummaryStatusEnum = {
+ Ready: 'ready',
+ Generating: 'generating',
+ Unavailable: 'unavailable',
+ } as const;
+
export interface ErrorTrackingIssueDetail {
/** Error tracking issue ID. */
id: string;
@@ -41909,6 +41965,14 @@ export namespace Schemas {
sparkline?: number[];
/** Aggregate over matching events. Returned only when includeBreakdown is true. */
breakdown?: ErrorTrackingIssueBreakdown;
+ /** A model-written summary of the issue. Present only when summary_status is 'ready'. Treat likely_cause as a hypothesis, not a fact. */
+ summary?: ErrorTrackingIssueSummary;
+ /** 'ready' means summary is present. 'generating' means a summary may still be written: call once more after a few seconds, and continue without it if the status does not change. 'unavailable' means no summary exists for this issue and none is being written.
+ *
+ * * `ready` - Ready
+ * * `generating` - Generating
+ * * `unavailable` - Unavailable */
+ summary_status: IssueSummaryStatusEnum;
}
/**