cito-mcp 0.3.21 → 0.4.1

package/dist/tools/player.js

@@ -53,9 +53,16 @@ function identityFrom(game, raw, idHint, slugHint) {
          * own domain, so it works from a browser without hotlink/CORS trouble.
          */
         images: {
-            headshotUrl: pickString(r.headshotUrl, r.headshot) ?? null,
+            // Tennis supplies exactly one likeness, `portrait_url` (a Wikimedia
+            // portrait), and no separate square headshot crop. Before this, the shaper
+            // read only headshotUrl/bodyImageUrl/imageUrl/photoUrl — none of which the
+            // tennis route emits — so every tennis profile shipped four explicit nulls
+            // while a perfectly good photo sat one key away, and builders concluded
+            // tennis had no images at all. The portrait fills the headshot slot too:
+            // a card with the real photo slightly cropped beats a faceless card.
+            headshotUrl: pickString(r.headshotUrl, r.headshot, r.portrait_url) ?? null,
             bodyImageUrl: pickString(r.bodyImageUrl, r.fullBodyImageUrl) ?? null,
-            imageUrl: pickString(r.imageUrl, r.image, r.photoUrl) ?? null,
+            imageUrl: pickString(r.imageUrl, r.image, r.photoUrl, r.portrait_url) ?? null,
             proxiedImageUrl: pickString(r.proxiedImageUrl, r.proxiedHeadshotUrl) ?? null,
         },
     };
@@ -769,4 +776,417 @@ Parallel-safe: yes. Upstream cost: 1.`,
         });
     },
 };
-export const playerTools = [playerProfile, playerForm];
+export const playerMatches = {
+    name: 'player_matches',
+    description: `Tennis player match log: every archived match for one player, newest first, with opponent, tournament, round, surface and score.
+
+When to use:
+- "Show me Shelton's last 20 matches"; full match history; every match at a given tournament; filtering a player's record by surface.
+
+Prefer over: player_form (a W/L summary with a small window and a streak, not the log); call_api for /tennis/players/{id}/matches.
+
+Do not use when: aggregate totals, titles, or win% → player_stats; identity → player_profile; one match's box score → match_details.
+
+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.`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game', 'playerId'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            playerId: stringSchema('Tennis player id, e.g. "atp_210097".', 'atp_210097'),
+            surface: stringSchema('Filter to one surface: Hard, Clay, or Grass.', 'Hard'),
+            tournamentId: stringSchema('Only matches at this tournament edition, e.g. "atp_2026_560".', 'atp_2026_560'),
+            limit: limitSchema({ default: 20, max: 50, description: 'Match rows (default 20, max 50).' }),
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const gameParse = parseGame(args.game, { allowAll: false, required: true });
+        if (gameParse.error || !gameParse.game || !isPrimaryGame(gameParse.game)) {
+            return errorEnvelope({
+                code: gameParse.error?.includes('unsupported') ? 'UNSUPPORTED_GAME' : 'VALIDATION',
+                message: gameParse.error ?? 'game is required',
+                game: null,
+                source: 'player_matches',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        if (game !== 'tennis') {
+            return errorEnvelope({
+                code: 'NOT_IMPLEMENTED',
+                message: `player_matches is tennis-only (game '${game}' has its own match-log shape)`,
+                game,
+                source: 'player_matches',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Use match_summary or call_api for this game', 'Retry with game tennis'],
+            });
+        }
+        const playerId = typeof args.playerId === 'string' ? args.playerId.trim() : '';
+        if (!playerId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'playerId is required',
+                game,
+                source: 'player_matches',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Find an id with search_entities or resolve_entity'],
+            });
+        }
+        const limit = clampInt(args.limit, 20, 1, 50);
+        const surfaceRaw = typeof args.surface === 'string' ? args.surface.trim() : '';
+        const tournamentId = typeof args.tournamentId === 'string' && args.tournamentId.trim()
+            ? args.tournamentId.trim()
+            : '';
+        const res = await fetchJson(ctx, `/tennis/players/${encodeURIComponent(playerId)}/matches`, {
+            query: {
+                limit,
+                ...(surfaceRaw ? { surface: surfaceRaw } : {}),
+                ...(tournamentId ? { tournament_id: tournamentId } : {}),
+            },
+        });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Player match log failed for '${playerId}' (HTTP ${res.status})`,
+                game,
+                source: 'player_matches',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                httpStatus: res.status,
+                rateLimit: res.headers,
+                recover: ['Check the player id with search_entities'],
+            });
+        }
+        const root = asRecord(res.data);
+        const body = asRecord(root?.data) ?? root ?? {};
+        const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+        const allRows = Array.isArray(body.items) ? body.items : [];
+        /**
+         * Derive the player's display name from their own side of any match.
+         *
+         * The match-log payload carries no player_name at all (verified against the
+         * live route: top-level keys are just items/total/page/page_size/has_next/
+         * has_prev/success/total_pages), so the earlier version titled every log
+         * "<id> match log" and reported playerName: null. Each row does carry the
+         * winner and loser objects, so whichever side matches the requested id gives
+         * a real name with no extra upstream call.
+         */
+        let derivedName = null;
+        for (const row of allRows) {
+            const r = asRecord(row) ?? {};
+            const w = asRecord(r.winner) ?? {};
+            const l = asRecord(r.loser) ?? {};
+            if (pickString(r.winner_id, w.id) === playerId) {
+                derivedName = pickString(w.name) ?? null;
+            }
+            else if (pickString(r.loser_id, l.id) === playerId) {
+                derivedName = pickString(l.name) ?? null;
+            }
+            if (derivedName)
+                break;
+        }
+        /**
+         * The route ignores ?limit= (verified: limit=5 returned 20), so the bound is
+         * applied here. total comes from the upstream header so callers still learn
+         * how many matches exist beyond this page.
+         */
+        const total = typeof body.total === 'number' ? body.total : allRows.length;
+        const rows = allRows.slice(0, limit).map((row) => {
+            const r = asRecord(row) ?? {};
+            const winner = asRecord(r.winner) ?? {};
+            const loser = asRecord(r.loser) ?? {};
+            const winnerId = pickString(r.winner_id, winner.id);
+            const lost = winnerId !== null && winnerId !== playerId;
+            // Opponent is whichever side is not this player. When the row's winner
+            // does not match the requested id the player lost, so the opponent is the
+            // winner.
+            const opponent = lost ? winner : loser;
+            return {
+                matchId: pickString(r.id, r.match_id) ?? null,
+                date: pickString(r.match_date, r.date) ?? null,
+                tournamentId: pickString(r.tournament_id) ?? null,
+                tournamentName: pickString(r.tournament_name, r.name) ?? null,
+                level: pickString(r.level) ?? null,
+                category: pickString(r.category) ?? null,
+                surface: pickString(r.surface) ?? null,
+                round: pickString(r.round) ?? null,
+                roundName: pickString(r.round_name) ?? null,
+                bestOf: num(r.best_of),
+                score: pickString(r.score, r.score_raw) ?? null,
+                outcome: pickString(r.outcome, r.status) ?? null,
+                result: lost ? 'L' : 'W',
+                opponent: {
+                    id: pickString(opponent.id) ?? null,
+                    name: pickString(opponent.name) ?? null,
+                    country: pickString(opponent.ioc) ?? null,
+                    rank: num(opponent.rank),
+                    seed: opponent.seed ?? null,
+                },
+            };
+        });
+        return successEnvelope({
+            pagination: {
+                limit,
+                offset: 0,
+                total,
+                hasMore: total > rows.length,
+                nextCursor: null,
+                prevCursor: null,
+            },
+            source: 'player_matches',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+            entities: { games: [game], ids: { playerId } },
+            data: {
+                title: `${derivedName ?? playerId} match log`,
+                playerId,
+                playerName: derivedName,
+                surfaceFilter: surfaceRaw || null,
+                tournamentFilter: tournamentId || null,
+                matches: rows,
+                total,
+                // Named explicitly because the bound is applied locally: the upstream
+                // route returns everything and ignores ?limit=.
+                returned: rows.length,
+            },
+        });
+    },
+};
+export const playerStats = {
+    name: 'player_stats',
+    description: `Tennis player career statistics: W/L totals, win percentage, titles, Grand Slam and Masters titles, plus per-surface and per-level breakdowns. Optional surface/year filters.
+
+When to use:
+- "How many titles does Alcaraz have?"; career win%; Grand Slam title count; record on clay; a season-scoped record.
+
+Prefer over: player_profile (identity + a summary block, no breakdowns); player_matches (individual rows, no aggregates).
+
+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.`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game', 'playerId'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            playerId: stringSchema('Tennis player id, e.g. "atp_207989".', 'atp_207989'),
+            surface: stringSchema('Filter to one surface: Hard, Clay, Grass, or Carpet.', 'Clay'),
+            yearFrom: { type: 'integer', minimum: 1877, maximum: 2100, description: 'Inclusive start year, e.g. 2020.' },
+            yearTo: { type: 'integer', minimum: 1877, maximum: 2100, description: 'Inclusive end year, e.g. 2026.' },
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const gameParse = parseGame(args.game, { allowAll: false, required: true });
+        if (gameParse.error || !gameParse.game || !isPrimaryGame(gameParse.game)) {
+            return errorEnvelope({
+                code: gameParse.error?.includes('unsupported') ? 'UNSUPPORTED_GAME' : 'VALIDATION',
+                message: gameParse.error ?? 'game is required',
+                game: null,
+                source: 'player_stats',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        if (game !== 'tennis') {
+            return errorEnvelope({
+                code: 'NOT_IMPLEMENTED',
+                message: `player_stats is tennis-only (game '${game}' exposes stats elsewhere)`,
+                game,
+                source: 'player_stats',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Use player_profile for this game', 'Retry with game tennis'],
+            });
+        }
+        const playerId = typeof args.playerId === 'string' ? args.playerId.trim() : '';
+        if (!playerId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'playerId is required',
+                game,
+                source: 'player_stats',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Find an id with search_entities or resolve_entity'],
+            });
+        }
+        const surfaceRaw = typeof args.surface === 'string' ? args.surface.trim() : '';
+        const yf = typeof args.yearFrom === 'number' && Number.isFinite(args.yearFrom) ? Math.trunc(args.yearFrom) : null;
+        const yt = typeof args.yearTo === 'number' && Number.isFinite(args.yearTo) ? Math.trunc(args.yearTo) : null;
+        if (yf !== null && yt !== null && yf > yt) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `yearFrom (${yf}) must not be greater than yearTo (${yt})`,
+                game,
+                source: 'player_stats',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const res = await fetchJson(ctx, `/tennis/players/${encodeURIComponent(playerId)}/stats`, {
+            query: {
+                ...(surfaceRaw ? { surface: surfaceRaw } : {}),
+                ...(yf !== null ? { year_from: yf } : {}),
+                ...(yt !== null ? { year_to: yt } : {}),
+            },
+        });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Player stats failed for '${playerId}' (HTTP ${res.status})`,
+                game,
+                source: 'player_stats',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                httpStatus: res.status,
+                rateLimit: res.headers,
+                recover: ['Check the player id with search_entities'],
+            });
+        }
+        const root = asRecord(res.data);
+        const body = asRecord(root?.data) ?? root ?? {};
+        const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+        const summary = asRecord(body.career_summary) ?? {};
+        const filters = asRecord(body.filters) ?? {};
+        /**
+         * Map an arbitrary {label: value} breakdown without assuming the upstream
+         * key set: the endpoint has grown keys before and a hardcoded list would
+         * silently drop new ones.
+         *
+         * Values that are OBJECTS are skipped rather than coerced to null. That
+         * coercion is exactly what broke `bySurface`: the endpoint publishes
+         * `surface_breakdown: { hard: { matches, won, lost, win_pct, titles }, ... }`
+         * (one object per surface) and this ran each value through Number(), so
+         * every tennis player's surface split came back
+         * `{hard:null, clay:null, grass:null, carpet:null}` — permanently, on every
+         * profile, while `player_profile` served the identical numbers from the
+         * identical source. A key that is present and null reads as "this player
+         * has no clay record", which is a worse lie than omitting it.
+         */
+        const camel = (key) => key.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+        const flatNumeric = (value) => {
+            const rec = asRecord(value);
+            if (!rec)
+                return null;
+            const out = {};
+            for (const [k, v] of Object.entries(rec)) {
+                if (asRecord(v))
+                    continue;
+                out[camel(k)] = num(v);
+            }
+            return Object.keys(out).length > 0 ? out : null;
+        };
+        /**
+         * One OBJECT per bucket (surface, level, …), with the bucket's own fields
+         * renamed to stable camelCase keys. A bucket that arrives as a bare number
+         * is preserved as { value }, so a shape change narrows the payload instead
+         * of emptying it.
+         */
+        const bucketBlock = (value, fields) => {
+            const rec = asRecord(value);
+            if (!rec)
+                return null;
+            const out = {};
+            for (const [bucket, raw] of Object.entries(rec)) {
+                const inner = asRecord(raw);
+                if (inner) {
+                    const mapped = {};
+                    for (const [outKey, srcKey] of fields) {
+                        if (srcKey in inner)
+                            mapped[outKey] = num(inner[srcKey]);
+                    }
+                    out[bucket] = Object.keys(mapped).length > 0 ? mapped : flatNumeric(inner) ?? {};
+                }
+                else {
+                    out[bucket] = { value: num(raw) };
+                }
+            }
+            return Object.keys(out).length > 0 ? out : null;
+        };
+        const SURFACE_FIELDS = [
+            ['matches', 'matches'],
+            ['won', 'won'],
+            ['lost', 'lost'],
+            ['winPct', 'win_pct'],
+            ['titles', 'titles'],
+        ];
+        const bySurface = bucketBlock(body.surface_breakdown ?? body.by_surface, SURFACE_FIELDS);
+        const byLevel = bucketBlock(body.by_level ?? body.level_breakdown, SURFACE_FIELDS);
+        const servingStats = flatNumeric(body.serving_stats);
+        const returnStats = flatNumeric(body.return_stats);
+        const clutchAndSituational = flatNumeric(body.clutch_and_situational);
+        const grandSlamBreakdown = bucketBlock(body.grand_slam_breakdown, SURFACE_FIELDS);
+        // Sections this endpoint declares but does not publish for this player.
+        // Named explicitly so an absent key is not read as "no such data exists".
+        const unavailable = {};
+        if (!byLevel) {
+            unavailable.byLevel =
+                'This endpoint publishes no per-level breakdown. Pass level= to a player_stats call, or use tournaments/event_card for level-scoped results.';
+        }
+        if (!returnStats)
+            unavailable.returnStats = 'Not published for this player yet.';
+        if (!clutchAndSituational) {
+            unavailable.clutchAndSituational = 'Not published for this player yet.';
+        }
+        if (!grandSlamBreakdown) {
+            unavailable.grandSlamBreakdown = 'Not published for this player yet.';
+        }
+        return successEnvelope({
+            source: 'player_stats',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+            entities: { games: [game], ids: { playerId } },
+            data: {
+                title: `${pickString(body.player_name) ?? playerId} career statistics`,
+                playerId: pickString(body.player_id) ?? playerId,
+                playerName: pickString(body.player_name) ?? null,
+                filters: {
+                    surface: pickString(filters.surface) ?? null,
+                    level: pickString(filters.level) ?? null,
+                    yearFrom: num(filters.year_from),
+                    yearTo: num(filters.year_to),
+                },
+                careerSummary: {
+                    matchesPlayed: num(summary.matches_played),
+                    matchesWon: num(summary.matches_won),
+                    matchesLost: num(summary.matches_lost),
+                    winPercentage: num(summary.win_percentage),
+                    titles: num(summary.titles_count),
+                    grandSlamTitles: num(summary.grand_slam_titles),
+                    mastersTitles: num(summary.masters_titles),
+                    finalsReached: num(summary.finals_reached),
+                },
+                bySurface,
+                byLevel,
+                servingStats,
+                returnStats,
+                clutchAndSituational,
+                grandSlamBreakdown,
+                ...(Object.keys(unavailable).length > 0 ? { unavailable } : {}),
+            },
+        });
+    },
+};
+export const playerTools = [playerProfile, playerForm, playerMatches, playerStats];

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,
@@ -225,4 +266,174 @@ Parallel-safe: yes. Upstream cost: 1.`,
         });
     },
 };
-export const rankingsTools = [rankingsMovers];
+export const playerRankingsHistory = {
+    name: 'player_rankings_history',
+    description: `Tennis player ranking trajectory: every published ranking date for one player, plus career-high and weeks at No.1.
+
+When to use:
+- "Show Alcaraz's ranking over time"; career-high rank and when it was reached; how a player climbed; plotting a rank chart.
+
+Prefer over: standings (latest snapshot only); rankings_movers (week-over-week delta for a whole tour); player_profile (has career-high but no per-date series).
+
+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.
+
+Parallel-safe: yes. Upstream cost: 1.`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game', 'playerId'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            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).' }),
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const gameParse = parseGame(args.game, { allowAll: false, required: true });
+        if (gameParse.error || !gameParse.game || !isPrimaryGame(gameParse.game)) {
+            return errorEnvelope({
+                code: gameParse.error?.includes('unsupported') ? 'UNSUPPORTED_GAME' : 'VALIDATION',
+                message: gameParse.error ?? 'game is required',
+                game: null,
+                source: 'player_rankings_history',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        if (game !== 'tennis') {
+            return errorEnvelope({
+                code: 'NOT_IMPLEMENTED',
+                message: `player_rankings_history is tennis-only (game '${game}' has no ranking-history endpoint)`,
+                game,
+                source: 'player_rankings_history',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Use standings for the latest snapshot of this game', 'Retry with game tennis'],
+            });
+        }
+        const playerId = typeof args.playerId === 'string' ? args.playerId.trim() : '';
+        if (!playerId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'playerId is required',
+                game,
+                source: 'player_rankings_history',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Find an id with search_entities or resolve_entity'],
+            });
+        }
+        const sinceRaw = typeof args.since === 'string' ? args.since.trim() : '';
+        if (sinceRaw && !/^\d{4}-\d{2}-\d{2}$/.test(sinceRaw)) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `since must be YYYY-MM-DD (got '${args.since}')`,
+                game,
+                source: 'player_rankings_history',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const limit = clampInt(args.limit, 20, 1, 500);
+        const res = await fetchJson(ctx, `/tennis/rankings/history/${encodeURIComponent(playerId)}`, {
+            query: { limit },
+        });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Ranking history failed for '${playerId}' (HTTP ${res.status})`,
+                game,
+                source: 'player_rankings_history',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                httpStatus: res.status,
+                rateLimit: res.headers,
+                recover: ['Check the player id with search_entities'],
+            });
+        }
+        const root = asRecord(res.data) ?? {};
+        const body = asRecord(root.data) ?? root;
+        const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+        const allHistory = (Array.isArray(body.history) ? body.history : []).map((row) => {
+            const r = asRecord(row) ?? {};
+            return {
+                date: pickString(r.date) ?? null,
+                rank: num(r.rank),
+                points: num(r.points),
+            };
+        });
+        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) => {
+            if (h.rank === null)
+                return acc;
+            if (!acc || acc.rank === null || h.rank < acc.rank)
+                return { date: h.date, rank: h.rank };
+            return acc;
+        }, null);
+        return successEnvelope({
+            pagination: {
+                limit,
+                offset: total - history.length,
+                total,
+                hasMore: total > history.length,
+                nextCursor: null,
+                prevCursor: null,
+            },
+            source: 'player_rankings_history',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+            data: {
+                title: `${pickString(body.player_name) ?? playerId} ranking history`,
+                playerId: pickString(body.player_id) ?? playerId,
+                playerName: pickString(body.player_name) ?? null,
+                tour: pickString(body.tour) ?? null,
+                careerHighRank: num(body.career_high_rank),
+                careerHighDate: pickString(body.career_high_date) ?? null,
+                weeksAtNo1: num(body.total_weeks_at_no_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,
+            },
+        });
+    },
+};
+export const rankingsTools = [rankingsMovers, playerRankingsHistory];