Watchability Index Engineering Guide

This guide translates the Watchability Index product requirements into an integration plan for teams building on top of Sports MCP Server 1.4.1.

Short version

use Sports MCP Server as the read-only retrieval and composition layer
use GSD for deep sports truth
use the dedicated availability contract for grounded watchability
use On Programs for program-first context and reverse linkage
use SportsEventCurrent only to refresh already linked watch/program rows
keep watchability scoring, market weighting, sentiment, storage, and delivery outside the MCP server

Split responsibilities cleanly

What the server should do
What the product stack should do

discover the right competition, participant, venue, event, or program
build a bounded candidate set for upcoming or live windows
separate competition-first schedule truth from watchable schedule truth
connect events to programs and programs back to sports entities
enrich selected events with standings, rankings, lineups, timeline, stats, odds, and media
preserve explicit provenance, partials, and crosswalk confidence

Recommended architecture

Recommended tool map

Product need	Start with	Add only if needed
Resolve a league, team, player, venue, event, or program	`resolve_entities`	`get_competition_structure`
Build the next 14-day baseline candidate set	`list_watchable_schedule`	`list_schedule`, `get_competition_structure`
Add sports context behind one future event	`get_event_summary`	`get_standings`, `get_rankings`, `get_participant_profile`
Build a live candidate set	`list_live_slate`	`get_event_center`, `get_event_timeline`, `get_event_stats`
Link events to actual programs	`list_programs_for_entity`	`get_watch_availability`, `get_program_context`
QA a program-first sports tile	`list_entities_for_program`	`get_program_context`
Add visuals to a promoted rail	`get_media_assets`	`get_event_center`

Recommended operating loops

Pre-event baseline generation
Live update loop
Program-first debugging

Call list_watchable_schedule for the next bounded window.
Call list_schedule only if the scoring job also needs competition-first rows.
For selected candidates, fetch get_event_summary.
Add standings or rankings only where the scoring model truly needs them.

Poll list_live_slate on a bounded cadence.
Deepen only the top events with get_event_timeline or get_event_stats.
Use get_watch_availability only when the product needs to confirm current watchability.

Start from list_entities_for_program.
Deepen with get_program_context.
Inspect crosswalkConfidence, sources, partial, and limitations before deciding the mapping is wrong.

Practical integration rules

treat schedule as a dual-source domain
keep candidate selection watchability-led and event enrichment GSD-led
keep scoring outside the server
preserve sources, crosswalkConfidence, partial, and limitations in your scoring pipeline

Read this next

Use Cases Tool Catalog