: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
chore(signals): tighten scout report tool descriptions (#126123)
posthog[bot]3befc9469fb7
diff --git a/products/signals/backend/scout_harness/serializers.py b/products/signals/backend/scout_harness/serializers.pyindex 84ac39cd460c..6a26d29c59ef 100644--- a/products/signals/backend/scout_harness/serializers.py+++ b/products/signals/backend/scout_harness/serializers.py@@ -54,7 +54,7 @@ from products.signals.backend.models import (from products.signals.backend.presentation.scout_suggestion_serializers import ScoutOriginfrom products.signals.backend.report_charts import MAX_REPORT_CHARTSfrom products.signals.backend.report_check_final_agents import MonitoringScoutResult-from products.signals.backend.report_metrics import MAX_REPORT_METRICS+from products.signals.backend.report_metrics import MAX_LIVE_METRIC_QUERY_POINTS, MAX_REPORT_METRICSfrom products.signals.backend.report_prompts import MAX_SUGGESTED_PROMPT_LENGTH, MAX_SUGGESTED_PROMPTSfrom products.signals.backend.report_scout_notes import MAX_REPORT_NOTE_TEXT_LENGTHfrom products.signals.backend.scout_harness.config_registry import CRON_SCHEDULE_MAX_LENGTH, cron_schedule_error@@ -1573,6 +1573,17 @@ class ReportLinkWriteSerializer(serializers.Serializer):)+_REPORT_METRICS_WRITE_HELP = (+ "Mark one metric `primary` for the key observation and the rest `supporting`, for users, "+ "sessions, occurrences, conversion, latency, or revenue. Every metric needs a live `query`: an "+ "InsightVizNode wrapping one bounded TrendsQuery built only from EventsNode or ActionsNode "+ f"sources, with at most {MAX_LIVE_METRIC_QUERY_POINTS} estimated longitudinal points. An "+ "affected-users metric counts distinct people through one series with `math: dau`; never sum "+ "its buckets. A `value`/`value_at` snapshot is only an optional cached fallback, and a metric "+ "without a query is invalid."+)++class EmitReportRequestSerializer(serializers.Serializer):"""Request body for the scout `emit-report` action and the inbox report `create` action. A scout run istaken from the URL path; a person is the authenticated caller."""@@ -1663,22 +1674,16 @@ class EmitReportRequestSerializer(serializers.Serializer):help_text=("Optional charts to attach to the report — the inbox renders them inline, so a metric move ""is something the reader sees rather than a number they take on trust. Attach one whenever "- "the finding rests on a trend, a spike, or a comparison you already queried."+ "the finding rests on a trend, a spike, or a comparison you already queried. Reference a "+ "chart from `summary` as `[label](chart:<chart_id>)` to place it in the body; an "+ "unreferenced chart renders below the summary."),)metrics = serializers.ListField(required=False,child=ReportMetricWriteSerializer(),max_length=MAX_REPORT_METRICS,- help_text=(- "Optional typed impact measurements. Use one primary metric for the key observation and "- "supporting metrics for users, sessions, occurrences, conversion, latency, or revenue. Every "- "metric requires a bounded live InsightVizNode/TrendsQuery built only from EventsNode or "- "ActionsNode sources and capped at 1,000 estimated longitudinal points. Consumers derive "- "BoldNumber and ActionsBar shapes. A value/value_at snapshot is an optional cached fallback. "- "Affected users must use one series with `math: dau`. Snapshot-only/queryless payloads are "- "invalid; legacy rows of that shape are always redacted."- ),+ help_text=(f"Optional typed impact measurements, at most {MAX_REPORT_METRICS}. " + _REPORT_METRICS_WRITE_HELP),)suggested_prompts = serializers.ListField(required=False,@@ -1818,11 +1823,18 @@ class EditReportRequestSerializer(ReviewerProposalSerializer):required=False,allow_null=True,max_length=MAX_NOTE_CONTENT_LENGTH,- help_text="Optional free-form note to append to the report's work log (attributed to this scout).",+ help_text=(+ "Optional free-form note to append to the report's work log, attributed to this scout. "+ "Prefer it over rewriting a report you did not author: a note is additive and keeps the audit trail."+ ),)corroboration_only = serializers.BooleanField(required=False,- help_text="Set only when append_note confirms the finding with no new information. After four confirmations, store only the count. Other notes remain in the work log.",+ help_text=(+ "Set only when `append_note` confirms the finding with no new information. The first four "+ "confirmations stay in the work log as entries; later ones only raise the report's "+ "corroboration count. Other notes always stay in the work log."+ ),)append_evidence = serializers.ListField(required=False,@@ -1859,7 +1871,8 @@ class EditReportRequestSerializer(ReviewerProposalSerializer):"duplicate. It replaces the report's current target and re-runs autostart, so a report ""that had no repository to open a PR against can now open a draft PR. Omit the field to ""leave the target as it is, and pass the `NO_REPO` sentinel for a report where nothing "- "under version control could change."+ "under version control could change. The response's `repository` reads the target back from "+ "the report, and the call fails when the target you named did not land."),)charts = serializers.ListField(@@ -1869,9 +1882,9 @@ class EditReportRequestSerializer(ReviewerProposalSerializer):max_length=MAX_REPORT_CHARTS,help_text=("The full set of charts the report should show. Replaces the report's charts rather than "- "adding to them, the way `summary` replaces the summary — so send every chart you want "- "kept. Omit the field (or send null) to leave the report's existing charts untouched, and "- "send an empty list to take them all down."+ "adding to them, the way `summary` replaces the summary — so read the report first and send "+ "every chart you want kept. Omit the field (or send null) to leave the report's existing "+ "charts untouched, and send an empty list to take them all down."),)metrics = serializers.ListField(@@ -1880,11 +1893,9 @@ class EditReportRequestSerializer(ReviewerProposalSerializer):child=ReportMetricWriteSerializer(),max_length=MAX_REPORT_METRICS,help_text=(- "The report's full impact-metric set. Omit or send null to preserve it; send an empty "- "list to clear it. Every metric requires a bounded live InsightVizNode/TrendsQuery built only "- "from EventsNode or ActionsNode sources and capped at 1,000 estimated longitudinal points. "- "Consumers derive BoldNumber and ActionsBar shapes; a snapshot is only an optional cached fallback. "- "Snapshot-only/queryless payloads are invalid, and legacy rows of that shape are always redacted."+ f"The report's full impact-metric set, at most {MAX_REPORT_METRICS}. Omit it or send null to "+ "keep the current set, send an empty list to clear it, or send the complete replacement. "+ + _REPORT_METRICS_WRITE_HELP),)suggested_prompts = serializers.ListField(@@ -1930,7 +1941,8 @@ class EditReportRequestSerializer(ReviewerProposalSerializer):help_text=("Set this only when your rewrite changes what the fix should be: a different root cause, ""a different file or layer, a materially wider or narrower scope. More evidence for the "- "same fix is not a reason, because the report's open pull request already implements it. "+ "same fix is not a reason, because the report's open pull request already implements it: "+ "put that in `append_note`. ""Setting it true records a replacement decision for a ready report. Policy and eligibility ""checks gate the replacement. The existing pull request closes only after a successful, ""verified replacement. Technical failures retry automatically; policy blocks wait for a new "diff --git a/products/signals/frontend/generated/api.schemas.ts b/products/signals/frontend/generated/api.schemas.tsindex f5ec316d8174..3c40997a4138 100644--- a/products/signals/frontend/generated/api.schemas.ts+++ b/products/signals/frontend/generated/api.schemas.ts@@ -2768,12 +2768,12 @@ export interface EmitReportRequestApi {*/suggested_reviewers?: SuggestedReviewerApi[]/**- * Optional charts to attach to the report — the inbox renders them inline, so a metric move is something the reader sees rather than a number they take on trust. Attach one whenever the finding rests on a trend, a spike, or a comparison you already queried.+ * Optional charts to attach to the report — the inbox renders them inline, so a metric move is something the reader sees rather than a number they take on trust. Attach one whenever the finding rests on a trend, a spike, or a comparison you already queried. Reference a chart from `summary` as `[label](chart:<chart_id>)` to place it in the body; an unreferenced chart renders below the summary.* @maxItems 20*/charts?: ReportChartApi[]/**- * Optional typed impact measurements. Use one primary metric for the key observation and supporting metrics for users, sessions, occurrences, conversion, latency, or revenue. Every metric requires a bounded live InsightVizNode/TrendsQuery built only from EventsNode or ActionsNode sources and capped at 1,000 estimated longitudinal points. Consumers derive BoldNumber and ActionsBar shapes. A value/value_at snapshot is an optional cached fallback. Affected users must use one series with `math: dau`. Snapshot-only/queryless payloads are invalid; legacy rows of that shape are always redacted.+ * Optional typed impact measurements, at most 6. Mark one metric `primary` for the key observation and the rest `supporting`, for users, sessions, occurrences, conversion, latency, or revenue. Every metric needs a live `query`: an InsightVizNode wrapping one bounded TrendsQuery built only from EventsNode or ActionsNode sources, with at most 1000 estimated longitudinal points. An affected-users metric counts distinct people through one series with `math: dau`; never sum its buckets. A `value`/`value_at` snapshot is only an optional cached fallback, and a metric without a query is invalid.* @maxItems 6*/metrics?: ReportMetricWriteApi[]@@ -10035,12 +10035,12 @@ export interface EditReportRequestApi {*/summary?: string | null/**- * Optional free-form note to append to the report's work log (attributed to this scout).+ * Optional free-form note to append to the report's work log, attributed to this scout. Prefer it over rewriting a report you did not author: a note is additive and keeps the audit trail.* @maxLength 10000* @nullable*/append_note?: string | null- /** Set only when append_note confirms the finding with no new information. After four confirmations, store only the count. Other notes remain in the work log. */+ /** Set only when `append_note` confirms the finding with no new information. The first four confirmations stay in the work log as entries; later ones only raise the report's corroboration count. Other notes always stay in the work log. */corroboration_only?: boolean/*** Optional observations to add to the report's evidence rail, each becoming a bound signal attributed to this scout — adds to the report's evidence rather than replacing it. Use this for a new observation a reader should be able to check, and `append_note` for commentary (the owning team knows, a deploy fixed it). The report's signal count and weight move with the appended rows. Emit plus every append share a cap of 50 signals per report.@@ -10054,18 +10054,18 @@ export interface EditReportRequestApi {*/suggested_reviewers?: SuggestedReviewerApi[]/**- * Optional repository to point the report at, as `owner/repo` — the fix for a report that surfaced against the wrong codebase, so you correct it in place instead of filing a duplicate. It replaces the report's current target and re-runs autostart, so a report that had no repository to open a PR against can now open a draft PR. Omit the field to leave the target as it is, and pass the `NO_REPO` sentinel for a report where nothing under version control could change.+ * Optional repository to point the report at, as `owner/repo` — the fix for a report that surfaced against the wrong codebase, so you correct it in place instead of filing a duplicate. It replaces the report's current target and re-runs autostart, so a report that had no repository to open a PR against can now open a draft PR. Omit the field to leave the target as it is, and pass the `NO_REPO` sentinel for a report where nothing under version control could change. The response's `repository` reads the target back from the report, and the call fails when the target you named did not land.* @nullable*/repository?: string | null/**- * The full set of charts the report should show. Replaces the report's charts rather than adding to them, the way `summary` replaces the summary — so send every chart you want kept. Omit the field (or send null) to leave the report's existing charts untouched, and send an empty list to take them all down.+ * The full set of charts the report should show. Replaces the report's charts rather than adding to them, the way `summary` replaces the summary — so read the report first and send every chart you want kept. Omit the field (or send null) to leave the report's existing charts untouched, and send an empty list to take them all down.* @maxItems 20* @nullable*/charts?: ReportChartApi[] | null/**- * The report's full impact-metric set. Omit or send null to preserve it; send an empty list to clear it. Every metric requires a bounded live InsightVizNode/TrendsQuery built only from EventsNode or ActionsNode sources and capped at 1,000 estimated longitudinal points. Consumers derive BoldNumber and ActionsBar shapes; a snapshot is only an optional cached fallback. Snapshot-only/queryless payloads are invalid, and legacy rows of that shape are always redacted.+ * The report's full impact-metric set, at most 6. Omit it or send null to keep the current set, send an empty list to clear it, or send the complete replacement. Mark one metric `primary` for the key observation and the rest `supporting`, for users, sessions, occurrences, conversion, latency, or revenue. Every metric needs a live `query`: an InsightVizNode wrapping one bounded TrendsQuery built only from EventsNode or ActionsNode sources, with at most 1000 estimated longitudinal points. An affected-users metric counts distinct people through one series with `math: dau`; never sum its buckets. A `value`/`value_at` snapshot is only an optional cached fallback, and a metric without a query is invalid.* @maxItems 6* @nullable*/@@ -10088,7 +10088,7 @@ export interface EditReportRequestApi {* @nullable*/tags?: string[] | null- /** Set this only when your rewrite changes what the fix should be: a different root cause, a different file or layer, a materially wider or narrower scope. More evidence for the same fix is not a reason, because the report's open pull request already implements it. Setting it true records a replacement decision for a ready report. Policy and eligibility checks gate the replacement. The existing pull request closes only after a successful, verified replacement. Technical failures retry automatically; policy blocks wait for a new edit or research trigger. Only honored alongside a `title` or `summary` that actually changes, and only within the first four content revisions, including revisions that did not request replacement. When the flag is not applied, `warnings` says why. */+ /** Set this only when your rewrite changes what the fix should be: a different root cause, a different file or layer, a materially wider or narrower scope. More evidence for the same fix is not a reason, because the report's open pull request already implements it: put that in `append_note`. Setting it true records a replacement decision for a ready report. Policy and eligibility checks gate the replacement. The existing pull request closes only after a successful, verified replacement. Technical failures retry automatically; policy blocks wait for a new edit or research trigger. Only honored alongside a `title` or `summary` that actually changes, and only within the first four content revisions, including revisions that did not request replacement. When the flag is not applied, `warnings` says why. */supersedes_implementation?: boolean/** Optional new actionability call, for when new evidence changed your judgment. Replaces the report's actionability decision and re-runs autostart: `immediately_actionable` can open a draft PR, `requires_human_input` and `not_actionable` stop autostart from opening one. The report's inbox status does not change. Send it with `actionability_explanation`, and with `already_addressed` when the issue is handled, since the three replace the decision as one unit.*diff --git a/products/signals/frontend/generated/api.zod.ts b/products/signals/frontend/generated/api.zod.tsindex e6aa69df79ee..13747971c23e 100644--- a/products/signals/frontend/generated/api.zod.ts+++ b/products/signals/frontend/generated/api.zod.ts@@ -860,7 +860,7 @@ export const SignalsReportsCreateBody = /* @__PURE__ */ zod.max(signalsReportsCreateBodyChartsMax).optional().describe(- 'Optional charts to attach to the report — the inbox renders them inline, so a metric move is something the reader sees rather than a number they take on trust. Attach one whenever the finding rests on a trend, a spike, or a comparison you already queried.'+ 'Optional charts to attach to the report — the inbox renders them inline, so a metric move is something the reader sees rather than a number they take on trust. Attach one whenever the finding rests on a trend, a spike, or a comparison you already queried. Reference a chart from `summary` as `[label](chart:<chart_id>)` to place it in the body; an unreferenced chart renders below the summary.'),metrics: zod.array(@@ -964,7 +964,7 @@ export const SignalsReportsCreateBody = /* @__PURE__ */ zod.max(signalsReportsCreateBodyMetricsMax).optional().describe(- 'Optional typed impact measurements. Use one primary metric for the key observation and supporting metrics for users, sessions, occurrences, conversion, latency, or revenue. Every metric requires a bounded live InsightVizNode\/TrendsQuery built only from EventsNode or ActionsNode sources and capped at 1,000 estimated longitudinal points. Consumers derive BoldNumber and ActionsBar shapes. A value\/value_at snapshot is an optional cached fallback. Affected users must use one series with `math: dau`. Snapshot-only\/queryless payloads are invalid; legacy rows of that shape are always redacted.'+ 'Optional typed impact measurements, at most 6. Mark one metric `primary` for the key observation and the rest `supporting`, for users, sessions, occurrences, conversion, latency, or revenue. Every metric needs a live `query`: an InsightVizNode wrapping one bounded TrendsQuery built only from EventsNode or ActionsNode sources, with at most 1000 estimated longitudinal points. An affected-users metric counts distinct people through one series with `math: dau`; never sum its buckets. A `value`\/`value_at` snapshot is only an optional cached fallback, and a metric without a query is invalid.'),suggested_prompts: zod.array(zod.string().max(signalsReportsCreateBodySuggestedPromptsItemMax))@@ -3168,12 +3168,14 @@ export const SignalsScoutEditReportBody = /* @__PURE__ */ zod.string().max(signalsScoutEditReportBodyAppendNoteMax).nullish()- .describe("Optional free-form note to append to the report's work log (attributed to this scout)."),+ .describe(+ "Optional free-form note to append to the report's work log, attributed to this scout. Prefer it over rewriting a report you did not author: a note is additive and keeps the audit trail."+ ),corroboration_only: zod.boolean().optional().describe(- 'Set only when append_note confirms the finding with no new information. After four confirmations, store only the count. Other notes remain in the work log.'+ "Set only when `append_note` confirms the finding with no new information. The first four confirmations stay in the work log as entries; later ones only raise the report's corroboration count. Other notes always stay in the work log."),append_evidence: zod.array(@@ -3236,7 +3238,7 @@ export const SignalsScoutEditReportBody = /* @__PURE__ */ zod.string().nullish().describe(- "Optional repository to point the report at, as `owner\/repo` — the fix for a report that surfaced against the wrong codebase, so you correct it in place instead of filing a duplicate. It replaces the report's current target and re-runs autostart, so a report that had no repository to open a PR against can now open a draft PR. Omit the field to leave the target as it is, and pass the `NO_REPO` sentinel for a report where nothing under version control could change."+ "Optional repository to point the report at, as `owner\/repo` — the fix for a report that surfaced against the wrong codebase, so you correct it in place instead of filing a duplicate. It replaces the report's current target and re-runs autostart, so a report that had no repository to open a PR against can now open a draft PR. Omit the field to leave the target as it is, and pass the `NO_REPO` sentinel for a report where nothing under version control could change. The response's `repository` reads the target back from the report, and the call fails when the target you named did not land."),charts: zod.array(@@ -3281,7 +3283,7 @@ export const SignalsScoutEditReportBody = /* @__PURE__ */ zod.max(signalsScoutEditReportBodyChartsMax).nullish().describe(- "The full set of charts the report should show. Replaces the report's charts rather than adding to them, the way `summary` replaces the summary — so send every chart you want kept. Omit the field (or send null) to leave the report's existing charts untouched, and send an empty list to take them all down."+ "The full set of charts the report should show. Replaces the report's charts rather than adding to them, the way `summary` replaces the summary — so read the report first and send every chart you want kept. Omit the field (or send null) to leave the report's existing charts untouched, and send an empty list to take them all down."),metrics: zod.array(@@ -3385,7 +3387,7 @@ export const SignalsScoutEditReportBody = /* @__PURE__ */ zod.max(signalsScoutEditReportBodyMetricsMax).nullish().describe(- "The report's full impact-metric set. Omit or send null to preserve it; send an empty list to clear it. Every metric requires a bounded live InsightVizNode\/TrendsQuery built only from EventsNode or ActionsNode sources and capped at 1,000 estimated longitudinal points. Consumers derive BoldNumber and ActionsBar shapes; a snapshot is only an optional cached fallback. Snapshot-only\/queryless payloads are invalid, and legacy rows of that shape are always redacted."+ "The report's full impact-metric set, at most 6. Omit it or send null to keep the current set, send an empty list to clear it, or send the complete replacement. Mark one metric `primary` for the key observation and the rest `supporting`, for users, sessions, occurrences, conversion, latency, or revenue. Every metric needs a live `query`: an InsightVizNode wrapping one bounded TrendsQuery built only from EventsNode or ActionsNode sources, with at most 1000 estimated longitudinal points. An affected-users metric counts distinct people through one series with `math: dau`; never sum its buckets. A `value`\/`value_at` snapshot is only an optional cached fallback, and a metric without a query is invalid."),suggested_prompts: zod.array(zod.string().max(signalsScoutEditReportBodySuggestedPromptsItemMax))@@ -3433,7 +3435,7 @@ export const SignalsScoutEditReportBody = /* @__PURE__ */ zod.boolean().optional().describe(- "Set this only when your rewrite changes what the fix should be: a different root cause, a different file or layer, a materially wider or narrower scope. More evidence for the same fix is not a reason, because the report's open pull request already implements it. Setting it true records a replacement decision for a ready report. Policy and eligibility checks gate the replacement. The existing pull request closes only after a successful, verified replacement. Technical failures retry automatically; policy blocks wait for a new edit or research trigger. Only honored alongside a `title` or `summary` that actually changes, and only within the first four content revisions, including revisions that did not request replacement. When the flag is not applied, `warnings` says why."+ "Set this only when your rewrite changes what the fix should be: a different root cause, a different file or layer, a materially wider or narrower scope. More evidence for the same fix is not a reason, because the report's open pull request already implements it: put that in `append_note`. Setting it true records a replacement decision for a ready report. Policy and eligibility checks gate the replacement. The existing pull request closes only after a successful, verified replacement. Technical failures retry automatically; policy blocks wait for a new edit or research trigger. Only honored alongside a `title` or `summary` that actually changes, and only within the first four content revisions, including revisions that did not request replacement. When the flag is not applied, `warnings` says why."),actionability: zod.union([@@ -3677,7 +3679,7 @@ export const SignalsScoutEmitReportBody = /* @__PURE__ */ zod.max(signalsScoutEmitReportBodyChartsMax).optional().describe(- 'Optional charts to attach to the report — the inbox renders them inline, so a metric move is something the reader sees rather than a number they take on trust. Attach one whenever the finding rests on a trend, a spike, or a comparison you already queried.'+ 'Optional charts to attach to the report — the inbox renders them inline, so a metric move is something the reader sees rather than a number they take on trust. Attach one whenever the finding rests on a trend, a spike, or a comparison you already queried. Reference a chart from `summary` as `[label](chart:<chart_id>)` to place it in the body; an unreferenced chart renders below the summary.'),metrics: zod.array(@@ -3781,7 +3783,7 @@ export const SignalsScoutEmitReportBody = /* @__PURE__ */ zod.max(signalsScoutEmitReportBodyMetricsMax).optional().describe(- 'Optional typed impact measurements. Use one primary metric for the key observation and supporting metrics for users, sessions, occurrences, conversion, latency, or revenue. Every metric requires a bounded live InsightVizNode\/TrendsQuery built only from EventsNode or ActionsNode sources and capped at 1,000 estimated longitudinal points. Consumers derive BoldNumber and ActionsBar shapes. A value\/value_at snapshot is an optional cached fallback. Affected users must use one series with `math: dau`. Snapshot-only\/queryless payloads are invalid; legacy rows of that shape are always redacted.'+ 'Optional typed impact measurements, at most 6. Mark one metric `primary` for the key observation and the rest `supporting`, for users, sessions, occurrences, conversion, latency, or revenue. Every metric needs a live `query`: an InsightVizNode wrapping one bounded TrendsQuery built only from EventsNode or ActionsNode sources, with at most 1000 estimated longitudinal points. An affected-users metric counts distinct people through one series with `math: dau`; never sum its buckets. A `value`\/`value_at` snapshot is only an optional cached fallback, and a metric without a query is invalid.'),suggested_prompts: zod.array(zod.string().max(signalsScoutEmitReportBodySuggestedPromptsItemMax))diff --git a/products/signals/mcp/tools.yaml b/products/signals/mcp/tools.yamlindex 584ff65c71e6..3e053425406d 100644--- a/products/signals/mcp/tools.yaml+++ b/products/signals/mcp/tools.yaml@@ -1065,36 +1065,14 @@ tools:idempotent: falsetitle: Edit an existing report for a rundescription: >- The report channel's edit half: rewrite a report's `title`/`summary`, append a note, set its- `suggested_reviewers`, and/or point it at another `repository`. Can target ANY of the project's inbox- reports, not just scout-authored ones — the edit is attributed to this scout. Setting reviewers is how you- rescue a report that surfaced routed to no one: it replaces the reviewer list and re-runs autostart, so a- report missing a qualifying reviewer can open a draft PR. Each reviewer is a `github_login` and/or a PostHog- `user_uuid` (resolved server-side to the linked GitHub login). Optional `repository` is the same rescue for- a report routed to the wrong codebase: pass `owner/repo` to replace the report's target in place, rather- than authoring a duplicate that carries the right one, or the `NO_REPO` sentinel for a report where nothing- under version control could change. It re-runs autostart too, and omitting it leaves the report's target- alone. The response carries `repository`, the target the report holds after the edit, read back from the- report — check it against what you sent, because the call fails when a correction you named did not land.- Prefer `append_note` over rewriting a report you didn't author (additive and audit-friendly); title/summary- edits are best-effort, since the pipeline may later re-research and overwrite them. Optional- `append_evidence` adds observations to the report's evidence rail, each becoming a bound signal that moves- the report's signal count and weight — use it for a new observation a reader should be able to check, and- `append_note` for commentary. Optional `charts` is the full set of queries the inbox renders on the report —- it replaces the report's charts rather than adding to them (omit it to leave them alone), so read the report- first when you mean to add one. Optional `metrics` is the report's complete typed impact-metric set: omit it- or send null to preserve the set, send an empty list to clear it, or send the complete replacement. Every- submitted metric requires a bounded live InsightVizNode/TrendsQuery built only from EventsNode or- ActionsNode sources, with no more than 1,000 estimated longitudinal points; its snapshot is only an optional- cached fallback. An affected-users metric uses one series with `math: dau`. Consumers derive a `BoldNumber`- query for each metric's whole-window `aggregated_value` and an `ActionsBar` query for its longitudinal- buckets; never sum affected-user buckets. NOT idempotent - a retried `append_note` appends a second note.- Set `supersedes_implementation` alongside a rewrite when the fix itself changed. Verified automated- predecessor PRs close only after the replacement completes with verified open PRs. More evidence for the- same fix belongs in `append_note`. Free-form notes always stay in the work log. Set `corroboration_only`- only for confirmations with no new information; the first four stay as entries and later confirmations raise- the corroboration count. Opt-in: only available to scouts that list `edit_report` in their skill's- `allowed_tools`.+ The report channel's edit half: change an existing inbox report in place instead of authoring a+ near-duplicate. Rewrite its `title` or `summary`, append a note or evidence, replace its reviewers,+ repository, charts, metrics, prompts, or tags, add links, or update its actionability or priority. Can+ target ANY of the project's inbox reports, not just scout-authored ones, and the edit is attributed to this+ scout. Use it to rescue a report that surfaced routed to no one or against the wrong codebase, or to record+ a judgment that new evidence changed. When part of an edit does not apply, the response's `warnings` names+ the field and says why, and the rest of the edit lands. NOT idempotent: a retried `append_note` appends a+ second note. Opt-in: only available to scouts that list `edit_report` in their skill's `allowed_tools`.scout-emit-report:operation: signals_scout_emit_reportenabled: true@@ -1106,31 +1084,15 @@ tools:idempotent: truetitle: Author a full report for a rundescription: >- The report channel: author a complete `SignalReport` directly instead of emitting a weak signal, when you've+ The report channel: author a complete inbox report directly instead of emitting a weak signal, when you'vealready done the research and want 1:1 control over the report rather than letting the pipeline cluster it.- The report passes the safety judge, then surfaces at the status your `actionability` call implies- (`immediately_actionable` → READY, `requires_human_input` → PENDING_INPUT, `not_actionable` → suppressed);- an unsafe report is suppressed regardless. Backing `evidence` is written as bound signals so the report- behaves like a pipeline report. Safe to retry: resending an emission returns the report the first call- authored (`idempotent_replay` true) rather than a second one, keyed on `idempotency_key` or, without one, on- the report's content — so a call that timed out is worth sending again. That is not cross-run dedup: use- `inbox-reports-list` to find a report from an earlier run and `scout-edit-report` to update it instead of- authoring a near-duplicate. `suggested_reviewers` is the primary way a report reaches a human (each a- `github_login` and/or a PostHog `user_uuid` resolved server-side); for a concrete, fixable issue, passing- `repository` + `priority` + `suggested_reviewers` also opens a draft PR automatically (autostart,- custom_agent parity); omit them to just surface the report. A `priority` requires a `priority_explanation`.- Optional `charts` attach queries the inbox renders inline — reference one from `summary` as- `[label](chart:<chart_id>)` to place it in the body, or leave it unreferenced and it renders below. Optional- `metrics` adds at most six typed impact measurements: one primary metric for the key observation and- supporting facts around it. Every metric requires a bounded live InsightVizNode/TrendsQuery built only from- EventsNode or ActionsNode sources, with no more than 1,000 estimated longitudinal points; its snapshot is- only an optional cached fallback. An affected-users metric counts distinct people through one series with- `math: dau`. Consumers derive a `BoldNumber` query for each metric's whole-window `aggregated_value` and an- `ActionsBar` query for its longitudinal buckets; never sum affected-user buckets. Optional `links` records- how the new report relates to existing reports (`duplicate_of`, `depends_on`, `part_of`, `follow_up_of`,- `recurrence_of`). Send them here rather than in a later `scout-edit-report`, because autostart reads them- when the report is created. Opt-in: only available to scouts that list `emit_report` in their skill's- `allowed_tools`.+ The report passes the safety judge, then surfaces at the status your `actionability` call sets. For a+ concrete, fixable issue, passing `repository`, `priority`, and `suggested_reviewers` together also opens a+ draft PR automatically (autostart); omit them to just surface the report. Safe to retry: resending an+ emission returns the report the first call authored (`idempotent_replay` true) rather than a second one, so+ a call that timed out is worth sending again. That is not cross-run dedup: use `inbox-reports-list` to find+ a report from an earlier run and `scout-edit-report` to update it instead of authoring a near-duplicate.+ Opt-in: only available to scouts that list `emit_report` in their skill's `allowed_tools`.required_when_set:priority:- priority_explanationdiff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.jsonindex 82261b1cf9e1..1a7d7e772d8e 100644--- a/services/mcp/schema/generated-tool-definitions.json+++ b/services/mcp/schema/generated-tool-definitions.json@@ -12839,7 +12839,7 @@}},"scout-edit-report": {- "description": "The report channel's edit half: rewrite a report's `title`/`summary`, append a note, set its `suggested_reviewers`, and/or point it at another `repository`. Can target ANY of the project's inbox reports, not just scout-authored ones — the edit is attributed to this scout. Setting reviewers is how you rescue a report that surfaced routed to no one: it replaces the reviewer list and re-runs autostart, so a report missing a qualifying reviewer can open a draft PR. Each reviewer is a `github_login` and/or a PostHog `user_uuid` (resolved server-side to the linked GitHub login). Optional `repository` is the same rescue for a report routed to the wrong codebase: pass `owner/repo` to replace the report's target in place, rather than authoring a duplicate that carries the right one, or the `NO_REPO` sentinel for a report where nothing under version control could change. It re-runs autostart too, and omitting it leaves the report's target alone. The response carries `repository`, the target the report holds after the edit, read back from the report — check it against what you sent, because the call fails when a correction you named did not land. Prefer `append_note` over rewriting a report you didn't author (additive and audit-friendly); title/summary edits are best-effort, since the pipeline may later re-research and overwrite them. Optional `append_evidence` adds observations to the report's evidence rail, each becoming a bound signal that moves the report's signal count and weight — use it for a new observation a reader should be able to check, and `append_note` for commentary. Optional `charts` is the full set of queries the inbox renders on the report — it replaces the report's charts rather than adding to them (omit it to leave them alone), so read the report first when you mean to add one. Optional `metrics` is the report's complete typed impact-metric set: omit it or send null to preserve the set, send an empty list to clear it, or send the complete replacement. Every submitted metric requires a bounded live InsightVizNode/TrendsQuery built only from EventsNode or ActionsNode sources, with no more than 1,000 estimated longitudinal points; its snapshot is only an optional cached fallback. An affected-users metric uses one series with `math: dau`. Consumers derive a `BoldNumber` query for each metric's whole-window `aggregated_value` and an `ActionsBar` query for its longitudinal buckets; never sum affected-user buckets. NOT idempotent - a retried `append_note` appends a second note. Set `supersedes_implementation` alongside a rewrite when the fix itself changed. Verified automated predecessor PRs close only after the replacement completes with verified open PRs. More evidence for the same fix belongs in `append_note`. Free-form notes always stay in the work log. Set `corroboration_only` only for confirmations with no new information; the first four stay as entries and later confirmations raise the corroboration count. Opt-in: only available to scouts that list `edit_report` in their skill's `allowed_tools`.",+ "description": "The report channel's edit half: change an existing inbox report in place instead of authoring a near-duplicate. Rewrite its `title` or `summary`, append a note or evidence, replace its reviewers, repository, charts, metrics, prompts, or tags, add links, or update its actionability or priority. Can target ANY of the project's inbox reports, not just scout-authored ones, and the edit is attributed to this scout. Use it to rescue a report that surfaced routed to no one or against the wrong codebase, or to record a judgment that new evidence changed. When part of an edit does not apply, the response's `warnings` names the field and says why, and the rest of the edit lands. NOT idempotent: a retried `append_note` appends a second note. Opt-in: only available to scouts that list `edit_report` in their skill's `allowed_tools`.","category": "Signals","feature": "signals","summary": "Edit an existing report for a run",@@ -12854,7 +12854,7 @@}},"scout-emit-report": {- "description": "The report channel: author a complete `SignalReport` directly instead of emitting a weak signal, when you've already done the research and want 1:1 control over the report rather than letting the pipeline cluster it. The report passes the safety judge, then surfaces at the status your `actionability` call implies (`immediately_actionable` → READY, `requires_human_input` → PENDING_INPUT, `not_actionable` → suppressed); an unsafe report is suppressed regardless. Backing `evidence` is written as bound signals so the report behaves like a pipeline report. Safe to retry: resending an emission returns the report the first call authored (`idempotent_replay` true) rather than a second one, keyed on `idempotency_key` or, without one, on the report's content — so a call that timed out is worth sending again. That is not cross-run dedup: use `inbox-reports-list` to find a report from an earlier run and `scout-edit-report` to update it instead of authoring a near-duplicate. `suggested_reviewers` is the primary way a report reaches a human (each a `github_login` and/or a PostHog `user_uuid` resolved server-side); for a concrete, fixable issue, passing `repository` + `priority` + `suggested_reviewers` also opens a draft PR automatically (autostart, custom_agent parity); omit them to just surface the report. A `priority` requires a `priority_explanation`. Optional `charts` attach queries the inbox renders inline — reference one from `summary` as `[label](chart:<chart_id>)` to place it in the body, or leave it unreferenced and it renders below. Optional `metrics` adds at most six typed impact measurements: one primary metric for the key observation and supporting facts around it. Every metric requires a bounded live InsightVizNode/TrendsQuery built only from EventsNode or ActionsNode sources, with no more than 1,000 estimated longitudinal points; its snapshot is only an optional cached fallback. An affected-users metric counts distinct people through one series with `math: dau`. Consumers derive a `BoldNumber` query for each metric's whole-window `aggregated_value` and an `ActionsBar` query for its longitudinal buckets; never sum affected-user buckets. Optional `links` records how the new report relates to existing reports (`duplicate_of`, `depends_on`, `part_of`, `follow_up_of`, `recurrence_of`). Send them here rather than in a later `scout-edit-report`, because autostart reads them when the report is created. Opt-in: only available to scouts that list `emit_report` in their skill's `allowed_tools`.",+ "description": "The report channel: author a complete inbox report directly instead of emitting a weak signal, when you've already done the research and want 1:1 control over the report rather than letting the pipeline cluster it. The report passes the safety judge, then surfaces at the status your `actionability` call sets. For a concrete, fixable issue, passing `repository`, `priority`, and `suggested_reviewers` together also opens a draft PR automatically (autostart); omit them to just surface the report. Safe to retry: resending an emission returns the report the first call authored (`idempotent_replay` true) rather than a second one, so a call that timed out is worth sending again. That is not cross-run dedup: use `inbox-reports-list` to find a report from an earlier run and `scout-edit-report` to update it instead of authoring a near-duplicate. Opt-in: only available to scouts that list `emit_report` in their skill's `allowed_tools`.","category": "Signals","feature": "signals","summary": "Author a full report for a run",diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.jsonindex 66283d6e3ba3..6de8eaed1ff8 100644--- a/services/mcp/schema/tool-definitions-all.json+++ b/services/mcp/schema/tool-definitions-all.json@@ -13540,7 +13540,7 @@}},"scout-edit-report": {- "description": "The report channel's edit half: rewrite a report's `title`/`summary`, append a note, set its `suggested_reviewers`, and/or point it at another `repository`. Can target ANY of the project's inbox reports, not just scout-authored ones — the edit is attributed to this scout. Setting reviewers is how you rescue a report that surfaced routed to no one: it replaces the reviewer list and re-runs autostart, so a report missing a qualifying reviewer can open a draft PR. Each reviewer is a `github_login` and/or a PostHog `user_uuid` (resolved server-side to the linked GitHub login). Optional `repository` is the same rescue for a report routed to the wrong codebase: pass `owner/repo` to replace the report's target in place, rather than authoring a duplicate that carries the right one, or the `NO_REPO` sentinel for a report where nothing under version control could change. It re-runs autostart too, and omitting it leaves the report's target alone. The response carries `repository`, the target the report holds after the edit, read back from the report — check it against what you sent, because the call fails when a correction you named did not land. Prefer `append_note` over rewriting a report you didn't author (additive and audit-friendly); title/summary edits are best-effort, since the pipeline may later re-research and overwrite them. Optional `append_evidence` adds observations to the report's evidence rail, each becoming a bound signal that moves the report's signal count and weight — use it for a new observation a reader should be able to check, and `append_note` for commentary. Optional `charts` is the full set of queries the inbox renders on the report — it replaces the report's charts rather than adding to them (omit it to leave them alone), so read the report first when you mean to add one. Optional `metrics` is the report's complete typed impact-metric set: omit it or send null to preserve the set, send an empty list to clear it, or send the complete replacement. Every submitted metric requires a bounded live InsightVizNode/TrendsQuery built only from EventsNode or ActionsNode sources, with no more than 1,000 estimated longitudinal points; its snapshot is only an optional cached fallback. An affected-users metric uses one series with `math: dau`. Consumers derive a `BoldNumber` query for each metric's whole-window `aggregated_value` and an `ActionsBar` query for its longitudinal buckets; never sum affected-user buckets. NOT idempotent - a retried `append_note` appends a second note. Set `supersedes_implementation` alongside a rewrite when the fix itself changed. Verified automated predecessor PRs close only after the replacement completes with verified open PRs. More evidence for the same fix belongs in `append_note`. Free-form notes always stay in the work log. Set `corroboration_only` only for confirmations with no new information; the first four stay as entries and later confirmations raise the corroboration count. Opt-in: only available to scouts that list `edit_report` in their skill's `allowed_tools`.",+ "description": "The report channel's edit half: change an existing inbox report in place instead of authoring a near-duplicate. Rewrite its `title` or `summary`, append a note or evidence, replace its reviewers, repository, charts, metrics, prompts, or tags, add links, or update its actionability or priority. Can target ANY of the project's inbox reports, not just scout-authored ones, and the edit is attributed to this scout. Use it to rescue a report that surfaced routed to no one or against the wrong codebase, or to record a judgment that new evidence changed. When part of an edit does not apply, the response's `warnings` names the field and says why, and the rest of the edit lands. NOT idempotent: a retried `append_note` appends a second note. Opt-in: only available to scouts that list `edit_report` in their skill's `allowed_tools`.","category": "Signals","feature": "signals","summary": "Edit an existing report for a run",@@ -13555,7 +13555,7 @@}},"scout-emit-report": {- "description": "The report channel: author a complete `SignalReport` directly instead of emitting a weak signal, when you've already done the research and want 1:1 control over the report rather than letting the pipeline cluster it. The report passes the safety judge, then surfaces at the status your `actionability` call implies (`immediately_actionable` → READY, `requires_human_input` → PENDING_INPUT, `not_actionable` → suppressed); an unsafe report is suppressed regardless. Backing `evidence` is written as bound signals so the report behaves like a pipeline report. Safe to retry: resending an emission returns the report the first call authored (`idempotent_replay` true) rather than a second one, keyed on `idempotency_key` or, without one, on the report's content — so a call that timed out is worth sending again. That is not cross-run dedup: use `inbox-reports-list` to find a report from an earlier run and `scout-edit-report` to update it instead of authoring a near-duplicate. `suggested_reviewers` is the primary way a report reaches a human (each a `github_login` and/or a PostHog `user_uuid` resolved server-side); for a concrete, fixable issue, passing `repository` + `priority` + `suggested_reviewers` also opens a draft PR automatically (autostart, custom_agent parity); omit them to just surface the report. A `priority` requires a `priority_explanation`. Optional `charts` attach queries the inbox renders inline — reference one from `summary` as `[label](chart:<chart_id>)` to place it in the body, or leave it unreferenced and it renders below. Optional `metrics` adds at most six typed impact measurements: one primary metric for the key observation and supporting facts around it. Every metric requires a bounded live InsightVizNode/TrendsQuery built only from EventsNode or ActionsNode sources, with no more than 1,000 estimated longitudinal points; its snapshot is only an optional cached fallback. An affected-users metric counts distinct people through one series with `math: dau`. Consumers derive a `BoldNumber` query for each metric's whole-window `aggregated_value` and an `ActionsBar` query for its longitudinal buckets; never sum affected-user buckets. Optional `links` records how the new report relates to existing reports (`duplicate_of`, `depends_on`, `part_of`, `follow_up_of`, `recurrence_of`). Send them here rather than in a later `scout-edit-report`, because autostart reads them when the report is created. Opt-in: only available to scouts that list `emit_report` in their skill's `allowed_tools`.",+ "description": "The report channel: author a complete inbox report directly instead of emitting a weak signal, when you've already done the research and want 1:1 control over the report rather than letting the pipeline cluster it. The report passes the safety judge, then surfaces at the status your `actionability` call sets. For a concrete, fixable issue, passing `repository`, `priority`, and `suggested_reviewers` together also opens a draft PR automatically (autostart); omit them to just surface the report. Safe to retry: resending an emission returns the report the first call authored (`idempotent_replay` true) rather than a second one, so a call that timed out is worth sending again. That is not cross-run dedup: use `inbox-reports-list` to find a report from an earlier run and `scout-edit-report` to update it instead of authoring a near-duplicate. Opt-in: only available to scouts that list `emit_report` in their skill's `allowed_tools`.","category": "Signals","feature": "signals","summary": "Author a full report for a run",diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex 3f458697d820..faf938b09c3e 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -36531,12 +36531,12 @@ export namespace Schemas {*/summary?: string | null;/**- * Optional free-form note to append to the report's work log (attributed to this scout).+ * Optional free-form note to append to the report's work log, attributed to this scout. Prefer it over rewriting a report you did not author: a note is additive and keeps the audit trail.* @maxLength 10000* @nullable*/append_note?: string | null;- /** Set only when append_note confirms the finding with no new information. After four confirmations, store only the count. Other notes remain in the work log. */+ /** Set only when `append_note` confirms the finding with no new information. The first four confirmations stay in the work log as entries; later ones only raise the report's corroboration count. Other notes always stay in the work log. */corroboration_only?: boolean;/*** Optional observations to add to the report's evidence rail, each becoming a bound signal attributed to this scout — adds to the report's evidence rather than replacing it. Use this for a new observation a reader should be able to check, and `append_note` for commentary (the owning team knows, a deploy fixed it). The report's signal count and weight move with the appended rows. Emit plus every append share a cap of 50 signals per report.@@ -36550,18 +36550,18 @@ export namespace Schemas {*/suggested_reviewers?: SuggestedReviewer[];/**- * Optional repository to point the report at, as `owner/repo` — the fix for a report that surfaced against the wrong codebase, so you correct it in place instead of filing a duplicate. It replaces the report's current target and re-runs autostart, so a report that had no repository to open a PR against can now open a draft PR. Omit the field to leave the target as it is, and pass the `NO_REPO` sentinel for a report where nothing under version control could change.+ * Optional repository to point the report at, as `owner/repo` — the fix for a report that surfaced against the wrong codebase, so you correct it in place instead of filing a duplicate. It replaces the report's current target and re-runs autostart, so a report that had no repository to open a PR against can now open a draft PR. Omit the field to leave the target as it is, and pass the `NO_REPO` sentinel for a report where nothing under version control could change. The response's `repository` reads the target back from the report, and the call fails when the target you named did not land.* @nullable*/repository?: string | null;/**- * The full set of charts the report should show. Replaces the report's charts rather than adding to them, the way `summary` replaces the summary — so send every chart you want kept. Omit the field (or send null) to leave the report's existing charts untouched, and send an empty list to take them all down.+ * The full set of charts the report should show. Replaces the report's charts rather than adding to them, the way `summary` replaces the summary — so read the report first and send every chart you want kept. Omit the field (or send null) to leave the report's existing charts untouched, and send an empty list to take them all down.* @maxItems 20* @nullable*/charts?: ReportChart[] | null;/**- * The report's full impact-metric set. Omit or send null to preserve it; send an empty list to clear it. Every metric requires a bounded live InsightVizNode/TrendsQuery built only from EventsNode or ActionsNode sources and capped at 1,000 estimated longitudinal points. Consumers derive BoldNumber and ActionsBar shapes; a snapshot is only an optional cached fallback. Snapshot-only/queryless payloads are invalid, and legacy rows of that shape are always redacted.+ * The report's full impact-metric set, at most 6. Omit it or send null to keep the current set, send an empty list to clear it, or send the complete replacement. Mark one metric `primary` for the key observation and the rest `supporting`, for users, sessions, occurrences, conversion, latency, or revenue. Every metric needs a live `query`: an InsightVizNode wrapping one bounded TrendsQuery built only from EventsNode or ActionsNode sources, with at most 1000 estimated longitudinal points. An affected-users metric counts distinct people through one series with `math: dau`; never sum its buckets. A `value`/`value_at` snapshot is only an optional cached fallback, and a metric without a query is invalid.* @maxItems 6* @nullable*/@@ -36584,7 +36584,7 @@ export namespace Schemas {* @nullable*/tags?: string[] | null;- /** Set this only when your rewrite changes what the fix should be: a different root cause, a different file or layer, a materially wider or narrower scope. More evidence for the same fix is not a reason, because the report's open pull request already implements it. Setting it true records a replacement decision for a ready report. Policy and eligibility checks gate the replacement. The existing pull request closes only after a successful, verified replacement. Technical failures retry automatically; policy blocks wait for a new edit or research trigger. Only honored alongside a `title` or `summary` that actually changes, and only within the first four content revisions, including revisions that did not request replacement. When the flag is not applied, `warnings` says why. */+ /** Set this only when your rewrite changes what the fix should be: a different root cause, a different file or layer, a materially wider or narrower scope. More evidence for the same fix is not a reason, because the report's open pull request already implements it: put that in `append_note`. Setting it true records a replacement decision for a ready report. Policy and eligibility checks gate the replacement. The existing pull request closes only after a successful, verified replacement. Technical failures retry automatically; policy blocks wait for a new edit or research trigger. Only honored alongside a `title` or `summary` that actually changes, and only within the first four content revisions, including revisions that did not request replacement. When the flag is not applied, `warnings` says why. */supersedes_implementation?: boolean;/** Optional new actionability call, for when new evidence changed your judgment. Replaces the report's actionability decision and re-runs autostart: `immediately_actionable` can open a draft PR, `requires_human_input` and `not_actionable` stop autostart from opening one. The report's inbox status does not change. Send it with `actionability_explanation`, and with `already_addressed` when the issue is handled, since the three replace the decision as one unit.*@@ -37537,12 +37537,12 @@ export namespace Schemas {*/suggested_reviewers?: SuggestedReviewer[];/**- * Optional charts to attach to the report — the inbox renders them inline, so a metric move is something the reader sees rather than a number they take on trust. Attach one whenever the finding rests on a trend, a spike, or a comparison you already queried.+ * Optional charts to attach to the report — the inbox renders them inline, so a metric move is something the reader sees rather than a number they take on trust. Attach one whenever the finding rests on a trend, a spike, or a comparison you already queried. Reference a chart from `summary` as `[label](chart:<chart_id>)` to place it in the body; an unreferenced chart renders below the summary.* @maxItems 20*/charts?: ReportChart[];/**- * Optional typed impact measurements. Use one primary metric for the key observation and supporting metrics for users, sessions, occurrences, conversion, latency, or revenue. Every metric requires a bounded live InsightVizNode/TrendsQuery built only from EventsNode or ActionsNode sources and capped at 1,000 estimated longitudinal points. Consumers derive BoldNumber and ActionsBar shapes. A value/value_at snapshot is an optional cached fallback. Affected users must use one series with `math: dau`. Snapshot-only/queryless payloads are invalid; legacy rows of that shape are always redacted.+ * Optional typed impact measurements, at most 6. Mark one metric `primary` for the key observation and the rest `supporting`, for users, sessions, occurrences, conversion, latency, or revenue. Every metric needs a live `query`: an InsightVizNode wrapping one bounded TrendsQuery built only from EventsNode or ActionsNode sources, with at most 1000 estimated longitudinal points. An affected-users metric counts distinct people through one series with `math: dau`; never sum its buckets. A `value`/`value_at` snapshot is only an optional cached fallback, and a metric without a query is invalid.* @maxItems 6*/metrics?: ReportMetricWrite[];diff --git a/services/mcp/src/generated/signals/api.ts b/services/mcp/src/generated/signals/api.tsindex bc31ed268d06..e7609f5abe41 100644--- a/services/mcp/src/generated/signals/api.ts+++ b/services/mcp/src/generated/signals/api.ts@@ -768,7 +768,7 @@ export const SignalsReportsCreateBody = () => zod.max(signalsReportsCreateBodyChartsMax).optional().describe(- 'Optional charts to attach to the report — the inbox renders them inline, so a metric move is something the reader sees rather than a number they take on trust. Attach one whenever the finding rests on a trend, a spike, or a comparison you already queried.'+ 'Optional charts to attach to the report — the inbox renders them inline, so a metric move is something the reader sees rather than a number they take on trust. Attach one whenever the finding rests on a trend, a spike, or a comparison you already queried. Reference a chart from `summary` as `[label](chart:<chart_id>)` to place it in the body; an unreferenced chart renders below the summary.'),suggested_prompts: zod.array(zod.string().max(signalsReportsCreateBodySuggestedPromptsItemMax))@@ -3633,12 +3633,14 @@ export const SignalsScoutEditReportBody = () => zod.string().max(signalsScoutEditReportBodyAppendNoteMax).nullish()- .describe("Optional free-form note to append to the report's work log (attributed to this scout)."),+ .describe(+ "Optional free-form note to append to the report's work log, attributed to this scout. Prefer it over rewriting a report you did not author: a note is additive and keeps the audit trail."+ ),corroboration_only: zod.boolean().optional().describe(- 'Set only when append_note confirms the finding with no new information. After four confirmations, store only the count. Other notes remain in the work log.'+ "Set only when `append_note` confirms the finding with no new information. The first four confirmations stay in the work log as entries; later ones only raise the report's corroboration count. Other notes always stay in the work log."),append_evidence: zod.array(@@ -3701,7 +3703,7 @@ export const SignalsScoutEditReportBody = () => zod.string().nullish().describe(- "Optional repository to point the report at, as `owner\/repo` — the fix for a report that surfaced against the wrong codebase, so you correct it in place instead of filing a duplicate. It replaces the report's current target and re-runs autostart, so a report that had no repository to open a PR against can now open a draft PR. Omit the field to leave the target as it is, and pass the `NO_REPO` sentinel for a report where nothing under version control could change."+ "Optional repository to point the report at, as `owner\/repo` — the fix for a report that surfaced against the wrong codebase, so you correct it in place instead of filing a duplicate. It replaces the report's current target and re-runs autostart, so a report that had no repository to open a PR against can now open a draft PR. Omit the field to leave the target as it is, and pass the `NO_REPO` sentinel for a report where nothing under version control could change. The response's `repository` reads the target back from the report, and the call fails when the target you named did not land."),charts: zod.array(@@ -3746,7 +3748,7 @@ export const SignalsScoutEditReportBody = () => zod.max(signalsScoutEditReportBodyChartsMax).nullish().describe(- "The full set of charts the report should show. Replaces the report's charts rather than adding to them, the way `summary` replaces the summary — so send every chart you want kept. Omit the field (or send null) to leave the report's existing charts untouched, and send an empty list to take them all down."+ "The full set of charts the report should show. Replaces the report's charts rather than adding to them, the way `summary` replaces the summary — so read the report first and send every chart you want kept. Omit the field (or send null) to leave the report's existing charts untouched, and send an empty list to take them all down."),metrics: zod.array(@@ -3850,7 +3852,7 @@ export const SignalsScoutEditReportBody = () => zod.max(signalsScoutEditReportBodyMetricsMax).nullish().describe(- "The report's full impact-metric set. Omit or send null to preserve it; send an empty list to clear it. Every metric requires a bounded live InsightVizNode\/TrendsQuery built only from EventsNode or ActionsNode sources and capped at 1,000 estimated longitudinal points. Consumers derive BoldNumber and ActionsBar shapes; a snapshot is only an optional cached fallback. Snapshot-only\/queryless payloads are invalid, and legacy rows of that shape are always redacted."+ "The report's full impact-metric set, at most 6. Omit it or send null to keep the current set, send an empty list to clear it, or send the complete replacement. Mark one metric `primary` for the key observation and the rest `supporting`, for users, sessions, occurrences, conversion, latency, or revenue. Every metric needs a live `query`: an InsightVizNode wrapping one bounded TrendsQuery built only from EventsNode or ActionsNode sources, with at most 1000 estimated longitudinal points. An affected-users metric counts distinct people through one series with `math: dau`; never sum its buckets. A `value`\/`value_at` snapshot is only an optional cached fallback, and a metric without a query is invalid."),suggested_prompts: zod.array(zod.string().max(signalsScoutEditReportBodySuggestedPromptsItemMax))@@ -3898,7 +3900,7 @@ export const SignalsScoutEditReportBody = () => zod.boolean().optional().describe(- "Set this only when your rewrite changes what the fix should be: a different root cause, a different file or layer, a materially wider or narrower scope. More evidence for the same fix is not a reason, because the report's open pull request already implements it. Setting it true records a replacement decision for a ready report. Policy and eligibility checks gate the replacement. The existing pull request closes only after a successful, verified replacement. Technical failures retry automatically; policy blocks wait for a new edit or research trigger. Only honored alongside a `title` or `summary` that actually changes, and only within the first four content revisions, including revisions that did not request replacement. When the flag is not applied, `warnings` says why."+ "Set this only when your rewrite changes what the fix should be: a different root cause, a different file or layer, a materially wider or narrower scope. More evidence for the same fix is not a reason, because the report's open pull request already implements it: put that in `append_note`. Setting it true records a replacement decision for a ready report. Policy and eligibility checks gate the replacement. The existing pull request closes only after a successful, verified replacement. Technical failures retry automatically; policy blocks wait for a new edit or research trigger. Only honored alongside a `title` or `summary` that actually changes, and only within the first four content revisions, including revisions that did not request replacement. When the flag is not applied, `warnings` says why."),actionability: zod.union([@@ -4177,7 +4179,7 @@ export const SignalsScoutEmitReportBody = () => zod.max(signalsScoutEmitReportBodyChartsMax).optional().describe(- 'Optional charts to attach to the report — the inbox renders them inline, so a metric move is something the reader sees rather than a number they take on trust. Attach one whenever the finding rests on a trend, a spike, or a comparison you already queried.'+ 'Optional charts to attach to the report — the inbox renders them inline, so a metric move is something the reader sees rather than a number they take on trust. Attach one whenever the finding rests on a trend, a spike, or a comparison you already queried. Reference a chart from `summary` as `[label](chart:<chart_id>)` to place it in the body; an unreferenced chart renders below the summary.'),metrics: zod.array(@@ -4281,7 +4283,7 @@ export const SignalsScoutEmitReportBody = () => zod.max(signalsScoutEmitReportBodyMetricsMax).optional().describe(- 'Optional typed impact measurements. Use one primary metric for the key observation and supporting metrics for users, sessions, occurrences, conversion, latency, or revenue. Every metric requires a bounded live InsightVizNode\/TrendsQuery built only from EventsNode or ActionsNode sources and capped at 1,000 estimated longitudinal points. Consumers derive BoldNumber and ActionsBar shapes. A value\/value_at snapshot is an optional cached fallback. Affected users must use one series with `math: dau`. Snapshot-only\/queryless payloads are invalid; legacy rows of that shape are always redacted.'+ 'Optional typed impact measurements, at most 6. Mark one metric `primary` for the key observation and the rest `supporting`, for users, sessions, occurrences, conversion, latency, or revenue. Every metric needs a live `query`: an InsightVizNode wrapping one bounded TrendsQuery built only from EventsNode or ActionsNode sources, with at most 1000 estimated longitudinal points. An affected-users metric counts distinct people through one series with `math: dau`; never sum its buckets. A `value`\/`value_at` snapshot is only an optional cached fallback, and a metric without a query is invalid.'),suggested_prompts: zod.array(zod.string().max(signalsScoutEmitReportBodySuggestedPromptsItemMax))diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-create.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-create.jsonindex 24cb5da4da73..c779eeb1bc43 100644--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-create.json+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-create.json@@ -17,7 +17,7 @@"type": "boolean"},"charts": {- "description": "Optional charts to attach to the report — the inbox renders them inline, so a metric move is something the reader sees rather than a number they take on trust. Attach one whenever the finding rests on a trend, a spike, or a comparison you already queried.",+ "description": "Optional charts to attach to the report — the inbox renders them inline, so a metric move is something the reader sees rather than a number they take on trust. Attach one whenever the finding rests on a trend, a spike, or a comparison you already queried. Reference a chart from `summary` as `[label](chart:<chart_id>)` to place it in the body; an unreferenced chart renders below the summary.","items": {"description": "One chart attached to a report — rendered in the inbox and referenceable from the summary.","properties": {