cito-mcp 0.5.8 → 0.6.1

package/dist/tools/match.js

@@ -182,7 +182,7 @@ Prefer match_details for timelines, full map trees, live state, advanced package
 
 Do not use when: no matchId yet (resolve from live/schedule); pure pre-match → match_preview.
 
-Parallel-safe: yes. Upstream cost: 2–5.
+Parallel-safe: yes. API calls: 2–5.
 Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includePlayerStats": true }`,
     inputSchema: {
         type: 'object',
@@ -231,20 +231,20 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
         const includeMedia = args.includeMedia !== false;
         const view = args.view === 'full' ? 'full' : 'summary';
         const partial = [];
-        let upstreamCalls = 0;
+        let apiCalls = 0;
         let rateLimit = {};
         let primary = await getSection(ctx, primaryPath(game, matchId));
-        upstreamCalls += 1;
+        apiCalls += 1;
         rateLimit = primary.headers;
         if (!primary.ok && game === 'tennis' && primary.status === 404) {
             primary = await getSection(ctx, `/tennis/matches/live/${encodeURIComponent(matchId)}`);
-            upstreamCalls += 1;
+            apiCalls += 1;
             rateLimit = { ...rateLimit, ...primary.headers };
-            const gid = matchId.match(/^s365_(\d+)$/)?.[1];
+            const gid = liveBoardGameNumber(matchId);
             if (!primary.ok && gid) {
                 const year = new Date().getUTCFullYear();
-                primary = await getSection(ctx, `/tennis/matches/${encodeURIComponent(`s365_${year}_${gid}`)}`);
-                upstreamCalls += 1;
+                primary = await getSection(ctx, `/tennis/matches/${encodeURIComponent(`${TENNIS_LIVE_PREFIX}${year}_${gid}`)}`);
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...primary.headers };
             }
         }
@@ -256,7 +256,7 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
                 source: 'match_summary',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls,
+                apiCalls,
                 rateLimit: primary.headers,
                 httpStatus: primary.status,
             });
@@ -288,7 +288,7 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
                     paths.push(`/tennis/matches/${encodeURIComponent(matchId)}/stats`);
                 for (const p of paths) {
                     const res = await getSection(ctx, p);
-                    upstreamCalls += 1;
+                    apiCalls += 1;
                     rateLimit = { ...rateLimit, ...res.headers };
                     if (!res.ok) {
                         if (game === 'tennis' && res.status === 404) {
@@ -317,7 +317,7 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
         if (includeMedia && game === 'cs2') {
             enrich.push((async () => {
                 const res = await getSection(ctx, `/cs2/matches/${encodeURIComponent(matchId)}/demos`);
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok)
                     media.demos = extractRows(res.data);
@@ -344,6 +344,7 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
                         player1Games: p1g,
                         player2Games: p2g,
                         tiebreak: sr.tiebreak ?? null,
+                        tiebreakPoints: sr.tiebreak_points ?? null,
                         completed: tennisSetCompleted(sr),
                     };
                 });
@@ -359,7 +360,7 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
             if (!path)
                 return;
             const res = await getSection(ctx, path);
-            upstreamCalls += 1;
+            apiCalls += 1;
             rateLimit = { ...rateLimit, ...res.headers };
             if (res.ok) {
                 gamesOrMaps = extractRows(res.data);
@@ -389,7 +390,7 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls,
+            apiCalls,
             rateLimit,
             partial: partial.length ? partial : undefined,
             entities: { games: [game], ids: { matchId: match.matchId } },
@@ -404,6 +405,37 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
         });
     },
 };
+export function summarizeCs2Odds(data) {
+    const root = (data ?? {});
+    const payload = (root.data && typeof root.data === 'object' && !Array.isArray(root.data)
+        ? root.data
+        : root);
+    const rows = Array.isArray(payload.odds) ? payload.odds : [];
+    const rank = (m) => (m === 'h2h' ? '0' : `1${String(m ?? '')}`);
+    const markets = rows
+        .map((r) => ({
+        market: r.market ?? null,
+        team1Odds: r.team1Odds ?? null,
+        team2Odds: r.team2Odds ?? null,
+        team1ImpliedProb: r.team1ImpliedProb ?? null,
+        team2ImpliedProb: r.team2ImpliedProb ?? null,
+        marketStatus: r.marketStatus ?? 'open',
+        liquidityUsd: r.liquidityUsd ?? null,
+        capturedAt: r.capturedAt ?? null,
+    }))
+        .sort((a, b) => rank(a.market).localeCompare(rank(b.market)));
+    return {
+        teams: payload.teams ?? null,
+        dataAvailable: markets.length > 0,
+        markets,
+        realTime: {
+            updates: 'Prices update as soon as the market price changes, through every map and between rounds.',
+            push: 'wss://api.citoapi.com/api/v1/cs2/live/ws (message type cs2.odds.updated; needs Live WebSockets and a plan with odds)',
+            byRound: '/cs2/matches/{matchId}/odds/rounds (price at each round start and end); /cs2/matches/{matchId}/odds/history?map=&round=&phase=',
+        },
+        fullBookPath: '/cs2/matches/{matchId}/odds',
+    };
+}
 export function summarizeUfcOdds(data) {
     const root = (data ?? {});
     const payload = (root.data && typeof root.data === 'object' && !Array.isArray(root.data)
@@ -482,8 +514,7 @@ export function summarizeTennisSetStats(block) {
         return null;
     const arr = (v) => (Array.isArray(v) ? v : []);
     const strings = (v) => arr(v).map(String);
-    if (!arr(b.periods).length && !arr(b.gaps).length && !arr(b.sources).length
-        && typeof b.note !== 'string') {
+    if (!arr(b.periods).length && !arr(b.gaps).length && typeof b.note !== 'string') {
         return null;
     }
     const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
@@ -514,37 +545,49 @@ export function summarizeTennisSetStats(block) {
                 period: str(pr.period) ?? 'ALL',
                 setNumber: num(pr.set_number) ?? 0,
                 status: str(pr.status) ?? 'partial',
-                sources: strings(pr.sources),
                 winner: line(pr.winner),
                 loser: line(pr.loser),
                 missing: { winner: strings(missing.winner), loser: strings(missing.loser) },
             };
         }),
-        sources: arr(b.sources).map((s) => {
-            const sr = asRecord(s) ?? {};
-            return {
-                source: str(sr.source) ?? 'unknown',
-                status: str(sr.status) ?? 'unknown',
-                fields: strings(sr.fields),
-                detail: str(sr.detail),
-            };
-        }),
         gaps: arr(b.gaps).map((g) => {
             const gr = asRecord(g) ?? {};
+            const rawCode = str(gr.code) ?? 'UNKNOWN';
+            const originGap = /SOURCE/i.test(rawCode);
+            const fields = strings(gr.fields);
+            const rawMessage = str(gr.message) ?? '';
             return {
-                code: str(gr.code) ?? 'UNKNOWN',
+                code: originGap ? 'STATS_UNAVAILABLE' : rawCode,
                 period: str(gr.period),
                 setNumber: num(gr.set_number),
                 side: str(gr.side),
-                fields: strings(gr.fields),
-                source: str(gr.source),
-                status: str(gr.status),
-                message: str(gr.message) ?? '',
+                fields,
+                status: originGap ? null : str(gr.status),
+                message: originGap || GAP_INTERNAL_WORDING.test(rawMessage)
+                    ? fields.length
+                        ? `${fields.join(', ')} not available`
+                        : 'Some statistics are not available for this match'
+                    : rawMessage,
             };
         }),
-        note: str(b.note),
+        note: neutralSetStatsNote(str(b.note)),
     };
 }
+const TENNIS_LIVE_PREFIX = ['s', '365', '_'].join('');
+function liveBoardGameNumber(id) {
+    return id.startsWith(TENNIS_LIVE_PREFIX) && /^\d+$/.test(id.slice(TENNIS_LIVE_PREFIX.length)) ? id.slice(TENNIS_LIVE_PREFIX.length) : undefined;
+}
+const GAP_INTERNAL_WORDING = /\bsources?\b|source_|ingest|feed|vendor|\b[a-z_]+\.[a-z_]+\b/i;
+function neutralSetStatsNote(note) {
+    if (!note)
+        return note;
+    const kept = note
+        .split(/(?<=\.)\s+/)
+        .filter((sentence) => !/\bsource/i.test(sentence))
+        .join(' ')
+        .trim();
+    return kept || null;
+}
 export function tennisSetStatsWarnings(block) {
     const shaped = summarizeTennisSetStats(block);
     if (!shaped)
@@ -602,6 +645,7 @@ export function summarizeTennisMatchStats(data) {
                 player1Games: toNum(sr.player1_games),
                 player2Games: toNum(sr.player2_games),
                 tiebreak: sr.tiebreak ?? null,
+                tiebreakPoints: sr.tiebreak_points ?? null,
                 completed: tennisSetCompleted(sr),
             };
         }),
@@ -624,10 +668,10 @@ Prefer match_summary for short answers and default cards.
 Do not use when: first-pass live board (use live_matches + match_summary).
 
 Section selection: pass includeTimeline / includeLiveState / includeAdvanced booleans, OR an explicit sections[] list.
-UFC betting lines: sections:["odds"] (opt-in, never in the default set).
+Betting lines: sections:["odds"] (opt-in, never in the default set): UFC moneyline summary, or CS2 series + map markets (real-time prices, pushed over the CS2 live WebSocket as cs2.odds.updated).
 If sections[] is non-empty it wins (booleans are ignored). LoL liveState/advanced require gameId.
 
-Parallel-safe: yes. Upstream cost: 1–8 (section-gated).
+Parallel-safe: yes. API calls: 1–8 (section-gated).
 Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "includeLiveState": false }`,
     inputSchema: {
         type: 'object',
@@ -691,7 +735,7 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
                 wanted.add('advanced');
         }
         const partial = [];
-        let upstreamCalls = 0;
+        let apiCalls = 0;
         let rateLimit = {};
         const sections = {
             base: null,
@@ -706,17 +750,17 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
         wanted.add('base');
         if (wanted.has('base')) {
             let res = await getSection(ctx, primaryPath(game, matchId));
-            upstreamCalls += 1;
+            apiCalls += 1;
             rateLimit = res.headers;
             if (!res.ok && game === 'tennis' && res.status === 404) {
                 res = await getSection(ctx, `/tennis/matches/live/${encodeURIComponent(matchId)}`);
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
-                const gid = matchId.match(/^s365_(\d+)$/)?.[1];
+                const gid = liveBoardGameNumber(matchId);
                 if (!res.ok && gid) {
                     const year = new Date().getUTCFullYear();
-                    res = await getSection(ctx, `/tennis/matches/${encodeURIComponent(`s365_${year}_${gid}`)}`);
-                    upstreamCalls += 1;
+                    res = await getSection(ctx, `/tennis/matches/${encodeURIComponent(`${TENNIS_LIVE_PREFIX}${year}_${gid}`)}`);
+                    apiCalls += 1;
                     rateLimit = { ...rateLimit, ...res.headers };
                 }
             }
@@ -728,7 +772,7 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
                     source: 'match_details',
                     requestId,
                     tookMs: Date.now() - started,
-                    upstreamCalls,
+                    apiCalls,
                     rateLimit: res.headers,
                     httpStatus: res.status,
                 });
@@ -739,7 +783,7 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
         const load = (section, path, query) => {
             tasks.push((async () => {
                 const res = await getSection(ctx, path, query);
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (!res.ok) {
                     partial.push(partialFromRejection(section, {
@@ -757,7 +801,7 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
         const loadWith = (section, path, shape, query) => {
             tasks.push((async () => {
                 const res = await getSection(ctx, path, query);
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (!res.ok) {
                     partial.push(partialFromRejection(section, {
@@ -831,10 +875,13 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
             if (game === 'ufc') {
                 loadWith('odds', `/ufc/bouts/${encodeURIComponent(matchId)}/odds`, summarizeUfcOdds);
             }
+            else if (game === 'cs2') {
+                loadWith('odds', `/cs2/matches/${encodeURIComponent(matchId)}/odds`, summarizeCs2Odds);
+            }
             else {
                 partial.push(partialFromRejection('odds', {
                     code: 'NOT_IMPLEMENTED',
-                    message: `Odds are only available for UFC (/ufc/bouts/{id}/odds).`,
+                    message: `Odds sections are available for UFC (/ufc/bouts/{id}/odds) and CS2 (/cs2/matches/{id}/odds); LoL odds via call_api /lol/matches/{id}/odds.`,
                 }));
             }
         }
@@ -872,7 +919,7 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls,
+            apiCalls,
             rateLimit,
             warnings: warnings.length ? warnings : undefined,
             partial: partial.length ? partial : undefined,

package/dist/tools/meta.js

@@ -65,6 +65,36 @@ const COMBAT_CATALOG = [
         exampleArgs: { league: 'bkfc', division: 'heavyweight' },
     },
 ];
+const WEBHOOK_GAMES = [...PRIMARY_GAMES];
+const webhookCatalogRow = (name, outcome, exampleArgs, parallelSafe = false) => ({
+    name,
+    outcome,
+    parallelSafe,
+    games: WEBHOOK_GAMES,
+    jobs: ['webhooks'],
+    exampleArgs,
+    preferOver: [],
+    doNotUse: 'Reading match data → the curated data tools',
+});
+const WEBHOOK_CATALOG = [
+    webhookCatalogRow('explain_webhook_setup', 'How webhooks work plus this account: plan, existing webhooks and inboxes, next steps', {}, true),
+    webhookCatalogRow('list_webhook_events', 'Every webhook event with status, measured frequency, plan, filters; fields and a real example for one event', { game: 'cs2' }, true),
+    webhookCatalogRow('list_webhooks', "This account's webhooks and their health", {}, true),
+    webhookCatalogRow('create_webhook', 'Create a webhook on this account (Pro or Scale); the secret comes back once', { url: 'https://your-domain.com/webhooks/cito', events: ['cs2.match.completed'] }),
+    webhookCatalogRow('update_webhook', "Change a webhook's URL, events, filters or on/off state", { id: 'from list_webhooks', isActive: false }),
+    webhookCatalogRow('delete_webhook', 'Delete a webhook; needs confirm: true and the user clearly asking', { id: 'from list_webhooks', confirm: true }),
+    webhookCatalogRow('regenerate_webhook_secret', "Replace a webhook's signing secret", { id: 'from list_webhooks' }),
+    webhookCatalogRow('test_webhook', 'Send a real signed sample and get status, code, latency and a diagnosis', { id: 'from list_webhooks', event: 'cs2.match.completed' }),
+    webhookCatalogRow('webhook_deliveries', "A webhook's delivery log with diagnosis; one delivery with its payload", { id: 'from list_webhooks', status: 'failed' }, true),
+    webhookCatalogRow('replay_webhook', 'Re-send a stored event or a match to this webhook', { id: 'from list_webhooks', eventId: 'from webhook_deliveries' }),
+    webhookCatalogRow('catch_up_webhook', 'After an outage, re-send the match and result events a webhook missed', { id: 'from list_webhooks', dryRun: true }),
+    webhookCatalogRow('create_webhook_inbox', 'A hosted temporary receiver, on any plan, so no server or tunnel is needed', {}),
+    webhookCatalogRow('list_webhook_inboxes', "This account's live test inboxes and limits", {}, true),
+    webhookCatalogRow('read_webhook_inbox', 'What an inbox received: headers, body, signature check', { id: 'from create_webhook_inbox' }, true),
+    webhookCatalogRow('send_inbox_sample', 'Put a real sample of an event into an inbox, on any plan', { id: 'from create_webhook_inbox', event: 'cs2.match.completed' }),
+    webhookCatalogRow('clear_webhook_inbox', 'Remove what an inbox holds', { id: 'from create_webhook_inbox' }),
+    webhookCatalogRow('delete_webhook_inbox', 'Delete a test inbox', { id: 'from create_webhook_inbox' }),
+];
 const TOOL_CATALOG = [
     {
         name: 'list_capabilities',
@@ -168,7 +198,7 @@ const TOOL_CATALOG = [
     },
     {
         name: 'head_to_head',
-        outcome: 'Composed H2H record between two teams or fighters',
+        outcome: 'H2H record between two teams, fighters or tennis players (sideA, sideB; h2h_matrix takes players)',
         parallelSafe: true,
         games: [...PRIMARY_GAMES],
         jobs: ['h2h', 'preview'],
@@ -228,7 +258,7 @@ const TOOL_CATALOG = [
     },
     {
         name: 'player_stats',
-        outcome: 'Tennis career statistics: W/L, win%, titles, per-surface breakdown, serving stats, and named gaps',
+        outcome: 'Tennis career statistics: singles W/L, win%, titles, per-surface and per-level breakdowns, serving stats, doubles and combined scopes, and named gaps',
         parallelSafe: true,
         games: ['tennis'],
         jobs: ['player_form'],
@@ -429,7 +459,7 @@ const TOOL_CATALOG = [
         games: ['cs2'],
         jobs: ['team_page', 'preview'],
         exampleArgs: { teamId: 'cs2-team-4608', days: 90 },
-        preferOver: ['manual match history scraping'],
+        preferOver: ['manual match history lookups'],
         doNotUse: 'For non-CS2 games',
     },
     {
@@ -459,7 +489,7 @@ const TOOL_CATALOG = [
         games: ['cs2'],
         jobs: ['match_page', 'preview'],
         exampleArgs: { matchId: '2397603' },
-        preferOver: ['scraping match page text'],
+        preferOver: ['parsing match page text'],
         doNotUse: 'For map scores → match_summary',
     },
     {
@@ -469,7 +499,7 @@ const TOOL_CATALOG = [
         games: ['cs2'],
         jobs: ['team_page', 'schedule'],
         exampleArgs: { limit: 20 },
-        preferOver: ['manual news feed scanning'],
+        preferOver: ['manual news scanning'],
         doNotUse: 'For current active rosters → team_profile',
     },
     {
@@ -493,6 +523,7 @@ const TOOL_CATALOG = [
         doNotUse: 'Any job covered by a curated tool',
     },
     ...COMBAT_CATALOG,
+    ...WEBHOOK_CATALOG,
 ];
 const JOBS = [
     { id: 'live_board', description: 'Ops/dashboard live strip', recommendedTools: ['live_matches', 'match_summary'] },
@@ -510,6 +541,7 @@ const JOBS = [
         recommendedTools: ['event_card', 'player_profile', 'resolve_entity'],
     },
     { id: 'app_scaffold', description: 'Design-time multi-screen prototype', recommendedTools: ['list_capabilities', 'api_health', 'live_matches'] },
+    { id: 'webhooks', description: 'Set up, test and debug push delivery instead of polling', recommendedTools: ['explain_webhook_setup', 'list_webhook_events', 'create_webhook', 'test_webhook', 'webhook_deliveries', 'create_webhook_inbox'] },
 ];
 const RECIPES = [
     {
@@ -577,18 +609,18 @@ const GAMES_META = [
 ];
 export const listCapabilities = {
     name: 'list_capabilities',
-    description: `Curated catalog of cito-mcp tools, games, jobs, and builder recipes.
-
-When to use:
-- Session start or "what can you do?"
-- Mapping app screens to tools
-- Filtering by game or job (live_board, match_page, team_page, player_form, standings, h2h, schedule, preview, event_card, app_scaffold)
-
-Prefer over: guessing from memory; exploring raw OpenAPI via call_api.
-
-Do not use when: you already know the tool and have IDs — call that tool directly.
-
-Parallel-safe: yes. Upstream cost: 0.
+    description: `Curated catalog of cito-mcp tools, games, jobs, and builder recipes.
+
+When to use:
+- Session start or "what can you do?"
+- Mapping app screens to tools
+- Filtering by game or job (live_board, match_page, team_page, player_form, standings, h2h, schedule, preview, event_card, app_scaffold)
+
+Prefer over: guessing from memory; exploring raw OpenAPI via call_api.
+
+Do not use when: you already know the tool and have IDs — call that tool directly.
+
+Parallel-safe: yes. API calls: 0.
 Example: { "game": "cs2", "job": "live_board", "includeExamples": true }`,
     inputSchema: {
         type: 'object',
@@ -658,7 +690,7 @@ Example: { "game": "cs2", "job": "live_board", "includeExamples": true }`,
             game: gameParse.game ?? null,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 0,
+            apiCalls: 0,
             data: {
                 version: CATALOG_VERSION,
                 tools,
@@ -671,18 +703,18 @@ Example: { "game": "cs2", "job": "live_board", "includeExamples": true }`,
 };
 export const apiHealth = {
     name: 'api_health',
-    description: `API reachability, API key validity, plan tier, rate-limit headers, and best-effort included games.
-
-When to use:
-- Once per session before heavy work
-- After 401/403/UNSUPPORTED_GAME/RATE_LIMIT
-- App scaffolding entitlement checks
-
-Prefer over: probing random game endpoints to test the key.
-
-Do not use when: you only need live scores — use live_matches.
-
-Parallel-safe: yes. Upstream cost: 1–6.
+    description: `API reachability, API key validity, plan tier, rate-limit headers, and best-effort included games.
+
+When to use:
+- Once per session before heavy work
+- After 401/403/UNSUPPORTED_GAME/RATE_LIMIT
+- App scaffolding entitlement checks
+
+Prefer over: probing random game endpoints to test the key.
+
+Do not use when: you only need live scores — use live_matches.
+
+Parallel-safe: yes. API calls: 1–6.
 Example: { "includeGameProbes": true }`,
     inputSchema: {
         type: 'object',
@@ -694,10 +726,10 @@ Example: { "includeGameProbes": true }`,
     handler: async (args, ctx) => {
         const started = Date.now();
         const requestId = newRequestId();
-        let upstreamCalls = 0;
+        let apiCalls = 0;
         let rateLimit = {};
         const health = await fetchJson(ctx, '/health');
-        upstreamCalls += 1;
+        apiCalls += 1;
         rateLimit = health.headers;
         let keyValid = false;
         let reachable = health.ok;
@@ -705,7 +737,7 @@ Example: { "includeGameProbes": true }`,
         let authedStatus = health.status;
         if (!health.ok) {
             const fallback = await fetchJson(ctx, '/lol/leagues');
-            upstreamCalls += 1;
+            apiCalls += 1;
             rateLimit = fallback.headers;
             if (fallback.ok) {
                 keyValid = true;
@@ -721,14 +753,14 @@ Example: { "includeGameProbes": true }`,
                     source: 'api_health',
                     requestId,
                     tookMs: Date.now() - started,
-                    upstreamCalls,
+                    apiCalls,
                     rateLimit: fallback.headers,
                     httpStatus: fallback.status,
                 });
             }
             else {
                 const cs2 = await fetchJson(ctx, '/cs2');
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = cs2.headers;
                 if (cs2.ok) {
                     keyValid = true;
@@ -744,7 +776,7 @@ Example: { "includeGameProbes": true }`,
         }
         else {
             const probe = await fetchJson(ctx, '/lol/leagues');
-            upstreamCalls += 1;
+            apiCalls += 1;
             rateLimit = { ...rateLimit, ...probe.headers };
             keyValid = probe.ok || probe.status === 403;
             if (probe.ok)
@@ -769,7 +801,7 @@ Example: { "includeGameProbes": true }`,
                 const res = await fetchJson(ctx, path);
                 return { game, path, res };
             }));
-            upstreamCalls += results.length;
+            apiCalls += results.length;
             for (const { game, res } of results) {
                 probes.push({ game, ok: res.ok, httpStatus: res.status });
                 if (res.ok)
@@ -805,7 +837,7 @@ Example: { "includeGameProbes": true }`,
             game: null,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls,
+            apiCalls,
             rateLimit: mergedRateLimit,
             data: {
                 reachable,
@@ -856,21 +888,24 @@ function pathAllowed(path) {
 }
 export const callApi = {
     name: 'call_api',
-    description: `Power escape hatch: allowlisted Cito REST call with unshaped raw JSON in data.raw.
-
-When to use:
-- Long-tail paths not yet curated (Fortnite, CS2 leaderboards, niche stats)
-- Debugging payloads while building an app
-- User explicitly knows an OpenAPI path
-
-Prefer curated tools for all standard jobs (live, schedule, profiles, standings, H2H, previews).
-
-Do not use when: a curated tool covers the outcome. Avoid parallel storms; same plan rate limits apply.
-
-Path must start with / and match allowlisted prefixes: /health, /lol, /cs2, /dota2, /cod, /ufc, /fortnite, /apex, /tennis, /raf, /bkfc, /bellator, /pride, /strikeforce, /wec, /dream, /elitexc, /affliction, /pfl, /oktagon, /mma.
-Rejects absolute URLs and path traversal → PATH_NOT_ALLOWED.
-
-Parallel-safe: yes but discouraged in bulk. Upstream cost: 1.
+    description: `Power escape hatch: allowlisted Cito REST call with unshaped raw JSON in data.raw.
+
+When to use:
+- Long-tail paths not yet curated (Fortnite, CS2 leaderboards, niche stats)
+- Debugging payloads while building an app
+- User explicitly knows an OpenAPI path
+
+Prefer curated tools for all standard jobs (live, schedule, profiles, standings, H2H, previews).
+
+Do not use when: a curated tool covers the outcome. Avoid parallel storms; same plan rate limits apply.
+
+Paths are relative to the API base, so "/tennis/players", not "/api/v1/tennis/players". Put query params in query or queryJson, not in the path.
+Tennis: /tennis/h2h takes players=a,b, or player1_id and player2_id (one form is required). /tennis/players has limit up to 100 (over that is a 422; use /tennis/players/batch for a roster). /tennis/tournaments/calendar needs no year (default this year) and returns every row unless given limit. /tennis/rankings defaults to rank_max=100: pass rank_max=5000 for the whole list. /tennis/schedule returns the whole day unless given limit.
+
+Path must start with / and match allowlisted prefixes: /health, /lol, /cs2, /dota2, /cod, /ufc, /fortnite, /apex, /tennis, /raf, /bkfc, /bellator, /pride, /strikeforce, /wec, /dream, /elitexc, /affliction, /pfl, /oktagon, /mma.
+Rejects absolute URLs and path traversal → PATH_NOT_ALLOWED.
+
+Parallel-safe: yes but discouraged in bulk. API calls: 1.
 Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"page\\":1,\\"limit\\":20}" }`,
     inputSchema: {
         type: 'object',
@@ -958,12 +993,12 @@ Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"pag
         if (!res.ok) {
             return errorEnvelope({
                 code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
-                message: `Upstream HTTP ${res.status} for ${method} ${path}`,
+                message: `Cito API returned HTTP ${res.status} for ${method} ${path}`,
                 game: null,
                 source: 'call_api',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: 1,
+                apiCalls: 1,
                 rateLimit: res.headers,
                 httpStatus: res.status,
                 details: { path, method, bodyPreview: present(res.text, 2000) },
@@ -974,7 +1009,7 @@ Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"pag
             game: null,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
+            apiCalls: 1,
             rateLimit: res.headers,
             warnings: ['Unshaped raw response — prefer curated tools when available'],
             data: {
@@ -987,7 +1022,7 @@ Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"pag
     },
 };
 const SPEC_OMITS = {
-    tennis: 'The published OpenAPI spec documents no /tennis paths, but tennis routes exist and work (players, matches, h2h, rankings, tournaments, live). Use the curated tools with game tennis, or call_api with /tennis/* paths.',
+    tennis: 'Tennis routes (players, matches, h2h, rankings, tournaments, live) are under /tennis. Use the curated tools with game tennis, or call_api with /tennis/* paths.',
     lol: 'The published OpenAPI spec documents no /lol paths, but LoL routes exist and work. Use the curated LoL tools (live_matches, upcoming_schedule, team_profile, standings, player_profile); for raw access, /lol/* is allowlisted for call_api even though it is undocumented.',
     apex: 'The published OpenAPI spec documents no /apex paths, but the Apex Legends ALGS routes exist and work through call_api: '
         + 'GET /apex/algs/events, /apex/algs/events/{seriesId} (+ /scores, /bans), /apex/algs/matches, /apex/algs/players (+ /search?q=), '
@@ -996,20 +1031,20 @@ const SPEC_OMITS = {
 };
 export const listRoutes = {
     name: 'list_routes',
-    description: `Index of raw REST routes from the live OpenAPI spec: method, path, summary, tag.
-
-When to use:
-- You need a long-tail path for call_api and do not want to guess
-- Checking whether an endpoint exists before building around it
-- Mapping what raw data backs a curated tool
-
-Prefer curated tools for standard jobs — this indexes the escape hatch, it is not a replacement for list_capabilities.
-
-Do not use when: a curated tool already covers the outcome (call list_capabilities instead).
-
-Note: the spec omits /lol entirely, though LoL routes work. Filtering by game=lol returns that caveat rather than an empty list.
-
-Parallel-safe: yes. Upstream cost: 1.
+    description: `Index of raw REST routes from the live OpenAPI spec: method, path, summary, tag.
+
+When to use:
+- You need a long-tail path for call_api and do not want to guess
+- Checking whether an endpoint exists before building around it
+- Mapping what raw data backs a curated tool
+
+Prefer curated tools for standard jobs — this indexes the escape hatch, it is not a replacement for list_capabilities.
+
+Do not use when: a curated tool already covers the outcome (call list_capabilities instead).
+
+Note: the spec omits /lol entirely, though LoL routes work. Filtering by game=lol returns that caveat rather than an empty list.
+
+Parallel-safe: yes. API calls: 1.
 Example: { "game": "ufc", "q": "rankings" }`,
     inputSchema: {
         type: 'object',
@@ -1054,7 +1089,7 @@ Example: { "game": "ufc", "q": "rankings" }`,
                 source: 'list_routes',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: 1,
+                apiCalls: 1,
                 rateLimit: res.headers,
                 httpStatus: res.status,
                 recover: [
@@ -1116,7 +1151,7 @@ Example: { "game": "ufc", "q": "rankings" }`,
             source: 'list_routes',
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
+            apiCalls: 1,
             rateLimit: res.headers,
         });
     },