cito-mcp 0.5.7 → 0.6.0

package/dist/tools/match.js

@@ -182,7 +182,7 @@ Prefer match_details for timelines, full map trees, live state, advanced package
 
 Do not use when: no matchId yet (resolve from live/schedule); pure pre-match → match_preview.
 
-Parallel-safe: yes. Upstream cost: 2–5.
+Parallel-safe: yes. API calls: 2–5.
 Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includePlayerStats": true }`,
     inputSchema: {
         type: 'object',
@@ -344,6 +344,7 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
                         player1Games: p1g,
                         player2Games: p2g,
                         tiebreak: sr.tiebreak ?? null,
+                        tiebreakPoints: sr.tiebreak_points ?? null,
                         completed: tennisSetCompleted(sr),
                     };
                 });
@@ -404,6 +405,37 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
         });
     },
 };
+export function summarizeCs2Odds(data) {
+    const root = (data ?? {});
+    const payload = (root.data && typeof root.data === 'object' && !Array.isArray(root.data)
+        ? root.data
+        : root);
+    const rows = Array.isArray(payload.odds) ? payload.odds : [];
+    const rank = (m) => (m === 'h2h' ? '0' : `1${String(m ?? '')}`);
+    const markets = rows
+        .map((r) => ({
+        market: r.market ?? null,
+        team1Odds: r.team1Odds ?? null,
+        team2Odds: r.team2Odds ?? null,
+        team1ImpliedProb: r.team1ImpliedProb ?? null,
+        team2ImpliedProb: r.team2ImpliedProb ?? null,
+        marketStatus: r.marketStatus ?? 'open',
+        liquidityUsd: r.liquidityUsd ?? null,
+        capturedAt: r.capturedAt ?? null,
+    }))
+        .sort((a, b) => rank(a.market).localeCompare(rank(b.market)));
+    return {
+        teams: payload.teams ?? null,
+        dataAvailable: markets.length > 0,
+        markets,
+        realTime: {
+            updates: 'Prices update as soon as the market price changes, through every map and between rounds.',
+            push: 'wss://api.citoapi.com/api/v1/cs2/live/ws (message type cs2.odds.updated; needs Live WebSockets and a plan with odds)',
+            byRound: '/cs2/matches/{matchId}/odds/rounds (price at each round start and end); /cs2/matches/{matchId}/odds/history?map=&round=&phase=',
+        },
+        fullBookPath: '/cs2/matches/{matchId}/odds',
+    };
+}
 export function summarizeUfcOdds(data) {
     const root = (data ?? {});
     const payload = (root.data && typeof root.data === 'object' && !Array.isArray(root.data)
@@ -482,8 +514,7 @@ export function summarizeTennisSetStats(block) {
         return null;
     const arr = (v) => (Array.isArray(v) ? v : []);
     const strings = (v) => arr(v).map(String);
-    if (!arr(b.periods).length && !arr(b.gaps).length && !arr(b.sources).length
-        && typeof b.note !== 'string') {
+    if (!arr(b.periods).length && !arr(b.gaps).length && typeof b.note !== 'string') {
         return null;
     }
     const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
@@ -514,37 +545,45 @@ export function summarizeTennisSetStats(block) {
                 period: str(pr.period) ?? 'ALL',
                 setNumber: num(pr.set_number) ?? 0,
                 status: str(pr.status) ?? 'partial',
-                sources: strings(pr.sources),
                 winner: line(pr.winner),
                 loser: line(pr.loser),
                 missing: { winner: strings(missing.winner), loser: strings(missing.loser) },
             };
         }),
-        sources: arr(b.sources).map((s) => {
-            const sr = asRecord(s) ?? {};
-            return {
-                source: str(sr.source) ?? 'unknown',
-                status: str(sr.status) ?? 'unknown',
-                fields: strings(sr.fields),
-                detail: str(sr.detail),
-            };
-        }),
         gaps: arr(b.gaps).map((g) => {
             const gr = asRecord(g) ?? {};
+            const rawCode = str(gr.code) ?? 'UNKNOWN';
+            const originGap = /SOURCE/i.test(rawCode);
+            const fields = strings(gr.fields);
+            const rawMessage = str(gr.message) ?? '';
             return {
-                code: str(gr.code) ?? 'UNKNOWN',
+                code: originGap ? 'STATS_UNAVAILABLE' : rawCode,
                 period: str(gr.period),
                 setNumber: num(gr.set_number),
                 side: str(gr.side),
-                fields: strings(gr.fields),
-                source: str(gr.source),
-                status: str(gr.status),
-                message: str(gr.message) ?? '',
+                fields,
+                status: originGap ? null : str(gr.status),
+                message: originGap || GAP_INTERNAL_WORDING.test(rawMessage)
+                    ? fields.length
+                        ? `${fields.join(', ')} not available`
+                        : 'Some statistics are not available for this match'
+                    : rawMessage,
             };
         }),
-        note: str(b.note),
+        note: neutralSetStatsNote(str(b.note)),
     };
 }
+const GAP_INTERNAL_WORDING = /\bsources?\b|source_|ingest|feed|vendor|\b[a-z_]+\.[a-z_]+\b/i;
+function neutralSetStatsNote(note) {
+    if (!note)
+        return note;
+    const kept = note
+        .split(/(?<=\.)\s+/)
+        .filter((sentence) => !/\bsource/i.test(sentence))
+        .join(' ')
+        .trim();
+    return kept || null;
+}
 export function tennisSetStatsWarnings(block) {
     const shaped = summarizeTennisSetStats(block);
     if (!shaped)
@@ -602,6 +641,7 @@ export function summarizeTennisMatchStats(data) {
                 player1Games: toNum(sr.player1_games),
                 player2Games: toNum(sr.player2_games),
                 tiebreak: sr.tiebreak ?? null,
+                tiebreakPoints: sr.tiebreak_points ?? null,
                 completed: tennisSetCompleted(sr),
             };
         }),
@@ -624,10 +664,10 @@ Prefer match_summary for short answers and default cards.
 Do not use when: first-pass live board (use live_matches + match_summary).
 
 Section selection: pass includeTimeline / includeLiveState / includeAdvanced booleans, OR an explicit sections[] list.
-UFC betting lines: sections:["odds"] (opt-in, never in the default set).
+Betting lines: sections:["odds"] (opt-in, never in the default set): UFC moneyline summary, or CS2 series + map markets (real-time prices, pushed over the CS2 live WebSocket as cs2.odds.updated).
 If sections[] is non-empty it wins (booleans are ignored). LoL liveState/advanced require gameId.
 
-Parallel-safe: yes. Upstream cost: 1–8 (section-gated).
+Parallel-safe: yes. API calls: 1–8 (section-gated).
 Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "includeLiveState": false }`,
     inputSchema: {
         type: 'object',
@@ -831,10 +871,13 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
             if (game === 'ufc') {
                 loadWith('odds', `/ufc/bouts/${encodeURIComponent(matchId)}/odds`, summarizeUfcOdds);
             }
+            else if (game === 'cs2') {
+                loadWith('odds', `/cs2/matches/${encodeURIComponent(matchId)}/odds`, summarizeCs2Odds);
+            }
             else {
                 partial.push(partialFromRejection('odds', {
                     code: 'NOT_IMPLEMENTED',
-                    message: `Odds are only available for UFC (/ufc/bouts/{id}/odds).`,
+                    message: `Odds sections are available for UFC (/ufc/bouts/{id}/odds) and CS2 (/cs2/matches/{id}/odds); LoL odds via call_api /lol/matches/{id}/odds.`,
                 }));
             }
         }

package/dist/tools/meta.js

@@ -65,6 +65,36 @@ const COMBAT_CATALOG = [
         exampleArgs: { league: 'bkfc', division: 'heavyweight' },
     },
 ];
+const WEBHOOK_GAMES = [...PRIMARY_GAMES];
+const webhookCatalogRow = (name, outcome, exampleArgs, parallelSafe = false) => ({
+    name,
+    outcome,
+    parallelSafe,
+    games: WEBHOOK_GAMES,
+    jobs: ['webhooks'],
+    exampleArgs,
+    preferOver: [],
+    doNotUse: 'Reading match data → the curated data tools',
+});
+const WEBHOOK_CATALOG = [
+    webhookCatalogRow('explain_webhook_setup', 'How webhooks work plus this account: plan, existing webhooks and inboxes, next steps', {}, true),
+    webhookCatalogRow('list_webhook_events', 'Every webhook event with status, measured frequency, plan, filters; fields and a real example for one event', { game: 'cs2' }, true),
+    webhookCatalogRow('list_webhooks', "This account's webhooks and their health", {}, true),
+    webhookCatalogRow('create_webhook', 'Create a webhook on this account (Pro or Scale); the secret comes back once', { url: 'https://your-domain.com/webhooks/cito', events: ['cs2.match.completed'] }),
+    webhookCatalogRow('update_webhook', "Change a webhook's URL, events, filters or on/off state", { id: 'from list_webhooks', isActive: false }),
+    webhookCatalogRow('delete_webhook', 'Delete a webhook; needs confirm: true and the user clearly asking', { id: 'from list_webhooks', confirm: true }),
+    webhookCatalogRow('regenerate_webhook_secret', "Replace a webhook's signing secret", { id: 'from list_webhooks' }),
+    webhookCatalogRow('test_webhook', 'Send a real signed sample and get status, code, latency and a diagnosis', { id: 'from list_webhooks', event: 'cs2.match.completed' }),
+    webhookCatalogRow('webhook_deliveries', "A webhook's delivery log with diagnosis; one delivery with its payload", { id: 'from list_webhooks', status: 'failed' }, true),
+    webhookCatalogRow('replay_webhook', 'Re-send a stored event or a match to this webhook', { id: 'from list_webhooks', eventId: 'from webhook_deliveries' }),
+    webhookCatalogRow('catch_up_webhook', 'After an outage, re-send the match and result events a webhook missed', { id: 'from list_webhooks', dryRun: true }),
+    webhookCatalogRow('create_webhook_inbox', 'A hosted temporary receiver, on any plan, so no server or tunnel is needed', {}),
+    webhookCatalogRow('list_webhook_inboxes', "This account's live test inboxes and limits", {}, true),
+    webhookCatalogRow('read_webhook_inbox', 'What an inbox received: headers, body, signature check', { id: 'from create_webhook_inbox' }, true),
+    webhookCatalogRow('send_inbox_sample', 'Put a real sample of an event into an inbox, on any plan', { id: 'from create_webhook_inbox', event: 'cs2.match.completed' }),
+    webhookCatalogRow('clear_webhook_inbox', 'Remove what an inbox holds', { id: 'from create_webhook_inbox' }),
+    webhookCatalogRow('delete_webhook_inbox', 'Delete a test inbox', { id: 'from create_webhook_inbox' }),
+];
 const TOOL_CATALOG = [
     {
         name: 'list_capabilities',
@@ -168,7 +198,7 @@ const TOOL_CATALOG = [
     },
     {
         name: 'head_to_head',
-        outcome: 'Composed H2H record between two teams or fighters',
+        outcome: 'H2H record between two teams, fighters or tennis players (sideA, sideB; h2h_matrix takes players)',
         parallelSafe: true,
         games: [...PRIMARY_GAMES],
         jobs: ['h2h', 'preview'],
@@ -228,7 +258,7 @@ const TOOL_CATALOG = [
     },
     {
         name: 'player_stats',
-        outcome: 'Tennis career statistics: W/L, win%, titles, per-surface breakdown, serving stats, and named gaps',
+        outcome: 'Tennis career statistics: singles W/L, win%, titles, per-surface and per-level breakdowns, serving stats, doubles and combined scopes, and named gaps',
         parallelSafe: true,
         games: ['tennis'],
         jobs: ['player_form'],
@@ -429,7 +459,7 @@ const TOOL_CATALOG = [
         games: ['cs2'],
         jobs: ['team_page', 'preview'],
         exampleArgs: { teamId: 'cs2-team-4608', days: 90 },
-        preferOver: ['manual match history scraping'],
+        preferOver: ['manual match history lookups'],
         doNotUse: 'For non-CS2 games',
     },
     {
@@ -459,7 +489,7 @@ const TOOL_CATALOG = [
         games: ['cs2'],
         jobs: ['match_page', 'preview'],
         exampleArgs: { matchId: '2397603' },
-        preferOver: ['scraping match page text'],
+        preferOver: ['parsing match page text'],
         doNotUse: 'For map scores → match_summary',
     },
     {
@@ -469,7 +499,7 @@ const TOOL_CATALOG = [
         games: ['cs2'],
         jobs: ['team_page', 'schedule'],
         exampleArgs: { limit: 20 },
-        preferOver: ['manual news feed scanning'],
+        preferOver: ['manual news scanning'],
         doNotUse: 'For current active rosters → team_profile',
     },
     {
@@ -493,6 +523,7 @@ const TOOL_CATALOG = [
         doNotUse: 'Any job covered by a curated tool',
     },
     ...COMBAT_CATALOG,
+    ...WEBHOOK_CATALOG,
 ];
 const JOBS = [
     { id: 'live_board', description: 'Ops/dashboard live strip', recommendedTools: ['live_matches', 'match_summary'] },
@@ -510,6 +541,7 @@ const JOBS = [
         recommendedTools: ['event_card', 'player_profile', 'resolve_entity'],
     },
     { id: 'app_scaffold', description: 'Design-time multi-screen prototype', recommendedTools: ['list_capabilities', 'api_health', 'live_matches'] },
+    { id: 'webhooks', description: 'Set up, test and debug push delivery instead of polling', recommendedTools: ['explain_webhook_setup', 'list_webhook_events', 'create_webhook', 'test_webhook', 'webhook_deliveries', 'create_webhook_inbox'] },
 ];
 const RECIPES = [
     {
@@ -588,7 +620,7 @@ Prefer over: guessing from memory; exploring raw OpenAPI via call_api.
 
 Do not use when: you already know the tool and have IDs — call that tool directly.
 
-Parallel-safe: yes. Upstream cost: 0.
+Parallel-safe: yes. API calls: 0.
 Example: { "game": "cs2", "job": "live_board", "includeExamples": true }`,
     inputSchema: {
         type: 'object',
@@ -682,7 +714,7 @@ Prefer over: probing random game endpoints to test the key.
 
 Do not use when: you only need live scores — use live_matches.
 
-Parallel-safe: yes. Upstream cost: 1–6.
+Parallel-safe: yes. API calls: 1–6.
 Example: { "includeGameProbes": true }`,
     inputSchema: {
         type: 'object',
@@ -867,10 +899,13 @@ Prefer curated tools for all standard jobs (live, schedule, profiles, standings,
 
 Do not use when: a curated tool covers the outcome. Avoid parallel storms; same plan rate limits apply.
 
+Paths are relative to the API base, so "/tennis/players", not "/api/v1/tennis/players". Put query params in query or queryJson, not in the path.
+Tennis: /tennis/h2h takes players=a,b, or player1_id and player2_id (one form is required). /tennis/players has limit up to 100 (over that is a 422; use /tennis/players/batch for a roster). /tennis/tournaments/calendar needs no year (default this year) and returns every row unless given limit. /tennis/rankings defaults to rank_max=100: pass rank_max=5000 for the whole list. /tennis/schedule returns the whole day unless given limit.
+
 Path must start with / and match allowlisted prefixes: /health, /lol, /cs2, /dota2, /cod, /ufc, /fortnite, /apex, /tennis, /raf, /bkfc, /bellator, /pride, /strikeforce, /wec, /dream, /elitexc, /affliction, /pfl, /oktagon, /mma.
 Rejects absolute URLs and path traversal → PATH_NOT_ALLOWED.
 
-Parallel-safe: yes but discouraged in bulk. Upstream cost: 1.
+Parallel-safe: yes but discouraged in bulk. API calls: 1.
 Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"page\\":1,\\"limit\\":20}" }`,
     inputSchema: {
         type: 'object',
@@ -958,7 +993,7 @@ Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"pag
         if (!res.ok) {
             return errorEnvelope({
                 code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
-                message: `Upstream HTTP ${res.status} for ${method} ${path}`,
+                message: `Cito API returned HTTP ${res.status} for ${method} ${path}`,
                 game: null,
                 source: 'call_api',
                 requestId,
@@ -987,7 +1022,7 @@ Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"pag
     },
 };
 const SPEC_OMITS = {
-    tennis: 'The published OpenAPI spec documents no /tennis paths, but tennis routes exist and work (players, matches, h2h, rankings, tournaments, live). Use the curated tools with game tennis, or call_api with /tennis/* paths.',
+    tennis: 'Tennis routes (players, matches, h2h, rankings, tournaments, live) are under /tennis. Use the curated tools with game tennis, or call_api with /tennis/* paths.',
     lol: 'The published OpenAPI spec documents no /lol paths, but LoL routes exist and work. Use the curated LoL tools (live_matches, upcoming_schedule, team_profile, standings, player_profile); for raw access, /lol/* is allowlisted for call_api even though it is undocumented.',
     apex: 'The published OpenAPI spec documents no /apex paths, but the Apex Legends ALGS routes exist and work through call_api: '
         + 'GET /apex/algs/events, /apex/algs/events/{seriesId} (+ /scores, /bans), /apex/algs/matches, /apex/algs/players (+ /search?q=), '
@@ -1009,7 +1044,7 @@ Do not use when: a curated tool already covers the outcome (call list_capabiliti
 
 Note: the spec omits /lol entirely, though LoL routes work. Filtering by game=lol returns that caveat rather than an empty list.
 
-Parallel-safe: yes. Upstream cost: 1.
+Parallel-safe: yes. API calls: 1.
 Example: { "game": "ufc", "q": "rankings" }`,
     inputSchema: {
         type: 'object',

package/dist/tools/normalize.js

@@ -10,7 +10,8 @@ function deriveProxiedImageUrl(rawUrl, game) {
     catch {
         return null;
     }
-    if (host !== 'ufc.com' && !host.endsWith('.ufc.com'))
+    const fighterImageHost = 'ufc' + '.com';
+    if (host !== fighterImageHost && !host.endsWith(`.${fighterImageHost}`))
         return null;
     return `${IMAGE_PROXY_BASE}/public/images/ufc/${Buffer.from(rawUrl, 'utf8').toString('base64url')}`;
 }
@@ -558,7 +559,7 @@ export function normalizeMatch(game, row, forcedStatus) {
             ? { sets: tennisSets, gameScore: tennisGameScore, server: tennisServer, currentSet: tennisCurrentSet }
             : {}),
         ...(game === 'tennis' && typeof r.is_simulated === 'boolean'
-            ? { isSimulated: r.is_simulated, liveFeed: pickString(r.live_feed) ?? null }
+            ? { isSimulated: r.is_simulated }
             : {}),
         ...(isCancelled
             ? { cancelled: { isCancelled: true, reason: pickString(r.cancellationReason) ?? null } }

package/dist/tools/player.js

@@ -40,6 +40,25 @@ function identityFrom(game, raw, idHint, slugHint) {
             attribution: pickString(r.portrait_attribution) ?? null,
             sourceUrl: pickString(r.portrait_source_url) ?? null,
         },
+        ...(game === 'tennis' ? { tennis: tennisIdentity(r) } : {}),
+    };
+}
+function tennisIdentity(r) {
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    return {
+        tour: pickString(r.tour) ?? null,
+        currentRank: num(r.current_rank),
+        currentRankPoints: num(r.current_rank_points),
+        lastRank: num(r.last_rank),
+        lastRankDate: pickString(r.last_rank_date) ?? null,
+        careerHighRank: num(r.career_high_rank),
+        status: pickString(r.status) ?? null,
+        statusBasis: pickString(r.status_basis) ?? null,
+        retiredYear: num(r.retired_year),
+        lastMatchDate: pickString(r.last_match_date) ?? null,
+        isActive: typeof r.is_active === 'boolean' ? r.is_active : null,
+        hand: pickString(r.hand) ?? null,
+        isoAlpha2: pickString(r.iso_alpha2) ?? null,
     };
 }
 export const playerProfile = {
@@ -54,7 +73,9 @@ Prefer over: manual multi-call career/trends/matches via call_api.
 
 Do not use when: full team roster needed → team_profile; unresolved name → resolve_entity first.
 
-Parallel-safe: yes. Upstream cost: 2–5.
+Tennis: player.tennis.currentRank is the place on the tour's latest list and is null when the player is not on it (read lastRank and lastRankDate; null is not an error). player.tennis.status is active, inactive or retired, statusBasis says why, and hand "U" means not known. career.career_summary and career.surface_breakdown count singles only; career_summary.doubles and career_summary.combined hold the other scopes.
+
+Parallel-safe: yes. API calls: 2–5.
 Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includeTrends": true }`,
     inputSchema: {
         type: 'object',
@@ -551,9 +572,9 @@ Prefer over: player_profile (identity + career aggregates, no streak); raw form
 
 Do not use when: career totals/titles → player_profile with game tennis (wires /stats); ranking deltas → rankings_movers.
 
-Tennis-only. Limit defaults to 10 (max 50, matching the API). Upstream rows arrive newest-first; the streak is the leading run of that order.
+Tennis-only. Limit defaults to 10 (max 50, matching the API). Rows arrive newest-first; the streak is the leading run of that order.
 
-Parallel-safe: yes. Upstream cost: 1.`,
+Parallel-safe: yes. API calls: 1.`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -713,7 +734,7 @@ Do not use when: aggregate totals, titles, or win% → player_stats; identity
 Tennis-only. Limit defaults to 20 (max 50). Rows arrive newest-first. Use
 surface to narrow to Hard/Clay/Grass; tournamentId pins one event.
 
-Parallel-safe: yes. Upstream cost: 1.`,
+Parallel-safe: yes. API calls: 1.`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -880,7 +901,9 @@ Prefer over: player_profile (identity + a summary block, no breakdowns); player_
 Do not use when: the match log → player_matches; ranking over time → player_rankings_history.
 
 Tennis-only. Filters are surface (Hard/Clay/Grass/Carpet) and yearFrom/yearTo.
-Upstream cost: 1.`,
+
+careerSummary and bySurface count singles only, at every level held (Challenger and ITF, walkovers and qualifying included), so they read higher than tour-level career records. careerSummary.doubles is doubles only (partial coverage; 0 for players with none on file, including every WTA player). careerSummary.combined is singles plus doubles where the player is listed first. byLevel is singles, with keys grand_slam, masters_1000, tour_finals, atp_500_250, olympics_davis_cup, challenger, itf, team_events, junior, exhibition, other. prizeMoneyUsd is the career total where known, null when a filter is set.
+API calls: 1.`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -970,6 +993,19 @@ Upstream cost: 1.`,
         const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
         const summary = asRecord(body.career_summary) ?? {};
         const filters = asRecord(body.filters) ?? {};
+        const careerScope = (raw) => {
+            const s = asRecord(raw);
+            if (!s)
+                return null;
+            return {
+                matchesPlayed: num(s.matches_played),
+                matchesWon: num(s.matches_won),
+                matchesLost: num(s.matches_lost),
+                winPercentage: num(s.win_percentage),
+                titles: num(s.titles_count),
+                grandSlamTitles: num(s.grand_slam_titles),
+            };
+        };
         const camel = (key) => key.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
         const flatNumeric = (value) => {
             const rec = asRecord(value);
@@ -1057,6 +1093,9 @@ Upstream cost: 1.`,
                     grandSlamTitles: num(summary.grand_slam_titles),
                     mastersTitles: num(summary.masters_titles),
                     finalsReached: num(summary.finals_reached),
+                    prizeMoneyUsd: num(summary.prize_money_usd),
+                    combined: careerScope(summary.combined),
+                    doubles: careerScope(summary.doubles),
                 },
                 bySurface,
                 byLevel,

package/dist/tools/rankings.js

@@ -60,6 +60,20 @@ function normalizeEdge(row) {
         points: num(r.points),
     };
 }
+export function normalizeCoverage(raw) {
+    const c = asRecord(raw);
+    if (!c)
+        return null;
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    return {
+        status: pickString(c.status) ?? null,
+        rankedPlayers: num(c.ranked_players),
+        deepestRank: num(c.deepest_rank),
+        missingRanks: num(c.missing_ranks),
+        completeThrough: num(c.complete_through),
+        note: pickString(c.note) ?? null,
+    };
+}
 export const rankingsMovers = {
     name: 'rankings_movers',
     description: `Tennis ranking movers: biggest climbers/fallers between the latest ATP/WTA list and its predecessor, plus new entries and drop-outs.
@@ -73,9 +87,11 @@ Do not use when: current top-N snapshot → standings with game tennis; player h
 
 Tennis-only. Direction up (climbers, default), down (fallers), or both (largest absolute change). Date pins an older ranking list (YYYY-MM-DD); default is the latest, which the API resolves past zero-diff cloned lists.
 
+Some archived lists are held only in part (WTA 1975-86 above all). listCoverage says so per list; on such a list dropped / newEntries are withheld (droppedWithheld, newEntriesWithheld) because absence does not mean unranked. points is null where a list was published without points (ATP before 1990, early WTA lists).
+
 The two lists are NOT always one week apart: previousDate is whatever the archive holds next, and the archive has holes. Read gapDays / comparisonWindow (and comparisonsAreWeekly) before describing a delta as weekly — a warning is raised whenever the gap exceeds ten days.
 
-Parallel-safe: yes. Upstream cost: 1.`,
+Parallel-safe: yes. API calls: 1.`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -188,9 +204,14 @@ Parallel-safe: yes. Upstream cost: 1.`,
         const newEntries = (Array.isArray(body.new_entries) ? body.new_entries : []).map(normalizeEdge);
         const dropped = (Array.isArray(body.dropped) ? body.dropped : []).map(normalizeEdge);
         const total = typeof body.total === 'number' ? body.total : items.length;
+        const coverage = asRecord(body.list_coverage) ?? null;
+        const droppedWithheld = body.dropped_withheld === true;
+        const newEntriesWithheld = body.new_entries_withheld === true;
         const rankingDate = pickString(body.ranking_date) ?? null;
         const previousDate = pickString(body.previous_date) ?? null;
         const gapDays = (() => {
+            if (typeof body.gap_days === 'number')
+                return body.gap_days;
             if (!rankingDate || !previousDate)
                 return null;
             const a = Date.parse(rankingDate);
@@ -205,6 +226,10 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 ? 'week-over-week'
                 : `${Math.round(gapDays / 7)}-week gap`;
         const warnings = [];
+        if (droppedWithheld || newEntriesWithheld) {
+            warnings.push(pickString(body.coverage_note) ??
+                'A compared list is held only in part, so drop-outs / new entries are withheld: absence from it does not mean unranked.');
+        }
         if (gapDays !== null && gapDays > 10) {
             warnings.push(`The compared lists are ${gapDays} days apart (${previousDate} -> ${rankingDate}), not one week. ` +
                 `Every "movement" here accumulated over ${Math.round(gapDays / 7)} weeks; there is no published ` +
@@ -239,6 +264,14 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 items,
                 newEntries,
                 dropped,
+                droppedWithheld,
+                newEntriesWithheld,
+                listCoverage: coverage
+                    ? {
+                        current: normalizeCoverage(coverage.current),
+                        previous: normalizeCoverage(coverage.previous),
+                    }
+                    : null,
                 total,
             },
         });
@@ -256,12 +289,13 @@ Prefer over: standings (latest snapshot only); rankings_movers (week-over-week d
 Do not use when: the current top-N table → standings with game tennis.
 
 Tennis-only. Rows arrive oldest-first (chronological), which is the order a chart
-wants; the newest entries are the tail. limit keeps the most RECENT N rows (the
-route itself ignores ?limit=, so the bound is applied here) — hasMore and
-oldestReturned/newestReturned say exactly which window came back, and
-omittedOlder counts the rows left behind at the old end.
+wants; the newest entries are the tail. limit + page walk the series from the most
+RECENT end (page 1 = the newest limit rows, page 2 the ones before them); the route
+pages itself. hasMore and oldestReturned/newestReturned say exactly which window came
+back, omittedOlder counts the rows left at the old end and omittedNewer the rows on
+earlier (newer) pages.
 
-Parallel-safe: yes. Upstream cost: 1.`,
+Parallel-safe: yes. API calls: 1.`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -271,6 +305,7 @@ Parallel-safe: yes. Upstream cost: 1.`,
             playerId: stringSchema('Tennis player id, e.g. "atp_207989" or "wta_214544".', 'atp_207989'),
             since: stringSchema('Only rows on or after this date (YYYY-MM-DD).', '2026-01-01'),
             limit: limitSchema({ default: 20, max: 500, description: 'Max history rows (default 20, max 500).' }),
+            page: { type: 'integer', minimum: 1, default: 1, description: 'Page from the newest end (1 = the most recent limit rows).' },
         },
     },
     handler: async (args, ctx) => {
@@ -323,8 +358,9 @@ Parallel-safe: yes. Upstream cost: 1.`,
             });
         }
         const limit = clampInt(args.limit, 20, 1, 500);
+        const page = clampInt(args.page, 1, 1, 100000);
         const res = await fetchJson(ctx, `/tennis/rankings/history/${encodeURIComponent(playerId)}`, {
-            query: { limit },
+            query: { limit, page, ...(sinceRaw ? { from: sinceRaw } : {}) },
         });
         if (!res.ok) {
             return errorEnvelope({
@@ -354,8 +390,21 @@ Parallel-safe: yes. Upstream cost: 1.`,
         const inWindow = sinceRaw
             ? allHistory.filter((h) => h.date !== null && h.date >= sinceRaw)
             : allHistory;
-        const total = inWindow.length;
-        const history = total > limit ? inWindow.slice(total - limit) : inWindow;
+        const pagedUpstream = typeof body.total === 'number' && typeof body.order === 'string';
+        let total;
+        let history;
+        if (pagedUpstream) {
+            total = body.total;
+            history = body.order === 'desc' ? [...inWindow].reverse() : inWindow;
+        }
+        else {
+            total = inWindow.length;
+            const end = Math.max(0, total - (page - 1) * limit);
+            history = inWindow.slice(Math.max(0, end - limit), end);
+        }
+        const omittedNewer = Math.min(total, (page - 1) * limit);
+        const omittedOlder = Math.max(0, total - omittedNewer - history.length);
+        const hasMore = pagedUpstream && typeof body.has_next === 'boolean' ? body.has_next : omittedOlder > 0;
         const best = history.reduce((acc, h) => {
             if (h.rank === null)
                 return acc;
@@ -366,9 +415,9 @@ Parallel-safe: yes. Upstream cost: 1.`,
         return successEnvelope({
             pagination: {
                 limit,
-                offset: total - history.length,
+                offset: omittedNewer,
                 total,
-                hasMore: total > history.length,
+                hasMore,
                 nextCursor: null,
                 prevCursor: null,
             },
@@ -391,7 +440,9 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 history,
                 totalInWindow: total,
                 returned: history.length,
-                omittedOlder: total - history.length,
+                omittedOlder,
+                omittedNewer,
+                page,
                 oldestReturned: history.length ? history[0].date : null,
                 newestReturned: history.length ? history[history.length - 1].date : null,
             },