EndzoneAPI

View saved version →

---
name: college-football
description: "Works with EndzoneAPI's FBS (NCAAF) and FCS college football data: games, rankings at kickoff, conference standings, Elo, play-by-play, player lines, and sportsbook lines. Use when user asks about college football, FBS, FCS, a bowl or playoff game, AP or CFP rank, Elo ratings, or college lines and props. Do not use for NFL questions, see game-lookup. Do not use for EPA or tracking data, college endpoints carry neither, see epa-analysis for the NFL."
metadata:
  version: 1.0.0
  author: EndzoneAPI
---

# College Football (FBS and FCS)

> **Default data tool:** EndzoneAPI (`endzoneapi-tool`), on the college routes.
> FBS: `POST https://mcp.endzoneapi.com/v1/ncaaf/<tool>` or MCP at `https://mcp.endzoneapi.com/mcp/ncaaf`.
> FCS: `POST https://mcp.endzoneapi.com/v1/fcs/<tool>` or MCP at `https://mcp.endzoneapi.com/mcp/fcs`.
> Same account, same credit balance and the same price per tool as the NFL.

You are a college football analyst. Your job is to use the college data for what it has, and to say plainly where it differs from the NFL data so no NFL assumption leaks into an FBS answer.

## When to Use

- "Which ranked teams played in week 1 of 2025?"
- "Show Montana State's FCS season"
- "What was Kansas State's Elo?"
- "Bowl and playoff games with closing lines"
- "College player props" (FBS only)

## When NOT to Use

- NFL schedules and standings, see `game-lookup`
- EPA, success rate, Next Gen Stats, injuries, depth charts, snap counts: none exist for college, see `epa-analysis` and `next-gen-stats` for the NFL
- General betting math, see `odds-analysis`

## Coverage (from the site's own copy)

| Data | FBS | FCS |
|------|-----|-----|
| Games | since 2004, 18,769 games, with AP and CFP rank of both teams at kickoff and bowl or playoff round | since 2004, 15,356 games; 2020 spring season included |
| Plays | 3.27M plays, win probability after each play from 2016 | 1.85M plays for most games since 2013, none before 2006; win probability from 2016 |
| Player lines | complete from 2016, partial earlier | partial earlier |
| Standings and Elo | conference standings, our Elo for every FBS team | conference standings, no ranks or ratings |
| Lines | about 6 to 10 books per game 2014 to 2023 (ESPN); 6 to 8 books incl. Pinnacle 2020 to 2025 (The Odds API) | ESPN lines from 2017, uneven coverage; 6 books for 2026 captured since August 28 2026 |
| Player props | passing, rushing, receiving yards, passing TDs, receptions, anytime TD, 2023 to 2025 | none |
| Alternate lines | seven books, 2023 to 2025 | none |

Game counts and play counts change as seasons load. Current numbers: https://endzoneapi.com/college-football and https://endzoneapi.com/fcs-football

## Commands Available

FBS (15 tools, read live from `GET /v1/ncaaf/tools`):

| Command | Parameters that differ from the NFL | Credits |
|---------|-------------------------------------|---------|
| `list_teams` | `season`, `conference` (a college conference name) | 1 |
| `get_games` | `season_type`, `ranked`, `offset`; no `game_type` | 5 |
| `get_schedule` | `team`, `days`; no `week` | 2 |
| `get_standings` | `season`, `conference` | 2 |
| `get_team_stats` | `team`, `season`, `season_type`; per-game averages and `elo` | 5 |
| `search_players` | `query`, `team`, `position` | 2 |
| `get_player_stats` | `player_id`, `season`, `season_type` | 5 |
| `get_player_leaders` | `stat`, `season`, `season_type`, `team`, `position`, `min_games` | 5 |
| `get_plays` | `scoring`, `quarter`, `down`, `red_zone`, `third_down`, `posteam`, `defteam` | 10 |
| `get_game_detail`, `get_head_to_head` | same as NFL | 10 |
| `get_odds` | `game_id`, `season`, `week`, `team` | 10 per game |
| `get_player_props`, `get_alt_lines` | same shape as NFL | 10 |
| `get_line_movement` | `game_id`, `bookmaker` | 25 |

FCS has 13 tools: the same list without `get_player_props` and `get_alt_lines`, and `get_games` has no `ranked` flag.

## Commands That Do NOT Exist (college)

| Not Ava

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

View saved version →

---
name: dispatch
description: "Routes football analytics requests to the right 2-3 skills. Load this FIRST when an NFL, FBS or FCS data request arrives and you are unsure which skills to activate. Prevents loading all skills when only a few are needed."
metadata:
  version: 1.0.0
  author: EndzoneAPI
---

# Skill Dispatch Guide

Match the request to a pattern. Load those skills. Do not load everything.

**Default data tool:** `endzoneapi-tool`. Load it alongside the analysis skill whenever a call is needed, for the exact names, parameters and credit costs.


## Where Does the Question Live?

| Signal | League route |
|--------|--------------|
| Team names like Chiefs, Bills; "NFL"; weeks 1 to 18 | NFL (default) |
| Ranked teams, bowls, "college football", FBS | `college-football` (route `/v1/ncaaf/`) |
| FCS, Montana State, Big Sky | `college-football` (route `/v1/fcs/`) |

## Persona Detection

| Signal | Persona | Start With |
|--------|---------|-----------|
| "Who plays this week?" / exploring | Explorer | `game-lookup` + `endzoneapi-tool` |
| "How good is this offense?" | Analyst | `epa-analysis` + `endzoneapi-tool` |
| "I want to build a model" | Builder | `feature-engineering` + `walk-forward-validation` |
| "Is my model any good?" | Validator | `walk-forward-validation` + `probability-calibration` |
| "I am new to reading odds" | Odds reader | `odds-analysis` + `odds-explorer` |

## Request Patterns to Skills

### "Who plays Sunday?" / "What was the score?" / "Standings" / "Playoff seeds"
1. `game-lookup`
2. `endzoneapi-tool` for `get_games`, `get_schedule`, `get_standings`

### "Preview Bills at Chiefs" / "Who has the edge in this game?"
1. `game-preview`
2. `epa-analysis` for the efficiency comparison
3. `odds-explorer` if the user wants book-level prices

### "Which offense is best?" / "Third-down EPA" / "Success rate" / "Play action"
1. `epa-analysis`
2. `endzoneapi-tool`

### "Tell me about [player]" / "Who leads in receiving yards?" / "Target share"
1. `player-scouting`
2. `next-gen-stats` if separation, time to throw, pressure or rush yards over expected come up

### "Does he get open?" / "Time to throw" / "Rush yards over expected" / "Drops"
1. `next-gen-stats`
2. `player-scouting` for counting stats

### "What is the line?" / "Best price" / "How did it move?" / "Alternate spread"
1. `odds-explorer`
2. `odds-analysis` for devig or implied probability

### "What does -150 mean?" / "Remove the vig" / "Fair price" / "Break-even rate"
1. `odds-analysis`

### "Will he go over 250.5?" / "Anytime TD price" / "Prop history"
1. `prop-modeling`
2. `player-scouting` for role, `odds-analysis` for the price

### "Build me a model" / "What features?" / "Elo"
1. `feature-engineering`
2. `walk-forward-validation`
3. `probability-calibration` after predictions exist

### "Is my model overconfident?" / "Brier score"
1. `probability-calibration`
2. `walk-forward-validation`

### "College football" / "Ranked teams" / "Bowl lines" / "FCS"
1. `college-football`
2. `odds-explorer` for lines, same math applies
3. Warn early that college has no EPA, tracking, injuries or depth charts

### "How much will this cost?" / "Which tool?" / "REST or MCP?"
1. `endzoneapi-tool`

## Multi-Skill Workflows

**Weekly odds review:**
1. `game-lookup` for the slate (2 credits)
2. `game-preview` on the games of interest
4. `odds-explorer` to place the best price

**Build and validate a model:**
1. `feature-engineering`
2. `walk-forward-validation`
3. `probability-calibration`

**Prop session:**
1. `player-scouting` for role
2. `prop-modeling` for the projection and price
3. `odds-analysis` to devig

## Credit Awareness

Before loading a skill that will make several calls, estimate the cost and say it. Expensive calls: `get_line_movement` (25), `get_odds` for a season (10 per game), `get_plays` (10 per page), `get_player_props` for many games (10 each). A season of consensus lines through `get_games` is 5. Use `estimate_only` on `get_odds` and `get_pla

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

View saved version →

---
name: endzoneapi-tool
description: "Router and reference for every EndzoneAPI tool: names, parameters, credit costs, coverage by season, the response envelope, and the college football and FCS endpoints. Use when any football data request needs a tool call, when you need the cost of a call before making it, or when a tool returns an empty or invalid-parameter result. Do not use for analysis method, see the skill each tool row points to."
metadata:
  version: 1.0.0
  author: EndzoneAPI
---

# EndzoneAPI Tool Reference

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


> **Default data tool:** EndzoneAPI. This skill is the map. Load it alongside whichever analysis skill you are using.
> Docs for each tool: https://endzoneapi.com/docs

You are the routing layer between a football question and the right tool call. Pick the cheapest call that answers the question, say what it costs before any expensive pull, and never invent a tool.

## When to Use

- You are about to call an EndzoneAPI tool and want the exact name, parameters and cost
- A call returned nothing and you need to know whether the data exists for that season
- You need to pick between a 5 credit and a 10 credit route to the same answer
- You are setting up REST or MCP access for the user

## When NOT to Use

- Interpreting EPA, success rate or tracking data, see `epa-analysis` and `next-gen-stats`
- Converting odds to probabilities, see `odds-analysis`
- Deciding which skills to load for a request, see `dispatch`

## Connecting

| Route | How |
|-------|-----|
| MCP (college) | `https://mcp.endzoneapi.com/mcp/ncaaf` for FBS, `https://mcp.endzoneapi.com/mcp/fcs` for FCS |
| REST (college) | `POST https://mcp.endzoneapi.com/v1/ncaaf/<tool>` or `/v1/fcs/<tool>`; `GET /v1/ncaaf/tools` lists that league's tools |

Listing tools works without signing in. Calling one needs the user's OAuth sign-in.

Every REST response is wrapped: `{"data": {...}}`. Read the payload from `data`. Errors come back as `{"error": "..."}` with the failing parameter named.

## Commands Available (NFL)

| Command | What It Does | Credits | Used by |
|---------|-------------|---------|---------|
| `list_teams` | 32 teams, conference, division, colours | 1 | `game-lookup` |
| `get_standings` | Standings with the real tiebreak step per rank | 2 | `game-lookup` |
| `get_schedule` | Unplayed games, next N days or one week | 2 | `game-lookup`, `game-preview` |
| `search_players` | Find a player, returns the GSIS and PFR ids | 2 | `player-scouting` |
| `get_injuries` | Official injury report by team and week | 2 | `game-preview`, `prop-modeling` |
| `get_depth_chart` | Depth chart by week | 2 | `game-preview`, `prop-modeling` |
| `get_team_stats` | Team season totals, EPA per play, weekly lines | 5 | `epa-analysis` |
| `get_player_stats` | One player: bio, season totals, weekly lines | 5 | `player-scouting` |
| `get_player_leaders` | Rank players on ~130 weekly stats | 5 | `player-scouting`, `epa-analysis` |
| `get_snap_counts` | Snaps and snap shares by game, player or team | 5 | `prop-modeling` |
| `get_advanced_stats` | Next Gen Stats and PFR advanced tables | 5 | `next-gen-stats` |
| `get_plays` | Play-by-play with EPA, WPA, win probability, charting | 10 | `epa-analysis`, `feature-engineering` |
| `get_game_detail` | One game: team stats, odds by book, weather, officials | 10 | `game-preview` |
| `get_head_to_head` | Two teams' meetings and record | 10 | `game-preview` |
| `get_player_props` | Prop lines by book, one game or one player-season | 10 | `prop-modeling` |
| `get_prop_history` | A player's results against his prop line | 10 | `prop-modeling` |
| `get_alt_lines` | Alternate spread and total ladders | 10 | `odds-explorer` |
| `get_line_movement` | Hourly line snapshots by book | 25 | `odds-explorer` |

## Commands That Do NOT E

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

View saved version →

---
name: epa-analysis
description: "Measures NFL team and unit efficiency with expected points added (EPA) per play, success rate, win probability added and situational splits, from play-by-play and team stats. Use when user asks about EPA, success rate, which offense or defense is best, third-down or red-zone efficiency, pass versus run efficiency, early-down tendencies, play action or motion effects, or how good a team really is. Do not use for player tracking metrics, see next-gen-stats. Do not use for score or schedule lookup, see game-lookup. Do not use for college football, which has no EPA field, see college-football."
metadata:
  version: 1.0.0
  author: EndzoneAPI
---

# EPA Analysis

> **Default data tool:** EndzoneAPI (`endzoneapi-tool`).
> `get_plays` (10 credits) returns plays plus a per-query EPA and success-rate summary. `get_team_stats` (5 credits) returns season EPA per play and weekly lines. `get_player_leaders` (5 credits) ranks players on `passing_epa`, `rushing_epa`, `receiving_epa`.

You are an expert in football efficiency metrics. Your goal is to answer "how good is this offense or defense" with a rate, a sample size, and a split that explains it.

## When to Use

- "Which offenses were best on third down in 2025?"
- "Is Kansas City's problem passing or running?"
- "How does play action change efficiency?"
- "What is a team's EPA per play when trailing?"
- "Rank quarterbacks by EPA"

## When NOT to Use

- Separation, pressure, time to throw, see `next-gen-stats`
- Win/loss records and schedules, see `game-lookup`
- FBS or FCS, which do not carry EPA, see `college-football`
- Turning EPA into a prediction model, see `feature-engineering`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_plays` | Plays with `epa`, `wpa`, `wp`, `success`, `yards_gained`; filters for down, quarter, play type, red zone, win probability band, charting flags; returns `summary` | 10 |
| `get_team_stats` | `totals.passing_epa_per_play`, `rushing_epa_per_play`, yards per attempt and carry, plus `weeks[]` | 5 |
| `get_player_leaders` | Rank by `passing_epa`, `rushing_epa`, `receiving_epa` | 5 |
| `get_games` | Join game results to your EPA numbers | 5 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_team_epa` | `get_team_stats`, or `get_plays` with `posteam` and read `summary.epa_per_play` |
| `get_defense_epa` | `get_plays` with `defteam` set instead of `posteam` |
| `get_epa_by_situation` | Filter `get_plays` (`down`, `quarter`, `red_zone`, `third_down`, `min_wp`, `max_wp`) |
| `get_success_rate` | `summary.success_rate` in `get_plays` |
| `get_cpoe` | `get_plays` returns CPOE per play; `get_advanced_stats` with an ngs_passing source has season CPOE |

## Definitions

- **EPA (expected points added):** points the offense is expected to score on the drive after the play minus before it. A 6 yard gain on 3rd and 10 can be negative.
- **EPA per play:** mean EPA over a set of plays. The unit is points per play. League-average offense sits near zero by construction; 0.1 per play is a very good offense, -0.1 a bad one.
- **Success:** a binary per play (`success` 1 or 0). Success rate is the mean. It ignores play size, so it is steadier than EPA and misses explosive plays.
- **WPA:** change in win probability from the play. Context-dependent; do not use to rate talent.
- **CPOE:** completion probability over expected, in percentage points, on pass plays.

Real example from the data: the first 2025 KC third-down pass returned was 3rd and 6, incomplete, `epa` -1.57, `wpa` -0.048, `success` 0. A 40-play pull of that split gave `epa_per_play` -0.112 and `success_rate` 0.375. Forty plays is a sample, not a verdict; it shows the shape.

## How It Works

**Step 1: Choose the scope.** Whole-season rate for a team: `get_team_stats(team="KC", season=2025)`. Any split: `get_plays` with filters.

**Step 2: Pull the split with the summary.*

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

View saved version →

---
name: feature-engineering
description: "Builds leak-free predictive features for NFL games and players: rolling EPA, opponent-adjusted rates, rest and travel, quarterback changes, Elo, and market-derived inputs. Use when user asks to build features, wants rolling averages, asks what to feed a model, asks about data leakage, or has a model that looks too good. Do not use for model training, evaluation or calibration, see walk-forward-validation and probability-calibration. Do not use for a single descriptive stat, see epa-analysis."
metadata:
  version: 1.0.0
  author: EndzoneAPI
---

# Feature Engineering

> **Default data tool:** EndzoneAPI (`endzoneapi-tool`).
> `get_games` (5 credits) gives a whole season of results, rest days, starting QBs and consensus lines. `get_team_stats` (5 credits per team-season) gives weekly team lines with EPA. `get_plays` (10 credits per page) gives play-level data when you need your own aggregation.
> For your own CSV: skip the tools, no credits used.

You are an expert in turning football data into model inputs without letting the future into the past. Your goal is a feature table where every row uses only information available before kickoff of that game.

## When to Use

- "What features should I use to predict NFL games?"
- "Build rolling EPA for each team"
- "My model hits 70% against the spread, is that real?"
- "How do I handle the quarterback changing?"
- "How do I use the closing line as a feature?"

## When NOT to Use

- Fitting and tuning a model, evaluating by time, see `walk-forward-validation`
- Checking probabilities, see `probability-calibration`
- Just exploring a team, see `epa-analysis`

## Commands Available

| Command | Feature Use | Credits |
|---------|-------------|---------|
| `get_games` | Target (`result`, `total`), rest, QBs, line, `div_game`, roof, surface | 5 per query |
| `get_team_stats` | Weekly team lines in `weeks[]` (passing EPA, rushing EPA, sacks, penalties, kicking) | 5 per team-season |
| `get_plays` | Play-level EPA, success, CPOE, down, distance, win probability, charting | 10 per page |
| `get_injuries` | Out/doubtful flags by week (2009+) | 2 |
| `get_snap_counts` | Usage and availability | 5 |
| `get_advanced_stats` | Tracking and pressure by week | 5 |
| `get_odds` | Opening line vs closing line, per book (2020+) | 10 per game |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_features` | Build from the calls above |
| `get_power_ratings` | Compute your own Elo from `get_games` results |
| `get_strength_of_schedule` | Derive from opponents' rolling rates |
| `get_travel_distance` | Use `list_teams` for division and your own stadium table |

## The One Rule: Information Cutoff

For a game at week W of season S, a feature may use only games with kickoff earlier than this game's kickoff, in a strictly earlier week. In pandas, sort by team and date, compute the statistic, then `shift(1)`.

```python
g = team_weeks.sort_values(["team", "season", "week"]).copy()
g["epa_l5"] = (g.groupby(["team"])["epa_per_play"]
                .transform(lambda s: s.shift(1).rolling(5, min_periods=3).mean()))
```

Forgetting `shift(1)` includes the game being predicted in its own feature. That is the most common reason a model beats the market in testing and fails in use.

## Feature Families

**1. Team efficiency (rolling).** Offensive and defensive EPA per play, pass and run separately, early-down success rate. Windows of 5 and 10 games plus an expanding season mean. An NFL season has 17 games, so a 10 game window spans over half of it; shrink toward last season or league mean early (see Shrinkage).

**2. Opponent adjustment.** A rolling mean is biased by who the team played. A simple fix: subtract the opponent's rolling defensive EPA allowed relative to league average, or fit a ridge regression of game EPA on offense and defense dummies using only prior games. Adjustment on 5 games is noise; use 8 or more or shr

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

View saved version →

---
name: game-lookup
description: "Finds NFL games, scores, schedules, standings and playoff seeding. Use when user asks who plays this week, what a final score was, a team's record or results, standings, division race, playoff seeds, rest days, starting quarterbacks, or the closing spread of a past game. Do not use for odds shopping across books, see odds-explorer. Do not use for team efficiency, see epa-analysis. Do not use for college games, see college-football."
metadata:
  version: 1.0.0
  author: EndzoneAPI
---

# Game Lookup

> **Default data tool:** EndzoneAPI (`endzoneapi-tool`).
> `get_games` (5 credits) for any past or future game filter. `get_schedule` (2 credits) for what is coming up. `get_standings` (2 credits) for records and seeds.

You are a football data lookup specialist. Your job is to find the right game or table in the fewest credits and return it with the context that makes it usable: week, kickoff, rest, starting QBs, and the closing line.

## When to Use

- "Who plays Sunday?" / "What is the schedule for Buffalo?"
- "What was the score of Chiefs at Raiders in Week 18?"
- "Show me every divisional playoff game since 2020"
- "Who is leading the NFC North, and by what tiebreaker?"
- "How many days of rest did each team have?"

## When NOT to Use

- Comparing prices across sportsbooks, see `odds-explorer`
- Team quality beyond record, see `epa-analysis`
- Matchup preview with form and odds together, see `game-preview`
- FBS or FCS games, see `college-football`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_games` | Filter by `season`, `week`, `team`, `date_from`, `date_to`, `game_type`, `status`, `limit` | 5 |
| `get_schedule` | Unplayed games for the next `days` (default 7), or one `week` of the current season | 2 |
| `get_standings` | Records, points for and against, home and away splits, streak, division and conference rank | 2 |
| `get_game_detail` | One game, everything: team box scores, per-book lines, weather, surface, officials | 10 |
| `list_teams` | Team codes, conference, division | 1 |
| `get_head_to_head` | Meetings between two teams | 10 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_box_score` | `get_game_detail` for team stats, `get_player_stats` for a player's line in that game |
| `get_scoreboard` | `get_games` with `week` and `season` |
| `get_playoff_picture` | `get_standings`, the `conference_rank` is the seed |
| `get_bye_weeks` | `get_schedule` with `week`, the missing team has the bye |

## Season and Week Resolution

- `season` is the year the regular season starts. September 2026 through early February 2027 is season 2026.
- In January and February, the "current" games are the previous calendar year's season. Do not pass the new year.
- Regular season weeks are 1 to 18. Postseason weeks are 19 to 22. `game_type` values: `REG`, `WC` (wild card), `DIV`, `CON`, `SB`, or `POST` for any playoff game.
- Without `season`, `get_games` can return multiple seasons. Always pass one for a bounded cost.

## How It Works

**Step 1: Resolve the team code.** `KC`, `BUF`, `LA` for the Rams (not LAR), `WAS` for Washington. If unsure, call `list_teams` once.

**Step 2: Pick the call.**

| Question | Call |
|----------|------|
| This week's slate | `get_schedule(week=5)` or `get_schedule(days=7)` |
| One team's season results | `get_games(season=2025, team="KC")` |
| All playoff games in a range | `get_games(season=2024, game_type="POST")` |
| Games on a date | `get_games(date_from="2025-12-25", date_to="2025-12-25")` |
| Division race | `get_standings(season=2025, division="AFC West")` |

**Step 3: Read the game row.** Each row from `get_games` carries:

- `result` = home score minus away score. Positive means the home team won.
- `total` = combined points.
- `spread_line` = the consensus closing spread from the home team's side, positive when the home team is favored. `total_line`, `

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

View saved version →

---
name: game-preview
description: "Builds a pre-game preview for one NFL matchup: schedule, form, efficiency, head-to-head, injuries, depth chart, rest, weather and betting lines in one brief. Use when user asks to preview a game, break down a matchup, what to know before Sunday, or who has the edge in a specific game. Do not use for a full model, see feature-engineering. Do not use for price shopping, see odds-explorer. Do not use for college games, see college-football."
metadata:
  version: 1.0.0
  author: EndzoneAPI
---

# Game Preview

> **Default data tool:** EndzoneAPI (`endzoneapi-tool`).
> Budget: about 45 credits for a full preview. A short version (schedule, team EPA for both sides, lines) is about 17.

You are a football analyst writing a preview. Your goal is a one-page brief that says who has the edge, why, how large the market thinks it is, and what could change it.

## When to Use

- "Preview Bills at Chiefs"
- "What should I know about this week's Eagles game?"
- "Who has the advantage in this matchup?"
- "Break down the Sunday night game"

## When NOT to Use

- Building a predictive model, see `feature-engineering` and `walk-forward-validation`
- Only the line, see `odds-explorer`
- Only one team's profile, see `epa-analysis`
- Player-specific questions, see `player-scouting`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_schedule` | Find the game, kickoff, consensus line | 2 |
| `get_team_stats` | Season EPA per play and totals, one team | 5 |
| `get_head_to_head` | Past meetings, record, average margin | 10 |
| `get_injuries` | Status by team | 2 |
| `get_depth_chart` | Starters | 2 |
| `get_game_detail` | Weather, surface, officials, per-book lines | 10 |
| `get_games` | Recent results with starting QBs and rest | 5 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_game_preview` | This skill, assembled from the calls above |
| `get_matchup_rankings` | Compute from two `get_team_stats` calls |
| `get_win_probability_pregame` | The consensus line is the market's estimate, see `odds-analysis` |
| `get_referee_stats` | Not available; `get_game_detail` names the officials only |

## How It Works

**Step 1: Locate the game.** `get_schedule(team="BUF")` returns the next games with `game_id`. For a past game or a specific week, `get_games(season=2025, week=5, team="BUF")`.

**Step 2: Efficiency for both teams.** `get_team_stats(team="BUF", season=2025)` and the same for the opponent: `totals.passing_epa_per_play`, `totals.rushing_epa_per_play`, `yards_per_attempt`, `yards_per_carry`, plus `weeks[]` for trend. Early in a season, use the last season as a prior and say how many 2026 games exist.

**Step 3: Form and context.** `get_games(season=2025, team="BUF", limit=5)` is the last results with `away_rest`, `home_rest`, `away_qb_name`, `home_qb_name`. A team that has changed starting quarterback has a different recent form than its season line.

**Step 4: Availability.** `get_injuries(team="BUF")` and `get_depth_chart(team="BUF", formation="Offense")`. Report only players that change the matchup: the quarterback, top two receivers, the left tackle, the top pass rusher. The injury report is incomplete until the Wednesday to Friday practice reports are in.

**Step 5: History.** `get_head_to_head(team1="BUF", team2="KC", limit=5)`. Head-to-head carries little predictive weight across rosters and coaches; use it for color, never as the argument. Say so.

**Step 6: Market.** The consensus line from the schedule row, then `get_game_detail(game_id=...)` for weather, surface and per-book numbers. Convert the spread into an implied margin and the total into implied team totals:

```
home_implied = (total + spread_line) / 2
away_implied = (total - spread_line) / 2
```

where `spread_line` is positive when home is favored. Check with DEN at KC: total 37.5, `spread_line` -13.5, so KC implied 12.0, DEN implied 25.5. K

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

View saved version →

---
name: next-gen-stats
description: "Reads Next Gen Stats tracking data and Pro Football Reference advanced stats for NFL passers, rushers and receivers: time to throw, air yards, CPOE, rush yards over expected, separation, cushion, yards after catch above expectation, pressures, drops, bad throws. Use when user asks about separation, time to throw, rush yards over expected, pressure rate, drop rate, or why a player's box score does not match how he plays. Do not use for EPA or success rate, see epa-analysis. Do not use for season totals and rankings, see player-scouting. Do not use for college football, which has no tracking data."
metadata:
  version: 1.0.0
  author: EndzoneAPI
---

# Next Gen Stats and Advanced Tracking

> **Default data tool:** EndzoneAPI (`endzoneapi-tool`).
> One tool: `get_advanced_stats` (5 credits per call). Choose a `source`, then filter by `season`, `week`, `player_id`, `team`, `limit`.

You are an expert in player tracking and charting metrics. Your goal is to explain what the box score hides: who creates separation, who holds the ball, who is pressured, and who beats the expected result on a given play.

## When to Use

- "Does this quarterback hold the ball too long?"
- "Which backs gain the most yards over expected?"
- "Who gets open?" / "Who drops passes?"
- "Is his completion percentage lucky?"
- "Which quarterbacks are pressured most?"

## When NOT to Use

- Team efficiency on every play, see `epa-analysis`
- Counting stats and leaderboards, see `player-scouting`
- Anything about college or FCS players, those leagues carry no tracking data, see `college-football`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_advanced_stats` | `source` plus filters, returns `metric_keys` and rows with a `metrics` object | 5 |
| `search_players` | Get the id the source needs | 2 |

## Sources

Verified by live calls (2025 season):

| `source` | From | Id to pass | Rows | `metrics` keys |
|----------|------|-----------|------|----------------|
| `ngs_passing` | 2016 | GSIS (`00-...`) | player-week; `week` 0 is season | attempts, completions, completion_percentage, expected_completion_percentage, completion_percentage_above_expectation, avg_time_to_throw, avg_intended_air_yards, avg_completed_air_yards, avg_air_yards_differential, avg_air_yards_to_sticks, aggressiveness, max_air_distance, passer_rating, pass_yards, pass_touchdowns, interceptions |
| `ngs_rushing` | 2016 | GSIS | player-week | rush_attempts, rush_yards, expected_rush_yards, rush_yards_over_expected, rush_yards_over_expected_per_att, rush_pct_over_expected, efficiency, avg_time_to_los, percent_attempts_gte_eight_defenders, rush_touchdowns |
| `ngs_receiving` | 2016 | GSIS | player-week | targets, receptions, yards, catch_percentage, avg_separation, avg_cushion, avg_intended_air_yards, percent_share_of_intended_air_yards, avg_yac, avg_expected_yac, avg_yac_above_expectation, rec_touchdowns |
| `pfr_passing` | 2018 | PFR id (`MahoPa00`) | player-game | times_pressured, times_pressured_pct, times_hurried, times_hit, times_sacked, times_blitzed, passing_drops, passing_drop_pct, passing_bad_throws, passing_bad_throw_pct |
| `pfr_receiving` | 2018 | PFR | player-game | receiving_drop, receiving_drop_pct, receiving_broken_tackles, receiving_int, receiving_rat |
| `pfr_rushing`, `pfr_defense` | 2018 | PFR | player-game | see `metric_keys` in the response |

The response always lists `metric_keys` and `player_id_kind` (gsis or pfr). Read them rather than guessing. The `pfr_*` rows also carry `game_id`, `opponent`.

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_player_tracking` | `get_advanced_stats` |
| `get_pressure_rate` | `get_advanced_stats` with `source` pfr_passing, `times_pressured_pct` |
| `get_route_data` | Not available; FTN charting flags are in `get_plays` (2022+) |
| `get_coverage_stats` | `get_advanced_stats` with `source` pfr_def

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

View saved version →

---
name: odds-analysis
description: "Converts American odds to implied probability, removes the vig (devigging), computes hold, no-vig fair lines, spread and total price conversions, and key-number value for NFL markets. Use when user asks what a price implies, how much vig a book charges, what the fair line is, how to devig a moneyline or spread, how many points a half-point is worth, or expected value from a price. Do not use for finding the best book, see odds-explorer. Do not use for props, see prop-modeling."
metadata:
  version: 1.0.0
  author: EndzoneAPI
---

# Odds Analysis

> **Default data tool:** EndzoneAPI (`endzoneapi-tool`).
> `get_odds` (10 credits per game) returns each book's prices. Math itself uses no credits. For lines you already have: skip the tool.

You are an expert in odds mathematics. Your goal is to turn prices into probabilities and expected value correctly, state the assumptions behind a devig method, and never present a market price as a fair probability without removing the vig.

## When to Use

- "What probability does -1100 imply?"
- "How much is the book charging?"
- "What is the fair price once vig is removed?"
- "Is half a point worth buying at -120?"
- "What is the break-even win rate at -110?"

## When NOT to Use

- Finding the best price across books, see `odds-explorer`
- Props, see `prop-modeling`

## Commands Available

| Command | Use Here | Credits |
|---------|---------|---------|
| `get_odds` | Per-book prices to devig | 10 per game |
| `get_games` | Consensus close, moneylines for a season | 5 |
| `get_alt_lines` | Priced ladders for point-value analysis | 10 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_implied_probability` | Compute it, the `get_odds` rows include `ml_home_prob` and `ml_away_prob` but those are the raw implied values |
| `get_fair_line` | Devig yourself as below |
| `get_hold` | Compute from the two sides |

The `ml_home_prob` and `ml_away_prob` fields in the real Pinnacle row for the 2025 Week 17 DEN at KC game were 0.1295 and 0.9019. They sum to 1.031, so they still contain the vig. Do not treat them as true probabilities.

## American Odds to Probability

```
if odds < 0:  p = -odds / (-odds + 100)
if odds > 0:  p = 100 / (odds + 100)
```

Worked, from the real Pinnacle moneyline: home +672 -> 100/772 = 0.1295. Away -920 -> 920/1020 = 0.9020. Sum 1.0315, so the hold is 3.15%.

## Devigging a Two-Way Market

Given raw probabilities `a` and `b` with `a + b > 1`:

**Proportional (multiplicative).** `a / (a + b)` and `b / (a + b)`. Simple. It assumes the vig is spread in proportion to probability. For the example: home 0.1295 / 1.0315 = 0.1256, away 0.9020 / 1.0315 = 0.8744.

**Power method.** Find `k` so `a^k + b^k = 1`. Shifts more of the vig off the longshot. Use it when one side is a heavy favorite, because proportional understates the favorite's share of the vig.

**Shin method.** Models insider trading; more complex, sometimes used for very lopsided markets.

Report which method you used. Differences between methods are small near 50/50 and grow with the price gap. For the example, proportional gives the home side 12.56% and the power method (k = 1.094) gives 10.68%, a gap of nearly two points on a +672 price. Compute both and show the range when one side is above -500.

Pinnacle's no-vig probability is the standard benchmark for the true probability, because it takes large bets and runs low hold. Treat it as a good estimate, not truth.

## Spread and Total Prices

Spreads and totals are priced around 50/50 (for example -109 / -102 on a spread, -114 / +101 on a total, both from the real Pinnacle row). Devig the pair the same way: two raw probabilities, divide by their sum. A -110 / -110 market has hold of 4.76%; break-even win rate at -110 is 52.38%.

```
break_even(odds): -odds / (-odds + 100) for negative odds
```

## What a Point Is Worth

In the NFL the final margin lands exactly on certain numb

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

View saved version →

---
name: odds-explorer
description: "Compares NFL spreads, totals and moneylines across sportsbooks, finds the best price, reads opening-to-closing movement, and browses alternate lines. Use when user asks about the line on a game, which book has the best number, how a line moved, Pinnacle versus the consensus, alternate spreads, or key numbers like 3 and 7. Do not use for devigging or implied probability math, see odds-analysis. Do not use for player props, see prop-modeling."
metadata:
  version: 1.0.0
  author: EndzoneAPI
---

# Odds Explorer

> **Default data tool:** EndzoneAPI (`endzoneapi-tool`).
> `get_odds` for one game's lines by book (10 credits). `get_line_movement` for the hourly series (25 credits). `get_alt_lines` for ladders (10 credits). `get_games` already carries the consensus closing line (5 credits per query).

You are an expert in football betting markets. Your goal is to show where the best price is, what the market says, and how it moved, in numbers the user can check.

## When to Use

- "What was the closing line for Denver at Kansas City?"
- "Which book had the best number on the Chiefs?"
- "Did the total move after the injury news?"
- "What does a 6.5 point alternate spread cost?"
- "How often do games land on 3 or 7?"

## When NOT to Use

- Removing vig and converting to probability, see `odds-analysis`
- Player props, see `prop-modeling`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_odds` | `game_id`: consensus close plus each book's opening, closing, latest. Or `season` (and optional `team`): a page of per-book closing lines | 10 per game |
| `get_line_movement` | Hourly snapshots grouped by `bookmaker` for one `game_id` | 25 |
| `get_alt_lines` | Alternate spread and total ladders, 2023 to 2025, 6 books | 10 |
| `get_games` | Consensus closing spread, total, moneylines for many games | 5 |
| `get_schedule` | Upcoming games with consensus lines where posted | 2 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_best_line` | Pull `get_odds`, compare the books yourself |
| `get_public_betting` | Not available. Infer nothing about bet percentages from line moves alone |
| `get_live_odds` | `get_odds` latest snapshot; not an in-game feed |
| `get_futures` | Not available |

## Data Coverage

- Consensus closing spread and total: every game since 1999. Moneyline since 2010.
- Per-book closing: 2014 onward (ESPN source, 4 to 9 books through 2019, closing only).
- Opening, closing and latest per book: 2020 onward from The Odds API, up to 8 books including Pinnacle. Each line carries its `source`.
- Books: draftkings, fanduel, betmgm, espnbet, pinnacle, bovada, betonlineag, mybookieag.
- Alternate ladders: one game at a time, 2023 to 2025 seasons.
- Hourly snapshots in season begin 2026. Earlier games have opening and closing only.

## Sign Conventions (the first bug everyone ships)

Two conventions meet in this API. Real example, 2025 Week 17 DEN at KC, where Denver was the favorite:

| Where | Field | Value | Meaning |
|-------|-------|-------|---------|
| `get_games`, `consensus_closing` | `spread_line` | -13.5 | Home-side number: negative means the away team is favored |
| Pinnacle book object | `spread_home` | 13.5 | Book convention: the home team gets +13.5 |
| Pinnacle book object | `spread_away` | -13.5 | Away team lays 13.5 |

Rule: `spread_line` is positive when home is favored. `spread_home` is negative when home is favored. They are negatives of each other. Convert before you compare.

Home covers if `result > spread_line` where `result` is home score minus away score. In the example, KC lost 13 to 20, `result` = -7, which is greater than -13.5, so KC covered.

## How It Works

**Step 1: Get the game id.** From `get_games` or `get_schedule`. Format `2025_17_DEN_KC`.

**Step 2: Pull the book lines.** `get_odds(game_id="2025_17_DEN_KC")`. Add `bookmaker="pinnacle"` to narrow. Real shape

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

View saved version →

---
name: player-scouting
description: "Searches NFL players and builds scouting profiles from weekly stats, season totals, leaderboards, snap counts, injuries and depth charts. Use when user asks about a specific player, compares players, wants leaders in a stat, asks about target share, usage, snap share, or a player's weekly game log. Do not use for tracking metrics like separation or time to throw, see next-gen-stats. Do not use for prop lines, see prop-modeling. Do not use for college players, see college-football."
metadata:
  version: 1.0.0
  author: EndzoneAPI
---

# Player Scouting

> **Default data tool:** EndzoneAPI (`endzoneapi-tool`).
> `search_players` (2 credits) first, always. Then `get_player_stats` (5) for a profile or `get_player_leaders` (5) for a ranking.

You are a football scout. Your job is to turn a name into an id, then into a profile that separates role from efficiency from luck.

## When to Use

- "How is Drake Maye playing?" / "Compare two receivers"
- "Who leads the league in receiving EPA?"
- "Is this running back's workload sustainable?"
- "Show me a player's game log for 2025"
- "Who is the starter on KC's depth chart?"

## When NOT to Use

- Separation, time to throw, rush yards over expected, see `next-gen-stats`
- Will he go over his yardage line, see `prop-modeling`
- Team-level efficiency, see `epa-analysis`
- FBS or FCS players, see `college-football`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `search_players` | Partial name match; returns GSIS id, PFR id, team, position, college | 2 |
| `get_player_stats` | Bio, draft, summed season totals, every weekly line, games played per season | 5 |
| `get_player_leaders` | Rank by any weekly stat; `position`, `team`, `min_games`, `limit` filters | 5 |
| `get_snap_counts` | Offense, defense, special teams snaps and shares | 5 |
| `get_depth_chart` | Depth rank by position for a week | 2 |
| `get_injuries` | Status and practice participation | 2 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_player_comparison` | Two `get_player_stats` calls, compare in your own table |
| `get_player_projection` | Not available, see `prop-modeling` for a method |
| `get_player_game_log` | `get_player_stats`, the weekly lines are in the response |
| `get_rookie_class` | `get_player_leaders` filtered by `position`, check `rookie_season` from `search_players` |
| `get_contract` | Not available |

## How It Works

**Step 1: Find the id.** `search_players(query="Mahomes")` returns the GSIS id (`00-0033873`), `pfr_id`, `team`, `position`, `college`, `rookie_season`, `last_season`. The search covers about 25,000 players back to 1999. Current-season players come first; if none match, it falls back to everyone and says so. Pass `active=false` to search everyone outright. Two players with the same surname: add `team` or `position`.

**Step 2: Profile.** `get_player_stats(player_id="00-0033873", season=2025)` returns season totals across passing, rushing, receiving, defense, kicking, returns and fantasy points, plus a weekly line for every game. Use the weekly lines to spot trends, the totals for the summary.

**Step 3: Rank in context.** `get_player_leaders(stat="receiving_epa", season=2025, position="WR", min_games=8, limit=20)`. Counting stats are summed, rate stats are averaged. Confirmed stat names include `passing_yards`, `passing_tds`, `rushing_yards`, `receiving_yards`, `receptions`, `targets`, `def_sacks`, `def_interceptions`, `fantasy_points_ppr`, `passing_epa`, `rushing_epa`, `receiving_epa`; about 130 more exist. If a name is rejected, pull one `get_player_stats` weekly line and copy a column name.

Real response shape: `data.leaders[]` = `{rank, player_id, name, position, team, games, value}`. In the 2025 regular season, `passing_epa` summed, QBs with 8+ games: Drake Maye first at 166.2, Matthew Stafford second at 150.5, both in 17 games.

**Step 4: Sepa

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

View saved version →

---
name: probability-calibration
description: "Checks and repairs predicted probabilities for NFL outcomes: reliability tables, Brier score, log loss, expected calibration error, Platt scaling, isotonic regression, and sample-size limits. Use when user asks if a model's 65% means 65%, how to calibrate, Brier score, log loss, why a model is overconfident. Do not use for building the model, see feature-engineering. Do not use for time-ordered testing, see walk-forward-validation. Do not use for turning odds into probability, see odds-analysis."
metadata:
  version: 1.0.0
  author: EndzoneAPI
---

# Probability Calibration

> **Default data tool:** EndzoneAPI (`endzoneapi-tool`) for outcomes only: `get_games` (5 credits) returns `result`, `spread_line`, `total`, `total_line` for scoring predictions. Calibration itself is local code.
> For your own predictions CSV: no credits used.

You are an expert in probabilistic forecast quality. Your goal is to check that a stated probability matches the observed frequency, and to fix it only when the evidence supports a fix.

## When to Use

- "My model says 70% for the home team, is that right?"
- "Is my model overconfident?"
- "Compute Brier score and log loss"
- "Should I use Platt scaling or isotonic?"
- "Are my cover probabilities good enough to size bets?"

## When NOT to Use

- Constructing inputs, see `feature-engineering`
- Choosing training windows, see `walk-forward-validation`
- Devigging market odds, see `odds-analysis`

## Commands Available

| Command | Use Here | Credits |
|---------|---------|---------|
| `get_games` | Realized outcomes and consensus lines for scoring | 5 per query |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_calibration` | Compute from your predictions and `get_games` outcomes |
| `get_model_probabilities` | Not provided; bring your own |

## Metrics

For predictions `p_i` in [0, 1] and outcomes `y_i` in {0, 1}:

```
Brier    = mean((p - y)^2)
LogLoss  = -mean(y * ln(p) + (1 - y) * ln(1 - p))
```

Reference points for a binary game outcome at 50/50 forecasts: Brier 0.25, log loss 0.693. A forecast has to beat those, then beat the market's own probabilities (see `odds-analysis`) on the same games.

**Reliability table.** Bin predictions (10 equal-count bins are better than 10 equal-width bins with small samples), then compare mean prediction to observed frequency per bin.

```python
df["bin"] = pd.qcut(df.p, 10, duplicates="drop")
rel = df.groupby("bin").agg(pred=("p", "mean"), obs=("y", "mean"), n=("y", "size"))
```

**Expected calibration error:** `sum(n_bin / N * |obs - pred|)`. Report with a bootstrap interval; with a few hundred games the interval is wide.

## Reading the Table

| Pattern | Meaning | Fix |
|---------|---------|-----|
| Predictions spread wider than outcomes (80% bin hits 68%) | Overconfident | Shrink toward the base rate, Platt scaling |
| Predictions narrower than outcomes | Underconfident | Rare; sharpen with Platt slope above 1 |
| Good in the middle, bad at the tails | Few tail samples | Do not fix tails with a flexible method on tiny n |
| Systematic offset (home always 3 points too high) | Bias | Intercept in Platt scaling |

## The Sample-Size Problem in Football

An NFL season has 272 regular season games. In 10 bins, that is about 27 games a bin per season. The standard error of an observed frequency near 0.5 at n = 27 is about 0.10. A bin at 0.60 predicted and 0.50 observed is inside the noise. Pool several seasons, use fewer bins (5), and show intervals. Do not conclude miscalibration from one season of one bin.

## Repairs

**Platt scaling (default).** Fit a logistic regression of outcome on the logit of your prediction:

```python
from sklearn.linear_model import LogisticRegression
z = np.log(p / (1 - p)).reshape(-1, 1)
cal = LogisticRegression(C=1e6).fit(z, y)      # two parameters: slope and intercept
p_cal = cal.predict_proba(z)[:, 1]
```

Two parameters, stabl

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

View saved version →

---
name: prop-modeling
description: "Builds NFL player prop models for passing yards, passing touchdowns, rushing yards, receiving yards, receptions and anytime touchdown, using prop history, usage, snap share, game script from the spread and total, and injuries. Use when user asks about player props, whether a player goes over a yardage line, prop projections, anytime TD odds, or the historical over rate against a line. Do not use for team game prediction, see feature-engineering. Do not use for browsing odds across books for a game side, see odds-explorer. Do not use for player profiles without a line, see player-scouting."
metadata:
  version: 1.0.0
  author: EndzoneAPI
---

# Prop Modeling

> **Default data tool:** EndzoneAPI (`endzoneapi-tool`).
> `get_player_props` (10 credits) for lines, `get_prop_history` (10 credits for up to 200 games) for how a player did against his line, `get_snap_counts` and `get_player_stats` (5 credits each) for usage, `get_games` (5 credits) for the game environment.
> Props coverage starts in the 2023 season. Samples are small by nature.

You are an expert in player prop modeling. Your goal is to project a player's stat for one game as a distribution, compare it with the book's line and price, and be honest about how little data a single player-season gives you.

## When to Use

- "Will Mahomes go over 250.5 passing yards?"
- "What has this receiver done against his line this year?"
- "Project a running back's yardage"
- "What is the fair price on an anytime touchdown?"
- "Which book has the best number on this prop?"

## When NOT to Use

- Which team wins, see `feature-engineering`
- A team's spread price, see `odds-explorer`
- General scouting, see `player-scouting`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_player_props` | Props by book. `game_id` for all players in a game, or `player_id` plus `season`. `market`, `bookmaker`, `snapshot_type` (closing or opening), `estimate_only` | 10 per game returned |
| `get_prop_history` | One player and market: a row per game with `line`, `open_line`, prices, `actual`, `result`, `margin`, plus an over-rate summary. `from_date`, `to_date`, `bookmaker`, `limit` | 10 for up to 200 games |
| `get_snap_counts` | Snaps and shares by game, `player_id` (PFR id), or `team` and `season` | 5 |
| `get_player_stats` | Weekly lines for the season | 5 |
| `get_injuries`, `get_depth_chart` | Availability and role | 2 each |
| `get_games` | Spread and total for the game environment | 5 |
| `get_advanced_stats` | Tracking and charting context | 5 |
| `search_players` | The ids (GSIS for props and stats, PFR for snaps) | 2 |

## Markets

`get_player_props` markets: `player_pass_yds`, `player_pass_tds`, `player_rush_yds`, `player_reception_yds`, `player_receptions`, `player_anytime_td` (over means he scores).
`get_prop_history` adds `player_pass_completions`, `player_pass_attempts`, `player_pass_interceptions`, `player_rush_attempts`.
Books on props: DraftKings, FanDuel, BetMGM, ESPN BET, Pinnacle, Bovada, BetOnline.

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_player_projection` | Build it as below |
| `get_dfs_projections` | Not provided |
| `get_prop_edges` | Compute edge from your distribution and the line |
| Props before 2023 | Not covered |

## Real Data Shapes

`get_prop_history(player_id="00-0033873", market="player_pass_yds", from_date="2025-09-01", limit=3)` (Mahomes) returned:

| game | line | open | over | under | books | actual | result | margin |
|------|------|------|------|-------|-------|--------|--------|--------|
| 2025_01_KC_LAC | 250.5 | 244.5 | -120 | -110 | 7 | 258 | over | +7.5 |
| 2025_02_PHI_KC | 245.5 | 245.5 | -110 | -121 | 7 | 187 | under | -58.5 |

with `summary` = overs 1, unders 2 of 3 graded, `over_rate` 0.333, `avg_line` 243.5, `avg_actual` 223, and `next_from_date` to continue. Three games is an illustration, not a sign

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

View saved version →

---
name: walk-forward-validation
description: "Evaluates sports models in time order: expanding or rolling windows, season-by-season holdouts, bye weeks and season rollover, baselines, and significance. Use when user asks how to validate an NFL model, whether k-fold is acceptable, why backtest results look too good, how many seasons to train on, or how to compare a model to the closing line. Do not use for building features, see feature-engineering. Do not use for probability checks, see probability-calibration."
metadata:
  version: 1.0.0
  author: EndzoneAPI
---

# Walk-Forward Validation

> **Default data tool:** EndzoneAPI (`endzoneapi-tool`).
> Data is the same as `feature-engineering`: `get_games` (5 credits per query) for seasons of results and consensus lines. Validation itself uses no credits.

You are an expert in evaluating predictive models on time-ordered data. Your goal is to estimate how a model would have done if used live, and to refuse any evaluation that lets the future inform the past.

## When to Use

- "How do I test my NFL model?"
- "Can I use cross-validation?"
- "My model has 58% against the spread in testing"
- "How many seasons should I train on?"
- "Does my model beat the closing line?"

## When NOT to Use

- Constructing inputs, see `feature-engineering`
- Checking if 70% means 70%, see `probability-calibration`

## Commands Available

| Command | Use Here | Credits |
|---------|---------|---------|
| `get_games` | Season results, scores, consensus lines for the test and baseline | 5 per query |
| `get_standings` | Sanity check of season records | 2 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_train_test_split` | Do it in your own code by season and week |
| `get_model_predictions` | Not provided; bring your own |
| `get_closing_line` | `get_games` consensus close |

## Why Random Splits Fail

Random k-fold puts week 12 games in the training set for a week 5 test game. Team strength is persistent, so the model learns the team from the future. In football, a coach, quarterback or scheme carries across weeks. Results from random splits are optimistic and the amount is not predictable. Walk-forward only.

## The Procedure

1. Sort games by kickoff time.
2. Choose an initial training window and a step. For NFL, the natural step is one week (retrain weekly) or one season (retrain yearly).
3. For each step: fit on data strictly before the step, predict the step, store predictions.
4. Concatenate predictions. Evaluate once, on the stitched out-of-sample set.

```python
def walk_forward(df, first_test_season, step="week"):
    preds = []
    for (season, week), test in df[df.season >= first_test_season].groupby(["season", "week"]):
        train = df[(df.season < season) | ((df.season == season) & (df.week < week))]
        model = fit(train)                 # features already shift(1)-safe
        test = test.assign(pred=model.predict(test))
        preds.append(test)
    return pd.concat(preds)
```

Fit hyperparameters inside the training window (nested), not on the final test set. Choosing the best of 20 settings on the test seasons and reporting that score is a leak.

## Football Specifics

**Season rollover.** Rosters, coaches and quarterbacks change. The first weeks of a season rely on priors; evaluate weeks 1 to 4 separately from weeks 5 to 18. A model that is strong only late hides an early-season problem.

**17-game seasons.** A season has about 272 regular season games, plus about 13 postseason games. Test over several seasons. One season of 272 games has a standard error on a hit rate near 3 percentage points (sqrt(0.25 / 272) is about 3.0 points). A 55% result on one season is within noise of 50%.

**Window choice.** Expanding window (all past data) is stable. Rolling window (last N seasons) adapts to rule changes: kickoff rules, passing-friendly officiating, and so on. Compare both by walk-forward error.

**Bye weeks and short weeks.*

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