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.

fix(signals): tidy agent-facing ranking predictions and track their use (#123109)

posthog[bot]1e3d1a793934
diff --git a/products/signals/backend/test/test_signal_report_api.py b/products/signals/backend/test/test_signal_report_api.py
index fb8e70f3f67c..abb9f0f6beb5 100644
--- a/products/signals/backend/test/test_signal_report_api.py
+++ b/products/signals/backend/test/test_signal_report_api.py
@@ -1093,6 +1093,49 @@ class TestSignalReportListAPI(APIBaseTest):
assert response.status_code == status.HTTP_200_OK
assert sorted(row["title"] for row in response.json()["results"]) == sorted(expected)
+ @parameterized.expand(
+ [
+ (
+ "mcp_public_ordering_and_lift",
+ True,
+ "",
+ {"ordering": "-ranking_fix", "ranking_min_lift": "fix:2"},
+ {"surface": "mcp", "ordering_outcomes": ["fix"], "min_lift": {"fix": 2.0}, "result_count": 1},
+ ),
+ (
+ "api_alias_and_internal_head",
+ False,
+ "",
+ {"ordering": "-ranking_fixed,ranking_pr_merged"},
+ {"surface": "api", "ordering_outcomes": ["fix", "internal"], "min_lift": {}, "result_count": 2},
+ ),
+ ("no_ranking_parameters", False, "", {"ordering": "-updated_at"}, None),
+ ("web_inbox_load", False, "Mozilla/5.0", {"ordering": "-ranking_fix"}, None),
+ ]
+ )
+ def test_list_captures_ranking_usage(self, _name, via_mcp, user_agent, query, expected):
+ self.user.is_staff = True
+ self.user.save()
+ high = self._create_report(title="High")
+ self._create_report(title="Low")
+ self._ranking_score_artefact(high, scores={"fixed": 0.6}, lifts={"fixed": 3.0})
+
+ with (
+ patch("products.signals.backend.views.is_mcp_request", return_value=via_mcp),
+ patch("products.signals.backend.views.report_user_action") as report_action,
+ ):
+ response = self.client.get(self._list_url(status="ready", **query), headers={"user-agent": user_agent})
+
+ assert response.status_code == status.HTTP_200_OK
+ events = [call for call in report_action.call_args_list if call.args[1] == "signals_inbox_ranking_used"]
+ if expected is None:
+ assert events == []
+ return
+ assert len(events) == 1
+ properties = events[0].kwargs["properties"]
+ assert {key: properties[key] for key in expected} == expected
+ assert properties["endpoint"] == "list"
+
def test_ranking_filter_match_shows_as_scored_despite_bad_readable_metadata(self):
self.user.is_staff = True
self.user.save()
@@ -1168,10 +1211,15 @@ class TestSignalReportListAPI(APIBaseTest):
def test_ranking_outcomes_without_a_readable_model(self, _name, is_staff, expected_status):
self.user.is_staff = is_staff
self.user.save()
- with patch("products.signals.backend.ranking.access.feature_enabled_or_false", return_value=False):
+ with (
+ patch("products.signals.backend.ranking.access.feature_enabled_or_false", return_value=False),
+ patch("products.signals.backend.views.report_user_action") as report_action,
+ ):
response = self.client.get(f"/api/projects/{self.team.id}/signals/reports/ranking_outcomes/")
assert response.status_code == status.HTTP_200_OK
assert response.json() == {"status": expected_status, "model": None, "outcomes": []}
+ report_action.assert_called_once()
+ assert report_action.call_args.kwargs["properties"]["ranking_status"] == expected_status
@parameterized.expand(
[
diff --git a/products/signals/backend/views.py b/products/signals/backend/views.py
index 077c02e4d5ac..1cb0f3073372 100644
--- a/products/signals/backend/views.py
+++ b/products/signals/backend/views.py
@@ -61,6 +61,7 @@ from posthog.auth import (
OAuthAccessTokenAuthentication,
PersonalAPIKeyAuthentication,
SessionAuthentication,
+ is_mcp_request,
)
from posthog.dataclasses import frozen
from posthog.egress.github.transport import GitHubEgressBudgetExhausted, GitHubRateLimitError
@@ -396,6 +397,27 @@ def parse_pr_ci_status_report_ids(raw: str | None) -> list[uuid.UUID]:
raise exceptions.ValidationError({"report_ids": "Every report id must be a UUID."})
+# Ordering field to the outcome head it reads from the served model of the latest ranking score. The API
+# documents only the public outcomes. Staff tools and saved URLs still use the internal heads and `ranking_fixed`,
+# the old name of `ranking_fix`, so the API accepts them but does not document them.
+PUBLIC_RANKING_ORDERING_HEADS: dict[str, str] = {
+ f"ranking_{outcome}": head for outcome, head in MODEL_HEAD_BY_OUTCOME.items()
+}
+UNDOCUMENTED_RANKING_ORDERING_HEADS: dict[str, str] = {
+ "ranking_fixed": "fixed",
+ "ranking_pr_merged": "pr_merged",
+ "ranking_pr_created": "pr_created",
+ "ranking_discuss": "discuss",
+ "ranking_thumbs_up": "thumbs_up",
+ "ranking_reviewer_fix": "reviewer_fix",
+ "ranking_refund": "refund",
+ "ranking_dismiss_wrong": "dismiss_wrong",
+ "ranking_dismiss_lowvalue": "dismiss_lowvalue",
+}
+RANKING_ORDERING_HEADS: dict[str, str] = PUBLIC_RANKING_ORDERING_HEADS | UNDOCUMENTED_RANKING_ORDERING_HEADS
+_OUTCOME_BY_MODEL_HEAD: dict[str, str] = {head: outcome for outcome, head in MODEL_HEAD_BY_OUTCOME.items()}
+
+
def classify_report_list_client(user_agent: str | None) -> str:
if user_agent and user_agent.startswith("posthog/desktop.hog.dev;"):
return "desktop"
@@ -1273,35 +1295,10 @@ class SignalReportViewSet(
"created_at": "created_at",
"updated_at": "updated_at",
"id": "id",
- "ranking_pr_merged": "ranking_pr_merged_score",
- "ranking_pr_created": "ranking_pr_created_score",
- "ranking_action": "ranking_action_score",
- "ranking_open": "ranking_open_score",
- "ranking_fix": "ranking_fix_score",
- # Old name of `ranking_fix`, kept for saved URLs and older clients. Not documented.
+ **{field: f"{field}_score" for field in RANKING_ORDERING_HEADS},
"ranking_fixed": "ranking_fix_score",
- "ranking_discuss": "ranking_discuss_score",
- "ranking_thumbs_up": "ranking_thumbs_up_score",
- "ranking_reviewer_fix": "ranking_reviewer_fix_score",
- "ranking_refund": "ranking_refund_score",
- "ranking_dismiss_wrong": "ranking_dismiss_wrong_score",
- "ranking_dismiss_lowvalue": "ranking_dismiss_lowvalue_score",
- }
- # Ordering field to the outcome head it reads from the served model of the latest ranking score.
- _RANKING_ORDERING_HEADS: dict[str, str] = {
- "ranking_pr_merged": "pr_merged",
- "ranking_pr_created": "pr_created",
- "ranking_action": "action",
- "ranking_open": "open",
- "ranking_fix": "fixed",
- "ranking_fixed": "fixed",
- "ranking_discuss": "discuss",
- "ranking_thumbs_up": "thumbs_up",
- "ranking_reviewer_fix": "reviewer_fix",
- "ranking_refund": "refund",
- "ranking_dismiss_wrong": "dismiss_wrong",
- "ranking_dismiss_lowvalue": "dismiss_lowvalue",
}
+ _RANKING_ORDERING_HEADS: dict[str, str] = RANKING_ORDERING_HEADS
@extend_schema(
responses={200: RankingOutcomesResponseSerializer},
@@ -1328,6 +1325,7 @@ class SignalReportViewSet(
else:
model, outcomes = served_outcomes(self.team_id)
status_value = RankingOutcomesStatus.SCORED if model is not None else RankingOutcomesStatus.UNSCORED
+ self._capture_ranking_usage("ranking_outcomes", ranking_status=status_value.value)
return Response(
RankingOutcomesResponseSerializer({"status": status_value.value, "model": model, "outcomes": outcomes}).data
)
@@ -2675,11 +2673,11 @@ class SignalReportViewSet(
description=(
"Comma-separated ordering clauses. Each clause is a field name optionally prefixed with '-' "
"for descending. Allowed fields: status, is_suggested_reviewer, signal_count, total_weight, "
- "priority, created_at, updated_at, id, ranking_pr_merged, ranking_pr_created, ranking_action, "
- "ranking_open, ranking_fix, ranking_discuss, ranking_thumbs_up, ranking_reviewer_fix, "
- "ranking_refund, ranking_dismiss_wrong, ranking_dismiss_lowvalue. Defaults to '-is_suggested_reviewer,status,-updated_at'. The ranking_* fields "
- "sort by the served ranking model's probability for that outcome head, with unscored reports "
- "last in either direction. They need staff or the inbox model sort rollout: other users get a 400."
+ f"priority, created_at, updated_at, id, {', '.join(PUBLIC_RANKING_ORDERING_HEADS)}. "
+ "Defaults to '-is_suggested_reviewer,status,-updated_at'. Each ranking_<outcome> field sorts by "
+ "the served ranking model's probability for that public outcome, with unscored reports last in "
+ "either direction. Read inbox-ranking-outcomes-list for what each outcome means. The ranking "
+ "fields need staff or the inbox model sort rollout: other users get a 400."
),
),
OpenApiParameter(
@@ -2790,6 +2788,7 @@ class SignalReportViewSet(
if count_only:
list_span.set_attribute("signals.reports.list.total_count", total_count)
+ self._capture_list_ranking_usage(total_count)
return Response({"count": total_count, "next": None, "previous": None, "results": []})
report_ids = [str(r.id) for r in reports]
@@ -2810,6 +2809,7 @@ class SignalReportViewSet(
)
data = self._render_report_rows(reports, include_source_metadata=include_source_metadata)
+ self._capture_list_ranking_usage(total_count if page is not None else len(reports))
if page is not None:
response = self.get_paginated_response(data)
@@ -2817,6 +2817,59 @@ class SignalReportViewSet(
return response
return Response(data)
+ def _capture_list_ranking_usage(self, result_count: int | None) -> None:
+ if classify_report_list_client(self.request.headers.get("user-agent")) in {"web", "desktop"}:
+ # The inbox clients capture their own list loads with the sort and the ranker.
+ return
+ raw_ordering = self.request.query_params.get("ordering") or ""
+ ordering_outcomes = sorted(
+ {
+ _OUTCOME_BY_MODEL_HEAD.get(RANKING_ORDERING_HEADS[name], "internal")
+ for name in (part.strip().removeprefix("-") for part in raw_ordering.split(","))
+ if name in RANKING_ORDERING_HEADS
+ }
+ )
+ min_lift = self._parse_ranking_minimums("ranking_min_lift")
+ min_probability = self._parse_ranking_minimums("ranking_min_probability")
+ if not (ordering_outcomes or self._inbox_ranker or min_lift or min_probability):
+ return
+ self._capture_ranking_usage(
+ "list",
+ ordering_outcomes=ordering_outcomes,
+ min_lift=min_lift,
+ min_probability=min_probability,
+ result_count=result_count,
+ )
+
+ def _capture_ranking_usage(
+ self,
+ endpoint: Literal["list", "ranking_outcomes"],
+ *,
+ ordering_outcomes: Sequence[str] | None = None,
+ min_lift: dict[str, float] | None = None,
+ min_probability: dict[str, float] | None = None,
+ ranking_status: str | None = None,
+ result_count: int | None = None,
+ ) -> None:
+ # The properties describe the request only. They never carry report content.
+ report_user_action(
+ self.request.user,
+ "signals_inbox_ranking_used",
+ properties={
+ "team_id": self.team_id,
+ "surface": "mcp" if is_mcp_request(self.request) else "api",
+ "endpoint": endpoint,
+ "ordering_outcomes": ordering_outcomes or [],
+ "ranker": self._inbox_ranker if endpoint == "list" else None,
+ "min_lift": min_lift or {},
+ "min_probability": min_probability or {},
+ "ranking_status": ranking_status,
+ "result_count": result_count,
+ },
+ team=self.team,
+ request=self.request,
+ )
+
def _render_report_rows(
self, reports: Sequence[SignalReport], *, include_source_metadata: bool
) -> Sequence[dict[str, object]]:
diff --git a/products/signals/frontend/generated/api.schemas.ts b/products/signals/frontend/generated/api.schemas.ts
index a4dd4b434cc9..657caceef24a 100644
--- a/products/signals/frontend/generated/api.schemas.ts
+++ b/products/signals/frontend/generated/api.schemas.ts
@@ -10197,7 +10197,7 @@ export type SignalsReportsListParams = {
*/
offset?: number
/**
- * Comma-separated ordering clauses. Each clause is a field name optionally prefixed with '-' for descending. Allowed fields: status, is_suggested_reviewer, signal_count, total_weight, priority, created_at, updated_at, id, ranking_pr_merged, ranking_pr_created, ranking_action, ranking_open, ranking_fix, ranking_discuss, ranking_thumbs_up, ranking_reviewer_fix, ranking_refund, ranking_dismiss_wrong, ranking_dismiss_lowvalue. Defaults to '-is_suggested_reviewer,status,-updated_at'. The ranking_* fields sort by the served ranking model's probability for that outcome head, with unscored reports last in either direction. They need staff or the inbox model sort rollout: other users get a 400.
+ * Comma-separated ordering clauses. Each clause is a field name optionally prefixed with '-' for descending. Allowed fields: status, is_suggested_reviewer, signal_count, total_weight, priority, created_at, updated_at, id, ranking_open, ranking_action, ranking_fix. Defaults to '-is_suggested_reviewer,status,-updated_at'. Each ranking_<outcome> field sorts by the served ranking model's probability for that public outcome, with unscored reports last in either direction. Read inbox-ranking-outcomes-list for what each outcome means. The ranking fields need staff or the inbox model sort rollout: other users get a 400.
*/
ordering?: string
/**
diff --git a/products/signals/mcp/tools.yaml b/products/signals/mcp/tools.yaml
index cabfd981d0b5..f3b4cd9defef 100644
--- a/products/signals/mcp/tools.yaml
+++ b/products/signals/mcp/tools.yaml
@@ -481,9 +481,10 @@ tools:
metric metadata and any accessible cached snapshot, but omits live query definitions and comparisons.
Queryless legacy or malformed metrics are always redacted. Listing reports does not execute metric queries.
Each row's `ranking.predictions` carries the inbox ranking model's predicted probability and lift per
- outcome (`open`, `action`, `fix`). Lift 1.0 is an average report. A prediction is a forecast, not the
- report's state, and `status: unscored` is not a low score. Order with `ordering=-ranking_<outcome>`, filter
- with `ranking_min_lift` and `ranking_min_probability` (for example `fix:2`), and read
+ outcome (`open`, `action`, `fix`), and `readable`. Lift 1.0 is an average report. `readable: false` means
+ training could not measure that outcome, so rank and filter on it with caution. A prediction is a forecast,
+ not the report's state, and `status: unscored` is not a low score. Order with `ordering=-ranking_<outcome>`,
+ filter with `ranking_min_lift` and `ranking_min_probability` (for example `fix:2`), and read
inbox-ranking-outcomes-list for what each outcome means.
agent_note: >
You may inspect reports without claiming them. A claim indicates active work that should not be duplicated.
diff --git a/products/signals/skills/inbox-exploration/SKILL.md b/products/signals/skills/inbox-exploration/SKILL.md
index c0743f20d65f..d93fe4d32fd4 100644
--- a/products/signals/skills/inbox-exploration/SKILL.md
+++ b/products/signals/skills/inbox-exploration/SKILL.md
@@ -621,6 +621,8 @@ The inbox ranking model predicts outcomes for each report. Each row of `inbox-re
- A lift is the probability divided by the outcome's base rate. 1.0 is an average report, 2.7 is
2.7x as likely. Compare lifts across outcomes. Raw probabilities do not compare, because each
outcome has its own base rate.
+- `readable: false` means the training run could not measure the holdout AUC of that outcome.
+ Rank and filter on that outcome with caution.
- `status` is `scored`, `stale` (the title or summary changed after scoring, so the predictions
describe the old text), `unscored` (no score yet, which is not a low score), or `not_available`
(the user cannot see the ranking model, so ordering and filtering by it return 400).
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index b005c1edd84d..7579ba8e759b 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -7902,7 +7902,7 @@
}
},
"inbox-reports-list": {
- "description": "List signal reports for the current project. A signal report is a cluster of related observations (signals) that PostHog has aggregated into a single issue or trend. Reports surface in the Inbox. Supports filtering by status (potential, candidate, in_progress, pending_input, ready, resolved, failed, suppressed), free-text search across title and summary, source_product (e.g. error_tracking, session_replay), suggested_reviewers, `unclaimed`, and `assignee=me`. Claimed reports remain actionable and visible; use `unclaimed=true` to pick work that has no owner and no draft, open, or unknown PR. Some statuses are hidden by default (currently suppressed); pass `include_all_statuses=true` to list reports in every status. Do this when deduplicating against the full inbox state, and read each row's `status` (plus `suppression_source`, `dismissal_reason`, and `dismissal_note` on suppressed rows) before acting. A suppressed row's `suppression_source` says whether someone dismissed it (`dismissed`) or a judge held it back before anyone saw it (`safety_judge`, `not_actionable`, `system`). For picking up work, filter to `ready` — earlier statuses are still moving through the pipeline, and `pending_input` reports are waiting on a human. Each report's full work log, including signal findings, judgments, and log entries, is readable via inbox-report-artefacts-list; read it before acting on a report. Results are paginated and ordered by '-is_suggested_reviewer,status,-updated_at' by default. To answer \"what should I look at next\", pass `view=actionable` with `use_priority_preference=true`, `sort=priority`, and `limit=10`: that returns ready, actionable reports that have no implementation PR yet, at or above the requesting user's personal PR-generation threshold, falling back to the project threshold. `use_priority_preference` selects which priorities to include, and does not order them, so pass `sort=priority` to put P0 first; the default ordering can put a recently updated P4 above an older P0. Without `limit` a page holds up to 100 reports, each with its summary. To answer \"what needs me\", pass `view=for_you` with `sort=priority`: that returns the open, actionable reports that wait for the requesting user's input, that they claimed, or that name them as a suggested reviewer, and `count` gives how many there are in total. The other views are `needs_input` (waiting on a human), `needs_decision` (failed reports, plus actionable ready or pending-input reports without an implementation PR), `monitoring` (an implementation PR is open), `resolved`, `dismissed` (suppressed by a person, an agent, a merge, or a closed PR), `held_back` (suppressed by a judge, with nobody's review yet), `not_actionable`, and `all`. Narrow by reviewer with `scope=for_me`, or `scope=teammate` plus `teammate_uuid`; the default `scope=entire_project` searches every report. `priority`, `source_product`, and `scout` each take a comma-separated list. To find the self-driving reports for one source record — e.g. what the inbox already investigated for a specific support ticket — pass that record's id as `source_id` together with exactly one `source_product` (for a support ticket: `source_product=conversations` and the ticket's UUID as `source_id`); add `include_all_statuses=true` to include dismissed ones. Each row includes typed impact metric metadata and any accessible cached snapshot, but omits live query definitions and comparisons. Queryless legacy or malformed metrics are always redacted. Listing reports does not execute metric queries. Each row's `ranking.predictions` carries the inbox ranking model's predicted probability and lift per outcome (`open`, `action`, `fix`). Lift 1.0 is an average report. A prediction is a forecast, not the report's state, and `status: unscored` is not a low score. Order with `ordering=-ranking_<outcome>`, filter with `ranking_min_lift` and `ranking_min_probability` (for example `fix:2`), and read inbox-ranking-outcomes-list for what each outcome means.",
+ "description": "List signal reports for the current project. A signal report is a cluster of related observations (signals) that PostHog has aggregated into a single issue or trend. Reports surface in the Inbox. Supports filtering by status (potential, candidate, in_progress, pending_input, ready, resolved, failed, suppressed), free-text search across title and summary, source_product (e.g. error_tracking, session_replay), suggested_reviewers, `unclaimed`, and `assignee=me`. Claimed reports remain actionable and visible; use `unclaimed=true` to pick work that has no owner and no draft, open, or unknown PR. Some statuses are hidden by default (currently suppressed); pass `include_all_statuses=true` to list reports in every status. Do this when deduplicating against the full inbox state, and read each row's `status` (plus `suppression_source`, `dismissal_reason`, and `dismissal_note` on suppressed rows) before acting. A suppressed row's `suppression_source` says whether someone dismissed it (`dismissed`) or a judge held it back before anyone saw it (`safety_judge`, `not_actionable`, `system`). For picking up work, filter to `ready` — earlier statuses are still moving through the pipeline, and `pending_input` reports are waiting on a human. Each report's full work log, including signal findings, judgments, and log entries, is readable via inbox-report-artefacts-list; read it before acting on a report. Results are paginated and ordered by '-is_suggested_reviewer,status,-updated_at' by default. To answer \"what should I look at next\", pass `view=actionable` with `use_priority_preference=true`, `sort=priority`, and `limit=10`: that returns ready, actionable reports that have no implementation PR yet, at or above the requesting user's personal PR-generation threshold, falling back to the project threshold. `use_priority_preference` selects which priorities to include, and does not order them, so pass `sort=priority` to put P0 first; the default ordering can put a recently updated P4 above an older P0. Without `limit` a page holds up to 100 reports, each with its summary. To answer \"what needs me\", pass `view=for_you` with `sort=priority`: that returns the open, actionable reports that wait for the requesting user's input, that they claimed, or that name them as a suggested reviewer, and `count` gives how many there are in total. The other views are `needs_input` (waiting on a human), `needs_decision` (failed reports, plus actionable ready or pending-input reports without an implementation PR), `monitoring` (an implementation PR is open), `resolved`, `dismissed` (suppressed by a person, an agent, a merge, or a closed PR), `held_back` (suppressed by a judge, with nobody's review yet), `not_actionable`, and `all`. Narrow by reviewer with `scope=for_me`, or `scope=teammate` plus `teammate_uuid`; the default `scope=entire_project` searches every report. `priority`, `source_product`, and `scout` each take a comma-separated list. To find the self-driving reports for one source record — e.g. what the inbox already investigated for a specific support ticket — pass that record's id as `source_id` together with exactly one `source_product` (for a support ticket: `source_product=conversations` and the ticket's UUID as `source_id`); add `include_all_statuses=true` to include dismissed ones. Each row includes typed impact metric metadata and any accessible cached snapshot, but omits live query definitions and comparisons. Queryless legacy or malformed metrics are always redacted. Listing reports does not execute metric queries. Each row's `ranking.predictions` carries the inbox ranking model's predicted probability and lift per outcome (`open`, `action`, `fix`), and `readable`. Lift 1.0 is an average report. `readable: false` means training could not measure that outcome, so rank and filter on it with caution. A prediction is a forecast, not the report's state, and `status: unscored` is not a low score. Order with `ordering=-ranking_<outcome>`, filter with `ranking_min_lift` and `ranking_min_probability` (for example `fix:2`), and read inbox-ranking-outcomes-list for what each outcome means.",
"category": "Signals",
"feature": "signals",
"summary": "List signal reports",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index c5c2049eafb5..b10f517d55b9 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -8104,7 +8104,7 @@
}
},
"inbox-reports-list": {
- "description": "List signal reports for the current project. A signal report is a cluster of related observations (signals) that PostHog has aggregated into a single issue or trend. Reports surface in the Inbox. Supports filtering by status (potential, candidate, in_progress, pending_input, ready, resolved, failed, suppressed), free-text search across title and summary, source_product (e.g. error_tracking, session_replay), suggested_reviewers, `unclaimed`, and `assignee=me`. Claimed reports remain actionable and visible; use `unclaimed=true` to pick work that has no owner and no draft, open, or unknown PR. Some statuses are hidden by default (currently suppressed); pass `include_all_statuses=true` to list reports in every status. Do this when deduplicating against the full inbox state, and read each row's `status` (plus `suppression_source`, `dismissal_reason`, and `dismissal_note` on suppressed rows) before acting. A suppressed row's `suppression_source` says whether someone dismissed it (`dismissed`) or a judge held it back before anyone saw it (`safety_judge`, `not_actionable`, `system`). For picking up work, filter to `ready` — earlier statuses are still moving through the pipeline, and `pending_input` reports are waiting on a human. Each report's full work log, including signal findings, judgments, and log entries, is readable via inbox-report-artefacts-list; read it before acting on a report. Results are paginated and ordered by '-is_suggested_reviewer,status,-updated_at' by default. To answer \"what should I look at next\", pass `view=actionable` with `use_priority_preference=true`, `sort=priority`, and `limit=10`: that returns ready, actionable reports that have no implementation PR yet, at or above the requesting user's personal PR-generation threshold, falling back to the project threshold. `use_priority_preference` selects which priorities to include, and does not order them, so pass `sort=priority` to put P0 first; the default ordering can put a recently updated P4 above an older P0. Without `limit` a page holds up to 100 reports, each with its summary. To answer \"what needs me\", pass `view=for_you` with `sort=priority`: that returns the open, actionable reports that wait for the requesting user's input, that they claimed, or that name them as a suggested reviewer, and `count` gives how many there are in total. The other views are `needs_input` (waiting on a human), `needs_decision` (failed reports, plus actionable ready or pending-input reports without an implementation PR), `monitoring` (an implementation PR is open), `resolved`, `dismissed` (suppressed by a person, an agent, a merge, or a closed PR), `held_back` (suppressed by a judge, with nobody's review yet), `not_actionable`, and `all`. Narrow by reviewer with `scope=for_me`, or `scope=teammate` plus `teammate_uuid`; the default `scope=entire_project` searches every report. `priority`, `source_product`, and `scout` each take a comma-separated list. To find the self-driving reports for one source record — e.g. what the inbox already investigated for a specific support ticket — pass that record's id as `source_id` together with exactly one `source_product` (for a support ticket: `source_product=conversations` and the ticket's UUID as `source_id`); add `include_all_statuses=true` to include dismissed ones. Each row includes typed impact metric metadata and any accessible cached snapshot, but omits live query definitions and comparisons. Queryless legacy or malformed metrics are always redacted. Listing reports does not execute metric queries. Each row's `ranking.predictions` carries the inbox ranking model's predicted probability and lift per outcome (`open`, `action`, `fix`). Lift 1.0 is an average report. A prediction is a forecast, not the report's state, and `status: unscored` is not a low score. Order with `ordering=-ranking_<outcome>`, filter with `ranking_min_lift` and `ranking_min_probability` (for example `fix:2`), and read inbox-ranking-outcomes-list for what each outcome means.",
+ "description": "List signal reports for the current project. A signal report is a cluster of related observations (signals) that PostHog has aggregated into a single issue or trend. Reports surface in the Inbox. Supports filtering by status (potential, candidate, in_progress, pending_input, ready, resolved, failed, suppressed), free-text search across title and summary, source_product (e.g. error_tracking, session_replay), suggested_reviewers, `unclaimed`, and `assignee=me`. Claimed reports remain actionable and visible; use `unclaimed=true` to pick work that has no owner and no draft, open, or unknown PR. Some statuses are hidden by default (currently suppressed); pass `include_all_statuses=true` to list reports in every status. Do this when deduplicating against the full inbox state, and read each row's `status` (plus `suppression_source`, `dismissal_reason`, and `dismissal_note` on suppressed rows) before acting. A suppressed row's `suppression_source` says whether someone dismissed it (`dismissed`) or a judge held it back before anyone saw it (`safety_judge`, `not_actionable`, `system`). For picking up work, filter to `ready` — earlier statuses are still moving through the pipeline, and `pending_input` reports are waiting on a human. Each report's full work log, including signal findings, judgments, and log entries, is readable via inbox-report-artefacts-list; read it before acting on a report. Results are paginated and ordered by '-is_suggested_reviewer,status,-updated_at' by default. To answer \"what should I look at next\", pass `view=actionable` with `use_priority_preference=true`, `sort=priority`, and `limit=10`: that returns ready, actionable reports that have no implementation PR yet, at or above the requesting user's personal PR-generation threshold, falling back to the project threshold. `use_priority_preference` selects which priorities to include, and does not order them, so pass `sort=priority` to put P0 first; the default ordering can put a recently updated P4 above an older P0. Without `limit` a page holds up to 100 reports, each with its summary. To answer \"what needs me\", pass `view=for_you` with `sort=priority`: that returns the open, actionable reports that wait for the requesting user's input, that they claimed, or that name them as a suggested reviewer, and `count` gives how many there are in total. The other views are `needs_input` (waiting on a human), `needs_decision` (failed reports, plus actionable ready or pending-input reports without an implementation PR), `monitoring` (an implementation PR is open), `resolved`, `dismissed` (suppressed by a person, an agent, a merge, or a closed PR), `held_back` (suppressed by a judge, with nobody's review yet), `not_actionable`, and `all`. Narrow by reviewer with `scope=for_me`, or `scope=teammate` plus `teammate_uuid`; the default `scope=entire_project` searches every report. `priority`, `source_product`, and `scout` each take a comma-separated list. To find the self-driving reports for one source record — e.g. what the inbox already investigated for a specific support ticket — pass that record's id as `source_id` together with exactly one `source_product` (for a support ticket: `source_product=conversations` and the ticket's UUID as `source_id`); add `include_all_statuses=true` to include dismissed ones. Each row includes typed impact metric metadata and any accessible cached snapshot, but omits live query definitions and comparisons. Queryless legacy or malformed metrics are always redacted. Listing reports does not execute metric queries. Each row's `ranking.predictions` carries the inbox ranking model's predicted probability and lift per outcome (`open`, `action`, `fix`), and `readable`. Lift 1.0 is an average report. `readable: false` means training could not measure that outcome, so rank and filter on it with caution. A prediction is a forecast, not the report's state, and `status: unscored` is not a low score. Order with `ordering=-ranking_<outcome>`, filter with `ranking_min_lift` and `ranking_min_probability` (for example `fix:2`), and read inbox-ranking-outcomes-list for what each outcome means.",
"category": "Signals",
"feature": "signals",
"summary": "List signal reports",
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 645602035f22..80e883ec16df 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -137466,7 +137466,7 @@ export namespace Schemas {
*/
offset?: number;
/**
- * Comma-separated ordering clauses. Each clause is a field name optionally prefixed with '-' for descending. Allowed fields: status, is_suggested_reviewer, signal_count, total_weight, priority, created_at, updated_at, id, ranking_pr_merged, ranking_pr_created, ranking_action, ranking_open, ranking_fix, ranking_discuss, ranking_thumbs_up, ranking_reviewer_fix, ranking_refund, ranking_dismiss_wrong, ranking_dismiss_lowvalue. Defaults to '-is_suggested_reviewer,status,-updated_at'. The ranking_* fields sort by the served ranking model's probability for that outcome head, with unscored reports last in either direction. They need staff or the inbox model sort rollout: other users get a 400.
+ * Comma-separated ordering clauses. Each clause is a field name optionally prefixed with '-' for descending. Allowed fields: status, is_suggested_reviewer, signal_count, total_weight, priority, created_at, updated_at, id, ranking_open, ranking_action, ranking_fix. Defaults to '-is_suggested_reviewer,status,-updated_at'. Each ranking_<outcome> field sorts by the served ranking model's probability for that public outcome, with unscored reports last in either direction. Read inbox-ranking-outcomes-list for what each outcome means. The ranking fields need staff or the inbox model sort rollout: other users get a 400.
*/
ordering?: string;
/**
diff --git a/services/mcp/src/generated/signals/api.ts b/services/mcp/src/generated/signals/api.ts
index d5a449104f2a..b1de033cef00 100644
--- a/services/mcp/src/generated/signals/api.ts
+++ b/services/mcp/src/generated/signals/api.ts
@@ -369,7 +369,7 @@ export const SignalsReportsListQueryParams = () => zod.object({
.string()
.optional()
.describe(
- "Comma-separated ordering clauses. Each clause is a field name optionally prefixed with '-' for descending. Allowed fields: status, is_suggested_reviewer, signal_count, total_weight, priority, created_at, updated_at, id, ranking_pr_merged, ranking_pr_created, ranking_action, ranking_open, ranking_fix, ranking_discuss, ranking_thumbs_up, ranking_reviewer_fix, ranking_refund, ranking_dismiss_wrong, ranking_dismiss_lowvalue. Defaults to '-is_suggested_reviewer,status,-updated_at'. The ranking_\* fields sort by the served ranking model's probability for that outcome head, with unscored reports last in either direction. They need staff or the inbox model sort rollout: other users get a 400."
+ "Comma-separated ordering clauses. Each clause is a field name optionally prefixed with '-' for descending. Allowed fields: status, is_suggested_reviewer, signal_count, total_weight, priority, created_at, updated_at, id, ranking_open, ranking_action, ranking_fix. Defaults to '-is_suggested_reviewer,status,-updated_at'. Each ranking_<outcome> field sorts by the served ranking model's probability for that public outcome, with unscored reports last in either direction. Read inbox-ranking-outcomes-list for what each outcome means. The ranking fields need staff or the inbox model sort rollout: other users get a 400."
),
priority: zod
.string()
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-list.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-list.json
index 9daf00f0300a..0401fb5acc57 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-list.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-list.json
@@ -64,7 +64,7 @@
"type": "number"
},
"ordering": {
- "description": "Comma-separated ordering clauses. Each clause is a field name optionally prefixed with '-' for descending. Allowed fields: status, is_suggested_reviewer, signal_count, total_weight, priority, created_at, updated_at, id, ranking_pr_merged, ranking_pr_created, ranking_action, ranking_open, ranking_fix, ranking_discuss, ranking_thumbs_up, ranking_reviewer_fix, ranking_refund, ranking_dismiss_wrong, ranking_dismiss_lowvalue. Defaults to '-is_suggested_reviewer,status,-updated_at'. The ranking_* fields sort by the served ranking model's probability for that outcome head, with unscored reports last in either direction. They need staff or the inbox model sort rollout: other users get a 400.",
+ "description": "Comma-separated ordering clauses. Each clause is a field name optionally prefixed with '-' for descending. Allowed fields: status, is_suggested_reviewer, signal_count, total_weight, priority, created_at, updated_at, id, ranking_open, ranking_action, ranking_fix. Defaults to '-is_suggested_reviewer,status,-updated_at'. Each ranking_<outcome> field sorts by the served ranking model's probability for that public outcome, with unscored reports last in either direction. Read inbox-ranking-outcomes-list for what each outcome means. The ranking fields need staff or the inbox model sort rollout: other users get a 400.",
"type": "string"
},
"priority": {