cito-mcp 0.4.0 → 0.4.2

package/dist/tools/rankings.js

@@ -82,6 +82,8 @@ 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.
 
+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.`,
     inputSchema: {
         type: 'object',
@@ -195,6 +197,39 @@ 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;
+        /**
+         * How far apart the two lists actually are.
+         *
+         * `previous_date` is simply the next list the archive holds — it is NOT
+         * guaranteed to be last week. On 2026-09-12 it was 2026-06-08 against a
+         * current 2026-08-31: an 84-day gap, because the weekly archive ends
+         * 2026-06-08 and the only snapshots after it are the current ESPN-sourced
+         * pair. Calling that "week-over-week movers" told every caller that a
+         * three-month climb was a one-week climb. The interval is measured and
+         * reported instead of assumed.
+         */
+        const rankingDate = pickString(body.ranking_date) ?? null;
+        const previousDate = pickString(body.previous_date) ?? null;
+        const gapDays = (() => {
+            if (!rankingDate || !previousDate)
+                return null;
+            const a = Date.parse(rankingDate);
+            const b = Date.parse(previousDate);
+            if (!Number.isFinite(a) || !Number.isFinite(b))
+                return null;
+            return Math.round((a - b) / 86_400_000);
+        })();
+        const comparisonWindow = gapDays === null
+            ? null
+            : gapDays <= 8
+                ? 'week-over-week'
+                : `${Math.round(gapDays / 7)}-week gap`;
+        const warnings = [];
+        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 ` +
+                `ranking snapshot strictly between those two dates. Treat the deltas as period-over-period, not weekly.`);
+        }
         return successEnvelope({
             pagination: {
                 limit,
@@ -210,13 +245,19 @@ Parallel-safe: yes. Upstream cost: 1.`,
             tookMs: Date.now() - started,
             upstreamCalls: 1,
             rateLimit: res.headers,
+            warnings: warnings.length ? warnings : undefined,
             data: {
                 title: `${tourParse.tour} ranking movers (${dirParse.direction})`,
                 tour: tourParse.tour,
                 direction: dirParse.direction,
                 within,
-                rankingDate: pickString(body.ranking_date) ?? null,
-                previousDate: pickString(body.previous_date) ?? null,
+                rankingDate,
+                previousDate,
+                /** Real interval between the two lists; null when only one list exists. */
+                gapDays,
+                /** 'week-over-week' only when the gap really is about a week. */
+                comparisonWindow,
+                comparisonsAreWeekly: gapDays !== null && gapDays <= 8,
                 items,
                 newEntries,
                 dropped,
@@ -237,8 +278,10 @@ 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. Use 'since' or 'limit' to bound the
-series — the full career can be hundreds of rows.
+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.
 
 Parallel-safe: yes. Upstream cost: 1.`,
     inputSchema: {
@@ -322,7 +365,7 @@ Parallel-safe: yes. Upstream cost: 1.`,
         const root = asRecord(res.data) ?? {};
         const body = asRecord(root.data) ?? root;
         const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
-        let history = (Array.isArray(body.history) ? body.history : []).map((row) => {
+        const allHistory = (Array.isArray(body.history) ? body.history : []).map((row) => {
             const r = asRecord(row) ?? {};
             return {
                 date: pickString(r.date) ?? null,
@@ -330,8 +373,23 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 points: num(r.points),
             };
         });
-        if (sinceRaw)
-            history = history.filter((h) => h.date !== null && h.date >= sinceRaw);
+        const inWindow = sinceRaw
+            ? allHistory.filter((h) => h.date !== null && h.date >= sinceRaw)
+            : allHistory;
+        /**
+         * The route IGNORES ?limit= — verified: `?limit=4` returned all 342 rows of
+         * Alcaraz's career with total:342 and hasMore:false. Asking for 4 and
+         * receiving 342 is not a bound, it is a payload the caller cannot control,
+         * so the bound is applied here.
+         *
+         * Rows arrive oldest-first because that is the order a chart wants. limit
+         * therefore keeps the most RECENT N (the tail), matching every other tool
+         * in this server: `player_matches` returns the newest rows and reports
+         * hasMore when older ones exist. The older end is what gets dropped, and
+         * oldestReturned/newestReturned say exactly which window came back.
+         */
+        const total = inWindow.length;
+        const history = total > limit ? inWindow.slice(total - limit) : inWindow;
         // Best rank actually present in the returned window, so a caller can label a
         // chart without recomputing. Null when the window is empty.
         const best = history.reduce((acc, h) => {
@@ -344,9 +402,9 @@ Parallel-safe: yes. Upstream cost: 1.`,
         return successEnvelope({
             pagination: {
                 limit,
-                offset: 0,
-                total: history.length,
-                hasMore: false,
+                offset: total - history.length,
+                total,
+                hasMore: total > history.length,
                 nextCursor: null,
                 prevCursor: null,
             },
@@ -367,6 +425,13 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 since: sinceRaw || null,
                 bestRankInWindow: best,
                 history,
+                // The bound is applied locally because the route ignores ?limit=; state
+                // it so a caller does not read a short series as a short career.
+                totalInWindow: total,
+                returned: history.length,
+                omittedOlder: total - history.length,
+                oldestReturned: history.length ? history[0].date : null,
+                newestReturned: history.length ? history[history.length - 1].date : null,
             },
         });
     },

package/dist/tools/resolve.js

@@ -5,6 +5,13 @@ import { clampInt, decodeCursor, encodeCursor, extractRows, fetchJson, gameNotIn
 import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT, errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
 import { editionYear, entityRef, rankScore } from './normalize.js';
 import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, PRIMARY_GAMES, stringSchema, } from './types.js';
+/**
+ * Minimum relevance a search result must reach to be returned when a query was
+ * given. rankScore returns 0 for "no part of the query appears anywhere in this
+ * row", so 1 means "must have matched something". See the floor note in
+ * searchEntities for the live evidence.
+ */
+export const RELEVANCE_FLOOR = 1;
 /**
  * Ranking order whose tiebreak never depends on the order upstream happened to
  * return rows in.
@@ -37,7 +44,11 @@ const ORG_ALIASES = {
     skt1: 't1',
 };
 function pushCandidates(out, game, type, rows, q, limit) {
+    // Position within the upstream's own result list. That ordering is a real
+    // signal we otherwise throw away.
+    let index = -1;
     for (const row of rows) {
+        index += 1;
         const ref = entityRef(row, type, game);
         const r = asRecord(row) ?? {};
         const nickname = pickString(r.nickname, asRecord(r.profile)?.nickname, ref.meta?.nickname);
@@ -49,9 +60,26 @@ function pushCandidates(out, game, type, rows, q, limit) {
         if (score > 0 && Number.isFinite(currentRank) && currentRank > 0) {
             score += currentRank <= 100 ? 8 : currentRank <= 1000 ? 4 : 2;
         }
-        // Prefer positive fuzzy hits; keep weak API hits at floor 1 so real search results are not wiped.
-        if (q && score <= 0) {
-            // still allow through at floor so dedicated search endpoints aren't empty on odd nicknames
+        /**
+         * The upstream's FIRST row is allowed to match on something we cannot see.
+         *
+         * /tennis/players/search is a dedicated name search and it knows nicknames
+         * and aliases that the payload does not carry: `q=Nole` returns Novak
+         * Djokovic first, and nothing in the string "Novak Djokovic" resembles
+         * "nole", so rankScore scores it 0. The old code floored every unmatched row
+         * to 1 and then sorted, which let a mere substring collision win —
+         * `resolve_entity { q: "Nole" }` answered **M Canoles** (a WTA player whose
+         * name contains "noles") and search_entities dropped Djokovic entirely.
+         *
+         * So when our own scorer finds no name match at all but the dedicated search
+         * put the row first, the row is kept as the alias answer and labelled. Only
+         * the first row, and only when our scorer is silent, so this can never
+         * outrank a query that genuinely matches a name.
+         */
+        let matchedBy;
+        if (q && score <= 0 && index === 0) {
+            score = 95;
+            matchedBy = 'upstream-first';
         }
         const secondary = {};
         for (const key of ['lolPlayerId', 'codPlayerId', 'matchId', 'boutId', 'tournamentId', 'eventId']) {
@@ -61,6 +89,8 @@ function pushCandidates(out, game, type, rows, q, limit) {
         }
         if (nickname)
             secondary.nickname = nickname;
+        if (matchedBy)
+            secondary.matchedBy = matchedBy;
         out.push({
             game,
             type: pickString(r.entity_type, r.type, type) ?? type,
@@ -840,11 +870,69 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             seen.add(key);
             return true;
         });
+        /**
+         * Relevance floor.
+         *
+         * The upstream player/tournament search is a substring match with no floor
+         * of its own: `q=Sinner` returns ten rows, of which only "Jannik Sinner" and
+         * "Martin Sinner" have anything to do with the query. The tool scored them
+         * all and then SORTED rather than filtered, so "A Winner", "J Skinner",
+         * "E Skinner", "C Sinkler", "Dr Sinnett", "H C Skinner", "Mrs Skinner" and
+         * "J J Sinnott" came back as equals — an agent asking for one player got
+         * eight strangers to ignore, and a caller paging the results paid for them.
+         *
+         * rankScore already separates them cleanly (Jannik 100, Martin 48, every
+         * other row 0), so the floor is simply "must have matched something at all".
+         * It is applied only when a query was given: with no q this tool is a browse
+         * list, and a floor there would delete the catalogue.
+         */
+        const scoreOf = (it) => typeof it.meta?.score === 'number'
+            ? it.meta.score
+            : rankScore(q, it.name, it.id, it.slug, it.meta?.nickname);
+        const upstreamTotal = total;
+        let droppedBelowFloor = [];
+        /**
+         * The first row the upstream returned is exempt from the floor.
+         *
+         * The upstream's dedicated search knows aliases the payload does not carry:
+         * `q=Nole` returns Novak Djokovic first, and rankScore cannot see why, so a
+         * pure floor would delete the correct answer and keep substring collisions
+         * instead. Exactly one row is protected, and only when a query was given, so
+         * the floor still removes all the padding it was added for.
+         */
+        const protectedRow = q && items.length > 0 ? items[0] : null;
+        const protectedKey = protectedRow ? `${protectedRow.game}:${protectedRow.type}:${protectedRow.id}` : null;
+        if (q) {
+            // Publish the score on every row, not just the ones the scored branch
+            // produced, so the floor is visible rather than mysterious.
+            items = items.map((it) => {
+                const key = `${it.game}:${it.type}:${it.id}`;
+                const isProtected = protectedKey !== null && key === protectedKey;
+                const raw = scoreOf(it);
+                return {
+                    ...it,
+                    meta: {
+                        ...(it.meta ?? {}),
+                        score: raw,
+                        ...(isProtected && raw < RELEVANCE_FLOOR ? { matchedBy: 'upstream-first' } : {}),
+                    },
+                };
+            });
+            const keep = (it) => it.meta?.score >= RELEVANCE_FLOOR || it.meta?.matchedBy === 'upstream-first';
+            droppedBelowFloor = items
+                .filter((it) => !keep(it))
+                .map((it) => ({ id: it.id, name: it.name, score: it.meta?.score }));
+            if (droppedBelowFloor.length)
+                items = items.filter(keep);
+        }
+        // An explicit (possibly rank-0) alias match beats a higher-scoring substring
+        // collision: the upstream's own top hit is the answer to a query we cannot
+        // score. This is what makes "Nole" resolve to Djokovic instead of M Canoles.
         if (q && !preserveUpstreamOrder) {
             items.sort((a, b) => {
-                const sa = typeof a.meta?.score === 'number' ? a.meta.score : rankScore(q, a.name, a.id, a.slug, a.meta?.nickname);
-                const sb = typeof b.meta?.score === 'number' ? b.meta.score : rankScore(q, b.name, b.id, b.slug, b.meta?.nickname);
-                return sb - sa || a.name.localeCompare(b.name);
+                const am = a.meta?.matchedBy === 'upstream-first' ? 1 : 0;
+                const bm = b.meta?.matchedBy === 'upstream-first' ? 1 : 0;
+                return bm - am || scoreOf(b) - scoreOf(a) || a.name.localeCompare(b.name);
             });
         }
         // pagination over ranked result set
@@ -852,21 +940,46 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
         const hasMore = upstreamPaged
             ? (total != null ? offset + pageItems.length < total : pageItems.length >= limit)
             : offset + pageItems.length < items.length;
+        const floorWarnings = [];
+        if (droppedBelowFloor.length) {
+            const sample = droppedBelowFloor
+                .slice(0, 5)
+                .map((d) => `${d.name} (${d.id})`)
+                .join(', ');
+            floorWarnings.push(`Dropped ${droppedBelowFloor.length} result(s) that do not match "${q}" at all — the upstream search is a ` +
+                `substring match with no relevance floor, so it pads every page: ${sample}. ` +
+                `If one of these is what you wanted, query it by name or id directly.`);
+        }
         return successEnvelope({
             source: 'search_entities',
             game,
             requestId,
             tookMs: Date.now() - started,
             upstreamCalls,
+            warnings: floorWarnings.length ? floorWarnings : undefined,
             pagination: {
                 limit,
                 offset,
-                total: total ?? (q ? items.length : null),
+                total: q ? items.length : (total ?? null),
                 hasMore,
                 nextCursor: hasMore ? encodeCursor({ offset: offset + limit }) : null,
                 prevCursor: offset > 0 ? encodeCursor({ offset: Math.max(0, offset - limit) }) : null,
             },
-            data: { items: pageItems },
+            data: {
+                items: pageItems,
+                ...(q
+                    ? {
+                        relevance: {
+                            query: q,
+                            floor: RELEVANCE_FLOOR,
+                            matched: items.length,
+                            droppedBelowFloor: droppedBelowFloor.length,
+                            dropped: droppedBelowFloor.slice(0, 25),
+                            upstreamTotal: upstreamTotal ?? null,
+                        },
+                    }
+                    : {}),
+            },
         });
     },
 };

package/dist/tools/schedule.js

@@ -33,12 +33,26 @@ function normalizeScheduled(row) {
         round: pickString(r.round) ?? null,
         roundName: pickString(r.round_name) ?? null,
         startsAt: pickString(r.starts_at, r.commence_time, r.match_date) ?? null,
+        /**
+         * Historical days report every match at T00:00:00 with
+         * `start_time_known: false` — the date is real, the clock is a placeholder.
+         * Emitting the midnight without this flag invites a caller to render "12:00
+         * AM" for a semi-final that finished at 3pm. Null when the route does not
+         * state it (the completed half does not).
+         */
+        startTimeKnown: typeof r.start_time_known === 'boolean' ? r.start_time_known : null,
         status: pickString(r.status, r.outcome) ?? null,
         player1: { id: pickString(p1.id, p1.player_id) ?? null, name: pickString(p1.name) ?? null },
         player2: { id: pickString(p2.id, p2.player_id) ?? null, name: pickString(p2.name) ?? null },
         score: pickString(r.score, r.score_raw) ?? null,
     };
 }
+/** A row is "played" when the feed says so, in either spelling it uses. */
+function isPlayed(row) {
+    const r = asRecord(row) ?? {};
+    const s = (pickString(r.status, r.outcome) ?? '').toLowerCase();
+    return /complete|finished|ended|final|closed|done|official|retire|walkover|default/.test(s);
+}
 export const tennisSchedule = {
     name: 'tennis_schedule',
     description: `One day of tennis: the day's schedule and/or the matches completed that day, across ATP and WTA.
@@ -54,6 +68,12 @@ Tennis-only. 'date' defaults to today (UTC) and MUST be YYYY-MM-DD. Choose with
 'include': both (default), scheduled, or completed. Both halves are fetched in
 parallel, so either can fail on its own without losing the other.
 
+'limit' bounds EACH half (the completed route ignores ?limit= upstream, so the
+bound is applied here); scheduledCount/completedCount report how many rows the
+day held and *Returned how many came back. The two halves overlap: the day's
+list includes matches already played, so the same matchId can appear in both —
+see the overlap block before de-duplicating or counting.
+
 Parallel-safe: yes. Upstream cost: 1 or 2.`,
     inputSchema: {
         type: 'object',
@@ -63,7 +83,7 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
             game: gameSchema({ allowAll: false, required: true }),
             date: stringSchema('Day to fetch, YYYY-MM-DD. Defaults to today (UTC).', '2026-09-12'),
             include: stringSchema('both (default) | scheduled | completed.', 'both'),
-            limit: limitSchema({ default: 20, max: 50, description: 'Rows per half (default 20, max 50).' }),
+            limit: limitSchema({ default: 20, max: 50, description: 'Rows per half, applied here (default 20, max 50). scheduledCount/completedCount still report the full day.' }),
         },
     },
     handler: async (args, ctx) => {
@@ -121,27 +141,44 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
         const limit = clampInt(args.limit, 20, 1, 50);
         const wantScheduled = includeRaw === 'both' || includeRaw === 'scheduled';
         const wantCompleted = includeRaw === 'both' || includeRaw === 'completed';
+        /**
+         * Ask for the whole day, then bound locally.
+         *
+         * /tennis/schedule honours ?limit= but /tennis/matches/completed ignores it,
+         * so passing `limit` upstream made `scheduledCount` mean "rows this call
+         * asked for" on one half and "rows the day held" on the other. Both halves
+         * are now fetched at the API's own page ceiling and sliced here, which makes
+         * scheduledCount/completedCount a fact about the day and *Returned a fact
+         * about the response.
+         */
+        const upstreamPage = 200;
         const settled = await Promise.allSettled([
             wantScheduled
-                ? fetchJson(ctx, '/tennis/schedule', { query: { date, limit } })
+                ? fetchJson(ctx, '/tennis/schedule', { query: { date, limit: upstreamPage } })
                 : Promise.resolve(null),
             wantCompleted
-                ? fetchJson(ctx, '/tennis/matches/completed', { query: { date, limit } })
+                ? fetchJson(ctx, '/tennis/matches/completed', { query: { date, limit: upstreamPage } })
                 : Promise.resolve(null),
         ]);
         const rejected = [];
         const rows = (value) => {
             const root = asRecord(value);
             const body = asRecord(root?.data) ?? root ?? {};
-            return Array.isArray(body.items) ? body.items : [];
+            const items = Array.isArray(body.items) ? body.items : [];
+            return { items, total: typeof body.total === 'number' ? body.total : null };
         };
         let scheduled = [];
         let completed = [];
+        let scheduledTotal = null;
+        let completedTotal = null;
         const [schedRes, compRes] = settled;
         if (schedRes.status === 'fulfilled' && schedRes.value) {
             const v = schedRes.value;
-            if (v.ok)
-                scheduled = rows(v.data);
+            if (v.ok) {
+                const parsed = rows(v.data);
+                scheduled = parsed.items;
+                scheduledTotal = parsed.total;
+            }
             else
                 rejected.push({
                     section: 'schedule',
@@ -159,8 +196,11 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
         }
         if (compRes.status === 'fulfilled' && compRes.value) {
             const v = compRes.value;
-            if (v.ok)
-                completed = rows(v.data);
+            if (v.ok) {
+                const parsed = rows(v.data);
+                completed = parsed.items;
+                completedTotal = parsed.total;
+            }
             else
                 rejected.push({
                     section: 'completed',
@@ -190,15 +230,64 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
                 recover: ['Check the date is a real calendar day', 'Retry, or widen include to both'],
             });
         }
+        /**
+         * /tennis/matches/completed IGNORES ?limit= — verified: `limit=3` returned
+         * all 13 rows of the day with page_size still 50. /tennis/schedule does
+         * honour it, but both halves are bounded here so one call site cannot drift
+         * from the other and `completedCount` stops being a number the caller asked
+         * to be smaller.
+         */
+        const scheduledWindow = scheduled.slice(0, limit);
+        const completedWindow = completed.slice(0, limit);
+        /**
+         * /tennis/schedule is the DAY's list, not an "upcoming" list: it carries
+         * matches that have already finished, with status COMPLETED. So the two
+         * halves of this response legitimately overlap, and the old key name
+         * ("scheduled") plus a status of COMPLETED inside it read as a
+         * contradiction. The overlap is now counted and the statuses summarised, so
+         * a caller can join or de-duplicate deliberately instead of discovering it.
+         */
+        const completedBySchedule = scheduled.filter(isPlayed);
+        const completedIds = new Set(completed
+            .map((row) => pickString(asRecord(row)?.id, asRecord(row)?.match_id))
+            .filter((id) => Boolean(id)));
+        const overlapIds = [
+            ...new Set(completedBySchedule
+                .map((row) => pickString(asRecord(row)?.id, asRecord(row)?.match_id))
+                .filter((id) => typeof id === 'string' && completedIds.has(id))),
+        ];
+        const statusCounts = {};
+        for (const row of scheduled) {
+            const key = (pickString(asRecord(row)?.status, asRecord(row)?.outcome) ?? 'UNKNOWN').toUpperCase();
+            statusCounts[key] = (statusCounts[key] ?? 0) + 1;
+        }
+        const anyUnknownClock = scheduled.some((row) => asRecord(row)?.start_time_known === false);
         const data = {
             title: `Tennis — ${date}`,
             date,
             include: includeRaw,
-            scheduled: scheduled.map(normalizeScheduled),
-            scheduledCount: scheduled.length,
-            completed: completed.map(normalizeScheduled),
-            completedCount: completed.length,
+            // Everything the day's list returned, then the bounded window. Both are
+            // present so `scheduledCount` never silently means two different things.
+            scheduled: scheduledWindow.map(normalizeScheduled),
+            scheduledCount: scheduledTotal ?? scheduled.length,
+            scheduledReturned: scheduledWindow.length,
+            completed: completedWindow.map(normalizeScheduled),
+            completedCount: completedTotal ?? completed.length,
+            completedReturned: completedWindow.length,
+            statusBreakdown: statusCounts,
+            overlap: {
+                count: overlapIds.length,
+                matchIds: overlapIds.slice(0, 50),
+                note: overlapIds.length
+                    ? 'These matches appear in BOTH halves: /tennis/schedule is the day\'s full list (played matches included) and /tennis/matches/completed is the played subset. Join on matchId and de-duplicate.'
+                    : 'The two halves returned no shared matchId on this date.',
+            },
             timezoneNote: 'The API groups by UTC date. For a local "today", pass the date explicitly rather than relying on the default.',
+            ...(anyUnknownClock
+                ? {
+                    startTimeNote: 'Rows with startTimeKnown:false carry a date-only startsAt (T00:00:00) — the clock is a placeholder, not a midnight start. The completed half does not report the flag at all.',
+                }
+                : {}),
         };
         const upstreamCalls = (wantScheduled ? 1 : 0) + (wantCompleted ? 1 : 0);
         // A half that failed is reported alongside the half that worked rather than

package/dist/tools/standings.js

@@ -126,6 +126,11 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             stage: stringSchema('Stage key (COD / LoL).'),
             division: stringSchema('UFC division key.'),
             limit: limitSchema({ default: 50, max: 100 }),
+            page: {
+                type: 'integer',
+                minimum: 1,
+                description: 'Tennis only: page over the full published ranking list. With limit=5 the ATP list is 30 pages (150 ranked players); the response reports total/rankedPlayers/totalPages/hasMore.',
+            },
             cursor: stringSchema('Opaque cursor from pagination.nextCursor. UFC world scope spans every division; page with it rather than raising limit.'),
         },
     },
@@ -155,6 +160,10 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
         const season = typeof args.season === 'string' ? args.season : undefined;
         const stage = typeof args.stage === 'string' ? args.stage : undefined;
         const division = typeof args.division === 'string' ? args.division : undefined;
+        // Tennis rankings are pageable now that the API reports the real list size.
+        const tennisPage = typeof args.page === 'number' && Number.isFinite(args.page) && args.page >= 1
+            ? Math.trunc(args.page)
+            : 1;
         let path = '';
         let query = {};
         let title = `${game} standings`;
@@ -247,7 +256,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             // rank_movement/previous_rank on every row. Pass tour via division.
             const tour = String(division ?? 'ATP').toUpperCase() === 'WTA' ? 'WTA' : 'ATP';
             path = '/tennis/standings';
-            query = { tour, top_n: Math.min(limit, 100) };
+            query = { tour, top_n: Math.min(limit, 100), page: tennisPage };
             effectiveScope = 'world';
             title = `${tour} singles rankings`;
         }
@@ -355,16 +364,36 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                 return rest;
             });
         }
+        const obj = asRecord(res.data);
+        const upstreamMeta = asRecord(obj?.meta) ?? {};
+        /**
+         * `total` is the size of the published table, NOT the size of this page.
+         *
+         * This read `total: allRows.length` — the rows that happened to arrive — so
+         * a tennis table of 150 ranked players reported total:5, hasMore:false and
+         * looked complete and unpaginated. The API now returns the real figure
+         * (total/ranked_players/total_pages/has_next); this prefers it and only
+         * falls back to the received count when the route does not state one.
+         *
+         * These are read BEFORE the pagination block, because that block had the
+         * identical bug: it published total: allRows.length too, so fixing only the
+         * data block left pagination.total disagreeing with data.total on the same
+         * response. Two counts, one response, only one of them true.
+         */
+        const upstreamTotal = typeof obj?.total === 'number' ? obj.total : null;
+        const rankedPlayers = typeof obj?.ranked_players === 'number' ? obj.ranked_players : null;
+        const totalPages = typeof obj?.total_pages === 'number' ? obj.total_pages : null;
+        const upstreamHasNext = typeof obj?.has_next === 'boolean' ? obj.has_next : null;
+        const effectiveTotal = upstreamTotal ?? allRows.length;
+        const effectiveHasMore = upstreamHasNext ?? offset + rows.length < effectiveTotal;
         const standingsPagination = {
             limit,
             offset,
-            total: allRows.length,
-            hasMore: offset + rows.length < allRows.length,
-            nextCursor: offset + rows.length < allRows.length ? String(offset + rows.length) : null,
+            total: effectiveTotal,
+            hasMore: effectiveHasMore,
+            nextCursor: effectiveHasMore ? String(offset + rows.length) : null,
             prevCursor: offset > 0 ? String(Math.max(0, offset - limit)) : null,
         };
-        const obj = asRecord(res.data);
-        const upstreamMeta = asRecord(obj?.meta) ?? {};
         const dataQuality = asRecord(upstreamMeta.dataQuality) ?? {};
         const warnings = [];
         const pushWarning = (value) => {
@@ -405,10 +434,34 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                 season: season ?? null,
                 stage: stage ?? null,
                 rows,
-                total: allRows.length,
-                hasMore: allRows.length > rows.length,
-                updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt) ??
-                    null,
+                total: effectiveTotal,
+                hasMore: effectiveHasMore,
+                ...(game === 'tennis'
+                    ? {
+                        // How deep the published list is, independent of this page.
+                        rankedPlayers: rankedPlayers ?? effectiveTotal,
+                        totalPages,
+                        page: tennisPage,
+                    }
+                    : {}),
+                ...(game === 'tennis'
+                    ? {
+                        /**
+                         * Tennis rankings are a dated weekly SNAPSHOT, and the route names
+                         * the date in `ranking_date`. updatedAt was read only from
+                         * updatedAt/lastUpdated/meta.syncedAt/meta.fetchedAt, none of which
+                         * the tennis route emits, so every tennis table claimed
+                         * updatedAt:null while the very date a caller needs sat in the
+                         * payload — and a consumer showing a stale-looking table had no
+                         * way to find out it was a week old.
+                         */
+                        rankingDate: pickString(obj?.ranking_date) ?? null,
+                        updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt, obj?.ranking_date) ?? null,
+                    }
+                    : {
+                        updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt) ??
+                            null,
+                    }),
                 ...(dataFreshness ? { dataFreshness } : {}),
                 ...(status ? { status } : {}),
                 ...(upstreamMeta.warning || dataQuality.warning