Tool Catalog

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.

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.

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.

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 from the source, plus `injury_type`, `return_date`, and `source`). 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).

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.

Use this when the user asks which betting markets or player props are posted for a game, or before picking a market for a line. Needs a contest id from search_games or get_mlb_matchups. Not for the current line or how a line moved (get_odds_spot, get_odds_history). Cheap discovery: lists markets that have at least one posted pregame line on this contest (`h2h`, `spreads`, `totals`, `team_total`, `player_prop`, plus measure/period when present). Pregame only — nothing after first pitch. Chain into get_odds_spot for the latest board, then get_odds_history only if the user asks how a line moved.

Use this when the user asks what the line is: moneyline, spread, total, or a player's current prop for a specific game. Needs a contest id from search_games or get_mlb_matchups. Not for how a line moved (get_odds_history) and not for listing which markets exist (get_odds_markets). Latest pregame board only — one tick per book, closing line at first pitch, never in-play. Optional books / markets / measure / period filters. Optional person_id scopes to that player's posted lines on this contest (person+contest). Prefer this over history for any current-line question. Call get_odds_markets first when the market or measure is unknown.

Use this when the user asks how a line moved, opened, shortened, or was bet down. Needs a contest id plus markets and/or measure. Not for the current line (get_odds_spot) and never for an unscoped person 30-day tape. Newest-first paged pregame poll-tape (stops at first pitch). Requires markets and/or measure — call get_odds_markets or get_odds_spot first. Optional person_id scopes a player-prop tape via the person+contest history route; contest_id is still required. Optional books, period, since, before, cursor, interval (auto|raw|15m|1h). MCP limit defaults to 30 (max 50). Surfaces engine truncated, next_cursor, and next_before. Prefer cursor=next_cursor: it is an opaque, tie-safe engine string — pass it back exactly as received, never construct one. next_before is timestamp-only and can drop same-time leftovers. If truncated, summarize this page and only request older ticks when the user asks. Do not auto-page the whole history.

Use this when the user names an athlete and wants anything about them: how they have been pitching or hitting lately, stats, splits, injuries, bio. Resolve the name to a person_id here first, then chain into search_games for game ids and get_play_by_play or get_box_score for the games, or get_player_props or get_injury_history directly. Not for team or league questions. 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. This search returns bio only, no injury status; for a player's current injury and full injured-list history, pass the `person_id` to get_injury_history (rostered players also carry a current `injury` object in get_team_roster). Each match also includes bio fields `dob, birth_country, height_inches, weight_lbs`. 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.

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 `source` and the sources are NEVER merged: an ESPN report and an MLB transaction describe the same player from two vantage points, so render them as separate timelines or pick one, never splice them together. Each source 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 source 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 source 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 source 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: each carries `kind`, `status`, `observed_at` (ingestion time), `effective_date` (when an MLB 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`, `il_tier`, and `source_event_id`. `unattached_events` is a source-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 source 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 has two sources with real history back to 2024-01-01; NFL, NBA, NHL, and WNBA carry ESPN report 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.

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.

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.

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).

Use this when the user asks about a player's averages, hit rates against a line (2+ hits, 20+ points, an over/under), or prop-style projections. Not for a single game's line (get_box_score) or the raw season log. Normal route for every account whose plan includes analysis; the engine decides access, not the plan name. Player-prop analysis card: season/recent/home/away averages and hit rates for an over/under line. Takes an optional `season` start year: without it the card covers the latest edition with completed games, which early in a new season can be this year with zero games for a player; pass last year (NCAAF Week 1: season=2025) to analyse the prior season. ANALYSIS ACCESS: if this account does not include analysis the tool returns 403 TIER_REQUIRES_PAID — do not retry; either upgrade at the link in the error (or, if it says billing setup is incomplete, complete billing setup), or derive hit rates yourself from get_box_score lines across the season (every raw-stats tool is available on every plan). A 429 QUOTA_EXCEEDED means the monthly units are used up; relay its upgrade link. 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, including AFL, NRL, and rugby union phases. 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. When the player has a current injury report, the card carries an `injury` object (source `status` verbatim, plus `injury_type`, `return_date`, `source`) and, when a stint is relevant to the sampled games, an `injury_window_flags` object (`games_before_latest_interval`, `latest_interval_days`, `window_spans_interval`, and the `interval`). The `interval` carries its own `source`, which the engine selects relevance-first and so may differ from the current `injury.source`. Those flags are ANNOTATION ONLY, meant to explain a stale-form window (e.g. every sampled game predates a long injured-list stint); they never change `averages`, `hit_rates`, or `games`. Both keys are ABSENT when there is no report or no relevant stint; absence is not a health guarantee, and injury data covers only MLB, NFL, NBA, NHL, and WNBA. For full injury history and coverage windows, call get_injury_history. Note: the old sport-specific context block (k_pct, whiff_rate, exit velo, etc.) and the pre-#215 availability/team_context blocks are no longer included in this response.