StatsHawk

Use this when the user asks who won, the final score, or the stat lines from a specific game, or wants a player's line from recent games (walk several game_ids for a last-N log). Needs a contest id from search_games or get_mlb_matchups. Not for standings or season totals (get_standings, get_player_props). Get a team-match contest (game) box score with per-player stat lines, including newer team sports such as AFL, NRL, and rugby union when data is ingested. Field/individual contest shapes (golf, racing, tennis, MMA) are not projected by this MCP tool yet. `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

Use this when the user asks whether a player is injured or on the IL, when they return, or how long they were out. Needs a person_id from search_player. Not for a whole team's availability (get_team_roster). A player's full injury history: current status plus derived injured-list intervals. Provide either player_name (resolved via search) or person_id directly (preferred). The response is one block per `vantage` and the vantages are NEVER merged: `reported_status` is the timeline of published injury reports (status and estimated return as listed) and `transaction_record` is the timeline of official roster transactions (injured-list placements and activations). They describe the same player from two independent vantage points, so render them as separate timelines or pick one, never splice them together. Each vantage reports its own coverage window (`covered_from`, `covered_through`); time OUTSIDE that window is UNKNOWN, not healthy, so do not read a gap before a vantage began tracking as the player being fine then. Each interval's edges are qualified. `start_kind` is one of `reported` (a dated transaction), `listed` (first seen on the report), `unknown` (left-censored: already injured when tracking began, so `start` is a bound, not the onset), or `tolerant_open` (a change or transfer arrived with no previously open interval, so the start boundary is inferred and weaker). `close_kind:"activated"` is an official return, `close_kind:"unlisted"` only means the player left the report (weaker than recovered), and an `end` of null (`close_kind:"open"`) is an ongoing stint. Events sit in a SIBLING `events` array, not nested under intervals, in delivered order (there is no event id to key on): each carries `kind`, `status`, `observed_at` (ingestion time), `effective_date` (when a transaction actually took effect, which differs from `observed_at`), `changed_fields` (which facts moved, e.g. an estimated-return slip), plus `return_date`, `resolution_date`, `detail`, `injury_type`, and `il_tier`. `unattached_events` is a vantage-wide count of events not attached to ANY person (not events that failed to form an interval); it qualifies how confidently an empty history for this player can be read. `status` is report vocabulary (e.g. `Out`, `Questionable`, `Day-To-Day`, `60-Day-IL`, `10-Day-IL`, `Active`), rendered verbatim, not an enum; `Active` is meaningful (on the report but playing), not an error. Coverage: MLB carries both vantages, with transaction records back to 2024-01-01; NFL, NBA, NHL, and WNBA carry `reported_status` transitions only, accruing since 2026-08-28, with no deep history; no other league has injury data. A known-healthy player returns 200 with empty interval and event lists (still with coverage blocks); a 404 means the person id is unknown, never that the player is healthy.

get_injury_history

Use this when the user asks about today's (or a date's) MLB games, probable starters, confirmed lineups, or platoon matchups. Not for other sports (search_games). 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 / get_odds_spot), 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

Use this when the user asks how a pitcher has been throwing recently, wants pitch-level or plate-appearance detail, batter-vs-pitcher history, or drive-by-drive NFL play data for a game. Needs a contest id from search_games or get_mlb_matchups, plus a person_id from search_player for player filters. Not for season totals. Play-by-play for a contest (`game_id` is a contest id, `cst_...`, from search_games or get_mlb_matchups). SPORT-SHAPED response: MLB serves plate appearances + Statcast pitches (default detail: full); NFL serves drives with nested plays (default detail: standard). Baseball filters: pitcher_id / batter_id (person ids; intersect for H2H) — for pitcher analysis prefer `pitcher_id=X&detail=standard` (~70% smaller, the right shape for K props). Football filters: quarter (5+ = OT), down (1-4), red_zone, scoring_only, team_id (offense). Filters are sport-checked: a baseball filter on a football contest (or vice versa) returns 400 rather than silently ignoring it.

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

Use this when the user asks for a league table, standings, records, or where a team sits. Not for single game results (search_games). Get team-match league standings, ranked best-record-first (rank = position in the list, 1-indexed). The shared W/L/T shape covers newer team sports such as AFL, NRL, rugby union, lacrosse, volleyball, water polo, and field hockey when data is ingested. Racing drivers/constructors use separate PointsRank tables in the REST API and are not projected here yet; golf intentionally has no edition standings table. 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

Use this when a stat key is rejected, or to learn which stats exist for a sport or a player before calling get_player_props. Not a data tool. Discover the exact stat keys get_player_props accepts for competitions whose sports register player-stat phases. Stat-bearing sports include the major US leagues plus soccer, golf (PGA/LPGA), racing (F1/NASCAR/IndyCar), AFL, NRL, and rugby union. All registered competition codes are accepted, but tennis (ATP/WTA), UFC, lacrosse, volleyball, water polo, and field hockey currently have no registered player-stat phase, so they return an empty phases list and no get_player_props stat keys. 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

Use this when the user asks who is on a team or a team's squad, or when you need person_ids for a team's players. Not for one named player (search_player), and not for a confirmed lineup or batting order: this lists associated players, including benched and injured ones; MLB lineups come from get_mlb_matchups. 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 (benched, not yet debuted, or out). Season stats and game logs are not inlined here; use the returned `person_id` with get_player_props for averages and hit rates. A rostered player who currently has an injury report carries an `injury` object (`status` verbatim, plus `injury_type`, `return_date`, and `vantage`: `reported_status` for a published injury report, `transaction_record` for an official injured-list transaction). The `injury` key is ABSENT when there is no current report; absence is NOT a health guarantee, since injury coverage is only MLB, NFL, NBA, NHL, and WNBA (a player on any other league never carries `injury`). For full injury history and coverage windows, call get_injury_history with the `person_id`. 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

Use this when the user asks how to connect StatsHawk, about API keys, plans, quotas, or endpoint reference. Not for sports questions. 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

Use this when the user asks what games are on a date, a team's schedule or recent results, or when you need a game id for a box score, play-by-play, or odds. Also the game-discovery step in player workflows: after search_player resolves a name, use this to find the recent game ids for that player's log or recent form. Not for player identity or bio lookup (search_player). Search team-backed match games by league, date, team, and/or status. This includes AFL, NRL, rugby union, lacrosse, volleyball, water polo, and field hockey in addition to the major leagues when those competitions have ingested data. Golf/racing fields and individual/pair contests (ATP/WTA/UFC) use the generalized REST contest surface and are not returned by this tool yet. `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 / get_odds_markets / get_odds_spot / get_odds_history. 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. `stage` filters by season stage server-side (preseason/regular/postseason/exhibition/allstar) and each returned game carries its `stage`; omit it to get all stages.

search_games