@zen-agentchecks…zen/fix-gong-cursor-expiry-doc-qrwpuf → master1 files · +5 −0updated 3w agoGong's /v2/calls/extensive endpoint (powering GONG_RETRIEVE_FILTERED_CALL_DETAILS) returns pagination cursors as short-lived JWTs. The cursor payload includes an exp claim that's typically only a few minutes in the future. When an agent pauses between pages (multi-tool reasoning, parallel work) and then tries to paginate with a stale cursor, Gong returns HTTP 400 with body:
{"requestId":"...","errors":["Json parse error, verify Json format matches the API description."]}
This error message is deeply misleading — the JSON is fine; the cursor has just expired. The action description didn't warn about this, so agents (Claude and otherwise) retry the same expired cursor in a loop instead of restarting with filter params.
This PR adds an explicit warning to the cursor field description so the agent reads, on every tool-call construction, that the failure mode exists and what to do about it.
Observed in production (2026-05-18): A customer agent paused for ~20 min between paginations and hit 7 consecutive 400s on cursors whose exp had already passed by 19-22 minutes. Decoded cursor JWTs confirmed expiration:
| Request UTC | Cursor exp UTC | Stale by |
|---|---|---|
| 19:39:17 | 19:18:54 | ~20 min |
| 19:39:30 | 19:18:54 | ~20 min |
| 19:39:49 | 19:18:27 | ~21 min |
| 19:40:02 | 19:18:27 | ~21 min |
| 19:40:16 | 19:18:27 | ~22 min |
| 19:42:26 | 19:21:01 | ~21 min |
| 19:42:37 | 19:21:01 | ~21 min |
nox -s chk_app -- apps/gong passes (ruff format check, ruff lint, mypy — all green; 62 files, no issues).cursor field's description string changed; surrounding code (alias, validator, request_params) is untouched.A behavioral fix worth following up via /cortex-fix:
exp claim in _request and short-circuit with a clear CURSOR_EXPIRED error before hitting Gong.Same gotcha likely applies to other Gong v2 cursor-paginated endpoints (/v2/calls, /v2/calls/transcript, etc.) which use the same JWT cursor format — worth a follow-up sweep.