cito-mcp 0.4.4 → 0.4.6

package/dist/tools/odds.js

@@ -1,23 +1,6 @@
-/**
- * tennis_odds — the betting-odds surface for tennis (TENNIS-24).
- *
- * WHY THIS EXISTS
- * The tennis API serves three odds routes, and NONE of them had a tool. Odds are
- * a headline feature of the paid tiers and one of the most common reasons to buy
- * a sports API, so a builder had to discover /tennis/odds/* through call_api or
- * the docs. This closes that gap.
- *
- * Coverage is genuinely partial upstream, and the tool says so rather than
- * returning an empty success: /tennis/odds/{id} answers with
- * `coverage: { odds: false }` and an empty bookmakers[] for any match the feed
- * has no prices for (verified against atp_2026_560, which returned exactly
- * that). An agent that cannot tell "no odds exist for this match" from "the call
- * failed" will invent a price, so the response distinguishes the two.
- */
 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';
-/** A bookmaker row: { key, title, last_update, markets: [{ key, outcomes: [{ name, price }] }] }. */
 function normalizeBookmaker(row) {
     const r = asRecord(row) ?? {};
     const markets = (Array.isArray(r.markets) ? r.markets : []).map((mk) => {
@@ -26,7 +9,6 @@ function normalizeBookmaker(row) {
             const oc = asRecord(o) ?? {};
             return {
                 name: pickString(oc.name) ?? null,
-                // Decimal odds as the feed supplies them; never recomputed or implied.
                 price: typeof oc.price === 'number' && Number.isFinite(oc.price) ? oc.price : null,
                 point: typeof oc.point === 'number' && Number.isFinite(oc.point) ? oc.point : null,
             };
@@ -34,8 +16,6 @@ function normalizeBookmaker(row) {
         return {
             market: pickString(m.key) ?? null,
             outcomes,
-            // Implied probability from the prices actually returned, so a caller does
-            // not have to redo the arithmetic. Null when any price is missing.
             impliedProbabilities: (() => {
                 const prices = outcomes.map((o) => o.price).filter((p) => p !== null && p > 1);
                 if (prices.length !== outcomes.length || prices.length === 0)
@@ -53,19 +33,8 @@ function normalizeBookmaker(row) {
         markets,
     };
 }
-/**
- * The one tennis-odds projection, shared by `tennis_odds` and `match_details`.
- *
- * Both surfaces read the same REST payload, and before this the two disagreed:
- * `tennis_odds scope=match` served FanDuel 1.105 / Matchbook 1.13 with implied
- * probabilities while `match_details sections:["odds"]` answered
- * NOT_IMPLEMENTED "UFC only today" for the same match id. A caller could not
- * tell whether tennis odds existed. One shaper, one answer.
- */
 export function summarizeTennisOdds(data) {
     const root = asRecord(data) ?? {};
-    // fetchJson hands back the whole REST envelope; the unit tests feed the inner
-    // object directly. Accept both.
     const payload = asRecord(root.data) ?? root;
     const coverage = asRecord(payload.coverage) ?? {};
     const bookmakers = (Array.isArray(payload.bookmakers) ? payload.bookmakers : []).map(normalizeBookmaker);
@@ -74,11 +43,8 @@ export function summarizeTennisOdds(data) {
         matchId: pickString(payload.match_id) ?? null,
         oddsFormat: pickString(payload.odds_format) ?? 'decimal',
         commenceTime: pickString(payload.commence_time) ?? null,
-        /** Upstream says the feed has since moved on; the prices are still real. */
         stale: payload.stale === true,
         bookmakers,
-        // Explicit, because an empty bookmakers[] is otherwise indistinguishable
-        // from a failed scrape.
         oddsAvailable: hasOdds,
         note: hasOdds
             ? null
@@ -216,21 +182,11 @@ Parallel-safe: yes. Upstream cost: 1.`,
                     player2: { name: pickString(away.name) ?? null, id: awayId },
                     bookmakers: Array.isArray(r.bookmakers) ? r.bookmakers.map((b) => pickString(b) ?? null) : [],
                     live: r.live === true,
-                    /**
-                     * The feed does not join its odds events to matches: every row of
-                     * /tennis/odds/upcoming carries match_id:null (verified on all 94
-                     * rows), so a caller could not go odds -> match and the two halves of
-                     * a betting UI could not be stitched together. matchId itself is left
-                     * exactly as the feed states it — null stays null, because inventing
-                     * one would be worse — and the join key that DOES resolve is named
-                     * alongside it.
-                     */
                     joinKey: matchId
                         ? { kind: 'matchId', matchId }
                         : oddsEventId
                             ? { kind: 'oddsEventId', oddsEventId }
                             : null,
-                    /** Player ids present on the row, which identify the fixture when matchId is null. */
                     playerIds: [homeId, awayId].filter((x) => Boolean(x)),
                 };
             });
@@ -280,23 +236,6 @@ Parallel-safe: yes. Upstream cost: 1.`,
             });
         }
         const summary = summarizeTennisOdds(res.data);
-        /**
-         * A match id that does not exist and a real match nobody is quoting look
-         * identical on the wire.
-         *
-         * /tennis/odds/{id} answers HTTP 200 with `coverage: { odds: false }` for
-         * EVERY id it does not know — verified for `s365_2026_0000000` (a plausible
-         * typo) and for the literal string `total-garbage-id`, both of which came
-         * back 200/odds:false. So the status code cannot tell them apart, and this
-         * tool used to report a typo as "upstream coverage gap, not an error" with
-         * ok:true — leaving the caller to conclude a real match has no prices.
-         *
-         * /tennis/matches/{id} DOES 404 for those same ids (verified: 404 NOT_FOUND
-         * for both, 200 for a real one), so that is the discriminator. It costs one
-         * extra call, and only on the no-odds path, where the answer is otherwise
-         * useless. player_stats already gets this right (404 -> NOT_FOUND); this
-         * makes odds agree with it.
-         */
         let matchExists = null;
         if (summary.oddsAvailable !== true) {
             const probe = await fetchJson(ctx, `/tennis/matches/${encodeURIComponent(matchId)}`);
@@ -304,7 +243,6 @@ Parallel-safe: yes. Upstream cost: 1.`,
             rateLimit = { ...rateLimit, ...probe.headers };
             matchExists = probe.ok;
             if (!matchExists) {
-                // Live ids live at /matches/live/{id} until the match archives.
                 const liveProbe = await fetchJson(ctx, `/tennis/matches/live/${encodeURIComponent(matchId)}`);
                 upstreamCalls += 1;
                 rateLimit = { ...rateLimit, ...liveProbe.headers };
@@ -339,12 +277,8 @@ Parallel-safe: yes. Upstream cost: 1.`,
             data: {
                 title: `Tennis ${scopeRaw} odds — ${matchId}`,
                 scope: scopeRaw,
-                // One projection, the same object match_details sections:["odds"]
-                // returns. See summarizeTennisOdds.
                 ...summary,
                 matchId: summary.matchId ?? matchId,
-                // true when the no-odds path verified the match exists; null when odds
-                // existed so no verification was needed.
                 matchExists,
             },
         });

package/dist/tools/player.js

@@ -1,6 +1,3 @@
-/**
- * player_profile
- */
 import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, unwrapPayload, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
 import { normalizeMatch } from './normalize.js';
@@ -9,13 +6,7 @@ function identityFrom(game, raw, idHint, slugHint) {
     const r = asRecord(raw) ?? {};
     const id = pickString(r.id, r.playerId, r.lolPlayerId, r.codPlayerId, idHint, slugHint) ?? 'unknown';
     const slug = pickString(r.slug, slugHint);
-    // currentIgn FIRST for LoL. The row carries currentIgn "Faker" and realName
-    // "Sanghyeok Lee" but no `name`, so this fell through every key to the id and
-    // served a raw UUID as the player's display name.
     const name = pickString(r.name, r.currentIgn, r.ign, r.full_name, r.nickname, r.displayName, r.tag, r.realName, slug, id) ?? id;
-    // currentTeam is a STRING on the LoL row ("T1"), not an object, so asRecord
-    // returned null and the profile reported a team of "?" while the slug sat
-    // right there in currentTeamSlug.
     const currentTeamName = pickString(r.currentTeam);
     const currentTeamSlug = pickString(r.currentTeamSlug, r.teamSlug, r.orgSlug);
     const team = asRecord(r.team) ??
@@ -40,40 +31,11 @@ function identityFrom(game, raw, idHint, slugHint) {
             : null,
         role: pickString(r.role, r.position) ?? null,
         nationality: pickString(r.nationality, r.country) ?? null,
-        /**
-         * Always present, keys always present, null when the upstream has no photo.
-         *
-         * REST has carried headshot/body/proxied images on /ufc/fighters/{slug} all
-         * along; this shaper silently dropped them, so every agent concluded the
-         * product had no images and either shipped faceless UIs or N+1'd call_api
-         * per fighter to dig them out. Emitting explicit nulls is the point: silence
-         * reads as "not supported", null reads as "not available for this one".
-         *
-         * proxiedImageUrl is the one builders should prefer — it is served from our
-         * own domain, so it works from a browser without hotlink/CORS trouble.
-         */
         images: {
-            // Tennis supplies exactly one likeness, `portrait_url` (a Wikimedia
-            // Commons portrait), and no separate square headshot crop. Before this,
-            // the shaper read only headshotUrl/bodyImageUrl/imageUrl/photoUrl — none of
-            // which the tennis route emits — so every tennis profile shipped four
-            // explicit nulls while a perfectly good photo sat one key away.
             headshotUrl: pickString(r.headshotUrl, r.headshot, r.portrait_url) ?? null,
             bodyImageUrl: pickString(r.bodyImageUrl, r.fullBodyImageUrl) ?? null,
             imageUrl: pickString(r.imageUrl, r.image, r.photoUrl, r.portrait_url) ?? null,
             proxiedImageUrl: pickString(r.proxiedImageUrl, r.proxiedHeadshotUrl) ?? null,
-            /**
-             * The licence and the credit, carried with the URL.
-             *
-             * Commons portraits are mostly CC BY / CC BY-SA, which for commercial
-             * display generally obliges you to name the author and state the licence.
-             * Handing back a bare URL and letting a builder render it silently is what
-             * gets a product a takedown letter, so the fields a UI must show travel in
-             * the same object as the image. `attribution` is null for public-domain
-             * and CC0 images, which need no credit — that is a fact, not missing data.
-             * Anything without a defensible licence has its URL removed upstream, so a
-             * non-null headshotUrl here always has a licence beside it.
-             */
             license: pickString(r.portrait_license) ?? null,
             attribution: pickString(r.portrait_attribution) ?? null,
             sourceUrl: pickString(r.portrait_source_url) ?? null,
@@ -82,17 +44,17 @@ function identityFrom(game, raw, idHint, slugHint) {
 }
 export const playerProfile = {
     name: 'player_profile',
-    description: `Player or UFC fighter profile: identity, current team, recent matches, and form/trends/radar when available.
-
-When to use:
-- "How is X playing lately?"
-- Player page scaffold; form inputs for previews
-
-Prefer over: manual multi-call career/trends/matches via call_api.
-
-Do not use when: full team roster needed → team_profile; unresolved name → resolve_entity first.
-
-Parallel-safe: yes. Upstream cost: 2–5.
+    description: `Player or UFC fighter profile: identity, current team, recent matches, and form/trends/radar when available.
+
+When to use:
+- "How is X playing lately?"
+- Player page scaffold; form inputs for previews
+
+Prefer over: manual multi-call career/trends/matches via call_api.
+
+Do not use when: full team roster needed → team_profile; unresolved name → resolve_entity first.
+
+Parallel-safe: yes. Upstream cost: 2–5.
 Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includeTrends": true }`,
     inputSchema: {
         type: 'object',
@@ -172,7 +134,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
         else if (game === 'cs2')
             primaryPath = `/cs2/players/${encodeURIComponent(idOrSlug)}`;
         else if (game === 'dota2')
-            primaryPath = `/dota2/players`; // list/search; detail via radar
+            primaryPath = `/dota2/players`;
         else if (game === 'cod')
             primaryPath = `/cod/players/${encodeURIComponent(idOrSlug)}`;
         else if (game === 'ufc')
@@ -181,7 +143,6 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
             primaryPath = `/tennis/players/${encodeURIComponent(idOrSlug)}`;
         let playerRaw = null;
         if (game === 'dota2') {
-            // Prefer radar as primary signal; try list filter
             const list = await fetchJson(ctx, '/dota2/players', { query: { search: idOrSlug, limit: 5 } });
             upstreamCalls += 1;
             rateLimit = list.headers;
@@ -195,7 +156,6 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                     }) ?? rows[0] ?? null;
             }
             if (!playerRaw) {
-                // still try radar with idOrSlug
                 playerRaw = { id: idOrSlug, slug: idOrSlug, name: idOrSlug };
             }
         }
@@ -235,14 +195,6 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                     const rows = extractRows(res.data);
                     const first = asRecord(rows[0]);
                     if (first) {
-                        // NEVER let team history overwrite the player row's own team.
-                        // This endpoint returns showmatch and novelty orgs alongside the
-                        // real one, all marked status "current" — for Faker the first row
-                        // is literally "Faker", then "Captain Faker", then "KR with
-                        // Influencers". Taking rows[0] reported the player as their own
-                        // team. The player row's currentTeamSlug is the answer; history is
-                        // only a fallback, and then only for a row that looks like a real
-                        // club rather than the player's own name.
                         const rows2 = rows.map((row) => asRecord(row) ?? {});
                         const preferred = (player.team?.slug
                             ? rows2.find((x) => pickString(x.orgSlug, x.slug) === player.team?.slug)
@@ -271,9 +223,6 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
             })());
         }
         if (game === 'lol') {
-            // /lol/players/{id}/matches exists and returns the player's real match
-            // index; only tennis was wired to its equivalent, so every LoL profile
-            // shipped recentMatches: [].
             tasks.push((async () => {
                 const res = await fetchJson(ctx, `/lol/players/${encodeURIComponent(idOrSlug)}/matches`, {
                     query: { limit: String(recentLimit) },
@@ -290,10 +239,6 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                         .slice()
                         .sort((a, b) => startMs(b) - startMs(a))
                         .slice(0, recentLimit);
-                    // The index carries team SLUGS and no names, so labels read
-                    // "hle vs t1". Resolve the distinct slugs once — deduplicated and
-                    // capped — rather than a lookup per match, and fall back to the
-                    // slug when a lookup fails so a label is never blank.
                     const slugs = [
                         ...new Set(picked.flatMap((row) => {
                             const r = asRecord(row) ?? {};
@@ -477,9 +422,6 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                 if (res.ok) {
                     const metrics = unwrapPayload(res.data);
                     form = { summary: 'UFC fighter stats', trend: null, window: null, metrics };
-                    // form.metrics and seasonStats were the same object twice, byte
-                    // for byte. One copy. seasonStats stays for the games that have
-                    // seasons; a fighter has a career, not a season.
                 }
                 else {
                     partial.push(partialFromRejection('form', {
@@ -490,7 +432,6 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                 }
             })());
             tasks.push((async () => {
-                // Fight-by-fight history — /fights and /history are aliases on the API
                 const res = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(fighterKey)}/fights`, {
                     query: { limit: recentLimit },
                 });
@@ -501,24 +442,8 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                         .slice(0, recentLimit)
                         .map((row) => {
                         const r = asRecord(row) ?? {};
-                        // Merge the row's own corner fields (fighterSlug / opponent /
-                        // outcome) over the nested bout: they are the only place the two
-                        // sides exist on a history row, and without them every entry
-                        // came back team1:null, team2:null with the division as label.
                         const bout = { ...(asRecord(r.bout) ?? {}), ...r };
-                        // Never force 'completed'. A fighter's history endpoint also
-                        // returns bouts that are booked but not yet fought, and forcing
-                        // the status told agents that a future main event had already
-                        // happened (Hernandez vs Rodrigues, ufc-12928: status
-                        // 'confirmed', no method, no winner, event still scheduled,
-                        // reported as completed with result null). Let normalizeMatch
-                        // derive it from the result and the start time instead.
                         const m = normalizeMatch('ufc', bout);
-                        // Keep the normalized result OBJECT (method, round, time,
-                        // winnerSlug), the same shape match_preview and match_summary
-                        // return. This used to overwrite it with the string "win",
-                        // giving the profile a fourth result schema of its own. The
-                        // fighter's-eye view lives on outcome instead.
                         return {
                             ...m,
                             outcome: pickString(r.outcome)?.toLowerCase() ?? null,
@@ -528,7 +453,6 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                     });
                 }
                 else {
-                    // fallback history path
                     const hist = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(fighterKey)}/history`, {
                         query: { limit: recentLimit },
                     });
@@ -540,7 +464,6 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                             .map((row) => {
                             const r = asRecord(row) ?? {};
                             const bout = { ...(asRecord(r.bout) ?? {}), ...r };
-                            // Same as above: derive, never assert. See the note there.
                             return normalizeMatch('ufc', bout);
                         });
                     }
@@ -573,10 +496,6 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                     ...(player.slug ? { slug: player.slug } : {}),
                 },
             },
-            // Two rules, so a consumer can tell the difference. A field that can
-            // never apply to this game is OMITTED (a fighter has no team, no radar,
-            // no season). A field that applies but is unknown is NULL (division,
-            // flag). Sending team:null on every UFC profile forever said nothing.
             data: game === 'ufc'
                 ? {
                     player: (({ team, role, nationality, ...rest }) => { void team; void role; void nationality; return rest; })(player),
@@ -595,15 +514,6 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
         });
     },
 };
-/**
- * player_form (TENNIS-12).
- *
- * Tennis-only: recent-match form for one player (GET /tennis/players/{id}/form).
- * The upstream answers wins/losses/win_pct over the last N completed matches
- * plus the per-match rows (result, opponent, score, surface) and the player's
- * current rank + movement. This tool normalizes those rows and derives the
- * current W/L streak from the leading run, newest first.
- */
 const SURFACES = ['Hard', 'Clay', 'Grass'];
 function parseFormSurface(args) {
     const raw = typeof args.surface === 'string' ? args.surface.trim() : '';
@@ -631,17 +541,17 @@ function normalizeFormMatch(row) {
 }
 export const playerForm = {
     name: 'player_form',
-    description: `Tennis player form: W/L record over the last N completed matches, current win/loss streak, and per-match rows (opponent, score, surface). Optional surface filter (Hard/Clay/Grass).
-
-When to use:
-- "How is X playing lately?"; current streak; surface-specific record (e.g. clay last 5).
-
-Prefer over: player_profile (identity + career aggregates, no streak); raw form via call_api for agent-normalized rows.
-
-Do not use when: career totals/titles → player_profile with game tennis (wires /stats); ranking deltas → rankings_movers.
-
-Tennis-only. Limit defaults to 10 (max 50, matching the API). Upstream rows arrive newest-first; the streak is the leading run of that order.
-
+    description: `Tennis player form: W/L record over the last N completed matches, current win/loss streak, and per-match rows (opponent, score, surface). Optional surface filter (Hard/Clay/Grass).
+
+When to use:
+- "How is X playing lately?"; current streak; surface-specific record (e.g. clay last 5).
+
+Prefer over: player_profile (identity + career aggregates, no streak); raw form via call_api for agent-normalized rows.
+
+Do not use when: career totals/titles → player_profile with game tennis (wires /stats); ranking deltas → rankings_movers.
+
+Tennis-only. Limit defaults to 10 (max 50, matching the API). Upstream rows arrive newest-first; the streak is the leading run of that order.
+
 Parallel-safe: yes. Upstream cost: 1.`,
     inputSchema: {
         type: 'object',
@@ -732,7 +642,6 @@ Parallel-safe: yes. Upstream cost: 1.`,
         const root = asRecord(res.data);
         const body = asRecord(root?.data) ?? root ?? {};
         const matches = (Array.isArray(body.matches) ? body.matches : []).map(normalizeFormMatch);
-        // Upstream rows arrive newest-first: the streak is the leading run.
         let streakCount = 0;
         let streakResult = null;
         for (const m of matches) {
@@ -791,18 +700,18 @@ Parallel-safe: yes. Upstream cost: 1.`,
 };
 export const playerMatches = {
     name: 'player_matches',
-    description: `Tennis player match log: every archived match for one player, newest first, with opponent, tournament, round, surface and score.
-
-When to use:
-- "Show me Shelton's last 20 matches"; full match history; every match at a given tournament; filtering a player's record by surface.
-
-Prefer over: player_form (a W/L summary with a small window and a streak, not the log); call_api for /tennis/players/{id}/matches.
-
-Do not use when: aggregate totals, titles, or win% → player_stats; identity → player_profile; one match's box score → match_details.
-
-Tennis-only. Limit defaults to 20 (max 50). Rows arrive newest-first. Use
-surface to narrow to Hard/Clay/Grass; tournamentId pins one event.
-
+    description: `Tennis player match log: every archived match for one player, newest first, with opponent, tournament, round, surface and score.
+
+When to use:
+- "Show me Shelton's last 20 matches"; full match history; every match at a given tournament; filtering a player's record by surface.
+
+Prefer over: player_form (a W/L summary with a small window and a streak, not the log); call_api for /tennis/players/{id}/matches.
+
+Do not use when: aggregate totals, titles, or win% → player_stats; identity → player_profile; one match's box score → match_details.
+
+Tennis-only. Limit defaults to 20 (max 50). Rows arrive newest-first. Use
+surface to narrow to Hard/Clay/Grass; tournamentId pins one event.
+
 Parallel-safe: yes. Upstream cost: 1.`,
     inputSchema: {
         type: 'object',
@@ -884,16 +793,6 @@ Parallel-safe: yes. Upstream cost: 1.`,
         const body = asRecord(root?.data) ?? root ?? {};
         const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
         const allRows = Array.isArray(body.items) ? body.items : [];
-        /**
-         * Derive the player's display name from their own side of any match.
-         *
-         * The match-log payload carries no player_name at all (verified against the
-         * live route: top-level keys are just items/total/page/page_size/has_next/
-         * has_prev/success/total_pages), so the earlier version titled every log
-         * "<id> match log" and reported playerName: null. Each row does carry the
-         * winner and loser objects, so whichever side matches the requested id gives
-         * a real name with no extra upstream call.
-         */
         let derivedName = null;
         for (const row of allRows) {
             const r = asRecord(row) ?? {};
@@ -908,11 +807,6 @@ Parallel-safe: yes. Upstream cost: 1.`,
             if (derivedName)
                 break;
         }
-        /**
-         * The route ignores ?limit= (verified: limit=5 returned 20), so the bound is
-         * applied here. total comes from the upstream header so callers still learn
-         * how many matches exist beyond this page.
-         */
         const total = typeof body.total === 'number' ? body.total : allRows.length;
         const rows = allRows.slice(0, limit).map((row) => {
             const r = asRecord(row) ?? {};
@@ -920,9 +814,6 @@ Parallel-safe: yes. Upstream cost: 1.`,
             const loser = asRecord(r.loser) ?? {};
             const winnerId = pickString(r.winner_id, winner.id);
             const lost = winnerId !== null && winnerId !== playerId;
-            // Opponent is whichever side is not this player. When the row's winner
-            // does not match the requested id the player lost, so the opponent is the
-            // winner.
             const opponent = lost ? winner : loser;
             return {
                 matchId: pickString(r.id, r.match_id) ?? null,
@@ -971,8 +862,6 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 tournamentFilter: tournamentId || null,
                 matches: rows,
                 total,
-                // Named explicitly because the bound is applied locally: the upstream
-                // route returns everything and ignores ?limit=.
                 returned: rows.length,
             },
         });
@@ -980,16 +869,16 @@ Parallel-safe: yes. Upstream cost: 1.`,
 };
 export const playerStats = {
     name: 'player_stats',
-    description: `Tennis player career statistics: W/L totals, win percentage, titles, Grand Slam and Masters titles, plus per-surface and per-level breakdowns. Optional surface/year filters.
-
-When to use:
-- "How many titles does Alcaraz have?"; career win%; Grand Slam title count; record on clay; a season-scoped record.
-
-Prefer over: player_profile (identity + a summary block, no breakdowns); player_matches (individual rows, no aggregates).
-
-Do not use when: the match log → player_matches; ranking over time → player_rankings_history.
-
-Tennis-only. Filters are surface (Hard/Clay/Grass/Carpet) and yearFrom/yearTo.
+    description: `Tennis player career statistics: W/L totals, win percentage, titles, Grand Slam and Masters titles, plus per-surface and per-level breakdowns. Optional surface/year filters.
+
+When to use:
+- "How many titles does Alcaraz have?"; career win%; Grand Slam title count; record on clay; a season-scoped record.
+
+Prefer over: player_profile (identity + a summary block, no breakdowns); player_matches (individual rows, no aggregates).
+
+Do not use when: the match log → player_matches; ranking over time → player_rankings_history.
+
+Tennis-only. Filters are surface (Hard/Clay/Grass/Carpet) and yearFrom/yearTo.
 Upstream cost: 1.`,
     inputSchema: {
         type: 'object',
@@ -1080,21 +969,6 @@ Upstream cost: 1.`,
         const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
         const summary = asRecord(body.career_summary) ?? {};
         const filters = asRecord(body.filters) ?? {};
-        /**
-         * Map an arbitrary {label: value} breakdown without assuming the upstream
-         * key set: the endpoint has grown keys before and a hardcoded list would
-         * silently drop new ones.
-         *
-         * Values that are OBJECTS are skipped rather than coerced to null. That
-         * coercion is exactly what broke `bySurface`: the endpoint publishes
-         * `surface_breakdown: { hard: { matches, won, lost, win_pct, titles }, ... }`
-         * (one object per surface) and this ran each value through Number(), so
-         * every tennis player's surface split came back
-         * `{hard:null, clay:null, grass:null, carpet:null}` — permanently, on every
-         * profile, while `player_profile` served the identical numbers from the
-         * identical source. A key that is present and null reads as "this player
-         * has no clay record", which is a worse lie than omitting it.
-         */
         const camel = (key) => key.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
         const flatNumeric = (value) => {
             const rec = asRecord(value);
@@ -1108,12 +982,6 @@ Upstream cost: 1.`,
             }
             return Object.keys(out).length > 0 ? out : null;
         };
-        /**
-         * One OBJECT per bucket (surface, level, …), with the bucket's own fields
-         * renamed to stable camelCase keys. A bucket that arrives as a bare number
-         * is preserved as { value }, so a shape change narrows the payload instead
-         * of emptying it.
-         */
         const bucketBlock = (value, fields) => {
             const rec = asRecord(value);
             if (!rec)
@@ -1148,8 +1016,6 @@ Upstream cost: 1.`,
         const returnStats = flatNumeric(body.return_stats);
         const clutchAndSituational = flatNumeric(body.clutch_and_situational);
         const grandSlamBreakdown = bucketBlock(body.grand_slam_breakdown, SURFACE_FIELDS);
-        // Sections this endpoint declares but does not publish for this player.
-        // Named explicitly so an absent key is not read as "no such data exists".
         const unavailable = {};
         if (!byLevel) {
             unavailable.byLevel =

package/dist/tools/rankings.js

@@ -1,12 +1,3 @@
-/**
- * rankings_movers (TENNIS-07).
- *
- * Tennis-only: biggest ranking movers between the latest ranking list and its
- * predecessor (GET /tennis/rankings/movers). The upstream payload already
- * carries new_entries[] and dropped[] alongside items[], so one tool covers
- * both halves of the deferred TENNIS-07 ask — there is no standalone
- * /rankings/new_entries route (it 404s; verified 2026-09-08).
- */
 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';
@@ -197,17 +188,6 @@ Parallel-safe: yes. Upstream cost: 1.`,
         const newEntries = (Array.isArray(body.new_entries) ? body.new_entries : []).map(normalizeEdge);
         const dropped = (Array.isArray(body.dropped) ? body.dropped : []).map(normalizeEdge);
         const total = typeof body.total === 'number' ? body.total : items.length;
-        /**
-         * How far apart the two lists actually are.
-         *
-         * `previous_date` is simply the next list the archive holds — it is NOT
-         * guaranteed to be last week. On 2026-09-12 it was 2026-06-08 against a
-         * current 2026-08-31: an 84-day gap, because the weekly archive ends
-         * 2026-06-08 and the only snapshots after it are the current ESPN-sourced
-         * pair. Calling that "week-over-week movers" told every caller that a
-         * three-month climb was a one-week climb. The interval is measured and
-         * reported instead of assumed.
-         */
         const rankingDate = pickString(body.ranking_date) ?? null;
         const previousDate = pickString(body.previous_date) ?? null;
         const gapDays = (() => {
@@ -253,9 +233,7 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 within,
                 rankingDate,
                 previousDate,
-                /** Real interval between the two lists; null when only one list exists. */
                 gapDays,
-                /** 'week-over-week' only when the gap really is about a week. */
                 comparisonWindow,
                 comparisonsAreWeekly: gapDays !== null && gapDays <= 8,
                 items,
@@ -376,22 +354,8 @@ Parallel-safe: yes. Upstream cost: 1.`,
         const inWindow = sinceRaw
             ? allHistory.filter((h) => h.date !== null && h.date >= sinceRaw)
             : allHistory;
-        /**
-         * The route IGNORES ?limit= — verified: `?limit=4` returned all 342 rows of
-         * Alcaraz's career with total:342 and hasMore:false. Asking for 4 and
-         * receiving 342 is not a bound, it is a payload the caller cannot control,
-         * so the bound is applied here.
-         *
-         * Rows arrive oldest-first because that is the order a chart wants. limit
-         * therefore keeps the most RECENT N (the tail), matching every other tool
-         * in this server: `player_matches` returns the newest rows and reports
-         * hasMore when older ones exist. The older end is what gets dropped, and
-         * oldestReturned/newestReturned say exactly which window came back.
-         */
         const total = inWindow.length;
         const history = total > limit ? inWindow.slice(total - limit) : inWindow;
-        // Best rank actually present in the returned window, so a caller can label a
-        // chart without recomputing. Null when the window is empty.
         const best = history.reduce((acc, h) => {
             if (h.rank === null)
                 return acc;
@@ -425,8 +389,6 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 since: sinceRaw || null,
                 bestRankInWindow: best,
                 history,
-                // The bound is applied locally because the route ignores ?limit=; state
-                // it so a caller does not read a short series as a short career.
                 totalInWindow: total,
                 returned: history.length,
                 omittedOlder: total - history.length,