Issue
`static/schemas/source/signals/get-signals-request.json` declares two pagination shapes:
- top-level `max_results` (`minimum: 1`, no maximum) — historical, predates the pagination envelope
- `pagination.max_results` via `/schemas/core/pagination-request.json` (`minimum: 1`, `maximum: 100`, `default: 50`) — the standard
The schema doesn't say which wins when both are present. PR #3109 (training agent fix + universal storyboard) reads `pagination?.max_results ?? max_results ?? MAX_SIGNAL_RESULTS` — pagination wins. That's the right forward direction (pagination is the standard envelope across all paginated reads), but a real seller agent in the field could plausibly:
- Honor top-level `max_results`, ignore `pagination` (because top-level is older).
- Reject the request (INVALID_REQUEST) because both are present and ambiguous.
- Take the smaller ("safest cap"), which would silently truncate when caller sets pagination.max_results higher than top-level.
The new `get_signals_pagination_integrity` storyboard sends only `pagination.max_results` so it doesn't exercise the conflict, but a conformant agent reading the spec the other way could legitimately fail it.
Asks (one of)
-
Deprecate top-level `max_results` on `get_signals`. Remove from the request schema in 4.0; mark it deprecated in 3.x with a description note pointing at `pagination.max_results`. Sibling endpoints (`list_creatives`, `list_creative_formats`, all the other paginated reads) only carry `pagination`; this brings `get_signals` into line.
-
Pin precedence in the schema description. Add a description field to `pagination.max_results` (or to the request schema at large) saying "When both `max_results` and `pagination.max_results` are present, agents MUST honor `pagination.max_results`." Doesn't break anything; documents the contract the new storyboard implies.
(1) is cleaner long-term; (2) is a 3.x-friendly stopgap.
Why filed
Surfaced by ad-tech-protocol-expert review on #3109. The reviewer flagged this as a "file an upstream issue and link it from the storyboard narrative" before the storyboard's expectation can be considered grounded.
Related
Cross-check
Same question for any other endpoint that carries both top-level `max_results` and `pagination` in its request schema. `get_products` is the candidate to audit next; flag if any other read endpoint has the same drift.
Issue
`static/schemas/source/signals/get-signals-request.json` declares two pagination shapes:
The schema doesn't say which wins when both are present. PR #3109 (training agent fix + universal storyboard) reads `pagination?.max_results ?? max_results ?? MAX_SIGNAL_RESULTS` — pagination wins. That's the right forward direction (pagination is the standard envelope across all paginated reads), but a real seller agent in the field could plausibly:
The new `get_signals_pagination_integrity` storyboard sends only `pagination.max_results` so it doesn't exercise the conflict, but a conformant agent reading the spec the other way could legitimately fail it.
Asks (one of)
Deprecate top-level `max_results` on `get_signals`. Remove from the request schema in 4.0; mark it deprecated in 3.x with a description note pointing at `pagination.max_results`. Sibling endpoints (`list_creatives`, `list_creative_formats`, all the other paginated reads) only carry `pagination`; this brings `get_signals` into line.
Pin precedence in the schema description. Add a description field to `pagination.max_results` (or to the request schema at large) saying "When both `max_results` and `pagination.max_results` are present, agents MUST honor `pagination.max_results`." Doesn't break anything; documents the contract the new storyboard implies.
(1) is cleaner long-term; (2) is a 3.x-friendly stopgap.
Why filed
Surfaced by ad-tech-protocol-expert review on #3109. The reviewer flagged this as a "file an upstream issue and link it from the storyboard narrative" before the storyboard's expectation can be considered grounded.
Related
Cross-check
Same question for any other endpoint that carries both top-level `max_results` and `pagination` in its request schema. `get_products` is the candidate to audit next; flag if any other read endpoint has the same drift.