cito-mcp 0.4.0 → 0.4.2

package/README.md

@@ -42,6 +42,19 @@ Composites multi-fetch server-side, return a **stable JSON envelope**, and isola
 
 **MCP is design-time / agent assistance.** Ship production backends with Cito REST + the user’s API key. Do not put multi-tenant traffic through this process.
 
+### Honest gaps, in-band
+
+Where the source data is partial, the tool says so instead of shipping a plausible-looking wrong value:
+
+| Situation | What the tool returns |
+| --- | --- |
+| The two ranking lists compared by `rankings_movers` are not a week apart | `gapDays` + `comparisonWindow` (`"12-week gap"`), `comparisonsAreWeekly: false`, and a warning naming both dates |
+| A tennis tournament draw is missing matches | `draw.shortRounds` (`["R128 45/64"]`), `draw.missingRounds`, `draw.complete` |
+| A stats section the endpoint does not publish | `player_stats.unavailable` names the section and why, rather than a block of nulls |
+| No bookmaker is quoting a match | `oddsAvailable: false` plus a note that it is a coverage gap, not an error |
+| The odds feed leaves `match_id` null | `joinKey` (`{kind:"oddsEventId", …}`) and `playerIds`, so the row is still joinable |
+| `search_entities` results that do not match at all | dropped, counted under `data.relevance.droppedBelowFloor`, with a warning naming them |
+
 ---
 
 ## Install
@@ -167,7 +180,7 @@ All tools are **read-only**. Names are `snake_case` with **no** `cito_` prefix (
 | `head_to_head` | Composed H2H (no first-class REST H2H) | Rivalry / series record; preview context | Single-side form only; live scores; standings | `game`, `sideA`, `sideB`, `entityType?`, `limit?`, `from?`, `to?` |
 | `standings` | League/event tables or world/division rankings | Playoff picture; UFC rankings; CDL / CS2 tables | Team form; live scores; match recaps | `game`, `scope?`, `leagueId?`, `tournamentId?`, `eventId?`, `season?`, `stage?`, `division?`, `limit?` |
 | `match_preview` | Pre-match briefing: sides, rosters/form, H2H stub | Upcoming deep link; pick’ems; preview cards | Completed recaps; deep live state | `game`, `matchId` **or** (`teamA` + `teamB`), `eventId?`, `includeH2H?`, `includeRosters?`, `recentLimit?` |
-| `event_card` | Event / fight-night card: identity + bouts in card order (main event first), each corner with photos, record, nickname, weight class; optional rankings | UFC card, CS2 event hub, tournament overview | Live-only strip; single match recap | `game`, `eventIdOrSlug` **or** `q`, `includeBouts?`, `includeStandings?`, `limit?` |
+| `event_card` | Event / fight-night card: identity + bouts in card order (main event first), each corner with photos, record, nickname, weight class; optional rankings. Tennis returns the draw bracket with per-round completeness | UFC card, CS2 event hub, tournament overview | Live-only strip; single match recap | `game`, `eventIdOrSlug` **or** `q`, `includeBouts?`, `includeStandings?`, `limit?`, `drawMaxMatches?` |
 | `list_routes` | Index of raw REST routes from the live OpenAPI spec (method, path, summary, tag) | Finding a long-tail path before `call_api`; checking an endpoint exists | A curated tool covers the outcome | `game?`, `q?`, `limit?` |
 | `call_api` | Allowlisted raw REST (`data.raw`) | Fortnite / long-tail paths; payload debugging | Any job covered by a curated tool | `path`, `method?`, `queryJson?`, `bodyJson?` |
 
@@ -199,6 +212,11 @@ When a key is `null` the image does not exist for that entity; when the whole
 `images` object is absent, upstream sent nothing for that side. The object is
 never partially shaped — if any image exists, all four keys are present.
 
+Tennis is the exception on purpose: the feed supplies a single `portrait_url`
+(Wikimedia) and no square crop, so that one URL fills both `headshotUrl` and
+`imageUrl`, and `proxiedImageUrl` stays `null` because only `ufc.com` URLs have
+a proxy. A card with the real photo slightly cropped beats a faceless card.
+
 ### Games
 
 | Game | Depth | Notes |
@@ -507,6 +525,35 @@ claude mcp add cito -e CITO_API_KEY=cito_… "--" npx -y cito-mcp
 
 ## Changelog (summary)
 
+### 0.4.2
+
+Second tennis correctness pass, from the 2026-09-12 re-sweep. Five defects, each reproduced from a raw payload and re-verified after the fix. Two were upstream (fixed on the API and verified with the 40/40 invariant gate); three were MCP-side.
+
+- **`tennis_odds` called a nonexistent match "no coverage".** `/tennis/odds/{id}` answers **HTTP 200 with `coverage.odds=false` for every id it does not know** — verified for `s365_2026_0000000` and for the literal `total-garbage-id`. So a typo and a genuine no-book gap were indistinguishable and both came back `ok:true`. `scope=match`/`live` now verify the id against `/tennis/matches/{id}` (which does 404) when no odds are quoted: unknown id → `NOT_FOUND` with recovery steps, real match → an honest coverage gap with `matchExists: true`.
+- **Tennis `standings` published a fake total and could not be paged.** `/tennis/standings?top_n=5` set `rank_max=top_n`, so the count (which carried the rank bounds) equalled the page size: `total:5`, `hasMore:false` for a list of **150** ranked players. The API now counts the population without the rank window and returns `ranked_players`/`total_pages`/`has_next`, `/standings` takes a `page` argument, and the tool reports `total`/`rankedPlayers`/`totalPages`/`hasMore` — page 2 of the ATP list now starts at rank 6. The same `allRows.length` mistake in the `pagination` block was fixed too, so the two counts cannot disagree.
+- **`event_card` published the requested id as the event name.** With a bad id it answered `ok:true` and `event.name = "atp_2026_999999"` over a 404 that `partial[]` reported correctly. Names now come from the payload or are `null`, with `event.resolved` recording whether the detail fetch succeeded.
+- **`leaderboard_*` reported the page size as the population.** Every board returned `"total": len(items)` after applying `.limit(limit)`, so `limit=2` answered `total:2` — for boards whose own docs record thousands of qualifiers. Upstream now carries `count(*) OVER ()` (Postgres evaluates it after `GROUP BY`/`HAVING`, so it is exactly the qualifying population, at no extra round trip): aces **2488**, break-conversion **1089** (matching the figure in its own docstring), 1st-serve-won 1141, bp-saved 1186, return-games 987, tiebreak 364, deciders 334, comebacks 611, finals 66. Each tool also reports `returned` and the board's `minimumAttempts`.
+- **`resolve_entity { q: "Nole" }` answered "M Canoles".** The upstream name search puts Novak Djokovic first for `Nole` — it knows a nickname nothing in the payload carries, so `rankScore` scores it 0 — and the tool floored every unmatched row to 1 and then *sorted*, letting a substring collision win. `pushCandidates` now lets the upstream's own first row stand as the alias answer (labelled `meta.matchedBy: "upstream-first"`) when our scorer is silent, and `search_entities` exempts exactly that one row from its relevance floor. Padding is still dropped: `Sinner` still returns only Sinner.
+- **`/tennis/tournaments/calendar` silently ignored `?month=`.** FastAPI drops unknown query parameters, so `?month=9` and `?month=3` returned the identical 621-event season list and a caller asking "what is on in September" got the whole year. The route now takes `month` and filters on the event's start month (2026-09 → 12 events).
+- **`standings` and `leaderboards` were never cached**, so every call re-ran its grouped scan and paid db1's ~90ms RTT per query: 474–922ms on *every* request while every cached route answered in <20ms. That held eleven tools permanently over the 400ms latency budget. Both prefixes now have TTLs (1800s / 600s); repeat calls measure **4–5ms**.
+- **`bestOf`** now reads `best_of`, the only spelling the tennis route emits.
+
+### 0.4.1
+
+Tennis correctness pass, driven by the 2026-09-12 sweep (`reports/tennis-mcp-sweep-2026-09-12.md`). Every item was reproduced against live ids and re-verified after the fix.
+
+- **`match_summary` tennis scoreline was always `- : -`.** `/tennis/matches/{id}` puts no `sets_won` on its player objects, so the sets-won score was null for every completed match while the same payload held the real score in `score` and `sets[]`. Sets won are now derived (explicit → `winner_sets_won` → `sets[]` → `score` string), `score.detail` carries the game score, and a set's `completed` is inferred when the archive omits `is_completed`. The winner-oriented `winner_games`/`loser_games` pair is deliberately not used as a side score. `bestOf` now reads `best_of`.
+- **`match_details` denied tennis odds existed.** The `odds` section was gated to UFC; the same match returned FanDuel/Matchbook prices from `tennis_odds`. Both surfaces now share one projection (`summarizeTennisOdds`), and `playerStats` (previously always `null` for tennis) is filled from `/tennis/matches/{id}/stats`.
+- **`player_stats.bySurface` was always four nulls.** The endpoint publishes one object per surface and the projector coerced each to a number. Real per-surface blocks, `servingStats`, and an explicit `unavailable` map for sections the endpoint does not publish.
+- **`limit` was ignored** by `player_rankings_history` (asked 4, got 342) and by `/tennis/matches/completed`. Both are bounded locally now, with `*Returned` versus `*Count` so the day total is never confused with the page.
+- **`tournaments level="WTA 1000"` returned ATP Masters events.** The API's level reverse-map is not tour-aware (`_TIER_WTA` maps both `PM` and `M` to "WTA 1000"), so the tool now sends and enforces the tour the level name states, and drops + counts contradicting rows. Fixed at the source too — the same widening also leaked `WTA 125`, `Challenger`, `Davis Cup` and `Billie Jean King Cup`.
+- **`rankings_movers` called an 84-day gap "week-over-week".** `gapDays`/`comparisonWindow`/`comparisonsAreWeekly` now state the real interval, with a warning. `standings` reports the tennis `ranking_date` as `updatedAt` instead of `null`.
+- **`tennis_odds upcoming` rows carried `matchId: null`** with no alternative key. `joinKey` and `playerIds` make the row joinable without inventing an id.
+- **`tennis_schedule`** now counts the day's list/completed overlap, summarises statuses, and flags date-only `startsAt` placeholders.
+- **`live_matches` labelled tennis rows by tournament**, not players, because the live route's `name` is the event.
+- **Tennis players had no images** although `/tennis/players/{id}` carries `portrait_url`. Now surfaced (plus `ioc` as the side country on boards).
+- **`search_entities` had no relevance floor**: `q=Sinner` returned eight unrelated names. Rows that match nothing are dropped and reported, and a one- or two-character fragment no longer counts as a match.
+
 ### 0.2.4
 
 - **UFC projection hardening** (offline-tested):

package/dist/tools/insight.js

@@ -811,8 +811,14 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
             limit: limitSchema({
                 default: 20,
                 max: 50,
-                description: 'Max bouts/matches on the card (default 20, max 50).',
+                description: 'Max bouts/matches on the card (default 20, max 50). For a tennis draw this bounds the flat `bouts` list; the bracket in `draw.rounds` is returned whole by default, because a truncated bracket is not a bracket. Use drawMaxMatches to bound it.',
             }),
+            drawMaxMatches: {
+                type: 'integer',
+                minimum: 1,
+                maximum: 500,
+                description: 'Tennis only. Cap the total matches carried in draw.rounds. The round list is filled from the business end backwards (Final, SF, QF, …) so a small cap keeps the decisive rounds and drops the early ones; draw.truncated and draw.omitted report what happened. Omit for the complete bracket.',
+            },
         },
     },
     handler: async (args, ctx) => {
@@ -835,6 +841,9 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
         const includeBouts = args.includeMatches !== false;
         const includeStandings = args.includeStandings === true;
         const limit = clampInt(args.limit, 20, 1, 50);
+        const drawMaxMatches = typeof args.drawMaxMatches === 'number' && Number.isFinite(args.drawMaxMatches)
+            ? Math.max(1, Math.min(500, Math.trunc(args.drawMaxMatches)))
+            : null;
         if (!eventKey && !q) {
             return errorEnvelope({
                 code: 'VALIDATION',
@@ -873,10 +882,22 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                 });
             }
         }
+        /**
+         * Seeded with the key but explicitly NOT resolved.
+         *
+         * `name: q || eventKey` used to put the raw requested id in the name slot,
+         * and the tennis branch then kept it whenever its detail fetch failed
+         * (`pickString(d.name) ?? event.name`). event_card { eventIdOrSlug:
+         * "atp_2026_999999" } therefore answered ok:true with
+         * event.name = "atp_2026_999999" — an id presented as a tournament name,
+         * over a 404 that the partial[] block reported correctly. A name is
+         * something the API supplied or it is null; an identifier is not a name.
+         */
         let event = {
             id: eventKey,
             slug: eventKey,
-            name: q || eventKey,
+            name: q || null,
+            resolved: false,
             game,
         };
         let bouts = [];
@@ -885,6 +906,33 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
         // upstream's own round code (Q1..R128, QF, SF, F) so an agent can render
         // the tournament tree rather than one flat, order-dependent match list.
         let drawRounds = null;
+        /**
+         * Draw completeness. A bracket is only useful if the caller knows whether it
+         * is whole: atp_2026_560 returns R32 15/16, R64 31/32 and R128 45/64 (the
+         * archived matches it actually holds), and the Final round is absent until
+         * it is played. The old response gave no signal at all, so a partial
+         * bracket silently looked like a complete one and a missing round looked
+         * like a missing feature.
+         */
+        let drawSummary = null;
+        /** Matches a round of this code must contain, or null when unrecognised. */
+        const expectedMatchesForRound = (code, drawSize) => {
+            const c = (code ?? '').toUpperCase();
+            const rMatch = /^R(\d+)$/.exec(c);
+            if (rMatch)
+                return Math.max(1, Math.floor(Number(rMatch[1]) / 2));
+            if (c === 'F' || c === 'FINAL')
+                return 1;
+            if (c === 'SF')
+                return 2;
+            if (c === 'QF')
+                return 4;
+            if (c === 'BR' || c === 'RR')
+                return null; // round robin has no fixed size
+            if (drawSize && drawSize > 0 && c.startsWith('Q'))
+                return null;
+            return null;
+        };
         if (game === 'ufc') {
             const detail = await fetchJson(ctx, `/ufc/events/${encodeURIComponent(eventKey)}`);
             upstreamCalls += 1;
@@ -1272,7 +1320,11 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                     ...event,
                     id: pickString(d.id) ?? eventKey,
                     slug: pickString(d.id) ?? eventKey,
-                    name: pickString(d.name) ?? event.name,
+                    // Never fall back to event.name here: that is the requested key, and
+                    // this branch only runs when the detail fetch SUCCEEDED, so the name
+                    // comes from the payload or it is honestly absent.
+                    name: pickString(d.name, d.id) ?? null,
+                    resolved: true,
                     tour: pickString(d.tour) ?? null,
                     level: pickString(d.level) ?? null,
                     tier: pickString(d.tier) ?? null,
@@ -1298,12 +1350,22 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                 if (draw.ok) {
                     const dd = asRecord(unwrapPayload(draw.data)) ?? {};
                     const rawRounds = Array.isArray(dd.rounds) ? dd.rounds : [];
+                    const drawSize = typeof dd.draw_size === 'number' ? dd.draw_size : null;
                     const flat = [];
+                    // Fill the bracket from the front (the upstream orders rounds from the
+                    // business end backwards: SF, QF, R16, … R128), so a cap keeps the
+                    // decisive rounds and drops the early ones rather than the reverse.
+                    let budget = drawMaxMatches ?? Number.POSITIVE_INFINITY;
+                    let omittedMatches = 0;
                     drawRounds = rawRounds.map((rr) => {
                         const rec = asRecord(rr) ?? {};
                         const roundCode = pickString(rec.round_code, rec.roundCode) ?? null;
                         const roundName = pickString(rec.round_name, rec.name, rec.round) ?? roundCode;
-                        const matches = (Array.isArray(rec.matches) ? rec.matches : []).map((mm) => {
+                        const all = Array.isArray(rec.matches) ? rec.matches : [];
+                        const kept = all.slice(0, Math.max(0, budget));
+                        omittedMatches += all.length - kept.length;
+                        budget -= kept.length;
+                        const matches = kept.map((mm) => {
                             const mr = asRecord(mm) ?? {};
                             const row = { ...mr, id: mr.match_id, round: roundName, tournament_name: event.name, status: 'completed' };
                             flat.push(row);
@@ -1318,11 +1380,56 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                                 nextMatchId: pickString(mr.next_match_id) ?? null,
                             }, 'tennis');
                         });
-                        return { roundCode, roundName, matches };
+                        return {
+                            roundCode,
+                            roundName,
+                            matches,
+                            returned: all.length,
+                            expected: expectedMatchesForRound(roundCode, drawSize),
+                            complete: (() => {
+                                const expected = expectedMatchesForRound(roundCode, drawSize);
+                                return expected === null ? null : all.length >= expected;
+                            })(),
+                        };
                     });
                     bouts = flat.slice(0, limit).map((row) => normalizeMatch('tennis', row));
                     if (!bouts.length)
                         warnings.push('No draw yet: the tournament has no archived results');
+                    const expectedTotal = drawRounds.reduce((sum, r) => sum + (r.expected ?? 0), 0);
+                    const returnedTotal = drawRounds.reduce((sum, r) => sum + r.returned, 0);
+                    const shortRounds = drawRounds
+                        .filter((r) => r.complete === false)
+                        .map((r) => `${r.roundCode ?? r.roundName ?? '?'} ${r.returned}/${r.expected}`);
+                    // A round of 128 draw must have a Final. Its absence is not an error
+                    // (the final may simply not be played yet) but it IS the difference
+                    // between "in progress" and "the API lost a round".
+                    const haveCodes = new Set(drawRounds.map((r) => (r.roundCode ?? '').toUpperCase()));
+                    const missingRounds = ['F', 'SF', 'QF']
+                        .filter((c) => !haveCodes.has(c))
+                        .filter((c) => !(c === 'F' && shortRounds.length > 0 && drawSize !== null && returnedTotal < drawSize / 2));
+                    drawSummary = {
+                        drawSize,
+                        // NOT `rounds`: that key holds the round ARRAY on the same object,
+                        // and spreading a count over it replaced the bracket with a number.
+                        roundCount: drawRounds.length,
+                        matchesReturned: returnedTotal,
+                        matchesExpected: expectedTotal || null,
+                        complete: expectedTotal > 0 ? returnedTotal >= expectedTotal : null,
+                        shortRounds,
+                        missingRounds,
+                        totalMatchesInCard: flat.length,
+                        returnedInBouts: bouts.length,
+                        truncated: omittedMatches > 0,
+                        omittedMatches,
+                        maxMatches: drawMaxMatches,
+                        note: 'matchesReturned counts what the archive holds for this tournament; matchesExpected counts a full draw of drawSize. shortRounds names every round that is short, and missingRounds names a round the bracket should contain but does not.',
+                    };
+                    if (shortRounds.length) {
+                        warnings.push(`Draw is partial: ${shortRounds.join(', ')}. The archive does not hold every match of this tournament yet.`);
+                    }
+                    if (omittedMatches > 0) {
+                        warnings.push(`drawMaxMatches=${drawMaxMatches} dropped ${omittedMatches} early-round match(es) from draw.rounds; raise or omit it for the complete bracket.`);
+                    }
                 }
                 else {
                     partial.push(partialFromRejection('bouts', {
@@ -1355,7 +1462,7 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                     message: `dota tournament HTTP ${detail.status}`,
                     httpStatus: detail.status,
                 }));
-                event = { id: eventKey, slug: eventKey, name: q || eventKey, game };
+                event = { id: eventKey, slug: eventKey, name: q || null, resolved: false, game };
             }
             if (includeBouts) {
                 const matchesRes = await fetchJson(ctx, '/dota2/matches/upcoming', { query: { limit } });
@@ -1390,6 +1497,18 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                 }));
             }
         }
+        /**
+         * Last line of defence against an identifier posing as a name.
+         *
+         * Every game branch seeds `event.name` from `q`/`eventKey` so a partially
+         * resolved card still has something in the slot. Any branch that failed and
+         * left that seed in place would publish "atp_2026_999999" as a tournament
+         * name, and nothing downstream can tell an id from a name. It is nulled
+         * here; `resolved` records that the detail fetch never succeeded.
+         */
+        if (event.resolved !== true && typeof event.name === 'string' && event.name === eventKey) {
+            event = { ...event, name: null, nameResolved: false };
+        }
         return successEnvelope({
             source: 'event_card',
             game,
@@ -1414,7 +1533,7 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                 // (Q1..R128, QF, SF, F) and each match's score/bracket progression —
                 // this is what makes a bracket renderable; `bouts` above is the flat
                 // list every other game already gets.
-                ...(game === 'tennis' ? { draw: drawRounds ? { rounds: drawRounds } : null } : {}),
+                ...(game === 'tennis' ? { draw: drawRounds ? { rounds: drawRounds, ...(drawSummary ?? {}) } : null } : {}),
                 standings: includeStandings ? standingsSnippet : null,
                 nextSteps: [
                     'For a featured bout/match: match_preview { game, matchId } or teamA+teamB',

package/dist/tools/leaderboard.js

@@ -156,13 +156,23 @@ Parallel-safe: yes. Upstream cost: 1.`,
         const root = asRecord(res.data);
         const body = asRecord(root?.data) ?? root ?? {};
         const items = (Array.isArray(body.items) ? body.items : []).map(normalizeAceRow);
+        /**
+         * `total` is the QUALIFYING POPULATION, not the page.
+         *
+         * The API used to return len(items) AFTER applying .limit(limit), so limit=2
+         * answered total:2 for a board with thousands of eligible players and the
+         * caller had no way to tell a page from the whole board. It now carries
+         * count(*) OVER (), the count of players passing the board's own threshold.
+         * `returned` and `hasMore` are stated separately so the two can never be
+         * confused again, and the threshold is surfaced so the number is explicable.
+         */
         const total = typeof body.total === 'number' ? body.total : items.length;
         return successEnvelope({
             pagination: {
                 limit,
                 offset: 0,
                 total,
-                hasMore: false,
+                hasMore: items.length < total,
                 nextCursor: null,
                 prevCursor: null,
             },
@@ -179,6 +189,8 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 stat: pickString(body.stat) ?? 'aces',
                 items,
                 total,
+                returned: items.length,
+                ...(typeof body.minimum_attempts === 'number' ? { minimumAttempts: body.minimum_attempts } : {}),
             },
         });
     },
@@ -306,13 +318,15 @@ Parallel-safe: yes. Upstream cost: 1.`,
             const root = asRecord(res.data);
             const body = asRecord(root?.data) ?? root ?? {};
             const items = (Array.isArray(body.items) ? body.items : []).map(normalizeRow);
+            // Same contract as leaderboard_aces: total is the qualifying population,
+            // not the page. See the note there.
             const total = typeof body.total === 'number' ? body.total : items.length;
             return successEnvelope({
                 pagination: {
                     limit,
                     offset: 0,
                     total,
-                    hasMore: false,
+                    hasMore: items.length < total,
                     nextCursor: null,
                     prevCursor: null,
                 },
@@ -329,6 +343,8 @@ Parallel-safe: yes. Upstream cost: 1.`,
                     stat: pickString(body.stat) ?? spec.stat,
                     items,
                     total,
+                    returned: items.length,
+                    ...(typeof body.minimum_attempts === 'number' ? { minimumAttempts: body.minimum_attempts } : {}),
                 },
             });
         },

package/dist/tools/match.js

@@ -3,7 +3,8 @@
  */
 import { extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, unwrapPayload, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
-import { normalizeMatch, normalizeUfcMethod, presentSides } from './normalize.js';
+import { normalizeMatch, normalizeUfcMethod, presentSides, tennisSetCompleted } from './normalize.js';
+import { summarizeTennisOdds } from './odds.js';
 import { boolSchema, gameSchema, isPrimaryGame, parseGame, stringSchema, } from './types.js';
 async function getSection(ctx, path, query) {
     return fetchJson(ctx, path, { query });
@@ -20,7 +21,7 @@ export function parseBestOf(r) {
         const n = Number(v);
         return Number.isFinite(n) && [1, 3, 5, 7, 9].includes(n) ? n : null;
     };
-    const direct = fromNumber(r.bestOf) ?? fromNumber(r.bo);
+    const direct = fromNumber(r.bestOf) ?? fromNumber(r.bo) ?? fromNumber(r.best_of);
     if (direct)
         return direct;
     const strat = r.strategy;
@@ -61,6 +62,12 @@ function matchCore(game, matchId, raw) {
     const scoreline = m.team1 || m.team2
         ? `${m.team1?.name ?? '?'} ${s1 ?? '-'} : ${s2 ?? '-'} ${m.team2?.name ?? '?'}`
         : null;
+    /**
+     * Tennis: `score` is the set-by-set game score ("4-6 6-3 6-3 7-5"), which is
+     * a DIFFERENT fact from the sets-won scoreline. "3 : 1" is the result; it
+     * cannot distinguish 6-0 6-0 from three tiebreaks. Both are carried.
+     */
+    const scoreDetail = game === 'tennis' ? (pickString(r.score, r.score_raw) ?? null) : null;
     const core = {
         matchId: m.matchId !== 'unknown' ? m.matchId : matchId,
         game,
@@ -73,6 +80,7 @@ function matchCore(game, matchId, raw) {
         score: {
             team1: s1,
             team2: s2,
+            ...(scoreDetail ? { detail: scoreDetail } : {}),
         },
         team1: m.team1,
         team2: m.team2,
@@ -385,7 +393,10 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
                         player1Games: p1g,
                         player2Games: p2g,
                         tiebreak: sr.tiebreak ?? null,
-                        completed: sr.is_completed === true,
+                        // is_completed is a LIVE-route field. The archive route omits it,
+                        // so every set of a finished match read completed:false. Fall
+                        // back to the games, which always decide whether a set is over.
+                        completed: tennisSetCompleted(sr),
                     };
                 });
                 return;
@@ -420,6 +431,7 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
             display: `${match.team1?.name ?? '?'} ${match.score.team1 ?? '-'} : ${match.score.team2 ?? '-'} ${match.team2?.name ?? '?'}`,
             team1: match.score.team1,
             team2: match.score.team2,
+            ...(game === 'tennis' && match.score.detail ? { detail: match.score.detail } : {}),
         }, game);
         if (view === 'summary' && playerPerformances.length > 10) {
             playerPerformances = playerPerformances.slice(0, 10);
@@ -540,6 +552,52 @@ export function summarizeUfcOdds(data) {
         fullBookPath: '/ufc/bouts/{boutId}/odds',
     };
 }
+/**
+ * Tennis per-match stats projection.
+ *
+ * `/tennis/matches/{id}/stats` does NOT return a row per player the way every
+ * other game's player-stats route does. It returns
+ * `{ stats: { winner: {...}, loser: {...} }, sets: [...], score }` — two objects
+ * keyed by OUTCOME. `match_details sections:["playerStats"]` had no tennis arm
+ * at all, so it answered `playerStats: null` while `match_summary` was filling
+ * `playerPerformances` from the same route.
+ *
+ * The sides stay keyed by outcome rather than being mislabelled as player1 /
+ * player2, because the payload carries no names and the ordering is not
+ * guaranteed to match the base row. `match.player1.is_winner` on the base
+ * section is what maps a name onto these numbers, and `sidesKeyedBy` says so.
+ */
+export function summarizeTennisMatchStats(data) {
+    const root = asRecord(data) ?? {};
+    const payload = asRecord(root.data) ?? root;
+    const stats = asRecord(payload.stats);
+    const sets = Array.isArray(payload.sets) ? payload.sets : [];
+    const toNum = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    return {
+        matchId: pickString(payload.match_id) ?? null,
+        score: pickString(payload.score) ?? null,
+        sidesKeyedBy: 'outcome',
+        players: stats
+            ? {
+                winner: asRecord(stats.winner) ?? null,
+                loser: asRecord(stats.loser) ?? null,
+            }
+            : null,
+        sets: sets.map((s) => {
+            const sr = asRecord(s) ?? {};
+            return {
+                setNumber: toNum(sr.set_num) ?? toNum(sr.set_number),
+                winnerGames: toNum(sr.winner_games),
+                loserGames: toNum(sr.loser_games),
+                player1Games: toNum(sr.player1_games),
+                player2Games: toNum(sr.player2_games),
+                tiebreak: sr.tiebreak ?? null,
+                completed: tennisSetCompleted(sr),
+            };
+        }),
+        rawPath: '/tennis/matches/{matchId}/stats',
+    };
+}
 export const matchDetails = {
     name: 'match_details',
     description: `Deep match package: optional timelines, advanced stats, live state/snapshots, full map/game tree, media inventory.
@@ -574,7 +632,7 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
                     type: 'string',
                     enum: ['base', 'playerStats', 'gamesOrMaps', 'timeline', 'liveState', 'media', 'advanced', 'odds'],
                 },
-                description: 'Explicit section list; defaults to base+playerStats+gamesOrMaps+media. "odds" (UFC) is opt-in: moneyline summarised per fighter with bookmaker count, best and median American price and implied probability, plus a count of every other market. Closing lines for a finished fight come back with currentlyOffered=false rather than being omitted.',
+                description: 'Explicit section list; defaults to base+playerStats+gamesOrMaps+media. "odds" is opt-in: UFC returns moneyline summarised per fighter with bookmaker count, best and median American price and implied probability plus a count of every other market (closing lines for a finished fight come back with currentlyOffered=false rather than being omitted); tennis returns the same bookmaker/market/outcome projection that tennis_odds serves, including oddsAvailable=false when no book is quoting. Odds exist for UFC and tennis only.',
             },
             includeTimeline: boolSchema('Include timeline section (heavy).', false),
             includeLiveState: boolSchema('Include live state/snapshots.', false),
@@ -726,6 +784,11 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
                 load('playerStats', `/cod/matches/${encodeURIComponent(matchId)}/player-stats`);
             if (game === 'ufc')
                 load('playerStats', `/ufc/bouts/${encodeURIComponent(matchId)}/stats`);
+            // Tennis has a real per-match stats route; the section simply had no arm
+            // for it and shipped playerStats:null forever.
+            if (game === 'tennis') {
+                loadWith('playerStats', `/tennis/matches/${encodeURIComponent(matchId)}/stats`, summarizeTennisMatchStats);
+            }
         }
         if (wanted.has('gamesOrMaps')) {
             if (game === 'lol')
@@ -772,10 +835,17 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
             if (game === 'ufc') {
                 loadWith('odds', `/ufc/bouts/${encodeURIComponent(matchId)}/odds`, summarizeUfcOdds);
             }
+            else if (game === 'tennis') {
+                // The gate that produced "Odds not curated for tennis; UFC only today"
+                // was written before /tennis/odds/{id} existed. It does: the same match
+                // returned FanDuel 1.105 / Matchbook 1.13 from tennis_odds while this
+                // section denied odds existed. Both surfaces now share one projection.
+                loadWith('odds', `/tennis/odds/${encodeURIComponent(matchId)}`, summarizeTennisOdds);
+            }
             else {
                 partial.push(partialFromRejection('odds', {
                     code: 'NOT_IMPLEMENTED',
-                    message: `Odds not curated for ${game}; UFC only today`,
+                    message: `Odds are not curated for ${game}. Available: UFC (/ufc/bouts/{id}/odds) and tennis (/tennis/odds/{id}).`,
                 }));
             }
         }

package/dist/tools/meta.js

@@ -38,7 +38,7 @@ const TOOL_CATALOG = [
     },
     {
         name: 'search_entities',
-        outcome: 'Browse/search entities with type filter and pagination',
+        outcome: 'Browse/search entities with type filter and pagination; when q is given, results below the relevance floor are dropped and reported under data.relevance',
         parallelSafe: true,
         games: [...PRIMARY_GAMES],
         jobs: ['team_page', 'player_form'],
@@ -138,7 +138,7 @@ const TOOL_CATALOG = [
     },
     {
         name: 'rankings_movers',
-        outcome: 'Tennis ranking movers: climbers/fallers plus new entries and drop-outs',
+        outcome: 'Tennis ranking climbers/fallers plus new entries and drop-outs, with gapDays/comparisonWindow stating the real interval between the two lists',
         parallelSafe: true,
         games: ['tennis'],
         jobs: ['standings'],
@@ -168,7 +168,7 @@ const TOOL_CATALOG = [
     },
     {
         name: 'player_stats',
-        outcome: 'Tennis career statistics: W/L, win%, titles, Grand Slam and Masters titles, breakdowns',
+        outcome: 'Tennis career statistics: W/L, win%, titles, per-surface breakdown, serving stats, and named gaps',
         parallelSafe: true,
         games: ['tennis'],
         jobs: ['player_form'],
@@ -188,7 +188,7 @@ const TOOL_CATALOG = [
     },
     {
         name: 'tennis_odds',
-        outcome: 'Tennis betting odds: upcoming matches with prices, plus pre-match and in-play for one match',
+        outcome: 'Tennis betting odds: upcoming matches with prices, plus pre-match and in-play for one match; upcoming rows carry a joinKey and playerIds because the feed leaves match_id null',
         parallelSafe: true,
         games: ['tennis'],
         jobs: ['preview', 'match_page', 'odds'],
@@ -198,7 +198,7 @@ const TOOL_CATALOG = [
     },
     {
         name: 'tournaments',
-        outcome: 'Tennis tournament catalog: filter by year, tour, level, surface or country',
+        outcome: 'Tennis tournament catalog: filter by year, tour, level, surface or country; a level name that names a tour also fixes it',
         parallelSafe: true,
         games: ['tennis'],
         jobs: ['preview', 'standings'],
@@ -208,7 +208,7 @@ const TOOL_CATALOG = [
     },
     {
         name: 'tennis_schedule',
-        outcome: "One day of tennis: that day's schedule and/or completed matches",
+        outcome: "One day of tennis: that day's schedule and/or completed matches, with limit applied to each half and the two halves' overlap counted",
         parallelSafe: true,
         games: ['tennis'],
         jobs: ['schedule', 'match_page'],