cito-mcp 0.3.20 → 0.3.21

package/dist/tools/cs2.js

@@ -0,0 +1,421 @@
+/**
+ * Dedicated CS2 esports analytics & live scorebot MCP tools.
+ *
+ * Exposes deep CS2 domain data from the 161 backend endpoints:
+ * - Live real-time scoreboards & round state
+ * - Round-by-round tactical economies & buy classifications
+ * - First blood / opening duels per player & map
+ * - 1vX clutch success rates (1v1 through 1v5)
+ * - Team map pool analytics (Mirage, Inferno, Nuke, Dust2, Ancient, Anubis, Vertigo)
+ * - Sub-second utility & flashbang efficiency leaderboard
+ * - Match map pick/ban veto sequence
+ * - Pro roster changes & transfers
+ */
+import { asRecord, clampInt, fetchJson, unwrapPayload, } from '../client.js';
+import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
+import { limitSchema, READ_TOOL_ANNOTATIONS, stringSchema, } from './types.js';
+/** Unwraps Cito envelope whether inner entity is an object or array */
+function unwrap(val) {
+    const p = unwrapPayload(val);
+    const r = asRecord(p);
+    if (r && Array.isArray(r.data))
+        return r.data;
+    if (r && Array.isArray(r.items))
+        return r.items;
+    return p;
+}
+/**
+ * 1. cs2_live_scoreboard
+ * Real-time round state, bomb status, and player combat stats for an active match.
+ */
+export const cs2LiveScoreboard = {
+    name: 'cs2_live_scoreboard',
+    description: 'Live real-time in-game scoreboard for an active CS2 match. Returns current round, bomb status, team scores, and individual player stats (K/A/D, ADR, HS%, alive status, HP, armor, weapon, and equipment value).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            matchId: stringSchema('Match ID (e.g. "cs2-match-2397733" or "2397733"). Required.', 'cs2-match-2397733'),
+        },
+        required: ['matchId'],
+        additionalProperties: false,
+    },
+    annotations: READ_TOOL_ANNOTATIONS,
+    handler: async (args, ctx) => {
+        const reqId = newRequestId();
+        const rawId = typeof args.matchId === 'string' ? args.matchId.trim() : '';
+        if (!rawId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'matchId is required',
+                game: 'cs2',
+                source: 'cs2_live_scoreboard',
+                requestId: reqId,
+            });
+        }
+        const cleanId = rawId.replace(/^cs2-match-/, '');
+        const path = `/cs2/live/${encodeURIComponent(cleanId)}/scoreboard`;
+        const res = await fetchJson(ctx, path);
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `Live scoreboard fetch failed: ${res.status} on ${path}`,
+                game: 'cs2',
+                source: 'cs2_live_scoreboard',
+                requestId: reqId,
+                httpStatus: res.status,
+            });
+        }
+        const payload = unwrap(res.data);
+        return successEnvelope({
+            data: payload,
+            game: 'cs2',
+            source: 'cs2_live_scoreboard',
+            requestId: reqId,
+            rateLimit: res.headers,
+        });
+    },
+};
+/**
+ * 2. cs2_round_economy
+ * Tactical round-by-round buy classification and equipment values for a map.
+ */
+export const cs2RoundEconomy = {
+    name: 'cs2_round_economy',
+    description: 'Round-by-round tactical economy for a CS2 map. Classifies every round buy type (Full Buy, Force Buy, Semi-Eco, Full Eco), team equipment spend, freeze-time equipment values, and loss bonus counter.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            mapId: stringSchema('Map ID or Game ID (e.g. "7716-map-1" or "cs2-game-123"). Required.', '7716-map-1'),
+        },
+        required: ['mapId'],
+        additionalProperties: false,
+    },
+    annotations: READ_TOOL_ANNOTATIONS,
+    handler: async (args, ctx) => {
+        const reqId = newRequestId();
+        const rawMapId = typeof args.mapId === 'string' ? args.mapId.trim() : '';
+        if (!rawMapId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'mapId is required',
+                game: 'cs2',
+                source: 'cs2_round_economy',
+                requestId: reqId,
+            });
+        }
+        const path = `/cs2/maps/${encodeURIComponent(rawMapId)}/rounds`;
+        let res = await fetchJson(ctx, path);
+        if (!res.ok && res.status === 404) {
+            res = await fetchJson(ctx, `/cs2/games/${encodeURIComponent(rawMapId)}/rounds`);
+        }
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `Round economy fetch failed: ${res.status} on ${path}`,
+                game: 'cs2',
+                source: 'cs2_round_economy',
+                requestId: reqId,
+                httpStatus: res.status,
+            });
+        }
+        const payload = unwrap(res.data);
+        return successEnvelope({
+            data: payload,
+            game: 'cs2',
+            source: 'cs2_round_economy',
+            requestId: reqId,
+            rateLimit: res.headers,
+        });
+    },
+};
+/**
+ * 3. cs2_opening_duels
+ * First blood / opening kill statistics by player or overall leaderboard.
+ */
+export const cs2OpeningDuels = {
+    name: 'cs2_opening_duels',
+    description: 'First blood and opening duel statistics. Pass playerId to view a pro player\'s First Kills (FK), First Deaths (FD), and opening duel conversion %, or omit playerId to view the global CS2 opening duel leaderboard.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            playerId: stringSchema('Optional player ID or slug (e.g. "chucky" or "cs2-player-123"). If omitted, returns global leaderboard.', 'chucky'),
+            limit: limitSchema({ default: 20, max: 100 }),
+        },
+        additionalProperties: false,
+    },
+    annotations: READ_TOOL_ANNOTATIONS,
+    handler: async (args, ctx) => {
+        const reqId = newRequestId();
+        const rawPlayer = typeof args.playerId === 'string' ? args.playerId.trim() : '';
+        const limit = clampInt(args.limit, 20, 1, 100);
+        const path = rawPlayer
+            ? `/cs2/players/${encodeURIComponent(rawPlayer)}/opening-duels`
+            : `/cs2/stats/opening-duels`;
+        const res = await fetchJson(ctx, path, { query: { limit } });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `Opening duels fetch failed: ${res.status} on ${path}`,
+                game: 'cs2',
+                source: 'cs2_opening_duels',
+                requestId: reqId,
+                httpStatus: res.status,
+            });
+        }
+        const payload = unwrap(res.data);
+        return successEnvelope({
+            data: payload,
+            game: 'cs2',
+            source: 'cs2_opening_duels',
+            requestId: reqId,
+            rateLimit: res.headers,
+        });
+    },
+};
+/**
+ * 4. cs2_clutches
+ * 1vX clutch situation success records (1v1 through 1v5).
+ */
+export const cs2Clutches = {
+    name: 'cs2_clutches',
+    description: '1vX clutch situation success records. Pass playerId for a specific player\'s clutch breakdown (1v1, 1v2, 1v3, 1v4, 1v5 attempted vs won), or omit to view the global clutch leaderboard.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            playerId: stringSchema('Optional player ID or slug (e.g. "xm1nd" or "cs2-player-456"). If omitted, returns global leaderboard.', 'xm1nd'),
+            limit: limitSchema({ default: 20, max: 100 }),
+        },
+        additionalProperties: false,
+    },
+    annotations: READ_TOOL_ANNOTATIONS,
+    handler: async (args, ctx) => {
+        const reqId = newRequestId();
+        const rawPlayer = typeof args.playerId === 'string' ? args.playerId.trim() : '';
+        const limit = clampInt(args.limit, 20, 1, 100);
+        const path = rawPlayer
+            ? `/cs2/players/${encodeURIComponent(rawPlayer)}/clutches`
+            : `/cs2/stats/clutches`;
+        const res = await fetchJson(ctx, path, { query: { limit } });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `Clutches fetch failed: ${res.status} on ${path}`,
+                game: 'cs2',
+                source: 'cs2_clutches',
+                requestId: reqId,
+                httpStatus: res.status,
+            });
+        }
+        const payload = unwrap(res.data);
+        return successEnvelope({
+            data: payload,
+            game: 'cs2',
+            source: 'cs2_clutches',
+            requestId: reqId,
+            rateLimit: res.headers,
+        });
+    },
+};
+/**
+ * 5. cs2_team_map_stats
+ * Team performance across the competitive map pool.
+ */
+export const cs2TeamMapStats = {
+    name: 'cs2_team_map_stats',
+    description: 'Team win rates, round win rates, and CT/T side win splits across the competitive map pool (Mirage, Inferno, Nuke, Dust2, Ancient, Anubis, Vertigo) over the last 30 or 90 days.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            teamId: stringSchema('Team ID or slug (e.g. "hltv-team-4608", "cs2-team-4608", or "natus-vincere"). Required.', 'hltv-team-4608'),
+            days: {
+                type: 'integer',
+                description: 'Timeframe in days: 30, 90, 180, or 365 (default 90).',
+                default: 90,
+            },
+        },
+        required: ['teamId'],
+        additionalProperties: false,
+    },
+    annotations: READ_TOOL_ANNOTATIONS,
+    handler: async (args, ctx) => {
+        const reqId = newRequestId();
+        const rawTeam = typeof args.teamId === 'string' ? args.teamId.trim() : '';
+        if (!rawTeam) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'teamId is required',
+                game: 'cs2',
+                source: 'cs2_team_map_stats',
+                requestId: reqId,
+            });
+        }
+        const days = typeof args.days === 'number' ? args.days : 90;
+        const path = `/cs2/teams/${encodeURIComponent(rawTeam)}/map-stats`;
+        const res = await fetchJson(ctx, path, { query: { days } });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `Team map stats fetch failed: ${res.status} on ${path}`,
+                game: 'cs2',
+                source: 'cs2_team_map_stats',
+                requestId: reqId,
+                httpStatus: res.status,
+            });
+        }
+        const payload = unwrap(res.data);
+        return successEnvelope({
+            data: payload,
+            game: 'cs2',
+            source: 'cs2_team_map_stats',
+            requestId: reqId,
+            rateLimit: res.headers,
+        });
+    },
+};
+/**
+ * 6. cs2_utility_leaderboard
+ * Sub-second cached leaderboard for flashbang & utility efficiency.
+ */
+export const cs2UtilityLeaderboard = {
+    name: 'cs2_utility_leaderboard',
+    description: 'Sub-second cached leaderboard of CS2 utility and flashbang efficiency. Returns pro player rankings for effective blind duration per flash, enemy blind time, flashes thrown, and grenade ADR.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            limit: limitSchema({ default: 20, max: 100 }),
+        },
+        additionalProperties: false,
+    },
+    annotations: READ_TOOL_ANNOTATIONS,
+    handler: async (args, ctx) => {
+        const reqId = newRequestId();
+        const limit = clampInt(args.limit, 20, 1, 100);
+        const path = `/cs2/stats/utility`;
+        const res = await fetchJson(ctx, path, { query: { limit } });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `Utility leaderboard fetch failed: ${res.status} on ${path}`,
+                game: 'cs2',
+                source: 'cs2_utility_leaderboard',
+                requestId: reqId,
+                httpStatus: res.status,
+            });
+        }
+        const payload = unwrap(res.data);
+        return successEnvelope({
+            data: payload,
+            game: 'cs2',
+            source: 'cs2_utility_leaderboard',
+            requestId: reqId,
+            rateLimit: res.headers,
+        });
+    },
+};
+/**
+ * 7. cs2_veto_sequence
+ * Map pick/ban sequence and veto history for a match.
+ */
+export const cs2VetoSequence = {
+    name: 'cs2_veto_sequence',
+    description: 'Map pick/ban veto sequence for a CS2 match. Shows which team banned which map, map picks, and decider map in chronological order.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            matchId: stringSchema('Match ID (e.g. "2397603" or "cs2-match-2397603"). Required.', '2397603'),
+        },
+        required: ['matchId'],
+        additionalProperties: false,
+    },
+    annotations: READ_TOOL_ANNOTATIONS,
+    handler: async (args, ctx) => {
+        const reqId = newRequestId();
+        const rawId = typeof args.matchId === 'string' ? args.matchId.trim() : '';
+        if (!rawId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'matchId is required',
+                game: 'cs2',
+                source: 'cs2_veto_sequence',
+                requestId: reqId,
+            });
+        }
+        const cleanId = rawId.replace(/^cs2-match-/, '');
+        const path = `/cs2/matches/${encodeURIComponent(cleanId)}/head-to-head`;
+        const res = await fetchJson(ctx, path);
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `Veto sequence fetch failed: ${res.status} on ${path}`,
+                game: 'cs2',
+                source: 'cs2_veto_sequence',
+                requestId: reqId,
+                httpStatus: res.status,
+            });
+        }
+        const payload = unwrap(res.data);
+        const r = asRecord(payload);
+        const veto = r?.veto ?? r?.vetoSequence ?? payload;
+        return successEnvelope({
+            data: veto,
+            game: 'cs2',
+            source: 'cs2_veto_sequence',
+            requestId: reqId,
+            rateLimit: res.headers,
+        });
+    },
+};
+/**
+ * 8. cs2_roster_transfers
+ * Recent professional roster changes, benchings, and transfers.
+ */
+export const cs2RosterTransfers = {
+    name: 'cs2_roster_transfers',
+    description: 'Recent professional CS2 roster changes, player benchings, stand-ins, and team transfers.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            limit: limitSchema({ default: 20, max: 100 }),
+        },
+        additionalProperties: false,
+    },
+    annotations: READ_TOOL_ANNOTATIONS,
+    handler: async (args, ctx) => {
+        const reqId = newRequestId();
+        const limit = clampInt(args.limit, 20, 1, 100);
+        const path = `/cs2/transfers/recent`;
+        let res = await fetchJson(ctx, path, { query: { limit } });
+        if (!res.ok && res.status === 404) {
+            res = await fetchJson(ctx, `/cs2/roster-changes/recent`, { query: { limit } });
+        }
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `Roster transfers fetch failed: ${res.status} on ${path}`,
+                game: 'cs2',
+                source: 'cs2_roster_transfers',
+                requestId: reqId,
+                httpStatus: res.status,
+            });
+        }
+        const payload = unwrap(res.data);
+        return successEnvelope({
+            data: payload,
+            game: 'cs2',
+            source: 'cs2_roster_transfers',
+            requestId: reqId,
+            rateLimit: res.headers,
+        });
+    },
+};
+/** All curated CS2 tools */
+export const cs2Tools = [
+    cs2LiveScoreboard,
+    cs2RoundEconomy,
+    cs2OpeningDuels,
+    cs2Clutches,
+    cs2TeamMapStats,
+    cs2UtilityLeaderboard,
+    cs2VetoSequence,
+    cs2RosterTransfers,
+];

package/dist/tools/index.js

@@ -6,8 +6,10 @@ import { playerTools } from './player.js';
 import { teamTools } from './team.js';
 import { standingsTools } from './standings.js';
 import { rankingsTools } from './rankings.js';
+import { leaderboardTools } from './leaderboard.js';
 import { insightTools } from './insight.js';
-/** Curated outcome-tool catalog (17 tools). Order matches preferred cold-start ladder. */
+import { cs2Tools } from './cs2.js';
+/** Curated outcome-tool catalog. Order matches preferred cold-start ladder. */
 export const allTools = [
     ...metaTools.filter((t) => t.name === 'list_capabilities' || t.name === 'api_health'),
     ...resolveTools,
@@ -17,7 +19,9 @@ export const allTools = [
     ...teamTools,
     ...standingsTools,
     ...rankingsTools,
+    ...leaderboardTools,
     ...insightTools,
+    ...cs2Tools,
     // Escape-hatch pair last: discover routes, then call one.
     ...metaTools.filter((t) => t.name === 'list_routes' || t.name === 'call_api'),
 ];

package/dist/tools/leaderboard.js

@@ -0,0 +1,427 @@
+/**
+ * leaderboard_aces (TENNIS-18 follow-up).
+ *
+ * Tennis-only: season aces leaderboard from real match_stats aggregates
+ * (GET /tennis/leaderboards/aces). Upstream shape (verified 2026-09-09):
+ * { season, tour, stat: 'aces', items: [{ player_id, full_name, aces, matches }], total }.
+ * Upstream defaults: season=2026, tour=null (both tours combined), and it
+ * 422s on a bad tour or a non-year season — both surface as VALIDATION here.
+ */
+import { asRecord, clampInt, fetchJson, gameNotIncludedHint, pickString, } from '../client.js';
+import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
+import { gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
+const DEFAULT_SEASON = 2026;
+const MIN_SEASON = 1968;
+const MAX_SEASON = 2100;
+function parseOptionalTour(args) {
+    const rawTour = typeof args.tour === 'string' ? args.tour.trim() : '';
+    const rawDivision = typeof args.division === 'string' ? args.division.trim() : '';
+    if (rawTour && rawDivision && rawTour.toUpperCase() !== rawDivision.toUpperCase()) {
+        return { error: `tour ('${rawTour}') and division ('${rawDivision}') disagree; pass one of ATP|WTA` };
+    }
+    const raw = rawTour || rawDivision;
+    if (!raw)
+        return {};
+    const upper = raw.toUpperCase();
+    if (upper !== 'ATP' && upper !== 'WTA') {
+        return { error: `tour must be ATP or WTA (got '${raw}')` };
+    }
+    return { tour: upper };
+}
+function parseSeason(args) {
+    const raw = args.season;
+    if (raw === undefined || raw === null || (typeof raw === 'string' && raw.trim() === '')) {
+        return { season: DEFAULT_SEASON };
+    }
+    const num = typeof raw === 'number' ? raw : Number(String(raw).trim());
+    if (!Number.isInteger(num) || num < MIN_SEASON || num > MAX_SEASON) {
+        return { error: `season must be a YYYY year ${MIN_SEASON}-${MAX_SEASON} (got '${String(raw)}')` };
+    }
+    return { season: num };
+}
+function normalizeAceRow(row) {
+    const r = asRecord(row) ?? {};
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    return {
+        playerId: pickString(r.player_id) ?? null,
+        playerName: pickString(r.full_name, r.player_name) ?? null,
+        aces: num(r.aces),
+        matches: num(r.matches),
+    };
+}
+export const leaderboardAces = {
+    name: 'leaderboard_aces',
+    description: `Tennis season aces leaderboard: most aces served in a season, from real match-stats aggregates.
+
+When to use:
+- Who leads the tour in aces this season; season serving-leader tables.
+
+Prefer over: raw leaderboard via call_api for agent-normalized rows.
+
+Do not use when: ranking position → standings with game tennis; week-over-week movement → rankings_movers; one player's recent form → player_form.
+
+Tennis-only. Season defaults to 2026; tour (ATP|WTA) is optional — omit it for the combined board. Rows carry aces + matches played, ordered most aces first.
+
+Parallel-safe: yes. Upstream cost: 1.`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            tour: stringSchema('ATP or WTA tour; omit for the combined board. Synonym: division.', 'WTA'),
+            division: stringSchema('Synonym for tour (ATP or WTA), matching the standings tool spelling.'),
+            season: {
+                type: 'integer',
+                minimum: MIN_SEASON,
+                maximum: MAX_SEASON,
+                default: DEFAULT_SEASON,
+                description: 'Season year (YYYY). Default 2026.',
+            },
+            limit: limitSchema({ default: 10, max: 100 }),
+        },
+    },
+    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: 'leaderboard_aces',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        if (game !== 'tennis') {
+            return errorEnvelope({
+                code: 'NOT_IMPLEMENTED',
+                message: `leaderboard_aces is tennis-only (game '${game}' has no aces leaderboard)`,
+                game,
+                source: 'leaderboard_aces',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [
+                    'Use standings for the latest snapshot of this game',
+                    'Retry leaderboard_aces with game tennis and an optional tour ATP|WTA',
+                ],
+            });
+        }
+        const tourParse = parseOptionalTour(args);
+        if (tourParse.error) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: tourParse.error,
+                game,
+                source: 'leaderboard_aces',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const seasonParse = parseSeason(args);
+        if (seasonParse.error || seasonParse.season === undefined) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: seasonParse.error ?? 'season is invalid',
+                game,
+                source: 'leaderboard_aces',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const limit = clampInt(args.limit, 10, 1, 100);
+        const res = await fetchJson(ctx, '/tennis/leaderboards/aces', {
+            query: {
+                season: seasonParse.season,
+                limit,
+                ...(tourParse.tour ? { tour: tourParse.tour } : {}),
+            },
+        });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Aces leaderboard failed (HTTP ${res.status})`,
+                game,
+                source: 'leaderboard_aces',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                httpStatus: res.status,
+                rateLimit: res.headers,
+            });
+        }
+        const root = asRecord(res.data);
+        const body = asRecord(root?.data) ?? root ?? {};
+        const items = (Array.isArray(body.items) ? body.items : []).map(normalizeAceRow);
+        const total = typeof body.total === 'number' ? body.total : items.length;
+        return successEnvelope({
+            pagination: {
+                limit,
+                offset: 0,
+                total,
+                hasMore: false,
+                nextCursor: null,
+                prevCursor: null,
+            },
+            source: 'leaderboard_aces',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+            data: {
+                title: `${tourParse.tour ?? 'Combined'} aces leaderboard ${seasonParse.season}`,
+                season: typeof body.season === 'number' ? body.season : seasonParse.season,
+                tour: pickString(body.tour) ?? tourParse.tour ?? null,
+                stat: pickString(body.stat) ?? 'aces',
+                items,
+                total,
+            },
+        });
+    },
+};
+function normalizePctRow(numKey, denKey) {
+    return (row) => {
+        const r = asRecord(row) ?? {};
+        const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+        return {
+            playerId: pickString(r.player_id) ?? null,
+            playerName: pickString(r.full_name, r.player_name) ?? null,
+            attempts: num(r[numKey]),
+            total: num(r[denKey]),
+            pct: num(r.pct),
+            matches: num(r.matches),
+        };
+    };
+}
+function makePctLeaderboardTool(spec) {
+    const normalizeRow = normalizePctRow(spec.numKey, spec.denKey);
+    return {
+        name: spec.name,
+        description: `Tennis season ${spec.titleNoun} leaderboard: ${spec.blurb}
+
+When to use:
+- ${spec.blurb} season tables; clutch/serve-efficiency leader queries.
+
+Prefer over: raw leaderboard via call_api for agent-normalized rows.
+
+Do not use when: ranking position → standings with game tennis; week-over-week movement → rankings_movers; one player's recent form → player_form.
+
+Tennis-only. Season defaults to 2026; tour (ATP|WTA) is optional — omit it for the combined board. ${spec.minAttemptsNote}
+
+Parallel-safe: yes. Upstream cost: 1.`,
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['game'],
+            properties: {
+                game: gameSchema({ allowAll: false, required: true }),
+                tour: stringSchema('ATP or WTA tour; omit for the combined board. Synonym: division.', 'WTA'),
+                division: stringSchema('Synonym for tour (ATP or WTA), matching the standings tool spelling.'),
+                season: {
+                    type: 'integer',
+                    minimum: MIN_SEASON,
+                    maximum: MAX_SEASON,
+                    default: DEFAULT_SEASON,
+                    description: 'Season year (YYYY). Default 2026.',
+                },
+                limit: limitSchema({ default: 10, max: 100 }),
+            },
+        },
+        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: spec.name,
+                    requestId,
+                    tookMs: Date.now() - started,
+                });
+            }
+            const game = gameParse.game;
+            if (game !== 'tennis') {
+                return errorEnvelope({
+                    code: 'NOT_IMPLEMENTED',
+                    message: `${spec.name} is tennis-only (game '${game}' has no ${spec.titleNoun} leaderboard)`,
+                    game,
+                    source: spec.name,
+                    requestId,
+                    tookMs: Date.now() - started,
+                    recover: [
+                        'Use standings for the latest snapshot of this game',
+                        `Retry ${spec.name} with game tennis and an optional tour ATP|WTA`,
+                    ],
+                });
+            }
+            const tourParse = parseOptionalTour(args);
+            if (tourParse.error) {
+                return errorEnvelope({
+                    code: 'VALIDATION',
+                    message: tourParse.error,
+                    game,
+                    source: spec.name,
+                    requestId,
+                    tookMs: Date.now() - started,
+                });
+            }
+            const seasonParse = parseSeason(args);
+            if (seasonParse.error || seasonParse.season === undefined) {
+                return errorEnvelope({
+                    code: 'VALIDATION',
+                    message: seasonParse.error ?? 'season is invalid',
+                    game,
+                    source: spec.name,
+                    requestId,
+                    tookMs: Date.now() - started,
+                });
+            }
+            const limit = clampInt(args.limit, 10, 1, 100);
+            const res = await fetchJson(ctx, `/tennis${spec.path}`, {
+                query: {
+                    season: seasonParse.season,
+                    limit,
+                    ...(tourParse.tour ? { tour: tourParse.tour } : {}),
+                },
+            });
+            if (!res.ok) {
+                return errorEnvelope({
+                    code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                    message: `${spec.titleNoun} leaderboard failed (HTTP ${res.status})`,
+                    game,
+                    source: spec.name,
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls: 1,
+                    httpStatus: res.status,
+                    rateLimit: res.headers,
+                });
+            }
+            const root = asRecord(res.data);
+            const body = asRecord(root?.data) ?? root ?? {};
+            const items = (Array.isArray(body.items) ? body.items : []).map(normalizeRow);
+            const total = typeof body.total === 'number' ? body.total : items.length;
+            return successEnvelope({
+                pagination: {
+                    limit,
+                    offset: 0,
+                    total,
+                    hasMore: false,
+                    nextCursor: null,
+                    prevCursor: null,
+                },
+                source: spec.name,
+                game,
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                rateLimit: res.headers,
+                data: {
+                    title: `${tourParse.tour ?? 'Combined'} ${spec.titleNoun} leaderboard ${seasonParse.season}`,
+                    season: typeof body.season === 'number' ? body.season : seasonParse.season,
+                    tour: pickString(body.tour) ?? tourParse.tour ?? null,
+                    stat: pickString(body.stat) ?? spec.stat,
+                    items,
+                    total,
+                },
+            });
+        },
+    };
+}
+export const leaderboardBreakPointsSaved = makePctLeaderboardTool({
+    name: 'leaderboard_break_points_saved',
+    path: '/leaderboards/break-points-saved',
+    stat: 'break_points_saved',
+    numKey: 'break_points_saved',
+    denKey: 'break_points_faced',
+    titleNoun: 'break-points-saved',
+    blurb: 'Share of break points saved per player, from real match-stats aggregates, ordered highest pct first.',
+    minAttemptsNote: 'Only players facing at least 50 break points qualify.',
+});
+export const leaderboardFirstServeWon = makePctLeaderboardTool({
+    name: 'leaderboard_first_serve_won',
+    path: '/leaderboards/1st-serve-won',
+    stat: 'first_serve_won',
+    numKey: 'first_serve_points_won',
+    denKey: 'first_serves_in',
+    titleNoun: 'first-serve-won',
+    blurb: 'Share of first-serve points won per player, from real match-stats aggregates, ordered highest pct first.',
+    minAttemptsNote: 'Only players with at least 300 first serves in qualify.',
+});
+export const leaderboardTiebreakWinPct = makePctLeaderboardTool({
+    name: 'leaderboard_tiebreak_win_pct',
+    path: '/leaderboards/tiebreak-win-pct',
+    stat: 'tiebreak_win_pct',
+    numKey: 'tiebreaks_won',
+    denKey: 'tiebreaks_played',
+    titleNoun: 'tiebreak-win-pct',
+    blurb: 'Share of classic 7-point tiebreaks won per player, from real match-set aggregates, ordered highest pct first.',
+    minAttemptsNote: 'Only players contesting at least 10 tiebreaks qualify.',
+});
+export const leaderboardBreakConversion = makePctLeaderboardTool({
+    name: 'leaderboard_break_conversion',
+    path: '/leaderboards/break-conversion',
+    stat: 'break_conversion',
+    numKey: 'break_points_won',
+    denKey: 'break_opportunities',
+    titleNoun: 'break-conversion',
+    blurb: 'Share of break opportunities converted per player, from real match-stats aggregates read return-side, ordered highest pct first.',
+    minAttemptsNote: 'Only players with at least 50 break opportunities qualify.',
+});
+export const leaderboardReturnGamesWon = makePctLeaderboardTool({
+    name: 'leaderboard_return_games_won',
+    path: '/leaderboards/return-games-won',
+    stat: 'return_games_won',
+    numKey: 'return_games_won',
+    denKey: 'return_games_played',
+    titleNoun: 'return-games-won',
+    blurb: 'Share of return games won per player (breaks over opponent service games played), from real match-stats aggregates read return-side, ordered highest pct first.',
+    minAttemptsNote: 'Only players with at least 100 return games played qualify.',
+});
+export const leaderboardFinalsRecord = makePctLeaderboardTool({
+    name: 'leaderboard_finals_record',
+    path: '/leaderboards/finals-record',
+    stat: 'finals_record',
+    numKey: 'finals_won',
+    denKey: 'finals_played',
+    titleNoun: 'finals-record',
+    blurb: 'Share of finals won (titles clutch) per player, from real completed finals rows, ordered highest pct first.',
+    minAttemptsNote: 'Only players contesting at least 3 finals qualify.',
+});
+export const leaderboardComebackWins = makePctLeaderboardTool({
+    name: 'leaderboard_comeback_wins',
+    path: '/leaderboards/comeback-wins',
+    stat: 'comeback_wins',
+    numKey: 'comebacks_won',
+    denKey: 'matches_with_first_set',
+    titleNoun: 'comeback-wins',
+    blurb: 'Share of matches won after losing the first set per player, from real first-set rows joined to completed matches, ordered highest pct first.',
+    minAttemptsNote: 'Only players with first-set data on at least 20 matches qualify.',
+});
+export const leaderboardDecidingSetRecord = makePctLeaderboardTool({
+    name: 'leaderboard_deciding_set_record',
+    path: '/leaderboards/deciding-set-record',
+    stat: 'deciding_set_record',
+    numKey: 'deciders_won',
+    denKey: 'deciders_played',
+    titleNoun: 'deciding-set-record',
+    blurb: 'Share of deciding sets (full-length final sets) won per player, from real match rows, ordered highest pct first.',
+    minAttemptsNote: 'Only players contesting at least 10 deciders qualify.',
+});
+export const leaderboardTools = [
+    leaderboardAces,
+    leaderboardBreakPointsSaved,
+    leaderboardFirstServeWon,
+    leaderboardTiebreakWinPct,
+    leaderboardBreakConversion,
+    leaderboardReturnGamesWon,
+    leaderboardDecidingSetRecord,
+    leaderboardComebackWins,
+    leaderboardFinalsRecord,
+];

package/dist/tools/meta.js

@@ -116,6 +116,16 @@ const TOOL_CATALOG = [
         preferOver: ['agent-side double match-list filtering'],
         doNotUse: 'Single-side form only → team_profile or player_profile',
     },
+    {
+        name: 'h2h_matrix',
+        outcome: 'Tennis multi-player H2H grid: every pair series record in one matrix',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['h2h', 'preview'],
+        exampleArgs: { game: 'tennis', players: ['atp_207989', 'atp_100644'] },
+        preferOver: ['N head_to_head calls for an N-player field', 'raw matrix via call_api'],
+        doNotUse: 'Two-player deep-dive with tiebreak splits → head_to_head; season leaders → leaderboard_*',
+    },
     {
         name: 'standings',
         outcome: 'League/event standings or world/division rankings',
@@ -146,6 +156,96 @@ const TOOL_CATALOG = [
         preferOver: ['raw form via call_api'],
         doNotUse: 'Career totals/titles → player_profile; ranking deltas → rankings_movers',
     },
+    {
+        name: 'leaderboard_aces',
+        outcome: 'Tennis season aces leaderboard: most aces served, ordered first',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
+    {
+        name: 'leaderboard_break_points_saved',
+        outcome: 'Tennis season break-points-saved pct leaderboard, min 50 faced',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
+    {
+        name: 'leaderboard_first_serve_won',
+        outcome: 'Tennis season first-serve-won pct leaderboard, min 300 in',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
+    {
+        name: 'leaderboard_tiebreak_win_pct',
+        outcome: 'Tennis season tiebreak-win-pct leaderboard, min 10 tiebreaks',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
+    {
+        name: 'leaderboard_break_conversion',
+        outcome: 'Tennis season break-conversion pct leaderboard, min 50 opportunities',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
+    {
+        name: 'leaderboard_return_games_won',
+        outcome: 'Tennis season return-games-won pct leaderboard, min 100 played',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
+    {
+        name: 'leaderboard_deciding_set_record',
+        outcome: 'Tennis season deciding-set-record pct leaderboard, min 10 deciders',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
+    {
+        name: 'leaderboard_comeback_wins',
+        outcome: 'Tennis season comeback-wins pct leaderboard, min 20 first sets',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
+    {
+        name: 'leaderboard_finals_record',
+        outcome: 'Tennis season finals-record pct leaderboard, min 3 finals',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
     {
         name: 'match_preview',
         outcome: 'Pre-match briefing: sides, rosters/form, H2H stub',
@@ -172,6 +272,86 @@ const TOOL_CATALOG = [
         ],
         doNotUse: 'Live-only strip → live_matches; single match recap → match_summary',
     },
+    {
+        name: 'cs2_live_scoreboard',
+        outcome: 'Live real-time in-game scoreboard for an active CS2 match',
+        parallelSafe: true,
+        games: ['cs2'],
+        jobs: ['live_board', 'match_page'],
+        exampleArgs: { matchId: 'cs2-match-2397733' },
+        preferOver: ['polling call_api for live scoreboard'],
+        doNotUse: 'For completed matches without live state',
+    },
+    {
+        name: 'cs2_round_economy',
+        outcome: 'Round-by-round tactical economy and buy types for a CS2 map',
+        parallelSafe: true,
+        games: ['cs2'],
+        jobs: ['match_page'],
+        exampleArgs: { mapId: '7716-map-1' },
+        preferOver: ['raw round event parsing'],
+        doNotUse: 'For overall match scorelines → match_summary',
+    },
+    {
+        name: 'cs2_opening_duels',
+        outcome: 'First blood and opening duel statistics by player or leaderboard',
+        parallelSafe: true,
+        games: ['cs2'],
+        jobs: ['player_form', 'match_page'],
+        exampleArgs: { playerId: 'chucky', limit: 20 },
+        preferOver: ['manual kill log counting'],
+        doNotUse: 'For general player stats → player_profile',
+    },
+    {
+        name: 'cs2_clutches',
+        outcome: '1vX clutch situation success records (1v1 to 1v5)',
+        parallelSafe: true,
+        games: ['cs2'],
+        jobs: ['player_form', 'match_page'],
+        exampleArgs: { playerId: 'xm1nd', limit: 20 },
+        preferOver: ['manual demo parse analysis'],
+        doNotUse: 'For regular player stats → player_profile',
+    },
+    {
+        name: 'cs2_team_map_stats',
+        outcome: 'Team win rates and CT/T side splits across competitive map pool',
+        parallelSafe: true,
+        games: ['cs2'],
+        jobs: ['team_page', 'preview'],
+        exampleArgs: { teamId: 'hltv-team-4608', days: 90 },
+        preferOver: ['manual match history scraping'],
+        doNotUse: 'For non-CS2 games',
+    },
+    {
+        name: 'cs2_utility_leaderboard',
+        outcome: 'Sub-second leaderboard of CS2 utility and flashbang efficiency',
+        parallelSafe: true,
+        games: ['cs2'],
+        jobs: ['standings', 'player_form'],
+        exampleArgs: { limit: 20 },
+        preferOver: ['unindexed round event aggregation'],
+        doNotUse: 'For standard weapon ratings',
+    },
+    {
+        name: 'cs2_veto_sequence',
+        outcome: 'Map pick/ban sequence and veto history for a CS2 match',
+        parallelSafe: true,
+        games: ['cs2'],
+        jobs: ['match_page', 'preview'],
+        exampleArgs: { matchId: '2397603' },
+        preferOver: ['scraping match page text'],
+        doNotUse: 'For map scores → match_summary',
+    },
+    {
+        name: 'cs2_roster_transfers',
+        outcome: 'Recent pro CS2 roster changes, benchings, stand-ins, and transfers',
+        parallelSafe: true,
+        games: ['cs2'],
+        jobs: ['team_page', 'schedule'],
+        exampleArgs: { limit: 20 },
+        preferOver: ['manual news feed scanning'],
+        doNotUse: 'For current active rosters → team_profile',
+    },
     {
         name: 'list_routes',
         outcome: 'Index of raw REST routes from the live OpenAPI spec (method, path, summary)',
@@ -199,7 +379,7 @@ const JOBS = [
     { id: 'team_page', description: 'Team/org profile screen', recommendedTools: ['resolve_entity', 'team_profile'] },
     { id: 'player_form', description: 'Player/fighter form card', recommendedTools: ['resolve_entity', 'player_profile'] },
     { id: 'standings', description: 'Tables and rankings', recommendedTools: ['standings'] },
-    { id: 'h2h', description: 'Historical rivalry record', recommendedTools: ['head_to_head'] },
+    { id: 'h2h', description: 'Historical rivalry record', recommendedTools: ['head_to_head', 'h2h_matrix'] },
     { id: 'schedule', description: 'Upcoming fixtures/events', recommendedTools: ['upcoming_schedule', 'event_card'] },
     { id: 'preview', description: 'Pre-match briefing', recommendedTools: ['match_preview'] },
     { id: 'event_card', description: 'Event / fight-night card page', recommendedTools: ['event_card', 'resolve_entity', 'match_preview'] },

package/dist/tools/team.js

@@ -1022,4 +1022,186 @@ Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
         });
     },
 };
-export const teamTools = [teamProfile, headToHead];
+/**
+ * h2h_matrix (TENNIS-24, cycle 60).
+ *
+ * Tennis-only: multi-player head-to-head comparison grid from the first-class
+ * GET /tennis/h2h/matrix route (2-16 player ids, comma-separated). Upstream
+ * shape (verified 2026-09-09): { players: [{ id, name, ioc, wins }], matrix:
+ * { [rowId]: { [colId]: "W-L" | "-" } } }. Cell "7-6" at [A][B] means A won 7
+ * and B won 6 of their meetings; "-" marks the self diagonal. Unknown ids get
+ * honest 0-0 cells and no players entry (no 404); fewer than 2 or more than 16
+ * ids 422, which surfaces as VALIDATION here.
+ *
+ * Names are resolved to atp_/wta_ ids via /tennis/players/search first (same
+ * id-shaped shortcut as the head_to_head tennis branch); duplicates collapse
+ * to one grid row.
+ */
+export const h2hMatrix = {
+    name: 'h2h_matrix',
+    description: `Multi-player tennis head-to-head grid: every pair's series record in one comparison matrix.
+
+When to use:
+- Draw/field analysis: how each contender fares against every other (e.g. Alcaraz vs Zverev vs Sinner round-robin records)
+- Group-stage or semifinal-field comparisons
+
+Prefer over: N head_to_head calls for an N-player field; raw matrix via call_api.
+
+Do not use when: a two-player rivalry deep-dive with tiebreak/decider splits → head_to_head; season stat leaders → leaderboard_*; rankings → standings.
+
+Tennis-only. players takes 2-16 ids or names (names resolve via player search). Each matrix cell is "W-L" from the row player's perspective, "-" on the diagonal.
+
+Parallel-safe: yes. Upstream cost: 1 + one search per unresolved name.`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game', 'players'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            players: {
+                type: 'array',
+                items: { type: 'string' },
+                minItems: 2,
+                maxItems: 16,
+                description: '2-16 tennis player ids (atp_207989) or names ("Carlos Alcaraz"); duplicates collapse.',
+            },
+        },
+    },
+    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: 'h2h_matrix',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        if (game !== 'tennis') {
+            return errorEnvelope({
+                code: 'NOT_IMPLEMENTED',
+                message: `h2h_matrix is tennis-only (game '${game}' has no H2H matrix)`,
+                game,
+                source: 'h2h_matrix',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [
+                    'Use head_to_head for a two-side rivalry record in this game',
+                    'Retry h2h_matrix with game tennis and 2-16 player ids or names',
+                ],
+            });
+        }
+        const rawPlayers = Array.isArray(args.players) ? args.players : [];
+        const cleaned = rawPlayers
+            .filter((p) => typeof p === 'string' && p.trim().length > 0)
+            .map((p) => p.trim());
+        if (cleaned.length < 2 || cleaned.length > 16) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `players must contain between 2 and 16 names or ids (got ${cleaned.length})`,
+                game,
+                source: 'h2h_matrix',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Pass 2-16 player ids (atp_207989) or names ("Carlos Alcaraz")'],
+            });
+        }
+        let upstreamCalls = 0;
+        let rateLimit = {};
+        const resolveTennisSide = async (side) => {
+            if (/^(atp|wta)_\d+$/i.test(side))
+                return { id: side, name: side };
+            const res = await fetchJson(ctx, '/tennis/players/search', { query: { q: side, limit: 3 } });
+            upstreamCalls += 1;
+            rateLimit = { ...rateLimit, ...res.headers };
+            if (!res.ok)
+                return null;
+            const envelope = asRecord(res.data) ?? {};
+            const data = asRecord(envelope.data) ?? envelope;
+            const first = asRecord(extractRows(data.items ?? data)[0]);
+            const id = pickString(first?.id, first?.player_id);
+            return id ? { id, name: pickString(first?.full_name, first?.name) ?? side } : null;
+        };
+        const resolved = await Promise.all(cleaned.map((side) => resolveTennisSide(side)));
+        const missing = cleaned.filter((_, i) => !resolved[i]);
+        if (missing.length > 0) {
+            return errorEnvelope({
+                code: 'NOT_FOUND',
+                message: `Tennis player(s) not found: ${missing.join(', ')} — pass names or ids like atp_104745`,
+                game,
+                source: 'h2h_matrix',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls,
+                rateLimit,
+                recover: [
+                    'resolve_entity { game: "tennis", type: "player", q } for each missing name',
+                    'Retry h2h_matrix with returned ids',
+                ],
+            });
+        }
+        // Dedupe resolved ids preserving order: REST dict keys would collapse
+        // anyway, but players_info would list the duplicate twice.
+        const ids = [...new Set(resolved.map((r) => r.id))];
+        if (ids.length < 2) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'players resolve to fewer than 2 distinct players — pass at least 2 different players',
+                game,
+                source: 'h2h_matrix',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls,
+                rateLimit,
+            });
+        }
+        const res = await fetchJson(ctx, '/tennis/h2h/matrix', {
+            query: { player_ids: ids.join(',') },
+        });
+        upstreamCalls += 1;
+        rateLimit = { ...rateLimit, ...res.headers };
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Tennis H2H matrix fetch failed (HTTP ${res.status})`,
+                game,
+                source: 'h2h_matrix',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls,
+                httpStatus: res.status,
+                rateLimit,
+            });
+        }
+        const envelope = asRecord(res.data) ?? {};
+        const payload = asRecord(envelope.data) ?? envelope;
+        const players = extractRows(payload.players ?? []).map((row) => {
+            const r = asRecord(row) ?? {};
+            return {
+                id: pickString(r.id, r.player_id) ?? null,
+                name: pickString(r.full_name, r.name) ?? null,
+                ioc: pickString(r.ioc) ?? null,
+            };
+        });
+        const matrix = asRecord(payload.matrix) ?? {};
+        return successEnvelope({
+            source: 'h2h_matrix',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls,
+            rateLimit,
+            data: {
+                players,
+                matrix,
+                notes: ['Cells are "W-L" from the row player vs the column player; "-" is the self diagonal'],
+            },
+        });
+    },
+};
+export const teamTools = [teamProfile, headToHead, h2hMatrix];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cito-mcp",
-  "version": "0.3.20",
-  "description": "Standalone MCP server for the Cito esports and sports API — 18 curated outcome tools for agents (live, schedule, profiles, standings, previews, event cards, player form, rankings movers).",
+  "version": "0.3.21",
+  "description": "Standalone MCP server for the Cito esports and sports API — 36 curated outcome tools for agents (live scoreboards, round economy, opening duels, clutches, vetoes, rosters, tennis, mma).",
   "type": "module",
   "bin": {
     "cito-mcp": "dist/index.js"