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.

perf(signals): skip candidate pools on fresh personal ranking reads (#128060)

posthog[bot]2c11e76330a1
diff --git a/products/signals/backend/personal_ranking/candidates.py b/products/signals/backend/personal_ranking/candidates.py
index bd8d86ae9fce..60782b47eb34 100644
--- a/products/signals/backend/personal_ranking/candidates.py
+++ b/products/signals/backend/personal_ranking/candidates.py
@@ -5,7 +5,7 @@ That order is the model order: the fallback when the LLM does not rank a report.
"""
import datetime
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
from typing import Literal
from django.db.models import Max, QuerySet
@@ -295,6 +295,26 @@ def gather_candidates(
"""`with_sources=False` skips the ClickHouse read of each report's source, which only the prompt shows."""
can_view_ranking = can_view_inbox_ranking(user, team)
merged = merge_pools(_pools(team, user, config, now=now, can_view_ranking=can_view_ranking), config.max_candidates)
+ return _load_candidates(team, user, merged, can_view_ranking=can_view_ranking, with_sources=with_sources)
+
+
+def stored_candidates(team: Team, user: User, report_ids: Sequence[str]) -> list[Candidate]:
+ """The current facts of the reports a stored list considered, with no pool query and no source read.
+
+ A report that no longer exists drops out, and no new report joins. `pools` is empty, because only a build reads it.
+ """
+ return _load_candidates(
+ team,
+ user,
+ {report_id: [] for report_id in report_ids},
+ can_view_ranking=can_view_inbox_ranking(user, team),
+ with_sources=False,
+ )
+
+
+def _load_candidates(
+ team: Team, user: User, merged: Mapping[str, Sequence[str]], *, can_view_ranking: bool, with_sources: bool
+) -> list[Candidate]:
if not merged:
return []
ids = list(merged)
diff --git a/products/signals/backend/personal_ranking/serve.py b/products/signals/backend/personal_ranking/serve.py
index cb608fa5b7ed..6ae4b7935646 100644
--- a/products/signals/backend/personal_ranking/serve.py
+++ b/products/signals/backend/personal_ranking/serve.py
@@ -7,11 +7,16 @@ there is none. The focus is part of the hash, so an unfocused request never reus
stores a list for the current inputs while the read runs answers the read, also a `refresh` read, so the read
queues no second build. A lock lets one build per person run at a time, and each queued build spends two
per-person token buckets. A build that may call the model also spends the shared daily limit of the region
-(`build_budget.py`). `wait_seconds` waits a bounded time for the queued build to store its list.
+(`build_budget.py`). `wait_seconds` waits a bounded time for the queued build to store its list, counted from the
+start of the request.
+
+While the stored list is young enough, the read checks only the reports that list considered, with a fixed number
+of queries, and skips the candidate pool queries. A new report joins at the next build after the list ages out.
"""
import time
import datetime
+import dataclasses
from collections.abc import Mapping, Sequence
from contextlib import suppress
from typing import Any, Literal
@@ -29,7 +34,7 @@ from posthog.token_bucket import BucketDecision, BucketUnavailable, Budget, cons
from products.signals.backend.activity_summary.read import ActivitySummaryStatus, get_summary
from products.signals.backend.models import PersonalInboxRanking
from products.signals.backend.personal_ranking.build_budget import DAILY_BUILD_COST, spend_shared_build
-from products.signals.backend.personal_ranking.candidates import Candidate, gather_candidates
+from products.signals.backend.personal_ranking.candidates import Candidate, gather_candidates, stored_candidates
from products.signals.backend.personal_ranking.config import PersonalRankingConfig, read_config
from products.signals.backend.personal_ranking.logic import (
input_hash,
@@ -91,6 +96,18 @@ class ServedFold:
reason: str
+@frozen
+class ReadTimings:
+ """The milliseconds each phase of a read took. None when the read skipped the phase."""
+
+ # The latest stored row, the activity summary, and the facts of the reports the stored list considered.
+ check_ms: int | None = None
+ # The candidate pools and the facts of every candidate.
+ gather_ms: int | None = None
+ # The poll for a new row, when `wait_seconds` asked for it.
+ wait_ms: int | None = None
+
+
@frozen
class ServedRanking:
status: ServeStatus
@@ -109,6 +126,7 @@ class ServedRanking:
ranked_count: int
results: tuple[ServedEntry, ...]
folded: tuple[ServedFold, ...]
+ timings: ReadTimings = ReadTimings()
UNAVAILABLE = ServedRanking(
@@ -212,9 +230,8 @@ def _row_stored_since(
def _wait_for_new_row(
- team: Team, user: User, previous: PersonalInboxRanking | None, wait_seconds: int
+ team: Team, user: User, previous: PersonalInboxRanking | None, deadline: float
) -> PersonalInboxRanking | None:
- deadline = time.monotonic() + wait_seconds
while True:
row = latest_row(team, user)
if row is not None and (previous is None or row.id != previous.id):
@@ -224,6 +241,10 @@ def _wait_for_new_row(
time.sleep(_WAIT_POLL_SECONDS)
+def _elapsed_ms(since: float) -> int:
+ return round((time.monotonic() - since) * 1000)
+
+
def ready_summary_version(team: Team, user: User) -> int | None:
summary = get_summary(team, user.id)
return summary.version if summary is not None and summary.status == ActivitySummaryStatus.READY else None
@@ -351,39 +372,57 @@ def serve_personal_ranking(
limit = min(max(limit or config.default_limit, 1), config.max_limit)
focus = normalize_focus(focus, config.focus_max_chars)
wait_seconds = min(max(wait_seconds, 0), MAX_WAIT_SECONDS)
- now = timezone.now()
+ started = time.monotonic()
+ gather_ms: int | None = None
+ wait_ms: int | None = None
+ def timed(served: ServedRanking) -> ServedRanking:
+ return dataclasses.replace(served, timings=ReadTimings(check_ms=check_ms, gather_ms=gather_ms, wait_ms=wait_ms))
+
+ def fresh(row: PersonalInboxRanking | None) -> bool:
+ return row is not None and (row.checked_at or row.created_at) >= now - datetime.timedelta(
+ minutes=config.freshness_minutes
+ )
+
+ now = timezone.now()
started_with = latest_row(team, user)
- candidates = gather_candidates(team, user, config, now=now, with_sources=False)
summary_version = ready_summary_version(team, user)
+ if started_with is not None and fresh(started_with) and not refresh and focus is None:
+ stored = stored_candidates(team, user, started_with.candidate_ids or ())
+ if input_hash(stored, activity_summary_version=summary_version, focus=None) == started_with.input_hash:
+ check_ms = _elapsed_ms(started)
+ return timed(_serve_row(started_with, stored, limit=limit, cached=True, stale=False, building=False))
+ check_ms = _elapsed_ms(started)
+
+ gather_started = time.monotonic()
+ candidates = gather_candidates(team, user, config, now=now, with_sources=False)
current_hash = input_hash(candidates, activity_summary_version=summary_version, focus=focus)
# Read again, because a build can store a row while the candidates are gathered.
latest = latest_row(team, user)
- current = (
- latest is not None
- and (latest.checked_at or latest.created_at) >= now - datetime.timedelta(minutes=config.freshness_minutes)
- and latest.input_hash == current_hash
- )
+ current = latest is not None and fresh(latest) and latest.input_hash == current_hash
+ gather_ms = _elapsed_ms(gather_started)
# A row stored after this read started also answers a refresh.
stored_since_start = latest is not None and (started_with is None or latest.id != started_with.id)
if latest is not None and current and focus is None and (not refresh or stored_since_start):
- return _serve_row(latest, candidates, limit=limit, cached=True, stale=False, building=False)
+ return timed(_serve_row(latest, candidates, limit=limit, cached=True, stale=False, building=False))
calls_model = bool(candidates) and may_call_model(team, summary_ready=summary_version is not None)
start = _start_build(
team, user, config, focus, limit, calls_model=calls_model, seen=latest, current_hash=current_hash
)
if isinstance(start, PersonalInboxRanking):
- return _serve_row(start, candidates, limit=limit, cached=True, stale=False, building=False)
+ return timed(_serve_row(start, candidates, limit=limit, cached=True, stale=False, building=False))
building = start in ("started", "running")
if building and wait_seconds:
- built = _wait_for_new_row(team, user, latest, wait_seconds)
+ wait_started = time.monotonic()
+ built = _wait_for_new_row(team, user, latest, started + wait_seconds)
+ wait_ms = _elapsed_ms(wait_started)
if built is not None:
stale = built.input_hash != current_hash
- return _serve_row(built, candidates, limit=limit, cached=False, stale=stale, building=False)
+ return timed(_serve_row(built, candidates, limit=limit, cached=False, stale=stale, building=False))
if latest is not None:
- return _serve_row(latest, candidates, limit=limit, cached=True, stale=not current, building=building)
+ return timed(_serve_row(latest, candidates, limit=limit, cached=True, stale=not current, building=building))
reason = (
FALLBACK_BUILDING if building else FALLBACK_RATE_LIMITED if start == "rate_limited" else FALLBACK_BUILD_FAILED
)
- return _serve_inbox_order(candidates, limit=limit, building=building, reason=reason)
+ return timed(_serve_inbox_order(candidates, limit=limit, building=building, reason=reason))
diff --git a/products/signals/backend/serializers.py b/products/signals/backend/serializers.py
index 1beb0366e194..58575bc1a241 100644
--- a/products/signals/backend/serializers.py
+++ b/products/signals/backend/serializers.py
@@ -1500,8 +1500,8 @@ class PersonalRankingQuerySerializer(serializers.Serializer):
min_value=0,
max_value=30,
help_text=(
- "When the request starts a build or one is running, wait up to this many seconds for its list. "
- "Defaults to 0, which returns at once. A build usually takes 10 to 60 seconds."
+ "When the request starts a build or one is running, wait for its list until this many seconds after "
+ "the request started. Defaults to 0, which does not wait. A build usually takes 10 to 60 seconds."
),
)
@@ -1632,7 +1632,7 @@ def personal_ranking_payload(served: "ServedRanking") -> dict[str, Any]:
**{
field.name: getattr(served, field.name)
for field in dataclasses.fields(served)
- if field.name not in {"results", "folded"}
+ if field.name not in {"results", "folded", "timings"}
},
"results": [
{
diff --git a/products/signals/backend/test/test_personal_ranking.py b/products/signals/backend/test/test_personal_ranking.py
index d367991ca051..d2e8a1fd5d35 100644
--- a/products/signals/backend/test/test_personal_ranking.py
+++ b/products/signals/backend/test/test_personal_ranking.py
@@ -11,6 +11,7 @@ from unittest.mock import MagicMock, patch
from django.core.cache import cache
from django.core.management import call_command
+from django.db.models import F
from django.test import SimpleTestCase
from django.utils import timezone
@@ -811,6 +812,12 @@ class TestForMeEndpoint(APIBaseTest):
assert (self._state(self._get()), self._rows()) == ((True, False, False), 3)
second = self._claimed_report("Second")
+ body = self._get()
+ assert (self._state(body), self.queued) == ((True, False, False), [])
+ assert [entry["report"]["id"] for entry in body["results"]] == [str(first.id)]
+ PersonalInboxRanking.objects.for_team(self.team.id).update(
+ created_at=F("created_at") - datetime.timedelta(days=2)
+ )
assert self._state(self._get()) == (True, True, True)
self._run_builds()
body = self._get()
@@ -872,6 +879,8 @@ class TestForMeEndpoint(APIBaseTest):
assert (self._state(self._get(refresh="true")), self.queued) == ((True, False, False), [])
self._claimed_report("Second")
+ first.title = "First, edited"
+ first.save()
body = self._get()
assert (self._state(body), self._rows()) == ((True, True, False), 1)
assert [entry["report"]["id"] for entry in body["results"]] == [str(first.id)]
diff --git a/products/signals/backend/views.py b/products/signals/backend/views.py
index 9a5d11e619cb..d5272b0a9cd9 100644
--- a/products/signals/backend/views.py
+++ b/products/signals/backend/views.py
@@ -1787,10 +1787,11 @@ class SignalReportViewSet(
description=(
"Your open inbox reports, ranked for you by one language model call over your activity summary, the "
"reports that need you and the ranking model's predictions. Each entry has a reason and a compact report. "
- "The request never waits on the model. A current stored list returns at once. Otherwise the request "
- "starts a background build and returns the last stored list with `stale: true`, or your reports in inbox "
- "order with `fallback_reason: building`, and `building: true`. Pass `wait_seconds` to wait a short time "
- "for the new list. Only the user the list is about can read it."
+ "The request never waits on the model. A current stored list returns quickly. Otherwise the request "
+ "reads every candidate report, which can take some seconds, starts a background build and returns the "
+ "last stored list with `stale: true`, or your reports in inbox order with `fallback_reason: building`, "
+ "and `building: true`. Pass `wait_seconds` to wait a short time for the new list. Only the user the list "
+ "is about can read it."
),
)
@action(detail=False, methods=["get"], url_path="for_me", required_scopes=["inbox:read"], pagination_class=None)
@@ -1830,6 +1831,9 @@ class SignalReportViewSet(
"wait_seconds": query["wait_seconds"],
"result_count": len(served.results),
"duration_ms": round((time.monotonic() - started) * 1000),
+ "check_ms": served.timings.check_ms,
+ "gather_ms": served.timings.gather_ms,
+ "wait_ms": served.timings.wait_ms,
},
team=self.team,
request=request,
diff --git a/products/signals/frontend/generated/api.schemas.ts b/products/signals/frontend/generated/api.schemas.ts
index 222b6ded5673..27d5b2951c9f 100644
--- a/products/signals/frontend/generated/api.schemas.ts
+++ b/products/signals/frontend/generated/api.schemas.ts
@@ -11316,7 +11316,7 @@ export type SignalsReportsForMeRetrieveParams = {
*/
refresh?: boolean
/**
- * When the request starts a build or one is running, wait up to this many seconds for its list. Defaults to 0, which returns at once. A build usually takes 10 to 60 seconds.
+ * When the request starts a build or one is running, wait for its list until this many seconds after the request started. Defaults to 0, which does not wait. A build usually takes 10 to 60 seconds.
* @minimum 0
* @maximum 30
*/
diff --git a/products/signals/frontend/generated/api.ts b/products/signals/frontend/generated/api.ts
index a7612e5e3367..366c7be2c35e 100644
--- a/products/signals/frontend/generated/api.ts
+++ b/products/signals/frontend/generated/api.ts
@@ -1612,7 +1612,7 @@ export const getSignalsReportsForMeRetrieveUrl = (projectId: string, params?: Si
}
/**
- * Your open inbox reports, ranked for you by one language model call over your activity summary, the reports that need you and the ranking model's predictions. Each entry has a reason and a compact report. The request never waits on the model. A current stored list returns at once. Otherwise the request starts a background build and returns the last stored list with `stale: true`, or your reports in inbox order with `fallback_reason: building`, and `building: true`. Pass `wait_seconds` to wait a short time for the new list. Only the user the list is about can read it.
+ * Your open inbox reports, ranked for you by one language model call over your activity summary, the reports that need you and the ranking model's predictions. Each entry has a reason and a compact report. The request never waits on the model. A current stored list returns quickly. Otherwise the request reads every candidate report, which can take some seconds, starts a background build and returns the last stored list with `stale: true`, or your reports in inbox order with `fallback_reason: building`, and `building: true`. Pass `wait_seconds` to wait a short time for the new list. Only the user the list is about can read it.
* @summary Get your personal ranked inbox
*/
export const signalsReportsForMeRetrieve = async (
diff --git a/products/signals/mcp/tools.yaml b/products/signals/mcp/tools.yaml
index e1ab19cddd63..a86160ecc3c8 100644
--- a/products/signals/mcp/tools.yaml
+++ b/products/signals/mcp/tools.yaml
@@ -452,14 +452,16 @@ tools:
highest, using their activity summary. Use it for "what should I work on" and "my top N" questions in place
of paging inbox-reports-list. Each entry has a rank, a tier, a short reason, a next step for the top entries
and a compact report. Read the full report with inbox-reports-retrieve before you act on it. The list is
- personal: only the user it describes can read it. The call returns at once and never waits on the model. A
- current stored list comes back as is. Otherwise the call starts a background build and returns the last
- stored list with `stale: true`, or the reports in inbox order with `fallback_reason: building`, and sets
- `building: true`. `refresh` and `focus` always start a build, and builds are rate limited. When `building`
- is true, call again a little later, or pass `wait_seconds` (up to 30) to wait for the new list in the same
- call. `personalized: false` means the user has no activity summary yet or the list is in inbox order (see
- `fallback_reason`). `stale: true` without `building` means the build limit was reached and the list may miss
- recent changes. `status: unavailable` means personal ranking is off for now.
+ personal: only the user it describes can read it. The call never waits on the model. A current stored list
+ comes back quickly, as is. Otherwise the call reads every candidate report, which can take some seconds,
+ starts a background build and returns the last stored list with `stale: true`, or the reports in inbox order
+ with `fallback_reason: building`, and sets `building: true`. `refresh` and `focus` always start a build, and
+ builds are rate limited. A report created after the stored list joins at the next build. When `building` is
+ true, call again a little later, or pass `wait_seconds` (up to 30, counted from the start of the call) to
+ wait for the new list in the same call. `personalized: false` means the user has no activity summary yet or
+ the list is in inbox order (see `fallback_reason`). `stale: true` without `building` means the build limit
+ was reached and the list may miss recent changes. `status: unavailable` means personal ranking is off for
+ now.
feature_flag: personal-inbox-ranking
inbox-reports-leave-reviewers:
operation: signals_reports_reviewers_me_create
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index c0ecb108eb39..2841a3328620 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -8057,7 +8057,7 @@
}
},
"inbox-reports-for-me": {
- "description": "Get the current user's own open inbox reports, ranked for them. One language model call ranks the reports that need them (suggested reviewer, claimed, waiting on their input) and the reports the ranking model rates highest, using their activity summary. Use it for \"what should I work on\" and \"my top N\" questions in place of paging inbox-reports-list. Each entry has a rank, a tier, a short reason, a next step for the top entries and a compact report. Read the full report with inbox-reports-retrieve before you act on it. The list is personal: only the user it describes can read it. The call returns at once and never waits on the model. A current stored list comes back as is. Otherwise the call starts a background build and returns the last stored list with `stale: true`, or the reports in inbox order with `fallback_reason: building`, and sets `building: true`. `refresh` and `focus` always start a build, and builds are rate limited. When `building` is true, call again a little later, or pass `wait_seconds` (up to 30) to wait for the new list in the same call. `personalized: false` means the user has no activity summary yet or the list is in inbox order (see `fallback_reason`). `stale: true` without `building` means the build limit was reached and the list may miss recent changes. `status: unavailable` means personal ranking is off for now.",
+ "description": "Get the current user's own open inbox reports, ranked for them. One language model call ranks the reports that need them (suggested reviewer, claimed, waiting on their input) and the reports the ranking model rates highest, using their activity summary. Use it for \"what should I work on\" and \"my top N\" questions in place of paging inbox-reports-list. Each entry has a rank, a tier, a short reason, a next step for the top entries and a compact report. Read the full report with inbox-reports-retrieve before you act on it. The list is personal: only the user it describes can read it. The call never waits on the model. A current stored list comes back quickly, as is. Otherwise the call reads every candidate report, which can take some seconds, starts a background build and returns the last stored list with `stale: true`, or the reports in inbox order with `fallback_reason: building`, and sets `building: true`. `refresh` and `focus` always start a build, and builds are rate limited. A report created after the stored list joins at the next build. When `building` is true, call again a little later, or pass `wait_seconds` (up to 30, counted from the start of the call) to wait for the new list in the same call. `personalized: false` means the user has no activity summary yet or the list is in inbox order (see `fallback_reason`). `stale: true` without `building` means the build limit was reached and the list may miss recent changes. `status: unavailable` means personal ranking is off for now.",
"category": "Signals",
"feature": "signals",
"summary": "Get your personal ranked inbox",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index 1ab643deb7b9..4b50cbd3c191 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -8289,7 +8289,7 @@
}
},
"inbox-reports-for-me": {
- "description": "Get the current user's own open inbox reports, ranked for them. One language model call ranks the reports that need them (suggested reviewer, claimed, waiting on their input) and the reports the ranking model rates highest, using their activity summary. Use it for \"what should I work on\" and \"my top N\" questions in place of paging inbox-reports-list. Each entry has a rank, a tier, a short reason, a next step for the top entries and a compact report. Read the full report with inbox-reports-retrieve before you act on it. The list is personal: only the user it describes can read it. The call returns at once and never waits on the model. A current stored list comes back as is. Otherwise the call starts a background build and returns the last stored list with `stale: true`, or the reports in inbox order with `fallback_reason: building`, and sets `building: true`. `refresh` and `focus` always start a build, and builds are rate limited. When `building` is true, call again a little later, or pass `wait_seconds` (up to 30) to wait for the new list in the same call. `personalized: false` means the user has no activity summary yet or the list is in inbox order (see `fallback_reason`). `stale: true` without `building` means the build limit was reached and the list may miss recent changes. `status: unavailable` means personal ranking is off for now.",
+ "description": "Get the current user's own open inbox reports, ranked for them. One language model call ranks the reports that need them (suggested reviewer, claimed, waiting on their input) and the reports the ranking model rates highest, using their activity summary. Use it for \"what should I work on\" and \"my top N\" questions in place of paging inbox-reports-list. Each entry has a rank, a tier, a short reason, a next step for the top entries and a compact report. Read the full report with inbox-reports-retrieve before you act on it. The list is personal: only the user it describes can read it. The call never waits on the model. A current stored list comes back quickly, as is. Otherwise the call reads every candidate report, which can take some seconds, starts a background build and returns the last stored list with `stale: true`, or the reports in inbox order with `fallback_reason: building`, and sets `building: true`. `refresh` and `focus` always start a build, and builds are rate limited. A report created after the stored list joins at the next build. When `building` is true, call again a little later, or pass `wait_seconds` (up to 30, counted from the start of the call) to wait for the new list in the same call. `personalized: false` means the user has no activity summary yet or the list is in inbox order (see `fallback_reason`). `stale: true` without `building` means the build limit was reached and the list may miss recent changes. `status: unavailable` means personal ranking is off for now.",
"category": "Signals",
"feature": "signals",
"summary": "Get your personal ranked inbox",
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 42ef1d9475fd..cfba73f08d9e 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -131039,7 +131039,7 @@ export namespace Schemas {
*/
refresh?: boolean;
/**
- * When the request starts a build or one is running, wait up to this many seconds for its list. Defaults to 0, which returns at once. A build usually takes 10 to 60 seconds.
+ * When the request starts a build or one is running, wait for its list until this many seconds after the request started. Defaults to 0, which does not wait. A build usually takes 10 to 60 seconds.
* @minimum 0
* @maximum 30
*/
diff --git a/services/mcp/src/generated/signals/api.ts b/services/mcp/src/generated/signals/api.ts
index 1fb9f80d2586..c2062bd26cd5 100644
--- a/services/mcp/src/generated/signals/api.ts
+++ b/services/mcp/src/generated/signals/api.ts
@@ -1516,7 +1516,7 @@ export const SignalsReportsBulkStateCreateBody = () => zod.object({
})
/**
- * Your open inbox reports, ranked for you by one language model call over your activity summary, the reports that need you and the ranking model's predictions. Each entry has a reason and a compact report. The request never waits on the model. A current stored list returns at once. Otherwise the request starts a background build and returns the last stored list with `stale: true`, or your reports in inbox order with `fallback_reason: building`, and `building: true`. Pass `wait_seconds` to wait a short time for the new list. Only the user the list is about can read it.
+ * Your open inbox reports, ranked for you by one language model call over your activity summary, the reports that need you and the ranking model's predictions. Each entry has a reason and a compact report. The request never waits on the model. A current stored list returns quickly. Otherwise the request reads every candidate report, which can take some seconds, starts a background build and returns the last stored list with `stale: true`, or your reports in inbox order with `fallback_reason: building`, and `building: true`. Pass `wait_seconds` to wait a short time for the new list. Only the user the list is about can read it.
* @summary Get your personal ranked inbox
*/
export const SignalsReportsForMeRetrieveParams = () => zod.object({
@@ -1564,7 +1564,7 @@ export const SignalsReportsForMeRetrieveQueryParams = () => zod.object({
.max(signalsReportsForMeRetrieveQueryWaitSecondsMax)
.default(signalsReportsForMeRetrieveQueryWaitSecondsDefault)
.describe(
- 'When the request starts a build or one is running, wait up to this many seconds for its list. Defaults to 0, which returns at once. A build usually takes 10 to 60 seconds.'
+ 'When the request starts a build or one is running, wait for its list until this many seconds after the request started. Defaults to 0, which does not wait. A build usually takes 10 to 60 seconds.'
),
})
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-for-me.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-for-me.json
index bda4906ce827..f7c518727fd4 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-for-me.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-for-me.json
@@ -19,7 +19,7 @@
},
"wait_seconds": {
"default": 0,
- "description": "When the request starts a build or one is running, wait up to this many seconds for its list. Defaults to 0, which returns at once. A build usually takes 10 to 60 seconds.",
+ "description": "When the request starts a build or one is running, wait for its list until this many seconds after the request started. Defaults to 0, which does not wait. A build usually takes 10 to 60 seconds.",
"maximum": 30,
"minimum": 0,
"type": "number"