cito-mcp 0.3.19 → 0.3.21

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',
@@ -126,6 +136,116 @@ const TOOL_CATALOG = [
         preferOver: ['raw standings via call_api'],
         doNotUse: 'Single team form → team_profile; live scores → live_matches',
     },
+    {
+        name: 'rankings_movers',
+        outcome: 'Tennis ranking movers: climbers/fallers plus new entries and drop-outs',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', direction: 'up', limit: 20 },
+        preferOver: ['raw movers via call_api'],
+        doNotUse: 'Latest snapshot without deltas → standings',
+    },
+    {
+        name: 'player_form',
+        outcome: 'Tennis recent form: W/L record, current streak, per-match rows',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['player_form', 'preview', 'match_page'],
+        exampleArgs: { game: 'tennis', playerId: 'atp_207989', surface: 'Clay', limit: 5 },
+        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',
@@ -152,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)',
@@ -179,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'] },