cito-mcp 0.4.0 → 0.4.1

package/dist/tools/rankings.js

@@ -82,6 +82,8 @@ Do not use when: current top-N snapshot → standings with game tennis; player h
 
 Tennis-only. Direction up (climbers, default), down (fallers), or both (largest absolute change). Date pins an older ranking list (YYYY-MM-DD); default is the latest, which the API resolves past zero-diff cloned lists.
 
+The two lists are NOT always one week apart: previousDate is whatever the archive holds next, and the archive has holes. Read gapDays / comparisonWindow (and comparisonsAreWeekly) before describing a delta as weekly — a warning is raised whenever the gap exceeds ten days.
+
 Parallel-safe: yes. Upstream cost: 1.`,
     inputSchema: {
         type: 'object',
@@ -195,6 +197,39 @@ 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 = (() => {
+            if (!rankingDate || !previousDate)
+                return null;
+            const a = Date.parse(rankingDate);
+            const b = Date.parse(previousDate);
+            if (!Number.isFinite(a) || !Number.isFinite(b))
+                return null;
+            return Math.round((a - b) / 86_400_000);
+        })();
+        const comparisonWindow = gapDays === null
+            ? null
+            : gapDays <= 8
+                ? 'week-over-week'
+                : `${Math.round(gapDays / 7)}-week gap`;
+        const warnings = [];
+        if (gapDays !== null && gapDays > 10) {
+            warnings.push(`The compared lists are ${gapDays} days apart (${previousDate} -> ${rankingDate}), not one week. ` +
+                `Every "movement" here accumulated over ${Math.round(gapDays / 7)} weeks; there is no published ` +
+                `ranking snapshot strictly between those two dates. Treat the deltas as period-over-period, not weekly.`);
+        }
         return successEnvelope({
             pagination: {
                 limit,
@@ -210,13 +245,19 @@ Parallel-safe: yes. Upstream cost: 1.`,
             tookMs: Date.now() - started,
             upstreamCalls: 1,
             rateLimit: res.headers,
+            warnings: warnings.length ? warnings : undefined,
             data: {
                 title: `${tourParse.tour} ranking movers (${dirParse.direction})`,
                 tour: tourParse.tour,
                 direction: dirParse.direction,
                 within,
-                rankingDate: pickString(body.ranking_date) ?? null,
-                previousDate: pickString(body.previous_date) ?? null,
+                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,
                 newEntries,
                 dropped,
@@ -237,8 +278,10 @@ Prefer over: standings (latest snapshot only); rankings_movers (week-over-week d
 Do not use when: the current top-N table → standings with game tennis.
 
 Tennis-only. Rows arrive oldest-first (chronological), which is the order a chart
-wants; the newest entries are the tail. Use 'since' or 'limit' to bound the
-series — the full career can be hundreds of rows.
+wants; the newest entries are the tail. limit keeps the most RECENT N rows (the
+route itself ignores ?limit=, so the bound is applied here) — hasMore and
+oldestReturned/newestReturned say exactly which window came back, and
+omittedOlder counts the rows left behind at the old end.
 
 Parallel-safe: yes. Upstream cost: 1.`,
     inputSchema: {
@@ -322,7 +365,7 @@ Parallel-safe: yes. Upstream cost: 1.`,
         const root = asRecord(res.data) ?? {};
         const body = asRecord(root.data) ?? root;
         const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
-        let history = (Array.isArray(body.history) ? body.history : []).map((row) => {
+        const allHistory = (Array.isArray(body.history) ? body.history : []).map((row) => {
             const r = asRecord(row) ?? {};
             return {
                 date: pickString(r.date) ?? null,
@@ -330,8 +373,23 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 points: num(r.points),
             };
         });
-        if (sinceRaw)
-            history = history.filter((h) => h.date !== null && h.date >= sinceRaw);
+        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) => {
@@ -344,9 +402,9 @@ Parallel-safe: yes. Upstream cost: 1.`,
         return successEnvelope({
             pagination: {
                 limit,
-                offset: 0,
-                total: history.length,
-                hasMore: false,
+                offset: total - history.length,
+                total,
+                hasMore: total > history.length,
                 nextCursor: null,
                 prevCursor: null,
             },
@@ -367,6 +425,13 @@ 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,
+                oldestReturned: history.length ? history[0].date : null,
+                newestReturned: history.length ? history[history.length - 1].date : null,
             },
         });
     },

package/dist/tools/resolve.js

@@ -5,6 +5,13 @@ import { clampInt, decodeCursor, encodeCursor, extractRows, fetchJson, gameNotIn
 import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT, errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
 import { editionYear, entityRef, rankScore } from './normalize.js';
 import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, PRIMARY_GAMES, stringSchema, } from './types.js';
+/**
+ * Minimum relevance a search result must reach to be returned when a query was
+ * given. rankScore returns 0 for "no part of the query appears anywhere in this
+ * row", so 1 means "must have matched something". See the floor note in
+ * searchEntities for the live evidence.
+ */
+export const RELEVANCE_FLOOR = 1;
 /**
  * Ranking order whose tiebreak never depends on the order upstream happened to
  * return rows in.
@@ -840,33 +847,86 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             seen.add(key);
             return true;
         });
+        /**
+         * Relevance floor.
+         *
+         * The upstream player/tournament search is a substring match with no floor
+         * of its own: `q=Sinner` returns ten rows, of which only "Jannik Sinner" and
+         * "Martin Sinner" have anything to do with the query. The tool scored them
+         * all and then SORTED rather than filtered, so "A Winner", "J Skinner",
+         * "E Skinner", "C Sinkler", "Dr Sinnett", "H C Skinner", "Mrs Skinner" and
+         * "J J Sinnott" came back as equals — an agent asking for one player got
+         * eight strangers to ignore, and a caller paging the results paid for them.
+         *
+         * rankScore already separates them cleanly (Jannik 100, Martin 48, every
+         * other row 0), so the floor is simply "must have matched something at all".
+         * It is applied only when a query was given: with no q this tool is a browse
+         * list, and a floor there would delete the catalogue.
+         */
+        const scoreOf = (it) => typeof it.meta?.score === 'number'
+            ? it.meta.score
+            : rankScore(q, it.name, it.id, it.slug, it.meta?.nickname);
+        const upstreamTotal = total;
+        let droppedBelowFloor = [];
+        if (q) {
+            // Publish the score on every row, not just the ones the scored branch
+            // produced, so the floor is visible rather than mysterious.
+            items = items.map((it) => ({ ...it, meta: { ...(it.meta ?? {}), score: scoreOf(it) } }));
+            droppedBelowFloor = items
+                .filter((it) => it.meta?.score < RELEVANCE_FLOOR)
+                .map((it) => ({ id: it.id, name: it.name, score: it.meta?.score }));
+            if (droppedBelowFloor.length) {
+                items = items.filter((it) => it.meta?.score >= RELEVANCE_FLOOR);
+            }
+        }
         if (q && !preserveUpstreamOrder) {
-            items.sort((a, b) => {
-                const sa = typeof a.meta?.score === 'number' ? a.meta.score : rankScore(q, a.name, a.id, a.slug, a.meta?.nickname);
-                const sb = typeof b.meta?.score === 'number' ? b.meta.score : rankScore(q, b.name, b.id, b.slug, b.meta?.nickname);
-                return sb - sa || a.name.localeCompare(b.name);
-            });
+            items.sort((a, b) => scoreOf(b) - scoreOf(a) || a.name.localeCompare(b.name));
         }
         // pagination over ranked result set
         const pageItems = upstreamPaged ? items.slice(0, limit) : items.slice(offset, offset + limit);
         const hasMore = upstreamPaged
             ? (total != null ? offset + pageItems.length < total : pageItems.length >= limit)
             : offset + pageItems.length < items.length;
+        const floorWarnings = [];
+        if (droppedBelowFloor.length) {
+            const sample = droppedBelowFloor
+                .slice(0, 5)
+                .map((d) => `${d.name} (${d.id})`)
+                .join(', ');
+            floorWarnings.push(`Dropped ${droppedBelowFloor.length} result(s) that do not match "${q}" at all — the upstream search is a ` +
+                `substring match with no relevance floor, so it pads every page: ${sample}. ` +
+                `If one of these is what you wanted, query it by name or id directly.`);
+        }
         return successEnvelope({
             source: 'search_entities',
             game,
             requestId,
             tookMs: Date.now() - started,
             upstreamCalls,
+            warnings: floorWarnings.length ? floorWarnings : undefined,
             pagination: {
                 limit,
                 offset,
-                total: total ?? (q ? items.length : null),
+                total: q ? items.length : (total ?? null),
                 hasMore,
                 nextCursor: hasMore ? encodeCursor({ offset: offset + limit }) : null,
                 prevCursor: offset > 0 ? encodeCursor({ offset: Math.max(0, offset - limit) }) : null,
             },
-            data: { items: pageItems },
+            data: {
+                items: pageItems,
+                ...(q
+                    ? {
+                        relevance: {
+                            query: q,
+                            floor: RELEVANCE_FLOOR,
+                            matched: items.length,
+                            droppedBelowFloor: droppedBelowFloor.length,
+                            dropped: droppedBelowFloor.slice(0, 25),
+                            upstreamTotal: upstreamTotal ?? null,
+                        },
+                    }
+                    : {}),
+            },
         });
     },
 };

package/dist/tools/schedule.js

@@ -33,12 +33,26 @@ function normalizeScheduled(row) {
         round: pickString(r.round) ?? null,
         roundName: pickString(r.round_name) ?? null,
         startsAt: pickString(r.starts_at, r.commence_time, r.match_date) ?? null,
+        /**
+         * Historical days report every match at T00:00:00 with
+         * `start_time_known: false` — the date is real, the clock is a placeholder.
+         * Emitting the midnight without this flag invites a caller to render "12:00
+         * AM" for a semi-final that finished at 3pm. Null when the route does not
+         * state it (the completed half does not).
+         */
+        startTimeKnown: typeof r.start_time_known === 'boolean' ? r.start_time_known : null,
         status: pickString(r.status, r.outcome) ?? null,
         player1: { id: pickString(p1.id, p1.player_id) ?? null, name: pickString(p1.name) ?? null },
         player2: { id: pickString(p2.id, p2.player_id) ?? null, name: pickString(p2.name) ?? null },
         score: pickString(r.score, r.score_raw) ?? null,
     };
 }
+/** A row is "played" when the feed says so, in either spelling it uses. */
+function isPlayed(row) {
+    const r = asRecord(row) ?? {};
+    const s = (pickString(r.status, r.outcome) ?? '').toLowerCase();
+    return /complete|finished|ended|final|closed|done|official|retire|walkover|default/.test(s);
+}
 export const tennisSchedule = {
     name: 'tennis_schedule',
     description: `One day of tennis: the day's schedule and/or the matches completed that day, across ATP and WTA.
@@ -54,6 +68,12 @@ Tennis-only. 'date' defaults to today (UTC) and MUST be YYYY-MM-DD. Choose with
 'include': both (default), scheduled, or completed. Both halves are fetched in
 parallel, so either can fail on its own without losing the other.
 
+'limit' bounds EACH half (the completed route ignores ?limit= upstream, so the
+bound is applied here); scheduledCount/completedCount report how many rows the
+day held and *Returned how many came back. The two halves overlap: the day's
+list includes matches already played, so the same matchId can appear in both —
+see the overlap block before de-duplicating or counting.
+
 Parallel-safe: yes. Upstream cost: 1 or 2.`,
     inputSchema: {
         type: 'object',
@@ -63,7 +83,7 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
             game: gameSchema({ allowAll: false, required: true }),
             date: stringSchema('Day to fetch, YYYY-MM-DD. Defaults to today (UTC).', '2026-09-12'),
             include: stringSchema('both (default) | scheduled | completed.', 'both'),
-            limit: limitSchema({ default: 20, max: 50, description: 'Rows per half (default 20, max 50).' }),
+            limit: limitSchema({ default: 20, max: 50, description: 'Rows per half, applied here (default 20, max 50). scheduledCount/completedCount still report the full day.' }),
         },
     },
     handler: async (args, ctx) => {
@@ -121,27 +141,44 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
         const limit = clampInt(args.limit, 20, 1, 50);
         const wantScheduled = includeRaw === 'both' || includeRaw === 'scheduled';
         const wantCompleted = includeRaw === 'both' || includeRaw === 'completed';
+        /**
+         * Ask for the whole day, then bound locally.
+         *
+         * /tennis/schedule honours ?limit= but /tennis/matches/completed ignores it,
+         * so passing `limit` upstream made `scheduledCount` mean "rows this call
+         * asked for" on one half and "rows the day held" on the other. Both halves
+         * are now fetched at the API's own page ceiling and sliced here, which makes
+         * scheduledCount/completedCount a fact about the day and *Returned a fact
+         * about the response.
+         */
+        const upstreamPage = 200;
         const settled = await Promise.allSettled([
             wantScheduled
-                ? fetchJson(ctx, '/tennis/schedule', { query: { date, limit } })
+                ? fetchJson(ctx, '/tennis/schedule', { query: { date, limit: upstreamPage } })
                 : Promise.resolve(null),
             wantCompleted
-                ? fetchJson(ctx, '/tennis/matches/completed', { query: { date, limit } })
+                ? fetchJson(ctx, '/tennis/matches/completed', { query: { date, limit: upstreamPage } })
                 : Promise.resolve(null),
         ]);
         const rejected = [];
         const rows = (value) => {
             const root = asRecord(value);
             const body = asRecord(root?.data) ?? root ?? {};
-            return Array.isArray(body.items) ? body.items : [];
+            const items = Array.isArray(body.items) ? body.items : [];
+            return { items, total: typeof body.total === 'number' ? body.total : null };
         };
         let scheduled = [];
         let completed = [];
+        let scheduledTotal = null;
+        let completedTotal = null;
         const [schedRes, compRes] = settled;
         if (schedRes.status === 'fulfilled' && schedRes.value) {
             const v = schedRes.value;
-            if (v.ok)
-                scheduled = rows(v.data);
+            if (v.ok) {
+                const parsed = rows(v.data);
+                scheduled = parsed.items;
+                scheduledTotal = parsed.total;
+            }
             else
                 rejected.push({
                     section: 'schedule',
@@ -159,8 +196,11 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
         }
         if (compRes.status === 'fulfilled' && compRes.value) {
             const v = compRes.value;
-            if (v.ok)
-                completed = rows(v.data);
+            if (v.ok) {
+                const parsed = rows(v.data);
+                completed = parsed.items;
+                completedTotal = parsed.total;
+            }
             else
                 rejected.push({
                     section: 'completed',
@@ -190,15 +230,64 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
                 recover: ['Check the date is a real calendar day', 'Retry, or widen include to both'],
             });
         }
+        /**
+         * /tennis/matches/completed IGNORES ?limit= — verified: `limit=3` returned
+         * all 13 rows of the day with page_size still 50. /tennis/schedule does
+         * honour it, but both halves are bounded here so one call site cannot drift
+         * from the other and `completedCount` stops being a number the caller asked
+         * to be smaller.
+         */
+        const scheduledWindow = scheduled.slice(0, limit);
+        const completedWindow = completed.slice(0, limit);
+        /**
+         * /tennis/schedule is the DAY's list, not an "upcoming" list: it carries
+         * matches that have already finished, with status COMPLETED. So the two
+         * halves of this response legitimately overlap, and the old key name
+         * ("scheduled") plus a status of COMPLETED inside it read as a
+         * contradiction. The overlap is now counted and the statuses summarised, so
+         * a caller can join or de-duplicate deliberately instead of discovering it.
+         */
+        const completedBySchedule = scheduled.filter(isPlayed);
+        const completedIds = new Set(completed
+            .map((row) => pickString(asRecord(row)?.id, asRecord(row)?.match_id))
+            .filter((id) => Boolean(id)));
+        const overlapIds = [
+            ...new Set(completedBySchedule
+                .map((row) => pickString(asRecord(row)?.id, asRecord(row)?.match_id))
+                .filter((id) => typeof id === 'string' && completedIds.has(id))),
+        ];
+        const statusCounts = {};
+        for (const row of scheduled) {
+            const key = (pickString(asRecord(row)?.status, asRecord(row)?.outcome) ?? 'UNKNOWN').toUpperCase();
+            statusCounts[key] = (statusCounts[key] ?? 0) + 1;
+        }
+        const anyUnknownClock = scheduled.some((row) => asRecord(row)?.start_time_known === false);
         const data = {
             title: `Tennis — ${date}`,
             date,
             include: includeRaw,
-            scheduled: scheduled.map(normalizeScheduled),
-            scheduledCount: scheduled.length,
-            completed: completed.map(normalizeScheduled),
-            completedCount: completed.length,
+            // Everything the day's list returned, then the bounded window. Both are
+            // present so `scheduledCount` never silently means two different things.
+            scheduled: scheduledWindow.map(normalizeScheduled),
+            scheduledCount: scheduledTotal ?? scheduled.length,
+            scheduledReturned: scheduledWindow.length,
+            completed: completedWindow.map(normalizeScheduled),
+            completedCount: completedTotal ?? completed.length,
+            completedReturned: completedWindow.length,
+            statusBreakdown: statusCounts,
+            overlap: {
+                count: overlapIds.length,
+                matchIds: overlapIds.slice(0, 50),
+                note: overlapIds.length
+                    ? 'These matches appear in BOTH halves: /tennis/schedule is the day\'s full list (played matches included) and /tennis/matches/completed is the played subset. Join on matchId and de-duplicate.'
+                    : 'The two halves returned no shared matchId on this date.',
+            },
             timezoneNote: 'The API groups by UTC date. For a local "today", pass the date explicitly rather than relying on the default.',
+            ...(anyUnknownClock
+                ? {
+                    startTimeNote: 'Rows with startTimeKnown:false carry a date-only startsAt (T00:00:00) — the clock is a placeholder, not a midnight start. The completed half does not report the flag at all.',
+                }
+                : {}),
         };
         const upstreamCalls = (wantScheduled ? 1 : 0) + (wantCompleted ? 1 : 0);
         // A half that failed is reported alongside the half that worked rather than

package/dist/tools/standings.js

@@ -407,8 +407,24 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                 rows,
                 total: allRows.length,
                 hasMore: allRows.length > rows.length,
-                updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt) ??
-                    null,
+                ...(game === 'tennis'
+                    ? {
+                        /**
+                         * Tennis rankings are a dated weekly SNAPSHOT, and the route names
+                         * the date in `ranking_date`. updatedAt was read only from
+                         * updatedAt/lastUpdated/meta.syncedAt/meta.fetchedAt, none of which
+                         * the tennis route emits, so every tennis table claimed
+                         * updatedAt:null while the very date a caller needs sat in the
+                         * payload — and a consumer showing a stale-looking table had no
+                         * way to find out it was a week old.
+                         */
+                        rankingDate: pickString(obj?.ranking_date) ?? null,
+                        updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt, obj?.ranking_date) ?? null,
+                    }
+                    : {
+                        updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt) ??
+                            null,
+                    }),
                 ...(dataFreshness ? { dataFreshness } : {}),
                 ...(status ? { status } : {}),
                 ...(upstreamMeta.warning || dataQuality.warning

package/dist/tools/tournaments.js

@@ -69,6 +69,9 @@ Do not use when: the draw bracket or a specific edition → event_card with the
 
 Tennis-only. Levels accept names (Grand Slam, WTA 1000, ATP 500, Challenger,
 ITF World Tennis Tour, Davis Cup, ...) or raw tier codes (G, M, A, C, D).
+A level name that starts with ATP or WTA also fixes the tour (and conflicts with
+a contradicting tour= argument are rejected), so "WTA 1000" cannot return ATP
+Masters events even though the upstream filter is not tour-aware.
 Note the source does not separate ATP 500 from ATP 250 — both are ATP Tour.
 
 Parallel-safe: yes. Upstream cost: 1.`,
@@ -171,6 +174,44 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 });
             }
         }
+        /**
+         * A level name that starts with a tour token constrains the tour, and the
+         * upstream filter does not know that.
+         *
+         * The API's reverse level map is not tour-aware: `_TIER_WTA` carries BOTH
+         * "PM" and "M" as "WTA 1000" (M is the fallback label for a WTA row stored
+         * with the ATP code), so `?level=WTA 1000` resolves to `tier_code IN
+         * ('PM','M')` and returns every ATP Masters 1000 event alongside the WTA
+         * ones. Verified live: asking for "WTA 1000" returned Rome Masters, Madrid
+         * Masters, Monte Carlo, Miami Masters and Indian Wells Masters (all ATP).
+         * The same widening hits "WTA 125" (code C, shared with ATP Challengers) and
+         * "ATP 500"/"ATP 250" (code A, shared with WTA tour-level rows).
+         *
+         * The tool therefore asserts the invariant the label states: it sends the
+         * tour, and it verifies the rows that come back. Rows that contradict the
+         * requested level are dropped and counted rather than passed through as
+         * "close enough" — a filter that returns other-tour events is worse than a
+         * filter that returns nothing, because the caller has no way to notice.
+         */
+        const levelTourPrefix = (() => {
+            const m = /^(ATP|WTA)\b/i.exec(levelRaw);
+            return m ? m[1].toUpperCase() : null;
+        })();
+        if (levelTourPrefix && tourRaw && tourRaw !== levelTourPrefix) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `tour ('${tourRaw}') contradicts level ('${levelRaw}'), which names the ${levelTourPrefix} tour`,
+                game,
+                source: 'tournaments',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [
+                    `Drop tour, or set tour=${levelTourPrefix}`,
+                    'A level name that starts with ATP/WTA already determines the tour',
+                ],
+            });
+        }
+        const effectiveTour = tourRaw || levelTourPrefix || '';
         const limit = clampInt(args.limit, 20, 1, 50);
         const page = clampInt(args.page, 1, 1, 10000);
         const countryCode = typeof args.countryCode === 'string' && args.countryCode.trim()
@@ -182,7 +223,7 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 limit,
                 page,
                 ...(year !== null ? { year } : {}),
-                ...(tourRaw ? { tour: tourRaw } : {}),
+                ...(effectiveTour ? { tour: effectiveTour } : {}),
                 ...(levelRaw ? { level: levelRaw } : {}),
                 ...(surface ? { surface } : {}),
                 ...(countryCode ? { country_code: countryCode } : {}),
@@ -204,17 +245,35 @@ 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(normalizeTournament);
+        const rawItems = (Array.isArray(body.items) ? body.items : []).map(normalizeTournament);
+        // Verify the invariant the level label states. See levelTourPrefix above.
+        const contradictions = levelTourPrefix
+            ? rawItems.filter((t) => t.tour && t.tour.toUpperCase() !== levelTourPrefix)
+            : [];
+        const items = contradictions.length
+            ? rawItems.filter((t) => !t.tour || t.tour.toUpperCase() === levelTourPrefix)
+            : rawItems;
         const total = typeof body.total === 'number' ? body.total : items.length;
         const pageSize = typeof body.page_size === 'number' ? body.page_size : limit;
         const filters = [
             year !== null ? String(year) : null,
-            tourRaw || null,
+            effectiveTour || null,
             levelRaw || null,
             surface || null,
             countryCode || null,
             q ? `"${q}"` : null,
         ].filter(Boolean);
+        const warnings = [];
+        if (contradictions.length) {
+            const sample = contradictions
+                .slice(0, 5)
+                .map((t) => `${t.id} (${t.tour})`)
+                .join(', ');
+            warnings.push(`The upstream level filter returned ${contradictions.length} tournament(s) that contradict level="${levelRaw}": ` +
+                `${sample}. They were dropped. The API's level reverse-map is not tour-aware (WTA 1000 resolves to tier codes ` +
+                `PM and M), which is a server-side defect; this tool sends tour=${levelTourPrefix} as well, so a repeat of this ` +
+                `warning means the upstream filter is widening again.`);
+        }
         return successEnvelope({
             pagination: {
                 limit: pageSize,
@@ -230,18 +289,25 @@ Parallel-safe: yes. Upstream cost: 1.`,
             tookMs: Date.now() - started,
             upstreamCalls: 1,
             rateLimit: res.headers,
+            warnings: warnings.length ? warnings : undefined,
             data: {
                 title: filters.length > 0
                     ? `Tennis tournaments — ${filters.join(' ')}`
                     : 'Tennis tournaments',
                 filters: {
                     year,
-                    tour: tourRaw || null,
+                    tour: effectiveTour || null,
                     level: levelRaw || null,
                     surface: surface ?? null,
                     countryCode: countryCode || null,
                     q: q || null,
                 },
+                levelFilterIntegrity: {
+                    levelNamesTour: levelTourPrefix,
+                    rowsChecked: rawItems.length,
+                    contradictionsDropped: contradictions.length,
+                    ok: contradictions.length === 0,
+                },
                 items,
                 total,
                 page,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cito-mcp",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Standalone MCP server for the Cito esports and sports API — 42 curated outcome tools for agents (live scoreboards, round economy, opening duels, clutches, vetoes, rosters, tennis, mma).",
   "type": "module",
   "bin": {