Tool Catalog
Nine tools, not 250. One tool per concept, league-aware where the concept is cross-league.
One tool per concept.
Statshawk's MCP server exposes a small catalog by design — one tool per concept — so the
LLM picks faster and burns fewer context tokens. Cross-league concepts (standings, box
scores, rosters, player search, player props) take a league parameter; sport-specific
concepts get their own tool (get_mlb_matchups and get_play_by_play are MLB,
get_country_matchup covers FIFA World Cup and qualifying). The list below is generated
from the live server's tools/list at build time.
get_standingsGet current league standings, optionally filtered by conference or division. Returned as conferences containing teams sorted by rank, with W/L/Pct/streak/GB.
leaguestringrequiredconferencestringoptionaldivisionstringoptionalget_box_scoreGet a game box score with per-player stats. Stats are normalized per sport: basketball returns points/rebounds/assists/steals/blocks/turnovers/plus_minus and shooting splits (fg_made/fg_attempts, three_made/three_attempts, ft_made/ft_attempts); baseball returns at_bats/hits/runs/home_runs/rbi/walks/strikeouts plus pitching stats (innings_pitched/era); football returns yards/touchdowns/sacks/receptions/etc.; hockey returns goals/assists/shots_on_goal/plus_minus plus goalie stats; soccer returns goals/assists/shots/cards/saves.
game_idstringrequiredleaguestringrequiredsearch_gamesSearch games by league, date, team, and/or status.
leaguestringrequireddatestringoptionalteamstringoptionalstatusstringoptionalscheduledin_progressfinalpostponedcancelledsuspendedget_team_rosterGet a team roster with each player's season averages, recent game lines, injury status, and (where applicable) handedness and jersey number.
team_idstringrequiredleaguestringrequiredget_mlb_matchupsMLB pregame matchups for a date (default = today ET, server-side). Returns each scheduled game with 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).
datestringoptionalget_country_matchupCountry-vs-country matchup analysis for FIFA World Cup / qualifying tournaments. Returns roster summaries, position-stratified key starters (1 GK + 2 DEF + 2 MID + 2 FWD), top-7 goal scorers ranked by club goals/game, composite team strength metrics (attacking pillar avg goals/game, midfield assists total, top GK games), international form (last 5 W/D/L + goals for/against per game), club-competition distribution (how many roster players are in UCL / EPL / LaLiga / etc.), and head-to-head history. Use this INSTEAD OF calling get_player_props on each roster player — one call returns the data needed to answer "Who wins? What's the spread? Top goal-scoring candidates?" for ~46x less quota usage. International form is sparse for nations that have not played in WCQ UEFA recently (data depth varies by qualifying tournament). When form is null, lean on club_stats in key_starters/top_scorers for scoring projections. Paid tiers only — free-tier accounts will receive a 403.
leaguestringrequiredInternational league. fifawc = FIFA World Cup, fifa_wcq_uefa = UEFA qualifying, fifa_wcq_conmebol = CONMEBOL qualifying.
fifawcfifa_wcq_uefafifa_wcq_conmebolhome_countrystringrequiredHome country name (case-insensitive). Examples: "USA", "Mexico", "England", "France", "Brazil", "Argentina". Three-letter abbreviations also accepted (USA, MEX, ENG, FRA).
away_countrystringrequiredAway country name (case-insensitive). Same format as home_country.
game_idstringoptionalOptional fixture UUID. When provided, the matchup metadata (kickoff_at, stage, venue) is populated from that specific scheduled game. Otherwise those fields return null.
get_play_by_playMLB play-by-play: plate appearances + Statcast pitches. Supports per-player filtering (pitcher_id, batter_id — 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.
game_idstringrequiredGame UUID from get_games or get_mlb_matchups.
detailstringoptionalPitch detail tier. `sparse` returns only sequencing (type, call, count, in-play). `standard` adds velocity (start_speed) and exit velocity (launch_speed). `full` (the default if omitted) also adds spin, plate location, zone, launch angle, distance, and trajectory. Prefer `standard` for prop analysis — it covers the headline numbers and is ~30% smaller than `full`.
sparsestandardfullpitcher_idstringoptionalFilter to PAs where this pitcher was on the mound. Combined with `detail=standard` this is the ideal shape for analyzing one pitcher (cuts response ~70% vs. an unfiltered call).
batter_idstringoptionalFilter to PAs for this batter. Combined with `pitcher_id` the result is the head-to-head PAs between the two players (usually ~4KB total).
search_playerFind a player by fuzzy name match within a league. The `name` arg is a case-insensitive partial match against first or last name; optionally narrow with `team` (name) or `team_id`.
namestringrequiredleaguestringrequiredteamstringoptionalteam_idstringoptionalget_player_propsPlayer-prop analysis card: season/recent averages, hit rates, and sport-specific context (e.g. k_pct, whiff_rate, exit velo) for an over/under line. Provide either player_name (fuzzy match) or player_id. Stat keys are canonical short forms (e.g. `hr`, `reb`, `sog`) — see the `stat` parameter description for the per-sport list. Unknown stat keys return a 400 listing the valid keys for that league. Paid tiers only — free-tier accounts will receive a 403.
player_namestringoptionalplayer_idstringoptionalstatstringrequiredCanonical stat key (short form, case-insensitive). Use the short form — e.g. `hr` not `home_runs`, `reb` not `rebounds`. MLB batter: h, hr, rbi, bb, r, k, so, sb, cs, ab, avg, obp, slg, ops, tb, hbp, 1b, 2b, 3b (k/so both = batter strikeouts). MLB pitcher: ip, pitcher_k, era, whip, w, l, sv, hld, er, hits_allowed, hr_allowed, bb_allowed, runs_allowed, batters_faced. NBA: pts, reb, ast, stl, blk, tov, 3pm, fgm, fga, ftm, fta, min, pf, oreb, dreb. NHL: g, a, pts, sog, plus_minus, pim, bs, ht, tk, gv, fw, ppg, ppa, shg, sha, gwg, fo_pct. NFL: pass_yds, pass_td, pass_cmp, pass_att, rush_yds, rush_td, rec_yds, rec_td, rec, tgts, car, int, rtg, qbr, tot, solo, tfl, sacks, pass_sacks, pass_sack_yds, qb_hts, pd, fum, lost, fg_made, fg_att, xp_made, xp_att, pts. Use the prefixed forms (`pass_yds`/`rush_yds`/`rec_yds`) for skill players — bare `yds`/`td` collide across categories (e.g. a dual-threat RB has both rush_yds AND rec_yds). Completions, field goals, and extra points are split into made/attempt pairs (`pass_cmp`/`pass_att`, `fg_made`/`fg_att`, `xp_made`/`xp_att`) — NOT combined "X/Y" strings. `sacks` = defensive sacks recorded; `pass_sacks`/`pass_sack_yds` = sacks taken by a QB and yards lost. Friendly aliases also accepted: `passing_yards`, `rushing_yards`, `receiving_yards`, `passing_touchdowns`, `rushing_touchdowns`, `receiving_touchdowns`, `completions`, `field_goals_made`, `extra_points_made`, `sacks_taken`. Soccer (EPL/LaLiga/Bundesliga/SerieA/Ligue1/UCL/MLS/FIFA*): total_goals, goal_assists, total_shots, shots_on_target, fouls_committed, fouls_suffered, yellow_cards, red_cards, offsides, own_goals, appearances, sub_ins (goalies also: saves, goals_conceded, shots_faced). Soccer uses underscored canonical keys — `total_goals` not `goals`, `goal_assists` not `assists`. Unknown keys return 400 with the valid list — use that to self-correct.
linenumberoptionalopponentstringoptionalleaguestringrequiredDesigning for small catalogs
| Principle | What it means |
|---|---|
| League as a parameter | Cross-league tools take league: "nba" | "mlb" | "nfl" | "nhl" | … instead of shipping per-league copies. Sport-specific data (MLB matchups, Statcast play-by-play, international soccer matchups) gets a dedicated tool. |
| Pre-shaped responses | Tools return ~1–2 KB JSON shaped for context windows. No dumps. |
| Verbs map to concepts | get_box_score, get_player_props — not box.score.get.v2. |
| Stable arg names | Once an arg ships, it doesn't get renamed. New optional args are additive. |
If you need a tool we don't ship, email tools@statshawk.ai
with a use case and we'll evaluate whether it earns a catalog slot.