StatsHawk

Get a contest (game) box score with per-player stat lines. `game_id` is a contest id (`cst_...`) — chain it from get_mlb_matchups (`contest`) or search_games (`game_id`). Each player line carries `phases`: an array of `{ phase, measures }`, where `phase` names the stat category (e.g. `baseball_batting`, `baseball_pitching`, `basketball_player_game`) and `measures` is a flat map of canonical, phase-qualified stat keys to values, passed through unchanged from the server — no client-side renaming or filtering. A two-way player (e.g. a pitcher who also bats) appears once with multiple phase entries. `player_name` is resolved server-side for every line (including large NFL boxscores); if it is ever `null`, resolve the `person_id` via search_player.

get_box_score

MLB pregame matchups for a date (default = today in US Eastern Time). Returns each scheduled game with a `contest` id (chains into get_box_score / get_play_by_play), home/away teams, probable starting pitchers (including throwing hand R/L), and confirmed batting lineups (player, position, batting order, bat side L/R). Use this for matchup-based projections — pitcher throws + batter bat_side gives you platoon advantage; batting order tells you projected plate appearances. lineups_available is false when lineups have not yet been posted (typically pre-3-hours-before-first-pitch).

get_mlb_matchups

MLB play-by-play: plate appearances + Statcast pitches. `game_id` is a contest id (`cst_...`) from search_games or get_mlb_matchups. Supports per-player filtering (pitcher_id, batter_id — both take person ids and intersect for H2H) and three detail tiers (sparse / standard / full). For pitcher analysis prefer `pitcher_id=X&detail=standard` — it returns just that pitcher's PAs with velocity + exit velo, ~70% smaller than the unfiltered default and the right shape for K props.

get_play_by_play

Player-prop analysis card: season/recent/home/away averages and hit rates for an over/under line. PAID TIER ONLY: on a free account this tool returns 403 TIER_REQUIRES_PAID — do not retry; either upgrade, or derive hit rates yourself on the free tier from get_box_score lines across the season (every raw-stats tool is available on free). Provide either player_name (resolved to a person via search) or person_id directly (preferred — skips name resolution). Results chain naturally from search_player or from a roster entry's `person_id` field (see get_team_roster). Stat keys are canonical short forms (e.g. `hr`, `reb`, `sog`) and are now phase-qualified where ambiguous — e.g. `pitching.so` for pitcher strikeouts — see the `stat` parameter description for the per-sport list. Unknown stat keys return a 400 whose structured error data includes `valid_stats`, `aliases`, and a capabilities endpoint; call get_stat_capabilities for the same discovery surface directly. The `context` field, when non-null, carries sport-tagged analysis context — baseball batting props: platoon splits by opposing starter hand; basketball/hockey props: back-to-back vs rested splits. Note: the old sport-specific context block (k_pct, whiff_rate, exit velo, etc.) and the availability/team_context blocks are no longer included in this response.

get_player_props

Get league standings, ranked best-record-first (rank = position in the list, 1-indexed). Serves the latest season with completed games — mid-season the live table, offseason the just-completed season — and reports the served season in `season_year` (never an empty upcoming season). Entries carry W/L/T, win_pct, points_for/against, and games_played. `points` is the ranking dimension where the sport has one: NHL `points` = 2*W + OTL (with `otl` = overtime/shootout losses — worth a point, NOT counted in `losses`) and soccer `points` = 3*W + 1*T (tables ranked by points, then goal difference, then goals scored; for soccer read `ties` as draws and points_for/against as goals). Both are null for pct-ranked leagues. Note: conference/division grouping and streak/games-back are not available in the current API — a missing `team_id`/`team_name` on an entry means the standings row has no linked team record.

get_standings

Discover the exact stat keys get_player_props accepts. Without person_id, lists every phase and its canonical measure ids for a competition (e.g. mlb -> batting + pitching phases). With person_id (and optionally a season START year), returns ONLY the phases that player actually recorded — the definitive fix for "X is not a known stat" errors. Measure ids are canonical and phase-qualified where a sport has multiple phases sharing a base id — collided ids are returned already qualified (`pitching.so` vs `batting.so`); a bare id works when unambiguous. Feed any returned id straight into get_player_props `stat`. Omitting season with person_id uses the current edition.

get_stat_capabilities

Get a team's roster — the list of players currently associated with the team. Each entry carries `source`: `appearance` means the player recently played for this team (data-confirmed via a game appearance), while `membership` means they are named to the squad but have no recent game appearance on record (may be injured, benched, or not yet debuted). Rich per-player stats, game logs, and injury detail are NOT included in this response — use the returned `person_id` with get_player_props to pull season/recent averages and hit rates for any player on the roster. Baseball players carry handedness — `bats` (`L`/`R`/`S` for switch) and `throws` (`L`/`R`). Three states: values = known; `null` = a baseball player whose hand is UNKNOWN — do not infer it from the name, position, or stat line; keys ABSENT = not a baseball player (rosters in other sports carry no handedness keys at all).

get_team_roster

Search the StatsHawk documentation site (setup guides, REST/MCP API reference, auth, quotas, stat-key reference, and the cookbook). Use it to answer questions about connecting the MCP server, authentication and API keys, plan/quota limits, valid stat keys, and available endpoints. Returns matching doc pages with titles, breadcrumbs, absolute URLs, and text snippets.

search_docs

Search games by league, date, team, and/or status. `date` is applied server-side; `team` (name substring match) and `status` are applied client-side after resolving team names. Returned `game_id` (a `cst_...` contest id) chains into get_box_score / get_play_by_play. When building a slate or counting games, EXCLUDE `status: 'postponed'` rows: a postponed game is a real provider record (MLB keeps the original game and issues a NEW id for the makeup), so the same matchup can legitimately appear twice — once postponed, once scheduled. The scheduled/final row is the one that will carry stats. Note: `season_type` filtering is not available in the current API.

search_games

Find a player by fuzzy name match. Search is GLOBAL and cross-sport (no league/team scoping — persons are canonical, not league-scoped). The `name` arg is a case-insensitive partial match. Returned `person_id` chains into get_player_props. Each match also includes bio fields `dob, birth_country, height_inches, weight_lbs, headshot_url`. Baseball players additionally carry handedness: `bats` (`L`/`R`/`S` for switch) and `throws` (`L`/`R`). Three states: values = known; `null` = a baseball player whose hand is UNKNOWN — do not guess it from name, position, or stats; keys ABSENT = not a baseball player, the field does not apply (e.g. soccer or NBA players have no `bats`/`throws` keys at all). Team affiliation is still not part of the person record: use get_team_roster.

search_player