cito-mcp 0.5.7 → 0.6.0

package/dist/tools/resolve.js

@@ -31,7 +31,7 @@ function pushCandidates(out, game, type, rows, q, limit) {
         let matchedBy;
         if (q && score <= 0 && index === 0) {
             score = 95;
-            matchedBy = 'upstream-first';
+            matchedBy = 'top-hit';
         }
         const secondary = {};
         for (const key of ['lolPlayerId', 'codPlayerId', 'matchId', 'boutId', 'tournamentId', 'eventId']) {
@@ -366,7 +366,7 @@ async function searchGame(ctx, game, q, type, limit) {
             candidates,
             calls,
             error: partialFromRejection(`game:${game}`, {
-                code: 'UPSTREAM',
+                code: 'SERVICE_ERROR',
                 message: e.message,
             }),
         };
@@ -389,7 +389,7 @@ Do not use when: you already have a stable id/slug from a prior tool.
 
 Empty/ambiguous results still return ok:true with best=null or needsDisambiguation=true — pick from candidates or refine q/game/type. Does not emit AMBIGUOUS_ENTITY as a hard error.
 
-Parallel-safe: yes. Upstream cost: 1–5.
+Parallel-safe: yes. API calls: 1–5.
 Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
     inputSchema: {
         type: 'object',
@@ -507,7 +507,7 @@ Do not use when: fetching a known entity profile — use team_profile or player_
 
 UFC: with q set, results are ranked (exact name > multi-token match > nickname). "Jon Jones" should return jon-jones first — never the generic P4P list.
 
-Parallel-safe: yes. Upstream cost: 1–3.
+Parallel-safe: yes. API calls: 1–3.
 Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
     inputSchema: {
         type: 'object',
@@ -792,11 +792,11 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
                     meta: {
                         ...(it.meta ?? {}),
                         score: raw,
-                        ...(isProtected && raw < RELEVANCE_FLOOR ? { matchedBy: 'upstream-first' } : {}),
+                        ...(isProtected && raw < RELEVANCE_FLOOR ? { matchedBy: 'top-hit' } : {}),
                     },
                 };
             });
-            const keep = (it) => it.meta?.score >= RELEVANCE_FLOOR || it.meta?.matchedBy === 'upstream-first';
+            const keep = (it) => it.meta?.score >= RELEVANCE_FLOOR || it.meta?.matchedBy === 'top-hit';
             droppedBelowFloor = items
                 .filter((it) => !keep(it))
                 .map((it) => ({ id: it.id, name: it.name, score: it.meta?.score }));
@@ -805,8 +805,8 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
         }
         if (q && !preserveUpstreamOrder) {
             items.sort((a, b) => {
-                const am = a.meta?.matchedBy === 'upstream-first' ? 1 : 0;
-                const bm = b.meta?.matchedBy === 'upstream-first' ? 1 : 0;
+                const am = a.meta?.matchedBy === 'top-hit' ? 1 : 0;
+                const bm = b.meta?.matchedBy === 'top-hit' ? 1 : 0;
                 return bm - am || scoreOf(b) - scoreOf(a) || a.name.localeCompare(b.name);
             });
         }
@@ -820,8 +820,8 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
                 .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}. ` +
+            floorWarnings.push(`Dropped ${droppedBelowFloor.length} result(s) that do not match "${q}" at all (the name 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({
@@ -849,7 +849,7 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
                             matched: items.length,
                             droppedBelowFloor: droppedBelowFloor.length,
                             dropped: droppedBelowFloor.slice(0, 25),
-                            upstreamTotal: upstreamTotal ?? null,
+                            unfilteredTotal: upstreamTotal ?? null,
                         },
                     }
                     : {}),

package/dist/tools/schedule.js

@@ -54,7 +54,7 @@ export const tennisSchedule = {
 When to use:
 - "What tennis is on today?"; a specific day's fixtures; results completed on a given date; building a daily digest.
 
-Prefer over: call_api for /tennis/schedule and /tennis/matches/completed (both require ?date=, which this tool supplies and validates); live_matches (in-progress only, right now); upcoming_schedule (a forward window, not a specific day).
+Prefer over: call_api for /tennis/schedule and /tennis/matches/completed (this tool supplies and validates the date, and bounds the rows); live_matches (in-progress only, right now); upcoming_schedule (a forward window, not a specific day).
 
 Do not use when: matches currently in play → live_matches; a named player's history → player_matches.
 
@@ -62,13 +62,14 @@ 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
+'limit' bounds EACH half (the bound is applied by this tool); 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.`,
+Rows: start_time_known false means no start time is held (scheduled_at is then midnight). start_time_kind says whether scheduled_at is when the match actually started (actual) or the published order-of-play time (scheduled). Read status for where a match is now and outcome for how it ended.
+
+Parallel-safe: yes. API calls: 1 or 2.`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -172,7 +173,7 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
         else if (schedRes.status === 'rejected') {
             rejected.push({
                 section: 'schedule',
-                code: 'UPSTREAM',
+                code: 'SERVICE_ERROR',
                 message: String(schedRes.reason).slice(0, 200),
             });
         }
@@ -194,7 +195,7 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
         else if (compRes.status === 'rejected') {
             rejected.push({
                 section: 'completed',
-                code: 'UPSTREAM',
+                code: 'SERVICE_ERROR',
                 message: String(compRes.reason).slice(0, 200),
             });
         }

package/dist/tools/standings.js

@@ -1,3 +1,4 @@
+import { normalizeCoverage } from './rankings.js';
 import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
 import { gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
@@ -77,26 +78,26 @@ export function normalizeStandingRow(row, index) {
 }
 export const standings = {
     name: 'standings',
-    description: `League/event standings or world/division rankings normalized to ranked rows.
-
-When to use:
-- Table / playoff picture
-- UFC rankings; CS2 world or event standings; CDL standings; LoL league/tournament tables
-
-Prefer over: raw standings via call_api for agent-normalized rows.
-
-Do not use when: single team form → team_profile; live scores → live_matches.
-Dota has no first-class standings (may NOT_IMPLEMENTED or weak worldRanking).
-
-Required scope keys by game:
-- lol: leagueId OR tournamentId
-- cs2: omit for world rankings; eventId for event standings
-- cod: optional season/stage
-- ufc: optional division (scope=division)
-- tennis: optional division (ATP or WTA tour; default ATP)
-- dota2: best-effort worldRanking only
-
-Parallel-safe: yes. Upstream cost: 1–2.
+    description: `League/event standings or world/division rankings normalized to ranked rows.
+
+When to use:
+- Table / playoff picture
+- UFC rankings; CS2 world or event standings; CDL standings; LoL league/tournament tables
+
+Prefer over: raw standings via call_api for agent-normalized rows.
+
+Do not use when: single team form → team_profile; live scores → live_matches.
+Dota has no first-class standings (may NOT_IMPLEMENTED or weak worldRanking).
+
+Required scope keys by game:
+- lol: leagueId OR tournamentId
+- cs2: omit for world rankings; eventId for event standings
+- cod: optional season/stage
+- ufc: optional division (scope=division)
+- tennis: optional division (ATP or WTA tour; default ATP); optional season YYYY = that season's last published list (default: latest). listCoverage says when an archived list is held only in part
+- dota2: best-effort worldRanking only
+
+Parallel-safe: yes. API calls: 1–2.
 Example: { "game": "cod", "season": "2026", "limit": 50 }`,
     inputSchema: {
         type: 'object',
@@ -112,7 +113,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             leagueId: stringSchema('LoL league id for league standings.'),
             tournamentId: stringSchema('LoL/COD tournament id.'),
             eventId: stringSchema('CS2 event id for event standings.'),
-            season: stringSchema('Season key (COD).'),
+            season: stringSchema('Season key (COD). Tennis: a year (YYYY) gives that season\'s last published ranking list.'),
             stage: stringSchema('Stage key (COD / LoL).'),
             division: stringSchema('UFC division key.'),
             limit: limitSchema({ default: 50, max: 100 }),
@@ -145,7 +146,11 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
         const leagueId = typeof args.leagueId === 'string' ? args.leagueId : undefined;
         const tournamentId = typeof args.tournamentId === 'string' ? args.tournamentId : undefined;
         const eventId = typeof args.eventId === 'string' ? args.eventId : undefined;
-        const season = typeof args.season === 'string' ? args.season : undefined;
+        const season = typeof args.season === 'string'
+            ? args.season
+            : typeof args.season === 'number' && Number.isFinite(args.season)
+                ? String(Math.trunc(args.season))
+                : undefined;
         const stage = typeof args.stage === 'string' ? args.stage : undefined;
         const division = typeof args.division === 'string' ? args.division : undefined;
         const tennisPage = typeof args.page === 'number' && Number.isFinite(args.page) && args.page >= 1
@@ -241,7 +246,18 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
         else if (game === 'tennis') {
             const tour = String(division ?? 'ATP').toUpperCase() === 'WTA' ? 'WTA' : 'ATP';
             path = '/tennis/standings';
-            query = { tour, top_n: Math.min(limit, 100), page: tennisPage };
+            const tennisSeason = season && /^\d{4}$/.test(season.trim()) ? season.trim() : undefined;
+            if (season && !tennisSeason) {
+                return errorEnvelope({
+                    code: 'VALIDATION',
+                    message: `season must be a year (YYYY) for tennis (got '${season}')`,
+                    game,
+                    source: 'standings',
+                    requestId,
+                    tookMs: Date.now() - started,
+                });
+            }
+            query = { tour, top_n: Math.min(limit, 100), page: tennisPage, ...(tennisSeason ? { season: tennisSeason } : {}) };
             effectiveScope = 'world';
             title = `${tour} singles rankings`;
         }
@@ -371,6 +387,9 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
         };
         pushWarning(upstreamMeta.warning);
         pushWarning(dataQuality.warning);
+        const tennisCoverage = game === 'tennis' ? asRecord(obj?.list_coverage) : null;
+        if (tennisCoverage && tennisCoverage.status === 'partial')
+            pushWarning(tennisCoverage.note);
         if (Array.isArray(upstreamMeta.warnings)) {
             for (const w of upstreamMeta.warnings)
                 pushWarning(w);
@@ -412,6 +431,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                 ...(game === 'tennis'
                     ? {
                         rankingDate: pickString(obj?.ranking_date) ?? null,
+                        listCoverage: tennisCoverage ? normalizeCoverage(tennisCoverage) : null,
                         updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt, obj?.ranking_date) ?? null,
                     }
                     : {

package/dist/tools/team.js

@@ -42,7 +42,7 @@ Prefer over: separate roster + matches + detail via call_api.
 Do not use when: UFC fighters → player_profile; unknown name → resolve_entity first.
 Dota may return partial roster (API gap). Prefer slug for lol/cod; teamId for cs2.
 
-Parallel-safe: yes. Upstream cost: 2–4.
+Parallel-safe: yes. API calls: 2–4.
 Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
     inputSchema: {
         type: 'object',
@@ -532,7 +532,7 @@ function winnerSide(match, a) {
 }
 export const headToHead = {
     name: 'head_to_head',
-    description: `Composed head-to-head record between two teams, two UFC fighters, or two tennis players. No first-class REST H2H exists — this tool filters match history server-side.
+    description: `Head-to-head record between two teams, two UFC fighters, or two tennis players. Tennis reads the tennis head-to-head route; other games filter match history server-side.
 
 When to use:
 - Rivalry / series record questions
@@ -544,7 +544,9 @@ Do not use when: single-side form only → team_profile or player_profile.
 
 Caveat: Dota filters are weaker; expect meta.warnings when data is sparse.
 
-Parallel-safe: yes. Upstream cost: 2–4.
+Tennis: pass entityType "player" with sideA and sideB (ids like atp_207989, or names). This tool has no players param; for three or more players use h2h_matrix, which does. limit pages the meetings list only (max 50); every tally covers all meetings. In the payload current_rank is null when a player is not on the tour's latest list: read last_rank. The tiebreak and level_breakdown keys are in data.h2h.
+
+Parallel-safe: yes. API calls: 2–4.
 Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
     inputSchema: {
         type: 'object',
@@ -558,8 +560,8 @@ Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
                 default: 'team',
                 description: 'team (default), fighter (UFC), or player (tennis).',
             },
-            sideA: stringSchema('Id or slug for side A.', 'faze'),
-            sideB: stringSchema('Id or slug for side B.', 'navi'),
+            sideA: stringSchema('Id or slug for side A (tennis: atp_207989 or a player name).', 'faze'),
+            sideB: stringSchema('Id or slug for side B (tennis: atp_206173 or a player name).', 'navi'),
             limit: limitSchema({ default: 20, max: 50, description: 'Max meetings returned.' }),
             from: stringSchema('ISO-8601 lower bound on meeting startTime (client filter).'),
             to: stringSchema('ISO-8601 upper bound on meeting startTime (client filter).'),
@@ -982,7 +984,7 @@ Do not use when: a two-player rivalry deep-dive with tiebreak/decider splits →
 
 Tennis-only. players takes 2-16 ids or names (names resolve via player search). Each matrix cell is "W-L" from the row player's perspective, "-" on the diagonal.
 
-Parallel-safe: yes. Upstream cost: 1 + one search per unresolved name.`,
+Parallel-safe: yes. API calls: 1 + one search per unresolved name.`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,

package/dist/tools/tournaments.js

@@ -54,10 +54,10 @@ 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.
+Masters events.
+The category field reports ATP 500 and ATP 250 both as atp_tour (read tier to tell them apart), and WTA 1000 events as wta_1000.
 
-Parallel-safe: yes. Upstream cost: 1.`,
+Parallel-safe: yes. API calls: 1.`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -232,10 +232,8 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 .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.`);
+            warnings.push(`The level filter returned ${contradictions.length} tournament(s) that contradict level="${levelRaw}": ` +
+                `${sample}. They were dropped; this tool also sends tour=${levelTourPrefix}.`);
         }
         return successEnvelope({
             pagination: {

package/dist/tools/types.js

@@ -156,7 +156,7 @@ export async function runTool(def, args, ctx) {
     catch (error) {
         const { errorEnvelope, toMcpResult: toResult } = await import('../envelope.js');
         return toResult(errorEnvelope({
-            code: 'UPSTREAM',
+            code: 'SERVICE_ERROR',
             message: error.message || 'Unhandled tool error',
             game: null,
             source: def.name,