cito-mcp 0.4.5 → 0.4.7

package/README.md

@@ -2,7 +2,7 @@
 
 Standalone [MCP](https://modelcontextprotocol.io) server for the [Cito esports API](https://api.citoapi.com) — **curated outcome tools** for agents building esports apps, dashboards, bots, and research flows.
 
-**Version:** `0.3.20` · **Node:** `>=20` · **Install:** `npx cito-mcp`
+**Version:** `0.4.7` · **Node:** `>=20` · **Install:** `npx cito-mcp`
 
 Primary games & sports: **lol · cs2 · dota2 · cod · ufc · tennis**. Long-tail REST stays available via `call_api`.
 
@@ -50,8 +50,6 @@ Where the source data is partial, the tool says so instead of shipping a plausib
 | 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 |
 
 ---
@@ -535,18 +533,21 @@ claude mcp add cito -e CITO_API_KEY=cito_… "--" npx -y cito-mcp
 ### Semver expectations
 
 - **0.2.4** is a **major surface break** vs 0.1 (tool rename + removal of OpenAPI mass-generation).
-- Further 0.2.x patches may refine envelopes and composite quality without renaming the 15 tools.
+- Further 0.2.x patches may refine envelopes and composite quality without renaming the shipped tools. (This line previously said "15 tools" while the catalog shipped 42 — the count here is intentionally not restated, because a number duplicated in prose drifts the moment the catalog changes.)
 - Promoting Fortnite (or other titles) into the primary `game` enum would be a minor feature bump with catalog/docs updates.
 
 ---
 
 ## Changelog (summary)
 
+### 0.4.7
+
+- Removed the unregistered tennis odds module and its README entries; `match_details` `sections:["odds"]` stays UFC-only and answers `NOT_IMPLEMENTED` for other games.
+
 ### 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`.
@@ -560,12 +561,10 @@ Second tennis correctness pass, from the 2026-09-12 re-sweep. Five defects, each
 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 bookmaker 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).

package/dist/client.js

@@ -102,6 +102,8 @@ export async function fetchJson(ctx, path, opts) {
     catch {
         data = text;
     }
+    if (!opts?.raw && response.ok && isTennisPath(path))
+        data = flattenTennisEnvelope(data);
     return {
         ok: response.ok,
         status: response.status,
@@ -158,6 +160,43 @@ export function asRecord(value) {
     }
     return null;
 }
+const TENNIS_LIST_META_KEYS = new Set(['count', 'limit', 'total', 'page', 'totalPages', 'hasNext', 'hasPrev']);
+function isTennisPath(path) {
+    return /^(\/api\/v1)?\/tennis(\/|\?|$)/.test(path);
+}
+function snakeKey(key) {
+    return key.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
+export function flattenTennisEnvelope(body) {
+    const env = asRecord(body);
+    if (!env || !('data' in env) || 'items' in env)
+        return body;
+    const meta = asRecord(env.meta);
+    if (!meta)
+        return body;
+    const success = env.success ?? true;
+    if (Array.isArray(env.data)) {
+        const out = { success, items: env.data };
+        for (const [key, value] of Object.entries(meta)) {
+            if (!TENNIS_LIST_META_KEYS.has(key))
+                out[snakeKey(key)] = value;
+        }
+        out.total = typeof meta.total === 'number' ? meta.total : env.data.length;
+        out.page = typeof meta.page === 'number' ? meta.page : 1;
+        out.page_size = typeof meta.limit === 'number' ? meta.limit : env.data.length;
+        if (typeof meta.totalPages === 'number')
+            out.total_pages = meta.totalPages;
+        if (typeof meta.hasNext === 'boolean')
+            out.has_next = meta.hasNext;
+        if (typeof meta.hasPrev === 'boolean')
+            out.has_prev = meta.hasPrev;
+        return out;
+    }
+    const resource = asRecord(env.data);
+    if (resource)
+        return { success, ...resource };
+    return body;
+}
 export function unwrapPayload(value) {
     let cur = value;
     for (let depth = 0; depth < 3; depth += 1) {

package/dist/instructions.js

@@ -1,77 +1,77 @@
-export const SERVER_INSTRUCTIONS = `# Cito MCP — agent operating manual
-
-You are connected to Cito esports data (read-only). Prefer curated outcome tools over raw REST. Production apps must call Cito REST with the user's API key; use this MCP to design, prototype, and resolve IDs — not as a multi-tenant runtime bus.
-
-## Hard rules
-
-1. **Never invent IDs.** Do not guess matchId, gameId, playerId, team slug, eventId, or boutId. Always obtain IDs from a prior tool result (resolve, live, schedule, search, or list). If the user gives a name ("T1", "s1mple", "UFC 300"), call resolve_entity/search_entities first.
-2. **Resolve before deep.** Name → ID/slug → summary/page → deep stats. Skip resolve only when the user already provided a Cito ID/slug.
-3. **One screen, one composite.** Prefer a page/summary tool over stitching 4–6 thin GETs.
-4. **Honor the envelope.** Parse ok, data, pagination, partial, error, meta.rateLimit, meta.entities. Partial section failures are not total failures — use successful sections.
-5. **Read-only.** All curated tools are safe to retry except where error.retryable is false for bad args / entitlement.
-
-## Game parameter
-
-game enum (unless a tool documents otherwise): lol | cs2 | dota2 | ufc | cod | tennis | all
-
-- Default when the user named one title: that game. Default for "what's live?" / multi-title: omit game or all on tools that accept it.
-- On UNSUPPORTED_GAME / 403 for a title: stop retrying that game; call api_health; report plan gaps.
-- Fortnite and other titles may appear via call_api/resources; do not assume they are in the curated enum until list_capabilities says so.
-
-## Preferred tool order
-
-1. Unsure → list_capabilities (filter by game or job). Optional: api_health for key/tier/included games.
-2. Name without ID → resolve_entity (best match) or search_entities (browse). Reuse returned id/slug.
-3. Live / upcoming → live_matches; upcoming_schedule.
-4. Match UI / recap → match_summary first. match_details only for timelines, full maps, demos, live state.
-5. Team page → team_profile. Player form → player_profile. Tables/ranks → standings.
-6. Pre-match → match_preview. Rivalry → head_to_head. Event / fight-night card → event_card.
-7. Escape hatch → call_api (allowlisted path prefixes; prefer GET). Prefer curated tools.
-
-Mnemonic: resolve → live/schedule → summary → deep.
-
-## Parallel vs sequence
-
-Parallel-safe: independent reads (team_profile A ∥ team_profile B; live_matches ∥ api_health). Cap ~3–5 concurrent agent tools; check meta.rateLimit.remaining.
-
-Serial required: resolve → detail; pagination (cursor from page N only); live board → selected match deep-dive.
-
-Prefer server-side fan-out inside composites (partial[] recovery) over agent N+1.
-
-## Pagination
-
-Lists use pagination: { limit, offset?, total?, hasMore, nextCursor, prevCursor }. Default limit 20, max 50. Loop with cursor: pagination.nextCursor and the same filters. Never invent cursors. Empty list is ok:true with items:[].
-
-## Errors
-
-ok:false → read error.code (VALIDATION, NOT_FOUND, UNSUPPORTED_GAME, RATE_LIMIT, UNAUTHORIZED, UPSTREAM, PATH_NOT_ALLOWED, NOT_IMPLEMENTED). Follow error.recover[]. Retry only when retryable.
-
-ok:true with partial[] → use successful sections; do not treat partial as total fail.
-ok:true with meta.warnings[] → filters or depth degraded; do not assume ignored filters applied.
-resolve_entity ambiguity is soft: ok:true with data.needsDisambiguation and data.candidates — pick a candidate; do not wait for AMBIGUOUS_ENTITY.
-
-## Recipes
-
-Live board: api_health (optional) → live_matches → match_summary for selected matchId.
-UFC empty live (count=0): read section.note / emptyReason / health (workerAlive, lag) / supervisor / nextCard — do not claim "API offline" without workerAlive/lag; never invent matchups from supervisor shells.
-Team page: resolve_entity {type:team} → team_profile.
-Player card: resolve_entity {type:player|fighter} → player_profile.
-Fight night / event card: resolve_entity {type:event} → event_card {includeMatches:true} → match_preview for a featured bout.
-Match preview (named sides): resolve_entity each side (optional) → match_preview {teamA, teamB}.
-App scaffold: list_capabilities ∥ api_health ∥ live_matches, then one composite per screen.
-
-## Resources
-
-- cito://llms.txt — product context when available
-- cito://capabilities — catalog summary
-- cito://openapi.json — optional public OpenAPI fetch for typed clients
-
-## What not to do
-
-- Invent match/player/team IDs from memory.
-- Parallel-paginate the same list with different cursors.
-- N+1 match_details for every live row.
-- Retry UNSUPPORTED_GAME or VALIDATION unchanged.
-- Ship production traffic through MCP.
-- Flood odds/timelines when a summary answers the question.
+export const SERVER_INSTRUCTIONS = `# Cito MCP — agent operating manual
+
+You are connected to Cito esports data (read-only). Prefer curated outcome tools over raw REST. Production apps must call Cito REST with the user's API key; use this MCP to design, prototype, and resolve IDs — not as a multi-tenant runtime bus.
+
+## Hard rules
+
+1. **Never invent IDs.** Do not guess matchId, gameId, playerId, team slug, eventId, or boutId. Always obtain IDs from a prior tool result (resolve, live, schedule, search, or list). If the user gives a name ("T1", "s1mple", "UFC 300"), call resolve_entity/search_entities first.
+2. **Resolve before deep.** Name → ID/slug → summary/page → deep stats. Skip resolve only when the user already provided a Cito ID/slug.
+3. **One screen, one composite.** Prefer a page/summary tool over stitching 4–6 thin GETs.
+4. **Honor the envelope.** Parse ok, data, pagination, partial, error, meta.rateLimit, meta.entities. Partial section failures are not total failures — use successful sections.
+5. **Read-only.** All curated tools are safe to retry except where error.retryable is false for bad args / entitlement.
+
+## Game parameter
+
+game enum (unless a tool documents otherwise): lol | cs2 | dota2 | ufc | cod | tennis | all
+
+- Default when the user named one title: that game. Default for "what's live?" / multi-title: omit game or all on tools that accept it.
+- On UNSUPPORTED_GAME / 403 for a title: stop retrying that game; call api_health; report plan gaps.
+- Fortnite and other titles may appear via call_api/resources; do not assume they are in the curated enum until list_capabilities says so.
+
+## Preferred tool order
+
+1. Unsure → list_capabilities (filter by game or job). Optional: api_health for key/tier/included games.
+2. Name without ID → resolve_entity (best match) or search_entities (browse). Reuse returned id/slug.
+3. Live / upcoming → live_matches; upcoming_schedule.
+4. Match UI / recap → match_summary first. match_details only for timelines, full maps, demos, live state.
+5. Team page → team_profile. Player form → player_profile. Tables/ranks → standings.
+6. Pre-match → match_preview. Rivalry → head_to_head. Event / fight-night card → event_card.
+7. Escape hatch → call_api (allowlisted path prefixes; prefer GET). Prefer curated tools.
+
+Mnemonic: resolve → live/schedule → summary → deep.
+
+## Parallel vs sequence
+
+Parallel-safe: independent reads (team_profile A ∥ team_profile B; live_matches ∥ api_health). Cap ~3–5 concurrent agent tools; check meta.rateLimit.remaining.
+
+Serial required: resolve → detail; pagination (cursor from page N only); live board → selected match deep-dive.
+
+Prefer server-side fan-out inside composites (partial[] recovery) over agent N+1.
+
+## Pagination
+
+Lists use pagination: { limit, offset?, total?, hasMore, nextCursor, prevCursor }. Default limit 20, max 50. Loop with cursor: pagination.nextCursor and the same filters. Never invent cursors. Empty list is ok:true with items:[].
+
+## Errors
+
+ok:false → read error.code (VALIDATION, NOT_FOUND, UNSUPPORTED_GAME, RATE_LIMIT, UNAUTHORIZED, UPSTREAM, PATH_NOT_ALLOWED, NOT_IMPLEMENTED). Follow error.recover[]. Retry only when retryable.
+
+ok:true with partial[] → use successful sections; do not treat partial as total fail.
+ok:true with meta.warnings[] → filters or depth degraded; do not assume ignored filters applied.
+resolve_entity ambiguity is soft: ok:true with data.needsDisambiguation and data.candidates — pick a candidate; do not wait for AMBIGUOUS_ENTITY.
+
+## Recipes
+
+Live board: api_health (optional) → live_matches → match_summary for selected matchId.
+UFC empty live (count=0): read section.note / emptyReason / health (workerAlive, lag) / supervisor / nextCard — do not claim "API offline" without workerAlive/lag; never invent matchups from supervisor shells.
+Team page: resolve_entity {type:team} → team_profile.
+Player card: resolve_entity {type:player|fighter} → player_profile.
+Fight night / event card: resolve_entity {type:event} → event_card {includeMatches:true} → match_preview for a featured bout.
+Match preview (named sides): resolve_entity each side (optional) → match_preview {teamA, teamB}.
+App scaffold: list_capabilities ∥ api_health ∥ live_matches, then one composite per screen.
+
+## Resources
+
+- cito://llms.txt — product context when available
+- cito://capabilities — catalog summary
+- cito://openapi.json — optional public OpenAPI fetch for typed clients
+
+## What not to do
+
+- Invent match/player/team IDs from memory.
+- Parallel-paginate the same list with different cursors.
+- N+1 match_details for every live row.
+- Retry UNSUPPORTED_GAME or VALIDATION unchanged.
+- Ship production traffic through MCP.
+- Flood odds/timelines when a summary answers the question.
 `;

package/dist/scrub.js

@@ -15,6 +15,50 @@ const INTERNAL_KEYS = new Set([
     'wikiUrl',
     'wiki_url',
     'jsonLd',
+    '_mergeSource',
+    '_provenance',
+    'duplicateOf',
+    'duplicate_of',
+    'identityConfidence',
+    'identity_confidence',
+    'roleSource',
+    'role_source',
+    'verifiedCompetitive',
+    'verified_competitive',
+    'profileAttemptedAt',
+    'profileFailureMessage',
+    'profileFailureReason',
+    'profileFetchStatus',
+    'profileImageAttemptedAt',
+    'profileImageAttempts',
+    'profileImageError',
+    'profileImageSteamAttemptedAt',
+    'profileImageWorker',
+    'ratingSource',
+    'requiredSourceData',
+    'rawText',
+    'raw_text',
+    'scrapedAt',
+    'scraped_at',
+    'sourceSummary',
+    'sourceNote',
+    'durableStatsTables',
+    'lineupSource',
+    'mapMediaSource',
+    'rosterSource',
+    'upstream',
+    'liveCandidateWindowMinutes',
+    'rowHash',
+    'row_hash',
+    'snapshotHash',
+    'snapshot_hash',
+    'syncRunId',
+    'sync_run_id',
+    'discoveredSources',
+    'sidecarAvailable',
+    'imageCandidates',
+    'image_candidates',
+    'source_url',
 ]);
 const SCRAPE_PARENTS = new Set(['dataAvailability', 'health']);
 const SCRAPE_KEYS = new Set(['strategy', 'samples']);

package/dist/tools/insight.js

@@ -260,20 +260,20 @@ export function composeH2H(game, sideA, sideB, rows, limit) {
 }
 export const matchPreview = {
     name: 'match_preview',
-    description: `COMPOSITE pre-match briefing: sides, roster/form snippets, H2H stub, event context — for pick'ems, articles, and match-page before state.
-
-When to use:
-- Upcoming match deep link
-- "Who should I watch before this game?"
-- App scaffold for preview cards
-
-Prefer over: manually chaining team_profile ×2 + head_to_head + schedule.
-Prefer match_summary when match is completed; match_details for live in-game.
-
-Do not use when: user wants final score/recap of a finished match.
-
-Parallel-safe: yes. Upstream cost: 4–8.
-Tennis H2H accepts an optional surface filter (Hard, Clay, Grass).
+    description: `COMPOSITE pre-match briefing: sides, roster/form snippets, H2H stub, event context — for pick'ems, articles, and match-page before state.
+
+When to use:
+- Upcoming match deep link
+- "Who should I watch before this game?"
+- App scaffold for preview cards
+
+Prefer over: manually chaining team_profile ×2 + head_to_head + schedule.
+Prefer match_summary when match is completed; match_details for live in-game.
+
+Do not use when: user wants final score/recap of a finished match.
+
+Parallel-safe: yes. Upstream cost: 4–8.
+Tennis H2H accepts an optional surface filter (Hard, Clay, Grass).
 Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "recentLimit": 5 }`,
     inputSchema: {
         type: 'object',
@@ -707,31 +707,31 @@ async function resolveEventKey(ctx, game, q) {
 }
 export const eventCard = {
     name: 'event_card',
-    description: `COMPOSITE event / fight-night card: identity, bout or match list, optional standings snippet.
-
-When to use:
-- UFC fight night / numbered event page ("UFC 300 card", "Fight Night")
-- CS2 event hub with match list
-- Tournament/event overview before match_preview drill-down
-
-Bouts come back in card order — main event first, then prelims, then early prelims.
-Each bout carries weightClass, titleBout, card placement, and (once fought) result
-{ method, round, time, referee, winnerSlug }. Each corner carries images
-{ headshotUrl, bodyImageUrl, imageUrl, proxiedImageUrl }, record, nickname, rank,
-championStatus, country and flag when upstream supplies them. Use proxiedImageUrl in
-browsers — the image host sends no CORS header. You do not need call_api per fighter for faces.
-
-Prefer over: agent-side resolve + call_api /ufc/events + bout expansion; N+1 match_summary for the card list only; per-fighter call_api just to fetch headshots.
-
-Prefer match_preview for one bout/match briefing; match_summary for completed recaps; live_matches for live-only strips; standings alone for pure tables.
-
-Do not use when: you only need live scores (live_matches); single finished match recap (match_summary); no event name/id yet and game unknown.
-
-Tennis: pass a tournament id/slug to get the draw bracket — rounds carry a round
-code (Q1..R128, QF, SF, F) with each match's players and score. Set is the
-primary tennis path here; there is no separate draw tool.
-
-Parallel-safe: yes. Upstream cost: 1–4.
+    description: `COMPOSITE event / fight-night card: identity, bout or match list, optional standings snippet.
+
+When to use:
+- UFC fight night / numbered event page ("UFC 300 card", "Fight Night")
+- CS2 event hub with match list
+- Tournament/event overview before match_preview drill-down
+
+Bouts come back in card order — main event first, then prelims, then early prelims.
+Each bout carries weightClass, titleBout, card placement, and (once fought) result
+{ method, round, time, referee, winnerSlug }. Each corner carries images
+{ headshotUrl, bodyImageUrl, imageUrl, proxiedImageUrl }, record, nickname, rank,
+championStatus, country and flag when upstream supplies them. Use proxiedImageUrl in
+browsers — the image host sends no CORS header. You do not need call_api per fighter for faces.
+
+Prefer over: agent-side resolve + call_api /ufc/events + bout expansion; N+1 match_summary for the card list only; per-fighter call_api just to fetch headshots.
+
+Prefer match_preview for one bout/match briefing; match_summary for completed recaps; live_matches for live-only strips; standings alone for pure tables.
+
+Do not use when: you only need live scores (live_matches); single finished match recap (match_summary); no event name/id yet and game unknown.
+
+Tennis: pass a tournament id/slug to get the draw bracket — rounds carry a round
+code (Q1..R128, QF, SF, F) with each match's players and score. Set is the
+primary tennis path here; there is no separate draw tool.
+
+Parallel-safe: yes. Upstream cost: 1–4.
 Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "includeStandings": false }`,
     inputSchema: {
         type: 'object',

package/dist/tools/live.js

@@ -154,20 +154,20 @@ function slimUfcNextCard(payload) {
 }
 export const liveMatches = {
     name: 'live_matches',
-    description: `Live matches board across primary games, or a single game filter. Normalized labels, scores, and matchIds.
-
-When to use:
-- "What's live right now?"
-- Ops/dashboard live strip
-
-Prefer over: sequential per-game call_api live probes.
-
-Do not use when: user wants upcoming fixtures → upcoming_schedule; historical results → match_summary.
-
-CS2 live path is /cs2/live; UFC is included in multi-game fan-out.
-UFC empty board: section.note + emptyReason + health (workerAlive/lag) + optional supervisor/nextCard (non-live); never fake match items from events[].
-
-Parallel-safe: yes. Upstream cost: 1–5 (allSettled).
+    description: `Live matches board across primary games, or a single game filter. Normalized labels, scores, and matchIds.
+
+When to use:
+- "What's live right now?"
+- Ops/dashboard live strip
+
+Prefer over: sequential per-game call_api live probes.
+
+Do not use when: user wants upcoming fixtures → upcoming_schedule; historical results → match_summary.
+
+CS2 live path is /cs2/live; UFC is included in multi-game fan-out.
+UFC empty board: section.note + emptyReason + health (workerAlive/lag) + optional supervisor/nextCard (non-live); never fake match items from events[].
+
+Parallel-safe: yes. Upstream cost: 1–5 (allSettled).
 Example: { "game": "all", "limitPerGame": 10 }`,
     inputSchema: {
         type: 'object',
@@ -347,24 +347,24 @@ Example: { "game": "all", "limitPerGame": 10 }`,
 };
 export const upcomingSchedule = {
     name: 'upcoming_schedule',
-    description: `Upcoming matches/events for one game, with game-specific filters.
-
-When to use:
-- "What's on this week?"
-- Calendar UI; team next matches
-
-Prefer over: live_matches for not-yet-started fixtures.
-
-Do not use when: only in-progress matches needed → live_matches.
-
-Filter support (unsupported params are ignored with meta.warnings — do not assume filtering worked):
-- lol: hours, team (slug), league (slug)
-- cs2: team, from, to (ISO); hours not applied upstream
-- cod: team, tournamentId
-- dota2: limit/cursor primarily; team may be client-filtered where data allows
-- ufc: hours / from / to applied client-side after bout expansion (API has no hours); event shells labeled by event name; bouts use fighters[] corners
-
-Parallel-safe: yes. Upstream cost: 1–2.
+    description: `Upcoming matches/events for one game, with game-specific filters.
+
+When to use:
+- "What's on this week?"
+- Calendar UI; team next matches
+
+Prefer over: live_matches for not-yet-started fixtures.
+
+Do not use when: only in-progress matches needed → live_matches.
+
+Filter support (unsupported params are ignored with meta.warnings — do not assume filtering worked):
+- lol: hours, team (slug), league (slug)
+- cs2: team, from, to (ISO); hours not applied upstream
+- cod: team, tournamentId
+- dota2: limit/cursor primarily; team may be client-filtered where data allows
+- ufc: hours / from / to applied client-side after bout expansion (API has no hours); event shells labeled by event name; bouts use fighters[] corners
+
+Parallel-safe: yes. Upstream cost: 1–2.
 Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
     inputSchema: {
         type: 'object',

package/dist/tools/match.js

@@ -163,18 +163,18 @@ function primaryPath(game, matchId) {
 }
 export const matchSummary = {
     name: 'match_summary',
-    description: `COMPOSITE match card: scoreline, key context, player performances, and VOD/demo links when available.
-
-When to use:
-- Match recap / default match UI
-- After user selects a live or completed matchId
-
-Prefer over match_details for chat answers and default UIs.
-Prefer match_details for timelines, full map trees, live state, advanced packages.
-
-Do not use when: no matchId yet (resolve from live/schedule); pure pre-match → match_preview.
-
-Parallel-safe: yes. Upstream cost: 2–5.
+    description: `COMPOSITE match card: scoreline, key context, player performances, and VOD/demo links when available.
+
+When to use:
+- Match recap / default match UI
+- After user selects a live or completed matchId
+
+Prefer over match_details for chat answers and default UIs.
+Prefer match_details for timelines, full map trees, live state, advanced packages.
+
+Do not use when: no matchId yet (resolve from live/schedule); pure pre-match → match_preview.
+
+Parallel-safe: yes. Upstream cost: 2–5.
 Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includePlayerStats": true }`,
     inputSchema: {
         type: 'object',
@@ -586,23 +586,23 @@ export function summarizeTennisMatchStats(data) {
 }
 export const matchDetails = {
     name: 'match_details',
-    description: `Deep match package: optional timelines, advanced stats, live state/snapshots, full map/game tree, media inventory.
-
-When to use:
-- Analyst deep dive
-- Live in-game window (LoL/CS2/UFC)
-- Full demo list
-
-Prefer over match_summary only when summary is insufficient.
-Prefer match_summary for short answers and default cards.
-
-Do not use when: first-pass live board (use live_matches + match_summary).
-
-Section selection: pass includeTimeline / includeLiveState / includeAdvanced booleans, OR an explicit sections[] list.
-UFC betting lines: sections:["odds"] (opt-in, never in the default set).
-If sections[] is non-empty it wins (booleans are ignored). LoL liveState/advanced require gameId.
-
-Parallel-safe: yes. Upstream cost: 1–8 (section-gated).
+    description: `Deep match package: optional timelines, advanced stats, live state/snapshots, full map/game tree, media inventory.
+
+When to use:
+- Analyst deep dive
+- Live in-game window (LoL/CS2/UFC)
+- Full demo list
+
+Prefer over match_summary only when summary is insufficient.
+Prefer match_summary for short answers and default cards.
+
+Do not use when: first-pass live board (use live_matches + match_summary).
+
+Section selection: pass includeTimeline / includeLiveState / includeAdvanced booleans, OR an explicit sections[] list.
+UFC betting lines: sections:["odds"] (opt-in, never in the default set).
+If sections[] is non-empty it wins (booleans are ignored). LoL liveState/advanced require gameId.
+
+Parallel-safe: yes. Upstream cost: 1–8 (section-gated).
 Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "includeLiveState": false }`,
     inputSchema: {
         type: 'object',
@@ -809,7 +809,7 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
             else {
                 partial.push(partialFromRejection('odds', {
                     code: 'NOT_IMPLEMENTED',
-                    message: `Odds are not curated for ${game}. Currently available: UFC (/ufc/bouts/{id}/odds). Tennis odds were withdrawn.`,
+                    message: `Odds are only available for UFC (/ufc/bouts/{id}/odds).`,
                 }));
             }
         }

package/dist/tools/meta.js

@@ -488,18 +488,18 @@ const GAMES_META = [
 ];
 export const listCapabilities = {
     name: 'list_capabilities',
-    description: `Curated catalog of cito-mcp tools, games, jobs, and builder recipes.
-
-When to use:
-- Session start or "what can you do?"
-- Mapping app screens to tools
-- Filtering by game or job (live_board, match_page, team_page, player_form, standings, h2h, schedule, preview, event_card, app_scaffold)
-
-Prefer over: guessing from memory; exploring raw OpenAPI via call_api.
-
-Do not use when: you already know the tool and have IDs — call that tool directly.
-
-Parallel-safe: yes. Upstream cost: 0.
+    description: `Curated catalog of cito-mcp tools, games, jobs, and builder recipes.
+
+When to use:
+- Session start or "what can you do?"
+- Mapping app screens to tools
+- Filtering by game or job (live_board, match_page, team_page, player_form, standings, h2h, schedule, preview, event_card, app_scaffold)
+
+Prefer over: guessing from memory; exploring raw OpenAPI via call_api.
+
+Do not use when: you already know the tool and have IDs — call that tool directly.
+
+Parallel-safe: yes. Upstream cost: 0.
 Example: { "game": "cs2", "job": "live_board", "includeExamples": true }`,
     inputSchema: {
         type: 'object',
@@ -582,18 +582,18 @@ Example: { "game": "cs2", "job": "live_board", "includeExamples": true }`,
 };
 export const apiHealth = {
     name: 'api_health',
-    description: `API reachability, API key validity, plan tier, rate-limit headers, and best-effort included games.
-
-When to use:
-- Once per session before heavy work
-- After 401/403/UNSUPPORTED_GAME/RATE_LIMIT
-- App scaffolding entitlement checks
-
-Prefer over: probing random game endpoints to test the key.
-
-Do not use when: you only need live scores — use live_matches.
-
-Parallel-safe: yes. Upstream cost: 1–6.
+    description: `API reachability, API key validity, plan tier, rate-limit headers, and best-effort included games.
+
+When to use:
+- Once per session before heavy work
+- After 401/403/UNSUPPORTED_GAME/RATE_LIMIT
+- App scaffolding entitlement checks
+
+Prefer over: probing random game endpoints to test the key.
+
+Do not use when: you only need live scores — use live_matches.
+
+Parallel-safe: yes. Upstream cost: 1–6.
 Example: { "includeGameProbes": true }`,
     inputSchema: {
         type: 'object',
@@ -736,21 +736,21 @@ function pathAllowed(path) {
 }
 export const callApi = {
     name: 'call_api',
-    description: `Power escape hatch: allowlisted Cito REST call with unshaped raw JSON in data.raw.
-
-When to use:
-- Long-tail paths not yet curated (Fortnite, CS2 leaderboards, niche stats)
-- Debugging payloads while building an app
-- User explicitly knows an OpenAPI path
-
-Prefer curated tools for all standard jobs (live, schedule, profiles, standings, H2H, previews).
-
-Do not use when: a curated tool covers the outcome. Avoid parallel storms; same plan rate limits apply.
-
-Path must start with / and match allowlisted prefixes: /health, /lol, /cs2, /dota2, /cod, /ufc, /fortnite, /tennis.
-Rejects absolute URLs and path traversal → PATH_NOT_ALLOWED.
-
-Parallel-safe: yes but discouraged in bulk. Upstream cost: 1.
+    description: `Power escape hatch: allowlisted Cito REST call with unshaped raw JSON in data.raw.
+
+When to use:
+- Long-tail paths not yet curated (Fortnite, CS2 leaderboards, niche stats)
+- Debugging payloads while building an app
+- User explicitly knows an OpenAPI path
+
+Prefer curated tools for all standard jobs (live, schedule, profiles, standings, H2H, previews).
+
+Do not use when: a curated tool covers the outcome. Avoid parallel storms; same plan rate limits apply.
+
+Path must start with / and match allowlisted prefixes: /health, /lol, /cs2, /dota2, /cod, /ufc, /fortnite, /tennis.
+Rejects absolute URLs and path traversal → PATH_NOT_ALLOWED.
+
+Parallel-safe: yes but discouraged in bulk. Upstream cost: 1.
 Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"page\\":1,\\"limit\\":20}" }`,
     inputSchema: {
         type: 'object',
@@ -834,7 +834,7 @@ Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"pag
                 });
             }
         }
-        const res = await fetchJson(ctx, path, { method, query });
+        const res = await fetchJson(ctx, path, { method, query, raw: true });
         if (!res.ok) {
             return errorEnvelope({
                 code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
@@ -872,20 +872,20 @@ const SPEC_OMITS = {
 };
 export const listRoutes = {
     name: 'list_routes',
-    description: `Index of raw REST routes from the live OpenAPI spec: method, path, summary, tag.
-
-When to use:
-- You need a long-tail path for call_api and do not want to guess
-- Checking whether an endpoint exists before building around it
-- Mapping what raw data backs a curated tool
-
-Prefer curated tools for standard jobs — this indexes the escape hatch, it is not a replacement for list_capabilities.
-
-Do not use when: a curated tool already covers the outcome (call list_capabilities instead).
-
-Note: the spec omits /lol entirely, though LoL routes work. Filtering by game=lol returns that caveat rather than an empty list.
-
-Parallel-safe: yes. Upstream cost: 1.
+    description: `Index of raw REST routes from the live OpenAPI spec: method, path, summary, tag.
+
+When to use:
+- You need a long-tail path for call_api and do not want to guess
+- Checking whether an endpoint exists before building around it
+- Mapping what raw data backs a curated tool
+
+Prefer curated tools for standard jobs — this indexes the escape hatch, it is not a replacement for list_capabilities.
+
+Do not use when: a curated tool already covers the outcome (call list_capabilities instead).
+
+Note: the spec omits /lol entirely, though LoL routes work. Filtering by game=lol returns that caveat rather than an empty list.
+
+Parallel-safe: yes. Upstream cost: 1.
 Example: { "game": "ufc", "q": "rankings" }`,
     inputSchema: {
         type: 'object',

package/dist/tools/player.js

@@ -44,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',
@@ -541,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',
@@ -700,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',
@@ -869,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',

package/dist/tools/standings.js

@@ -77,26 +77,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)
+- dota2: best-effort worldRanking only
+
+Parallel-safe: yes. Upstream cost: 1–2.
 Example: { "game": "cod", "season": "2026", "limit": 50 }`,
     inputSchema: {
         type: 'object',

package/dist/tools/team.js

@@ -31,18 +31,18 @@ function numberOrNull(value) {
 }
 export const teamProfile = {
     name: 'team_profile',
-    description: `Team/org card: identity, roster, recent matches, and form/trends/radar when available.
-
-When to use:
-- Team page / "who is on this roster?"
-- Builder team screen sample
-
-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.
+    description: `Team/org card: identity, roster, recent matches, and form/trends/radar when available.
+
+When to use:
+- Team page / "who is on this roster?"
+- Builder team screen sample
+
+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.
 Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
     inputSchema: {
         type: 'object',
@@ -532,19 +532,19 @@ 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.
-
-When to use:
-- Rivalry / series record questions
-- Supporting context for previews
-
-Prefer over: agent-side double match-list filtering.
-
-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.
+    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.
+
+When to use:
+- Rivalry / series record questions
+- Supporting context for previews
+
+Prefer over: agent-side double match-list filtering.
+
+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.
 Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
     inputSchema: {
         type: 'object',
@@ -960,18 +960,18 @@ Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
 };
 export const h2hMatrix = {
     name: 'h2h_matrix',
-    description: `Multi-player tennis head-to-head grid: every pair's series record in one comparison matrix.
-
-When to use:
-- Draw/field analysis: how each contender fares against every other (e.g. Alcaraz vs Zverev vs Sinner round-robin records)
-- Group-stage or semifinal-field comparisons
-
-Prefer over: N head_to_head calls for an N-player field; raw matrix via call_api.
-
-Do not use when: a two-player rivalry deep-dive with tiebreak/decider splits → head_to_head; season stat leaders → leaderboard_*; rankings → standings.
-
-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.
-
+    description: `Multi-player tennis head-to-head grid: every pair's series record in one comparison matrix.
+
+When to use:
+- Draw/field analysis: how each contender fares against every other (e.g. Alcaraz vs Zverev vs Sinner round-robin records)
+- Group-stage or semifinal-field comparisons
+
+Prefer over: N head_to_head calls for an N-player field; raw matrix via call_api.
+
+Do not use when: a two-player rivalry deep-dive with tiebreak/decider splits → head_to_head; season stat leaders → leaderboard_*; rankings → standings.
+
+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.`,
     inputSchema: {
         type: 'object',

package/package.json

@@ -1,8 +1,28 @@
 {
   "name": "cito-mcp",
-  "version": "0.4.5",
-  "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).",
+  "version": "0.4.7",
+  "description": "Standalone MCP server for the Cito esports and sports API — curated outcome tools for agents (live scoreboards, round economy, opening duels, clutches, vetoes, rosters, tennis, mma).",
   "type": "module",
+  "homepage": "https://cito.gg",
+  "//REPOSITORY": "Intentionally NOT set. cito-api-scraper and cito.gg are PRIVATE repos and must stay that way, so a repository URL pointing at them would render as a broken 404 link on the public npm page and would not satisfy MCP Registry npm ownership validation. Set this only if a PUBLIC repo for this package is ever created (e.g. achillesscriptsvip/cito-mcp with this directory as root) — then use `git+https://github.com/OWNER/REPO.git` and mirror it in the `mcpName`/server.json `name` pair. Do not point it at the private monorepo.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "esports",
+    "cs2",
+    "counter-strike",
+    "counter-strike-2",
+    "lol",
+    "league-of-legends",
+    "dota2",
+    "cod",
+    "ufc",
+    "mma",
+    "tennis",
+    "live-scores",
+    "sports-data",
+    "esports-api"
+  ],
   "bin": {
     "cito-mcp": "dist/index.js"
   },

package/dist/tools/odds.js

@@ -1,287 +0,0 @@
-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';
-function normalizeBookmaker(row) {
-    const r = asRecord(row) ?? {};
-    const markets = (Array.isArray(r.markets) ? r.markets : []).map((mk) => {
-        const m = asRecord(mk) ?? {};
-        const outcomes = (Array.isArray(m.outcomes) ? m.outcomes : []).map((o) => {
-            const oc = asRecord(o) ?? {};
-            return {
-                name: pickString(oc.name) ?? null,
-                price: typeof oc.price === 'number' && Number.isFinite(oc.price) ? oc.price : null,
-                point: typeof oc.point === 'number' && Number.isFinite(oc.point) ? oc.point : null,
-            };
-        });
-        return {
-            market: pickString(m.key) ?? null,
-            outcomes,
-            impliedProbabilities: (() => {
-                const prices = outcomes.map((o) => o.price).filter((p) => p !== null && p > 1);
-                if (prices.length !== outcomes.length || prices.length === 0)
-                    return null;
-                const inv = prices.map((p) => 1 / p);
-                const sum = inv.reduce((a, b) => a + b, 0);
-                return inv.map((v) => Number((v / sum).toFixed(4)));
-            })(),
-        };
-    });
-    return {
-        key: pickString(r.key) ?? null,
-        title: pickString(r.title) ?? null,
-        lastUpdate: pickString(r.last_update) ?? null,
-        markets,
-    };
-}
-export function summarizeTennisOdds(data) {
-    const root = asRecord(data) ?? {};
-    const payload = asRecord(root.data) ?? root;
-    const coverage = asRecord(payload.coverage) ?? {};
-    const bookmakers = (Array.isArray(payload.bookmakers) ? payload.bookmakers : []).map(normalizeBookmaker);
-    const hasOdds = coverage.odds === true || bookmakers.length > 0;
-    return {
-        matchId: pickString(payload.match_id) ?? null,
-        oddsFormat: pickString(payload.odds_format) ?? 'decimal',
-        commenceTime: pickString(payload.commence_time) ?? null,
-        stale: payload.stale === true,
-        bookmakers,
-        oddsAvailable: hasOdds,
-        note: hasOdds
-            ? null
-            : 'No bookmaker is currently quoting this match. This is an upstream coverage gap, not an error; retry closer to the start time.',
-        fullBookPath: '/tennis/odds/{matchId}',
-    };
-}
-function parseTennis(args, tool) {
-    const gameParse = parseGame(args.game, { allowAll: false, required: true });
-    if (gameParse.error || !gameParse.game || !isPrimaryGame(gameParse.game)) {
-        return { error: gameParse.error ?? 'game is required', game: null };
-    }
-    const game = gameParse.game;
-    if (game !== 'tennis') {
-        return {
-            error: `${tool} is tennis-only (odds for '${game}' is not served by this endpoint)`,
-            game,
-        };
-    }
-    return { game };
-}
-function requireTennisId(args, tool) {
-    const id = typeof args.matchId === 'string' ? args.matchId.trim() : '';
-    if (!id)
-        return { error: `${tool} requires matchId` };
-    return { matchId: id };
-}
-export const tennisOdds = {
-    name: 'tennis_odds',
-    description: `Tennis betting odds: upcoming matches with prices, plus pre-match and in-play odds for one match.
-
-Modes (pick with 'scope'):
-- upcoming (default): matches with odds available, each with the bookmakers quoting it.
-- match: pre-match odds for one match_id.
-- live: in-play odds for one match_id.
-
-When to use:
-- "What are the odds on X vs Y?"; pre-match prices; in-play prices; which matches have odds today.
-
-Prefer over: call_api for /tennis/odds/*; match_preview (no prices).
-
-Do not use when: the match result → match_details; rankings → standings.
-
-Tennis-only. Odds are decimal. Coverage is partial upstream: a match with no
-priced bookmaker returns coverage.odds=false and an empty bookmakers[] rather
-than invented numbers, and this tool surfaces that distinction explicitly.
-A match id that does not exist is a NOT_FOUND error, not a coverage gap: the
-odds route answers 200/odds:false for every unknown id, so scope=match and
-scope=live verify the match against /tennis/matches/{id} before reporting a gap,
-and set matchExists.
-
-Parallel-safe: yes. Upstream cost: 1.`,
-    inputSchema: {
-        type: 'object',
-        additionalProperties: false,
-        required: ['game'],
-        properties: {
-            game: gameSchema({ allowAll: false, required: true }),
-            scope: stringSchema('upcoming (default) | match | live.', 'upcoming'),
-            matchId: stringSchema('Match id for scope=match or scope=live, e.g. "s365_2026_4853596".', 's365_2026_4853596'),
-            limit: limitSchema({ default: 20, max: 50, description: 'Rows for scope=upcoming (default 20, max 50).' }),
-        },
-    },
-    handler: async (args, ctx) => {
-        const started = Date.now();
-        const requestId = newRequestId();
-        const parsed = parseTennis(args, 'tennis_odds');
-        if (parsed.error) {
-            return errorEnvelope({
-                code: parsed.error.includes('unsupported') ? 'UNSUPPORTED_GAME' : 'VALIDATION',
-                message: parsed.error,
-                game: parsed.game,
-                source: 'tennis_odds',
-                requestId,
-                tookMs: Date.now() - started,
-            });
-        }
-        const game = parsed.game;
-        const scopeRaw = typeof args.scope === 'string' ? args.scope.trim().toLowerCase() : 'upcoming';
-        if (!['upcoming', 'match', 'live'].includes(scopeRaw)) {
-            return errorEnvelope({
-                code: 'VALIDATION',
-                message: `scope must be upcoming, match, or live (got '${args.scope}')`,
-                game,
-                source: 'tennis_odds',
-                requestId,
-                tookMs: Date.now() - started,
-                recover: ['Use scope=upcoming for matches with odds', 'Use scope=match or scope=live with a matchId'],
-            });
-        }
-        const matchId = typeof args.matchId === 'string' ? args.matchId.trim() : '';
-        if (scopeRaw !== 'upcoming' && !matchId) {
-            return errorEnvelope({
-                code: 'VALIDATION',
-                message: `matchId is required when scope=${scopeRaw}`,
-                game,
-                source: 'tennis_odds',
-                requestId,
-                tookMs: Date.now() - started,
-                recover: [`Pass matchId, or use scope=upcoming with no id`],
-            });
-        }
-        const limit = clampInt(args.limit, 20, 1, 50);
-        if (scopeRaw === 'upcoming') {
-            const res = await fetchJson(ctx, '/tennis/odds/upcoming', { query: { limit } });
-            if (!res.ok) {
-                return errorEnvelope({
-                    code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
-                    message: `Upcoming tennis odds failed (HTTP ${res.status})`,
-                    game,
-                    source: 'tennis_odds',
-                    requestId,
-                    tookMs: Date.now() - started,
-                    upstreamCalls: 1,
-                    httpStatus: res.status,
-                    rateLimit: res.headers,
-                });
-            }
-            const root = asRecord(res.data) ?? {};
-            const body = asRecord(root.data) ?? root;
-            const items = (Array.isArray(body.items) ? body.items : []).map((row) => {
-                const r = asRecord(row) ?? {};
-                const home = asRecord(r.home) ?? {};
-                const away = asRecord(r.away) ?? {};
-                const homeId = pickString(home.player_id, home.id) ?? null;
-                const awayId = pickString(away.player_id, away.id) ?? null;
-                const matchId = pickString(r.match_id, r.id) ?? null;
-                const oddsEventId = pickString(r.odds_event_id) ?? null;
-                return {
-                    matchId,
-                    oddsEventId,
-                    tournament: pickString(r.tournament) ?? null,
-                    commenceTime: pickString(r.commence_time, r.starts_at) ?? null,
-                    player1: { name: pickString(home.name) ?? null, id: homeId },
-                    player2: { name: pickString(away.name) ?? null, id: awayId },
-                    bookmakers: Array.isArray(r.bookmakers) ? r.bookmakers.map((b) => pickString(b) ?? null) : [],
-                    live: r.live === true,
-                    joinKey: matchId
-                        ? { kind: 'matchId', matchId }
-                        : oddsEventId
-                            ? { kind: 'oddsEventId', oddsEventId }
-                            : null,
-                    playerIds: [homeId, awayId].filter((x) => Boolean(x)),
-                };
-            });
-            const total = typeof body.total === 'number' ? body.total : items.length;
-            return successEnvelope({
-                pagination: {
-                    limit,
-                    offset: 0,
-                    total,
-                    hasMore: body.has_next === true,
-                    nextCursor: null,
-                    prevCursor: null,
-                },
-                source: 'tennis_odds',
-                game,
-                requestId,
-                tookMs: Date.now() - started,
-                upstreamCalls: 1,
-                rateLimit: res.headers,
-                data: {
-                    title: `Tennis odds — upcoming (${items.length} of ${total})`,
-                    scope: scopeRaw,
-                    oddsFormat: 'decimal',
-                    items,
-                    total,
-                },
-            });
-        }
-        const path = scopeRaw === 'match'
-            ? `/tennis/odds/${encodeURIComponent(matchId)}`
-            : `/tennis/odds/${encodeURIComponent(matchId)}/live`;
-        const res = await fetchJson(ctx, path, {});
-        let upstreamCalls = 1;
-        let rateLimit = res.headers;
-        if (!res.ok) {
-            return errorEnvelope({
-                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
-                message: `Tennis ${scopeRaw} odds failed for '${matchId}' (HTTP ${res.status})`,
-                game,
-                source: 'tennis_odds',
-                requestId,
-                tookMs: Date.now() - started,
-                upstreamCalls: 1,
-                httpStatus: res.status,
-                rateLimit: res.headers,
-                recover: ['Check the match id with live_matches or match_details'],
-            });
-        }
-        const summary = summarizeTennisOdds(res.data);
-        let matchExists = null;
-        if (summary.oddsAvailable !== true) {
-            const probe = await fetchJson(ctx, `/tennis/matches/${encodeURIComponent(matchId)}`);
-            upstreamCalls += 1;
-            rateLimit = { ...rateLimit, ...probe.headers };
-            matchExists = probe.ok;
-            if (!matchExists) {
-                const liveProbe = await fetchJson(ctx, `/tennis/matches/live/${encodeURIComponent(matchId)}`);
-                upstreamCalls += 1;
-                rateLimit = { ...rateLimit, ...liveProbe.headers };
-                matchExists = liveProbe.ok;
-            }
-            if (!matchExists) {
-                return errorEnvelope({
-                    code: 'NOT_FOUND',
-                    message: `No tennis match with id '${matchId}' — the odds feed has no event for it because the id itself does not exist`,
-                    game,
-                    source: 'tennis_odds',
-                    requestId,
-                    tookMs: Date.now() - started,
-                    upstreamCalls,
-                    rateLimit,
-                    httpStatus: 200,
-                    recover: [
-                        'Check the id with live_matches or tennis_schedule / match_summary',
-                        'Ids come from live_matches (s365_*) or the archive (s365_{year}_{gid})',
-                        `For the pre-match odds list instead, call tennis_odds { game: "tennis", scope: "upcoming" }`,
-                    ],
-                });
-            }
-        }
-        return successEnvelope({
-            source: 'tennis_odds',
-            game,
-            requestId,
-            tookMs: Date.now() - started,
-            upstreamCalls,
-            rateLimit,
-            data: {
-                title: `Tennis ${scopeRaw} odds — ${matchId}`,
-                scope: scopeRaw,
-                ...summary,
-                matchId: summary.matchId ?? matchId,
-                matchExists,
-            },
-        });
-    },
-};
-export const oddsTools = [tennisOdds];