FastballAPI

View saved version →

---
name: dispatch
description: "Routes a baseball analytics request to the right 2 to 3 skills in this pack. Load this FIRST when an MLB or college baseball data or analytics request comes in and you are unsure which skills to activate. Prevents loading all 16 skills when two will do. Do not use when the request already names one skill's job, such as devigging two prices: load odds-analysis directly."
metadata:
  version: 1.0.0
  author: FastballAPI
---

# Skill Dispatch Guide

Match the request to a pattern, load those skills, stop. Always pair with `fastballapi-tool` when live data is needed: it holds the tool list, credit costs and the coverage limits.

## First-Use Persona Check

| Signal | Persona | Start with |
|--------|---------|------------|
| "What happened last night?" / exploring | Explorer | `game-lookup` |
| "Who is better, X or Y?" / scouting | Scout | `player-scouting`, `pitch-mix-analysis` |
| "I want to build a model" | Builder | `walk-forward-validation`, `pythagorean-record` |

## Request Patterns

### "What was the score?" / "Who plays tonight?" / "Schedule"
1. `game-lookup`: `get_games`, `get_schedule`, `get_game`.
2. Add `fastballapi-tool` only if you need cost or parameter detail.

### "How are the Dodgers doing?" / "Standings" / "Best team" / "Run differential"
1. `team-analysis`: standings, team stats, Elo.
2. `pythagorean-record` if the question is luck, regression or "are they as good as their record?".

### "Tell me about Aaron Judge" / "Compare two hitters" / "Who leads the league in OPS?"
1. `player-scouting`: search, season lines, leaders, injuries.
2. `run-value-analysis` if the user wants RE24 or clutch splits.
3. `spray-chart-analysis` if the question is where he hits the ball.

### "What does Tarik Skubal throw?" / "Whiff rate by pitch" / "Pitch mix"
1. `pitch-mix-analysis`: `get_pitch_mix`, `get_pitches`.
2. `player-scouting` for the season line behind it.

### "Run value" / "RE24" / "How much did that home run matter?" / "Hitting with runners in scoring position"
1. `run-value-analysis`: `get_plate_appearances`, `get_player`.

### "Where does he hit the ball?" / "Shift" / "Pull rate" / "Spray chart"
1. `spray-chart-analysis`: `get_spray_chart`.
2. `player-scouting` for context.

### "Pythagorean record" / "Who got lucky?" / "Expected wins"
1. `pythagorean-record`: `get_standings`, `get_team_stats`.
2. `team-analysis` for the surrounding picture.

### "What are the odds?" / "Best price" / "Did the line move?"
1. `odds-explorer`: `get_odds`, `get_line_movement`.
2. `odds-analysis` for devigging and implied probability.

### "Preview tonight's Dodgers game" / "Game breakdown"
1. `game-preview`: composes standings, ratings, schedule, injuries and odds.
2. `odds-explorer` only if the user wants the full book-by-book table.

### "Devig these odds" / "No-vig price" / "Implied probability"
1. `odds-analysis`. No data call needed for plain math.

### "Strikeout prop" / "Total bases over" / "Will he go over his hits line?"
1. `prop-modeling`: pitcher strikeouts, hits, total bases.

### "Backtest this" / "Would this have made money?" / "Closing line value"
2. `walk-forward-validation` for the model underneath.

### "Is my model accurate?" / "Cross-validation" / "Train/test split" / "Features"
1. `walk-forward-validation`: temporal splits, leakage, calibration check.

### "College baseball" / "Omaha" / "NCAA"
1. Route as above, then tell the user what college lacks (no pitch rows, no spray charts, no props, no injuries). `fastballapi-tool` has the full list.

## Common Chains

| Goal | Chain |
|------|-------|
| Scout a pitcher end to end | `player-scouting` (season line) then `pitch-mix-analysis` (arsenal) then `prop-modeling` (strikeout line) |
| Understand a hitter's power | `player-scouting` then `spray-chart-analysis` then `run-value-analysis` |
| Find out if a club is overrated | `team-analysis` then `pythagorean-record` |
| Cover tonight's game | `game-preview` then `odds-explorer`, adding `pr

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: fastballapi-tool
description: "Default data source for the FastballAPI skills. Routes every MLB and college baseball data request to the right one of the 20 FastballAPI tools, with credit costs, parameters, coverage limits and the response envelope. Use when any other skill needs games, box scores, standings, player stats, pitches, plate appearances, spray charts, odds or player props."
metadata:
  version: 1.0.0
  author: FastballAPI
  user-invocable: false
---

# FastballAPI Tool

> Connection: this plugin reaches the data through its MCP server, which the user connects with a normal OAuth sign-in. Never ask the user for an API key, token or password, and never put one in a tool argument.


Every other skill in this pack gets its data here. This skill owns the 20 tools, picks the cheapest call that answers the question, and states what the data cannot do.


## Response Envelope

Every REST response is wrapped as `{"data": ...}`. Read `body["data"]` first. Errors come back as `{"error": "..."}` with an HTTP error status. Headers `X-Credits-Used` and `X-Credits-Remaining` report the spend.

```json
{"data": {"players": [{"player_id": "32081", "name": "Gerrit Cole", "position": "SP", "bats": "R", "team": "NYY"}], "count": 1}}
```

Code examples in these skills write `get_x(**args)` for a thin helper that POSTs the tool name and arguments to the REST endpoint and returns the parsed JSON (so `get_x(...)["data"]` is the payload).

## The 20 Tools

| Tool | What it returns | Credits | Skills that use it |
|------|-----------------|---------|--------------------|
| `list_teams` | Team ids, abbreviations, colours for a season | 1 | all (id lookup) |
| `search_players` | Player ids by (partial) name | 1 | player-scouting, prop-modeling |
| `get_schedule` | Next 1 to 30 days of games with the median line | 2 | game-lookup, game-preview |
| `get_standings` | Record, splits, run differential, Pythagorean win pct | 2 | pythagorean-record, team-analysis |
| `get_injuries` | Latest injury report (MLB only) | 2 | game-preview, player-scouting |
| `get_ratings` | Our team Elo ratings, ranked | 2 | team-analysis, walk-forward-validation |
| `get_game` | One game: line score, every batting and pitching line, books, win probability | 5 | game-lookup, game-preview |
| `get_player` | Season-by-season batting and pitching, with RE24 | 5 | player-scouting |
| `get_player_games` | A player's game log (batting and pitching) | 5 | prop-modeling, player-scouting |
| `get_leaders` | Qualified season leaders for 13 stats | 5 | player-scouting |
| `get_team_stats` | Runs for and against, team batting and opponents' batting | 5 | team-analysis, pythagorean-record |
| `get_pitch_mix` | A pitcher's arsenal: usage, velocity, whiff rate, ball rate (MLB only) | 5 | pitch-mix-analysis, prop-modeling |
| `get_plate_appearances` | Play-by-play with base-out state, batted ball, win probability, RE24 | 10 | run-value-analysis |
| `get_pitches` | Pitch-by-pitch: count, type, velocity, location, result (MLB only) | 10 | pitch-mix-analysis |
| `get_spray_chart` | Balls in play by trajectory and field, optional x/y points (MLB only) | 10 | spray-chart-analysis |
| `get_player_props` | Prop lines by book, opening or closing (MLB only) | 10 | prop-modeling |

## Tool Selection

| You need | Use | Not this |
|----------|-----|----------|
| Last night's scores | `get_games` with `date` | `get_schedule` (future only) |
| This week's games and the median line | `get_schedule` | `get_odds` per game |
| One game's box score plus every book's line | `get_game` | `get_games` then `get_odds` |
| A pitcher's arsenal and whiff rates | `get_pitch_mix` (5) | `get_pitches` (10, only for pitch-level detail) |
| Where Judge hits the ball | `get_spray_chart` | `get_plate_appearances` |
| Win probability and run value per plate appearance | `get_plate_appearances` | `get_game` (range only) |
| Closing hits line and the result | `get_prop_history` | `get_player_props` in a loop |
|

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: game-lookup
description: "Finds MLB and college baseball games by date, date range, team or season, and pulls one game in full: line score, box score, starters, bullpen usage, each book's line and the win-probability range. Use when the user asks for scores, last night's games, a team's schedule or results, the box score for a game, who pitched, or what the line was. Do not use for team trends over a season: see team-analysis. Do not use for odds comparison across books: see odds-explorer. Do not use for pre-game analysis: see game-preview."
metadata:
  version: 1.0.0
  author: FastballAPI
---

# Game Lookup

> **Default data tool:** FastballAPI (`fastballapi-tool`).
> `get_games` (2 credits) for lists, `get_schedule` (2) for the coming days, `get_game` (5) for one game in full.

You find the right game fast and report it plainly. Most mistakes here are wrong dates (time zones), wrong ids and forgetting the postseason.

## When to Use

- Scores for a date, a week or a team's recent games
- A team's upcoming schedule with the median line
- A box score: batting lines, pitching lines, line score
- "Who started?", "How many pitches did the starter throw?", "Who closed?"
- Whether the favourite won or the total went over for a finished game
- Finding a `game_id` for another skill

## When NOT to Use

- Season-long team form or rankings: `team-analysis`
- Comparing every book's price or line movement: `odds-explorer`
- A pre-game report with context: `game-preview`
- Play-by-play detail or run value: `run-value-analysis`

## Commands Available

| Command | What it does | Credits |
|---------|--------------|---------|
| `get_games` | Games by `season`, `season_type`, `team`, `date`, `from`/`to`, `status`; `limit` up to 200, `offset` to page | 2 |
| `get_schedule` | Next `days` (1 to 30, default 7), optional `team`, with median moneyline, run line, total | 2 |
| `get_game` | One game: line score, batting, pitching, each book's open and close, win-probability range | 5 |
| `list_teams` | Team ids and abbreviations | 1 |

All four accept `league` (`mlb` default, `ncaabase`). College postseason games carry a `round` field.

## Commands That Do NOT Exist

| Not available | Use instead |
|---------------|-------------|
| `get_boxscore`, `get_scores` | `get_game`, `get_games` |
| `get_live_scores` | Not available. Data is final scores plus daily schedule snapshots |
| `get_probable_pitchers` | Not available. Ask the user or read the team's own announcement |
| `get_head_to_head` | `get_games` with `team`, then filter opponents in code |
| `get_team_schedule` | `get_schedule` with `team` for future, `get_games` with `team` for past |

## Date and Season Rules

- Dates are US Eastern, `YYYY-MM-DD`. A night game that ends after midnight Eastern still belongs to the starting date.
- `starts_at` is UTC. Convert before telling a user a first pitch time.
- Omit `season` for the latest. In January the latest season is last year's.
- `season_type` is `regular` or `postseason`; omit it and you get both. A World Series game and an April game come back from the same call.
- `get_games` returns newest first. For a team's last 10, use `team` plus `limit: 10`.

## How It Works

**Step 1: Resolve the team.** Use the abbreviation (`NYY`). If unsure, `list_teams` (1 credit). Do not pass "Yankees".

**Step 2: Pick the list call.**

- Past games: `get_games` with `date`, or `from` and `to`, or `team` and `season`.
- Future games: `get_schedule` with `days` and optional `team`.
- Only finals: `status: "final"`. Only unplayed: `status: "scheduled"`.

```json
POST /v1/get_games
{"team": "NYY", "season": 2025, "limit": 2}
```

Real response shape (trimmed):

```json
{"data": {"games": [{
  "game_id": "401809266", "season": 2025, "season_type": "postseason",
  "date": "2025-10-08", "status": "final",
  "home": {"abbrev": "NYY", "runs": 2, "hits": 6, "errors": 1},
  "away": {"abbrev": "TOR", "runs": 5, "hits": 12, "errors": 0},
  "innings": 9, "extra_innin

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: game-preview
description: "Builds a pre-game report for one MLB or college baseball matchup: records, run differential, Elo, recent form, injuries, the median and per-book lines, and what the market implies. Use when the user asks for a game preview, a breakdown of Team A vs Team B, tonight's matchup, or a shareable pre-game summary. Do not use for a full slate: loop get_odds by date instead and see odds-explorer. Do not use for odds-only lookups: see odds-explorer. Do not use for building a model: see walk-forward-validation."
metadata:
  version: 1.0.0
  author: FastballAPI
---

# Game Preview

> **Default data tool:** FastballAPI (`fastballapi-tool`).
> Typical cost: `get_schedule` (2) + `get_standings` (2) + `get_ratings` (2) + `get_team_stats` (5) + `get_injuries` (2 per team) + `get_odds` (5) = about 20 credits.
> If the user only needs the lines, stop at `get_odds` and use `odds-explorer`.

You compose one tight report that replaces 20 minutes of tab hopping. Starting pitchers drive baseball games and FastballAPI has no probable-pitcher endpoint, so the report states that gap instead of papering over it.

## When to Use

- "Preview tonight's Dodgers game"
- "Brewers vs Dodgers, what should I know?"
- "Break down Game 3"
- A shareable one-page summary of a matchup

## When NOT to Use

- A whole slate: use `get_odds` with `date` (10 credits) and `odds-explorer`
- Only prices or line moves: `odds-explorer`
- Season-long team assessment: `team-analysis`
- A pitcher's full arsenal: `pitch-mix-analysis`

## Commands Available

| Command | Use in a preview | Credits |
|---------|------------------|---------|
| `get_schedule` | Find the game, its id, first pitch, and the median line | 2 |
| `get_standings` | Record, home/away split, last 10, run differential, Pythagorean | 2 |
| `get_ratings` | Elo for both teams | 2 |
| `get_team_stats` | Team offence and run prevention (omit `team` for the league in one call, 5) | 5 |
| `get_injuries` | Injured list for each club (MLB only) | 2 per team |
| `get_odds` | Every book's lines for the `game_id` | 5 |
| `get_games` | The last meetings between the two teams (filter in code) | 2 |
| `get_pitch_mix` | The starter's arsenal, if the user names him | 5 |

## Commands That Do NOT Exist

| Not available | Use instead |
|---------------|-------------|
| `get_game_preview` | Compose from the calls above |
| `get_probable_pitchers`, `get_starting_lineups` | Not available. Ask the user who is starting, or label the section "starter unconfirmed" |
| `get_head_to_head` | `get_games` for one team and filter by opponent |
| `get_weather`, `get_park_factors` | Not available. Do not guess the wind |
| `get_bullpen_usage` | Rebuild from recent `get_game` pitching rows if the user asks (5 credits each) |
| `get_umpire` | Not available |

## How It Works

**Step 1: Find the game.** `get_schedule` with `team` and `days`. Take `game_id`, `starts_at` (UTC; convert), `venue`, `line` (median `home_ml`, `away_ml`, `home_run_line`, `total`, `books`). If `line` is null, the books have not posted. Say so; do not estimate.

**Step 2: Context for both clubs.** One `get_standings` call returns both. One `get_ratings` call returns both. From the standings row take `win_pct`, `pythagorean_win_pct`, home/away record, `last10_wins`, `run_differential`. A 2025 comparison, real values: MIL 97-65, +172, Pythagorean .608; LAD 93-69, +142, Pythagorean .586; Elo 1564.4 vs 1578.3.

**Step 3: Process.** `get_team_stats` (no `team`, 5 credits) gives both clubs in one call. Compare `runs_per_game`, `runs_allowed_per_game`, `batting.ops`, `pitching_against.ops`, `k_pct`, `bb_pct`.

**Step 4: Availability.** `get_injuries` for each `team`. List only players who matter to the game: starters, regulars, closers. `return_date` is the club's estimate.

**Step 5: Starting pitchers.** No endpoint. Options, in order:
1. The user states them. Then pull each starter with `search_players` (1) and `get_pitch_mix` (5), plus `get_pla

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: odds-analysis
description: "Converts baseball betting odds between formats and removes the bookmaker margin to get true implied probabilities for moneylines, run lines, totals and player props. Use when the user asks about devigging, vig, implied probability, no-vig price, multiplicative, power or Shin methods, American vs decimal odds, or what a price really says. Prerequisite for edge detection. Do not use for browsing current lines: see odds-explorer. Do not use for calibrating model output: see walk-forward-validation."
metadata:
  version: 1.0.0
  author: FastballAPI
---

# Odds Analysis

> **Default data tool:** FastballAPI (`fastballapi-tool`).
> Mostly pure math. Use `get_odds` (5 credits per game, 10 per date) for closing prices and `get_player_props` or `get_prop_history` (10 credits) for two-way prop prices. User-supplied prices cost nothing.

You turn prices into probabilities honestly. Every price carries a margin; a fair probability needs it removed, and the method you choose matters most on lopsided markets, which baseball has plenty of (pitching mismatches, run lines, props with one juiced side).

## When to Use

- "What is -174 / +142 really saying?"
- Removing the margin from a two-way market (moneyline, over/under, run line)
- Comparing prices across books on an equal footing
- Turning a prop price pair (over -146, under +115) into a fair probability
- Explaining American vs decimal odds

## When NOT to Use

- Browsing current lines: `odds-explorer`
- Judging whether a model's probabilities are well calibrated: `walk-forward-validation`

## Commands Available

| Command | What it does | Credits |
|---------|--------------|---------|
| `get_odds` | Prices by book for a game (5) or a date (10); finished games include `result` | 5 or 10 |
| `get_player_props` | Over and under prices by book for a game or a player | 10 |
| `get_prop_history` | Closing line and prices for a player-market over time | 10 |

## Commands That Do NOT Exist

| Not available | Use instead |
|---------------|-------------|
| `get_no_vig_line`, `get_fair_odds` | Compute from `get_odds` with the methods below |
| `get_true_probability` | Compute it; the API's `*_close_prob` fields still contain the margin |
| `get_three_way_odds` | Not applicable: baseball has no draw in the moneyline |

## Conversions

```python
def implied(american):
    return -american / (-american + 100) if american < 0 else 100 / (american + 100)

def decimal(american):
    return 1 + (american / 100 if american > 0 else 100 / -american)
```

| American | Decimal | Implied |
|----------|---------|---------|
| -174 | 1.575 | 63.5% |
| +142 | 2.420 | 41.3% |
| -146 | 1.685 | 59.3% |
| +115 | 2.150 | 46.5% |
| -110 | 1.909 | 52.4% |

Payout on a winning stake S is S times (decimal minus 1). A push returns the stake.

## The Margin

For a two-way market, the sum of the implied probabilities exceeds 1. The excess is the margin (vig, overround).

Real example: DraftKings closing moneyline on NYY vs TOR (2025-10-07), NYY -174, TOR +142 from `get_odds`:

```
implied NYY = 174/274 = 0.6350
implied TOR = 100/242 = 0.4132
sum         = 1.0483     margin = 4.8%
```

The `home_close_prob` and `away_close_prob` fields in the API response (0.635, 0.413) are exactly these raw numbers. They are not fair probabilities.

## Devig Methods

All three return probabilities that sum to 1. They differ on how the margin is spread.

**1. Multiplicative (proportional).** Divide each implied probability by the sum.

```
NYY: 0.6350 / 1.0483 = 0.6058     TOR: 0.4132 / 1.0483 = 0.3942
```

Simple, and assumes the margin is spread in proportion to probability. Tends to under-correct favourites.

**2. Power.** Find k such that p_home^k + p_away^k = 1, then use the powered values.

```
k = 1.0758:  NYY 0.6136, TOR 0.3864
```

Takes more margin off the longshot than multiplicative does. Use when you believe the favourite-longshot bias is present.

**3. Shin.** Solves for the share of money f

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: odds-explorer
description: "Compares MLB and college baseball sportsbook lines across books: moneyline, run line and total, best price, opening vs closing, vig, and pre-game line movement. Use when the user asks what the odds are, which book has the best price, how a line moved, what the closing line was, or whether the favourite won and the total went over. Do not use for devigging or implied probability math: see odds-analysis. Do not use for player prop lines: see prop-modeling."
metadata:
  version: 1.0.0
  author: FastballAPI
---

# Odds Explorer

> **Default data tool:** FastballAPI (`fastballapi-tool`).
> `get_odds` with `game_id` (5 credits) or `date` (10 credits for the whole slate). `get_line_movement` (10 credits per game). `get_schedule` (2) for the median line of upcoming games.

You report what the books posted, find the best price, and read movement without over-reading it. FastballAPI stores snapshots of lines, not a live betting feed. Always say when the snapshot was taken.

## When to Use

- "What are the lines on Dodgers at Brewers?"
- Best moneyline, run line or total across books
- Opening vs closing line, per book
- How a line moved before first pitch
- Did the favourite win and did the total go over (finished games)
- Which book is consistently the outlier on a market

## When NOT to Use

- Removing the margin or converting odds to probabilities: `odds-analysis`
- Player props (hits, strikeouts, total bases): `prop-modeling`
- Anything needing a live in-game price: not available

## Commands Available

| Command | What it does | Credits |
|---------|--------------|---------|
| `get_odds` | Each book's moneyline, run line, total for a game (`game_id`, 5) or a date (`date`, 10); opening and closing per book | 5 or 10 |
| `get_line_movement` | Snapshots of each book's line before first pitch for one `game_id`; optional `provider` | 10 |
| `get_schedule` | Upcoming games with the median line across books | 2 |
| `get_game` | One game with each book's open and close inside the box score | 5 |

## Commands That Do NOT Exist

| Not available | Use instead |
|---------------|-------------|
| `get_live_odds` | `get_schedule` or `get_odds` (stored snapshots) |
| `get_best_line`, `compare_books` | Compute from the `get_odds` `books` array |
| `get_public_betting` | Not available. Infer nothing about bet splits |
| `get_closing_line` | `get_odds` for a finished game: `home_ml_close`, `total_close` |
| `get_alt_lines`, `get_first_five` | Not available. Only full-game moneyline, run line, total |
| `get_odds_history` | `get_odds` for a past `game_id` or `date` |

## Coverage

- Per-book opening and closing lines from July 2020 (The Odds API), and from 2024 ESPN's feed as well. Before July 2020, only ESPN's final line.
- Books per game: 4 to 13 from 2015 to 2023; 6 to 8 with opening and closing since July 2020. The book list in a response is the truth: do not assume Pinnacle or FanDuel is present for an old game. Live per-season counts: https://fastballapi.com/docs/atlas.
- Pre-game snapshots (`get_line_movement`) are ESPN's once a day and The Odds API's hourly for games in the next two days. That is coarse: a steam move between two snapshots is invisible.
- College lines start in 2023, a median of 5 or 6 books per game, some with one.

## How It Works

**Step 1: Get the game id.** `get_schedule` (upcoming) or `get_games` (past). Do not call `get_odds` with a team name.

**Step 2: Pull the lines.**

```json
POST /v1/get_odds
{"game_id": "401809265"}
```

Real response (NYY 9, TOR 6, 2025-10-07, 8 books, one book shown, trimmed):

```json
{"data": {"games": [{"game_id": "401809265", "date": "2025-10-07",
  "home": {"abbrev": "NYY", "runs": 9}, "away": {"abbrev": "TOR", "runs": 6},
  "books": [{"provider": "DraftKings",
    "home_ml_open": -139, "home_ml_close": -174,
    "away_ml_open": 114,  "away_ml_close": 142,
    "home_close_prob": 0.635, "away_close_prob": 0.413,
    "home_run_line_close": -1.5, "run_lin

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: pitch-mix-analysis
description: "Analyzes an MLB pitcher's arsenal: pitch types, usage, average and top velocity, whiff rate per swing, ball rate, usage by count, velocity by inning and platoon splits, from FastballAPI pitch-by-pitch data. Use when the user asks what a pitcher throws, which pitch gets whiffs, how his velocity changes through a game or season, or what his pitch mix means for strikeouts. Do not use for season ERA or WHIP lines: see player-scouting. Do not use for pricing a strikeout prop: see prop-modeling. Do not use for college baseball: no pitch data exists there."
metadata:
  version: 1.0.0
  author: FastballAPI
---

# Pitch Mix Analysis

> **Default data tool:** FastballAPI (`fastballapi-tool`).
> `get_pitch_mix` (5 credits) gives the arsenal summary. `get_pitches` (10 credits, up to 2,000 rows a call) gives every pitch for custom cuts. `search_players` (1) first.

You read a pitcher's arsenal the way a scout reads a scouting report: what he throws, how hard, how often, and what batters do against it. MLB only. College baseball has no pitch rows.

## When to Use

- "What does Tarik Skubal throw?"
- "Which of his pitches gets the most whiffs?"
- Usage vs whiff: does he throw his best pitch enough?
- Velocity trend within a start or across a season
- Changes in pitch mix between seasons
- Inputs for a strikeout model (see `prop-modeling`)

## When NOT to Use

- Season ERA, WHIP, K/9: `player-scouting`
- Hitter-side batted-ball profile: `spray-chart-analysis`
- Run value of outcomes: `run-value-analysis`
- College pitchers: not available

## Commands Available

| Command | What it does | Credits |
|---------|--------------|---------|
| `get_pitch_mix` | Per pitch type: `pitches`, `usage`, `avg_velocity`, `max_velocity`, `whiff_rate`, `ball_rate`, `in_play`; takes `pitcher_id`, `season` | 5 |
| `get_pitches` | Every pitch: `at_bat_id`, `pitch_number`, `inning`, `half`, `balls`, `strikes`, `pitch_type`, `pitch_type_name`, `velocity`, `px`, `py`, `result`, `in_play`; filters `game_id`, `pitcher_id`, `batter_id`, `season`, `pitch_type`, `limit` up to 2,000, `offset` | 10 |
| `search_players` | Find `pitcher_id` | 1 |
| `get_player` | Season line to set the context | 5 |

## Commands That Do NOT Exist

| Not available | Use instead |
|---------------|-------------|
| `get_spin_rate`, `get_movement`, `get_extension` | Not available. No spin, break or release data |
| `get_stuff_plus`, `get_pitch_value` | Not available. Build run value from `get_plate_appearances` outcomes |
| `get_pitch_mix` for a game | Not available. Use `get_pitches` with `game_id` and aggregate |
| `get_pitch_arsenal_by_batter_hand` | Use `get_pitches` with `batter_id` filters or batch by handedness in code |
| `get_bullpen_mix` | Same tools, run per reliever |

## Coverage

- Every pitch since 2018. For 2015 to 2017, about 98 to 99% of each season's pitches.
- Pitch type and velocity are on 96% or more of each season's pitches, and 99.8% or more from 2020.
- Automatic balls and strikes (intentional walks, pitch-timer violations) are not pitches.
- `px` and `py` are ESPN's pitch-location frame in pixels, as sent. They are not feet and the strike zone boundaries are not given. Use them for relative location (up/down, in/out) within one pitcher, not for zone-rate claims against an official zone.
- Pitch type labels are ESPN's feed classifications (FF, SI, FC, SL, CH, CU, KC). Some pitchers' four-seam and sinker labels blur.

## How It Works

**Step 1: Resolve the pitcher.** `search_players` with `name`. Check `position` is SP or RP. Real: Tarik Skubal, `player_id` 42409.

**Step 2: Arsenal summary.**

```json
POST /v1/get_pitch_mix
{"pitcher_id": "42409", "season": 2025}
```

Real response (2025, trimmed to the four main pitches):

```json
{"data": {"pitcher": {"id": "42409", "name": "Tarik Skubal"}, "season": 2025, "pitches": 3152,
 "mix": [
  {"pitch_type": "CH", "name": "Changeup",     "pitches": 974, "usage": 0.309, "avg_velocity": 8

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: player-scouting
description: "Scouts MLB and college baseball players: finds a player id, pulls season-by-season batting (AVG, OBP, SLG, OPS, K%, BB%, RE24) and pitching (ERA, WHIP, K/9, BB/9) lines, game logs, season leaders and injury status, and compares players fairly. Use when the user asks about a named player, wants two players compared, asks who leads the league in a stat, or asks if a player is hurt. Do not use for a pitcher's arsenal detail: see pitch-mix-analysis. Do not use for where a hitter hits the ball: see spray-chart-analysis. Do not use for prop pricing: see prop-modeling."
metadata:
  version: 1.0.0
  author: FastballAPI
---

# Player Scouting

> **Default data tool:** FastballAPI (`fastballapi-tool`).
> `search_players` (1 credit) always comes first. Then `get_player` (5), `get_player_games` (5), `get_leaders` (5), `get_injuries` (2).

You build an honest picture of a player from rate stats, sample size and role. A hot month is not a skill change; a .380 BABIP is not a breakout.

## When to Use

- "How good is Aaron Judge?" or "How has he trended since 2022?"
- Comparing two hitters or two pitchers
- "Who leads MLB in OPS / K/9 / RE24?"
- A player's recent game log
- Is a player injured, and when is the expected return?
- Building a player list that a model or prop will use

## When NOT to Use

- Pitch types, velocity, whiff rate: `pitch-mix-analysis`
- Hit direction and batted-ball profile: `spray-chart-analysis`
- Run value per plate appearance and RISP splits: `run-value-analysis`
- Pricing a player's over/under: `prop-modeling`

## Commands Available

| Command | What it does | Credits |
|---------|--------------|---------|
| `search_players` | Player id by `name` (partial ok), `limit` 1 to 50 | 1 |
| `get_player` | Every season: batting (PA, AB, H, doubles, triples, HR, BB, SO, HBP, SF, RE24, AVG, OBP, SLG, OPS, K%, BB%) and pitching (G, GS, IP, ERA, WHIP, K/9, BB/9, HR/9) | 5 |
| `get_player_games` | Game log: each game's batting and pitching line, newest first; `season`, `season_type`, `limit` up to 200 | 5 |
| `get_leaders` | Qualified leaders. `stat` one of avg, obp, slg, ops, hr, re24, bb_pct, k_pct, era, whip, so, k_per_9, bb_per_9; `min_pa`, `min_ip`, `limit` up to 100 | 5 |
| `get_injuries` | Status, injury type, expected return for listed players; filter by `team` (MLB only) | 2 |

## Commands That Do NOT Exist

| Not available | Use instead |
|---------------|-------------|
| `get_war`, `get_fwar` | Not available. Use RE24 from `get_player` or `get_leaders` with `stat: "re24"` |
| `get_statcast`, `get_barrel_rate`, `get_exit_velocity` | Not available. No launch data. Use `get_spray_chart` trajectories |
| `get_contract`, `get_salary` | Not available |
| `get_minor_league_stats` | Not available |
| `get_splits` (vs LHP, day/night) | Not available as a call. Pull `get_plate_appearances` for the batter and group in code |
| `get_defense`, `get_oaa` | Not available |

## How It Works

**Step 1: Resolve the id.** `search_players` with `name`. Real response:

```json
{"data": {"players": [{"player_id": "33192", "name": "Aaron Judge", "position": "RF", "bats": "R", "team": "NYY"}], "count": 1}}
```

If several players match (a search for "Cole" returns Cole Hamels, Gerrit Cole, Cole Gillespie), confirm which one, by team and position, before spending 5 credits on stats. Ids are strings.

**Step 2: Season lines.** `get_player` returns `batting` and `pitching` arrays, one object per season, current season first. Real row (Judge, 2025): 679 PA, 53 HR, .331/.457/.688, OPS 1.144, K% .236, BB% .183, RE24 74.3. Real pitching row (Skubal, 2025): 195.1 IP, 2.21 ERA, 0.89 WHIP, 11.1 K/9, 1.5 BB/9. The current in-progress season is included: check `pa` or `ip` before comparing it to full years.

**Step 3: Qualify the sample.** Use these floors before saying anything is "real":

| Stat | Stabilizes roughly at | Rule |
|------|----------------------|------|
| K% (batter) | 60 PA | Trust early |
| BB% 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: prop-modeling
description: "Builds player prop projections for MLB: pitcher strikeouts and outs, batter hits, total bases, home runs and RBI. Pulls prop lines and results from FastballAPI, projects workload and rates, adjusts for the opponent, converts to over and under probabilities and compares them with the devigged market. Use when the user asks about a strikeout prop, a hits or total bases line, how often a player goes over, or how to model a prop. Do not use for team-level game prediction: see walk-forward-validation. Do not use to browse lines: see odds-explorer."
metadata:
  version: 1.0.0
  author: FastballAPI
---

# Prop Modeling

> **Default data tool:** FastballAPI (`fastballapi-tool`).
> `get_prop_history` (10 credits, up to 200 games) for line vs result history. `get_player_props` (10) for tonight's lines by book. `get_player_games` (5), `get_player` (5), `get_team_stats` (5), `get_pitch_mix` (5) for inputs. `estimate_only: true` on `get_player_props` prices a call without charging.

You project a number of events for one player in one game, turn it into a probability, and compare with the market's devigged price. Props are one-game, high-variance bets with margins near 5% to 6% on each side. Honest conclusion most of the time: the market is about right.

MLB only. College baseball has no props.

## When to Use

- "What is the projection for Skubal's strikeouts tonight?"
- "How often does Judge go over 1.5 total bases?"
- Pitcher strikeouts (`pitcher_strikeouts`), pitcher outs (`pitcher_outs`)
- Batter hits (`batter_hits`), total bases (`batter_total_bases`), home runs (`batter_home_runs`), RBI (`batter_rbis`)
- Evaluating whether a prop model beats the closing line over a sample

## When NOT to Use

- Browsing prop lines: `odds-explorer` covers game lines; use `get_player_props` here
- Game-level win probability: `walk-forward-validation`

## Commands Available

| Command | What it does | Credits |
|---------|--------------|---------|
| `get_player_props` | Lines by book. `game_id`: every player's props in that game. `player_id` plus `from_date` (and `to_date`): one player across games. `market`, `bookmaker`, `snapshot_type` (`closing` default, `opening`), `estimate_only` | 10 (per game returned on the player route, up to 100) |
| `get_prop_history` | One row per game for a player and `market`: closing `line`, `open_line`, `over_odds`, `under_odds`, `books`, `actual`, `result`, `margin`, plus a summary with `over_rate`. `from_date`, `to_date`, `bookmaker`, `limit` up to 200 | 10 |
| `get_player_games` | Game log: pitching rows have `starter`, `outs`, `h`, `r`, `er`, `bb`, `so`, `hr`, `pitches`, `strikes`; batting rows have `ab`, `h`, `hr`, `bb`, `so`, `batting_order` | 5 |
| `get_player` | Season line including doubles, triples, HR (for total bases) | 5 |
| `get_team_stats` | Opponent K%, BB%, OPS (omit `team` for all 30 clubs) | 5 |
| `get_pitch_mix` | Pitcher arsenal and whiff rates | 5 |
| `search_players` | Player ids | 1 |

## Commands That Do NOT Exist

| Not available | Use instead |
|---------------|-------------|
| `get_probable_pitchers`, `get_lineups` | Not available. Props posted for a pitcher imply he is starting; confirm from the club's own announcement |
| `get_umpire`, `get_weather`, `get_park_factors` | Not available. Leave these out and say so |
| `get_prop_projection`, `get_dfs_projection` | Not available. Build with the method below |
| `get_alt_lines` | Not available. One posted line per book per market |
| `get_live_props` | Not available. Closing or opening snapshots only |
| `get_player_splits` | Not available as a call. Use `get_plate_appearances` for a batter and group by pitcher in code |

## Coverage

- Prop lines start in May 2023 (DraftKings, FanDuel, BetMGM, ESPN BET, Pinnacle and others); markets: hits, home runs, total bases, RBI, pitcher strikeouts, pitcher outs.
- Closing is the last line before first pitch. Opening is the first captured. Both per book.
- Check counts

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: pythagorean-record
description: "Computes Pythagorean and Pythagenpat expected records from runs scored and allowed, measures how far a team's actual record is from it (luck), and projects regression for MLB and college baseball. Use when the user asks about Pythagorean record, expected wins, run differential, who got lucky or unlucky, one-run-game luck, or whether a team is as good as its record. Do not use for general standings and rankings: see team-analysis. Do not use for single-game prediction: see game-preview. Do not use to validate a model: see walk-forward-validation."
metadata:
  version: 1.0.0
  author: FastballAPI
---

# Pythagorean Record

> **Default data tool:** FastballAPI (`fastballapi-tool`).
> `get_standings` (2 credits) already returns `runs_scored`, `runs_allowed`, `run_differential` and `pythagorean_win_pct` for every team. `get_team_stats` (5) adds the process behind the runs.

You separate what a team did from what its scoring says it should have done. The gap is mostly luck in one-run games and sequencing, and it regresses.

## When to Use

- "Who was lucky in 2025?"
- "Is Toronto really a 94-win team?"
- "What does run differential say about the Brewers?"
- Expected wins at midseason, and what to expect the rest of the way
- Fitting a Pythagorean exponent for college baseball or another run environment

## When NOT to Use

- Standings, rankings, form: `team-analysis`
- A single game's price: `game-preview`, `odds-explorer`
- Testing a prediction model: `walk-forward-validation`

## Commands Available

| Command | What it does | Credits |
|---------|--------------|---------|
| `get_standings` | W-L, home/away, last 10, `runs_scored`, `runs_allowed`, `run_differential`, `win_pct`, `pythagorean_win_pct` | 2 |
| `get_team_stats` | Runs per game for and against, team batting and opponents' batting | 5 |
| `get_games` | Final scores for one-run-game splits | 2 |
| `get_ratings` | Elo, a cross-check that accounts for opponent strength | 2 |

All accept `league` (`mlb`, `ncaabase`) and `season`.

## Commands That Do NOT Exist

| Not available | Use instead |
|---------------|-------------|
| `get_expected_record`, `get_pythag` | Read `pythagorean_win_pct` from `get_standings`, or compute below |
| `get_base_runs`, `get_xwins` | Not available. Compute BaseRuns yourself from `get_team_stats` if needed |
| `get_one_run_record` | `get_games` for the team, then count games decided by one run |
| `get_clutch` | Not available. See `run-value-analysis` for RISP splits |

## The Formulas

**Classic Pythagorean** (James): expected win pct = RS^x / (RS^x + RA^x).

**Exponent.** The classic value is 2. A better fit for modern MLB is about 1.83. FastballAPI's own `pythagorean_win_pct` matches 1.83: checked against four 2025 teams (MIL .608, NYY .597, TOR .546, PHI .583), the exponent 1.83 reproduces the API value to three decimals each time, and the exponent 2 does not. Use 1.83 for MLB unless you fit your own.

**Pythagenpat** (Smyth/Patriot): exponent x = ((RS + RA) / G)^0.287, so the exponent rises with run environment. For 2025 MIL, x = 1.87 and the result is within a fraction of a win of the 1.83 version. It matters more for college and other high-scoring environments.

```python
def pythag(rs, ra, exp=1.83):
    return rs**exp / (rs**exp + ra**exp)

def pythagenpat(rs, ra, g):
    x = ((rs + ra) / g) ** 0.287
    return rs**x / (rs**x + ra**x)
```

**Rule of thumb:** about 10 runs of differential is about 1 win in MLB. Check it against your own data rather than quoting it blindly.

## How It Works

**Step 1: Pull standings.** `get_standings` with `season`.

```json
POST /v1/get_standings
{"season": 2025}
```

Real rows (2025, trimmed):

```json
{"data": {"season": 2025, "standings": [
 {"abbrev": "MIL", "wins": 97, "losses": 65, "runs_scored": 806, "runs_allowed": 634, "run_differential": 172, "win_pct": 0.599, "pythagorean_win_pct": 0.608},
 {"abbrev": "TOR", "wins": 94, "losses": 68, "runs_scored": 798,

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: run-value-analysis
description: "Measures what happened in baseball in runs and win probability: RE24 run value per plate appearance, base-out state, runners in scoring position splits, win probability added and leverage-style context for MLB and college baseball. Use when the user asks about run value, RE24, run expectancy, clutch or RISP hitting, how much a home run mattered, or which plate appearances decided a game. Do not use for season rate stats: see player-scouting. Do not use for hit direction: see spray-chart-analysis. Do not use for pitcher arsenals: see pitch-mix-analysis."
metadata:
  version: 1.0.0
  author: FastballAPI
---

# Run Value Analysis

> **Default data tool:** FastballAPI (`fastballapi-tool`).
> `get_plate_appearances` (10 credits, up to 1,000 rows a call) has the base-out state, result, run value and win probability for every plate appearance. `get_player` (5) and `get_leaders` with `stat: "re24"` (5) give season RE24 totals.

You value outcomes by the runs and wins they add, not by the box-score label. A home run with the bases empty and two outs is worth exactly one run. A double with the bases loaded is worth far more than a double with the bases empty.

## When to Use

- "How much was that home run worth?"
- Player RE24 totals and per-PA values
- RISP (runners in scoring position) hitting, honestly framed
- Win probability swings in one game: which plate appearances decided it
- Comparing two hitters in run terms
- Building a context-neutral input for a model

## When NOT to Use

- Season rate stats (AVG, OBP, K%): `player-scouting`
- Hit direction and batted-ball type: `spray-chart-analysis`
- Pitch-type detail: `pitch-mix-analysis`

## Commands Available

| Command | What it does | Credits |
|---------|--------------|---------|
| `get_plate_appearances` | One row per plate appearance: `before` (outs, on_first, on_second, on_third), `result`, `batted_ball` (trajectory, x, y), `runs_scored`, `outs_after`, `score_after`, `home_win_prob` after, `run_value`. Filters: `game_id`, `batter_id`, `pitcher_id`, `team`, `season`, `season_type`, `result`, `inning`, `risp`, `limit` (max 1,000), `offset` | 10 |
| `get_player` | Season RE24 beside the rate stats | 5 |
| `get_leaders` | RE24 leaders (`stat: "re24"`), qualified | 5 |
| `get_game` | Win-probability range for one game | 5 |

## Commands That Do NOT Exist

| Not available | Use instead |
|---------------|-------------|
| `get_run_expectancy_table` | Not available as a call. Rebuild it from `get_plate_appearances` or use `run_value` directly |
| `get_leverage_index`, `get_wpa` | Not available. Compute WPA from consecutive `home_win_prob` as shown below |
| `get_war`, `get_wrc_plus` | Not available |
| `get_splits` | Filter `get_plate_appearances` (`risp`, `inning`, `result`) |
| `get_clutch_stats` | Not available. Build a RISP split and report the sample |

## What `run_value` Is

RE24 for a plate appearance:

```
run_value = runs_scored + RE(after) - RE(before)
```

where RE(state) is the average number of runs scored from that base-out state to the end of the inning, taken from each season's own run expectancy table (the API states it uses each season's own table). There are 24 states: 8 base configurations times 3 outs.

Real rows from two Judge home runs (2025):

```
Home run, bases empty, 2 outs, 1 run scored:   run_value 1.0
Home run, runner on first, 1 out, 2 runs:      run_value 1.749
```

The first is exactly 1 because the base-out state is the same before and after (bases empty, 2 outs) and one run scored. The second is above 2 minus the loss from clearing the runner: 2 runs plus RE(bases empty, 1 out) minus RE(runner on first, 1 out). The state before is more valuable than the state after, so the value lands under 2, near 1.75.

Rules this gives you: a walk with the bases empty is worth roughly the gain in expectation for adding a runner; an out with a runner on third and fewer than two outs is costly unless a run scores.

## How 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: spray-chart-analysis
description: "Reads where an MLB batter or team hits the ball: balls in play by trajectory (ground ball, line drive, fly ball, pop-up) and by field (left, center, right), hit rates, home runs per fly ball, pull and opposite-field tendencies, and ball-by-ball x/y points for drawing a spray chart. Use when the user asks where a hitter hits the ball, whether he pulls, how many of his fly balls leave the park, or wants a spray chart. Do not use for season rate stats: see player-scouting. Do not use for run value: see run-value-analysis. Do not use for pitch data: see pitch-mix-analysis."
metadata:
  version: 1.0.0
  author: FastballAPI
---

# Spray Chart Analysis

> **Default data tool:** FastballAPI (`fastballapi-tool`).
> `get_spray_chart` (10 credits). Add `include_balls: true` for each ball's x/y (up to 3,000 balls). `search_players` (1) first. MLB only.

You describe a hitter's batted-ball profile from the data FastballAPI holds: trajectory, field and location. There is no exit velocity or launch angle, so you describe where and what kind, not how hard.

## When to Use

- "Where does Aaron Judge hit the ball?"
- Pull, center and opposite-field shares
- Home runs per fly ball; line-drive rate
- Draw a spray chart (scatter of x/y)
- Compare a team's batted-ball tendencies with another team's
- Context for a hitter's BABIP or home run total

## When NOT to Use

- Season slash lines and plate discipline: `player-scouting`
- Run value of outcomes: `run-value-analysis`
- Pitcher arsenals: `pitch-mix-analysis`
- Exit velocity, barrels, launch angle: not available in this data

## Commands Available

| Command | What it does | Credits |
|---------|--------------|---------|
| `get_spray_chart` | Balls in play by trajectory and by field with hit rates. `batter_id` or `team`, `season`, `include_balls` | 10 |
| `get_plate_appearances` | Each batted ball with `trajectory`, `x`, `y`, result and run value, if you need per-event detail (filter by `batter_id`, `result`) | 10 |
| `search_players` | Find `batter_id` | 1 |

## Commands That Do NOT Exist

| Not available | Use instead |
|---------------|-------------|
| `get_exit_velocity`, `get_launch_angle`, `get_barrels`, `get_xwoba` | Not available |
| `get_hit_distance` | The `description` text on a `get_plate_appearances` home run includes distance in feet (for example "383 feet"); parse it, and do not assume other hits have it |
| `get_shift_data` | Not available |
| `get_hard_hit_rate` | Not available. Line-drive rate is the nearest proxy |
| `get_spray_chart` for college | Not available |

## Trajectory and Field Codes

| Code | Meaning |
|------|---------|
| `G` | Ground ball |
| `L` | Line drive |
| `F` | Fly ball |
| `P` | Pop-up |
| `unknown` | Not classified (a handful per season) |

Fields are `left`, `center`, `right`, `unknown`. For a right-handed hitter, left field is the pull side; for a left-handed hitter, right field is. Get the handedness from `search_players` (`bats`: R, L, or null for some players) before labeling pull or opposite.

## How It Works

**Step 1: Pull the chart.**

```json
POST /v1/get_spray_chart
{"batter_id": "33192", "season": 2025}
```

Real response (Aaron Judge, 2025):

```json
{"data": {"season": 2025, "balls_in_play": 410,
 "by_trajectory": [
  {"trajectory": "F", "balls": 154, "hits": 70, "hr": 52, "hit_rate": 0.455},
  {"trajectory": "G", "balls": 138, "hits": 50, "hr": 0,  "hit_rate": 0.362},
  {"trajectory": "L", "balls": 95,  "hits": 72, "hr": 2,  "hit_rate": 0.758},
  {"trajectory": "P", "balls": 22,  "hits": 0,  "hr": 0,  "hit_rate": 0}],
 "by_field": [
  {"field": "left",   "balls": 168, "hits": 99, "hr": 24, "hit_rate": 0.589},
  {"field": "center", "balls": 122, "hits": 34, "hr": 6,  "hit_rate": 0.279},
  {"field": "right",  "balls": 119, "hits": 59, "hr": 24, "hit_rate": 0.496}]}}
```

Two things to notice. First, `balls_in_play` here includes home runs (52 of the 154 fly balls are home runs), so it is a count 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: team-analysis
description: "Analyzes MLB and college baseball teams: standings, home and away splits, runs scored and allowed, team batting and run prevention, Elo power ratings and strength of schedule. Use when the user asks how a team is doing, who the best team is, which offense or pitching staff is better, or wants a power ranking. Do not use for single-player questions: see player-scouting. Do not use for Pythagorean luck analysis on its own: see pythagorean-record. Do not use for a single upcoming game: see game-preview."
metadata:
  version: 1.0.0
  author: FastballAPI
---

# Team Analysis

> **Default data tool:** FastballAPI (`fastballapi-tool`).
> `get_standings` (2 credits), `get_ratings` (2), `get_team_stats` (5), `get_games` (2) for splits and schedule strength.

You describe how good a team is and why, using results (standings), process (rates from every plate appearance) and our Elo. Records alone mislead in baseball: 162 games is a short sample for team quality.

## When to Use

- "How are the Brewers doing?"
- "Who is the best team in baseball?" (power ranking)
- "Which offense is best? Which staff prevents runs?"
- Comparing two teams before a series
- A division race or wild-card picture from the standings
- College baseball team ratings and tournament seeding context

## When NOT to Use

- One player's performance: `player-scouting`
- Whether a record is lucky: `pythagorean-record` (this skill points there)
- A specific game and its price: `game-preview`

## Commands Available

| Command | What it does | Credits |
|---------|--------------|---------|
| `get_standings` | Record, home/away, last 10, runs scored and allowed, run differential, Pythagorean win pct | 2 |
| `get_ratings` | Elo for every team, ranked, as of season end or today | 2 |
| `get_team_stats` | Runs per game for and against; team batting and opponents' batting (AVG, OBP, SLG, OPS, K%, BB%, HR) | 5 |
| `get_games` | A team's games, for splits and schedule strength | 2 |
| `get_injuries` | Current injured list (MLB only) | 2 |
| `list_teams` | Team ids and abbreviations | 1 |

## Commands That Do NOT Exist

| Not available | Use instead |
|---------------|-------------|
| `get_team_roster`, `get_depth_chart` | Not available. Use `get_leaders` and `get_player` for named players |
| `get_bullpen_stats` | Not available. Derive from `get_game` pitching rows where `starter` is false |
| `get_team_defense`, `get_drs` | Not available. Use opponents' batting from `get_team_stats` as a rough proxy |
| `get_strength_of_schedule` | Compute from `get_games` and `get_ratings` as shown below |
| `get_playoff_odds` | Not available. Simulate with Elo if the user wants a number |

## How It Works

**Step 1: Standings snapshot.** `get_standings` with `season`. Each row has `wins`, `losses`, `home_wins`, `home_losses`, `away_wins`, `away_losses`, `last10_wins`, `runs_scored`, `runs_allowed`, `run_differential`, `win_pct`, `pythagorean_win_pct`. Real row (2025 Brewers): 97-65, 806 runs scored, 634 allowed, +172, `pythagorean_win_pct` 0.608.

**Step 2: Process stats.** `get_team_stats` with `team` and `season`. Real shape (2025 Yankees, trimmed):

```json
{"data": {"teams": [{"abbrev": "NYY", "games": 162,
  "runs_per_game": 5.24, "runs_allowed_per_game": 4.23, "run_differential": 164,
  "batting": {"hr": 274, "avg": 0.251, "obp": 0.332, "slg": 0.455, "ops": 0.787, "k_pct": 0.235, "bb_pct": 0.102},
  "pitching_against": {"hr": 175, "avg": 0.229, "obp": 0.305, "slg": 0.379, "ops": 0.684, "k_pct": 0.236, "bb_pct": 0.092}
}]}}
```

Reading it: offense is `batting`; run prevention is `pitching_against` (opponents' line against this team, so it mixes pitching and defense). A team with a .787 OPS and a .684 OPS against is a plus team on both sides.

**Step 3: Power rating.** `get_ratings` returns Elo, 1500 average. The method note in the response says a 100-point gap is about a 64% favourite on a neutral field, and ratings regress a third of the way to the 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: walk-forward-validation
description: "Evaluates baseball prediction models honestly with time-ordered walk-forward splits: leakage-safe rolling features, expanding vs sliding windows, baselines (home field, Elo, closing line), log loss, Brier score and calibration checks. Use when the user asks how to validate a model, whether cross-validation is okay, how to engineer features without leakage, or whether a model's accuracy is real. Refuses random k-fold on games. Do not use for odds math: see odds-analysis. Do not use for prop pricing: see prop-modeling."
metadata:
  version: 1.0.0
  author: FastballAPI
---

# Walk-Forward Validation

> **Default data tool:** FastballAPI (`fastballapi-tool`).
> `get_games` (2 credits per call, up to 200 games) for results, `get_standings` (2) and `get_ratings` (2) for as-of-season context, `get_odds` (10 per date) for a market baseline. This skill is mostly method.

You make a model's score honest. Baseball is the hardest major sport to predict from team data: even the best clubs win about 60% of games, so the gap between a real model and noise is a couple of percentage points. Leakage or a bad split can create that much by itself.

## When to Use

- "Is my win-probability model any good?"
- "Can I use k-fold cross-validation on games?" (no)
- Choosing features and making sure they use only past information
- Comparing a model with Elo, home field and the closing line
- Checking whether predicted probabilities are calibrated
- Setting up a train/test structure for props or totals

## When NOT to Use

- Computing fair probabilities from prices: `odds-analysis`
- Pitcher or hitter prop math: `prop-modeling`
- Team record luck: `pythagorean-record`

## Commands Available

| Command | What it does | Credits |
|---------|--------------|---------|
| `get_games` | Final scores by season, date range or team; `limit` up to 200, `offset` to page | 2 per call |
| `get_standings` | Season standings (use only as-of-prior-season for features) | 2 |
| `get_ratings` | Elo, "as of the end of a season or today" | 2 |
| `get_odds` | Closing prices for a date (10) or a game (5), with `result` for finished games | 5 or 10 |
| `get_team_stats` | Season team process stats | 5 |

## Commands That Do NOT Exist

| Not available | Use instead |
|---------------|-------------|
| `get_train_test_split`, `evaluate_model` | Implement the splits and metrics below |
| `get_rolling_stats`, `get_team_form` | Build from `get_games` with a lag, as shown |
| `get_elo_history` | `get_ratings` is end-of-season or today only. Build your own game-by-game Elo from `get_games` for as-of features |
| `get_probable_pitchers` | Not available. Pitcher identity cannot be a pre-game feature from this API |
| `get_lineups`, `get_weather`, `get_park_factors` | Not available |

A hard limit to say up front: `get_ratings` returns one rating per team per call, as of a season's end or now. Using `get_ratings` for season N as a feature for games in season N is leakage. Use the previous season's end rating, or build a rolling Elo yourself.

## Why Random K-Fold Fails

Random folds put games from the same week in train and test. A team's April and May games share its roster, its Elo and its streaks. The model sees the future of the team's season and the test score rises. Measure it: run both a random k-fold and a walk-forward split on the same data and report the gap. If the random score is higher, that gap is the leak.

Walk-forward means every prediction is made with only information that existed before first pitch.

## Splits

**Expanding window (default).** Train seasons 2015 to N-1, test season N, for N from 2019 to the latest complete season. The train set grows each fold.

**Sliding window.** Train on the last K seasons only, if the older data hurts (rule changes, the 2020 shortened season, pitch-clock effects). Test this with data, not by assumption.

**Within a season (for in-season models).** Train through date D, predict D+1 to D+

Preview of the first 4,000 characters. Read full instructions →