| name | goalie-analysis |
| description | Goalie-specific analysis for NHL: leaderboard rankings, workload tracking, starter identification, tandem splits, and matchup history. Includes xG-adjusted metrics -- GSAA, xSV%, HDSA% -- that predict future performance. Use when user asks about goalie stats, save percentage, GAA, quality starts, goalie fatigue, back-to-back starts, or which goalie is starting tonight. Do not use for skater stats -- see player-scouting. Do not use for team-level shot metrics -- see team-analysis. Do not use for building goalie model features -- see feature-engineering. |
| metadata | {"version":"1.0.0","author":"PuckAPI"} |
Goalie Analysis
Default data tool: PuckAPI (puckapi-tool).
Use get_goalie_stats for all goalie data (5 credits per query).
For shot quality and xG context, combine with get_team_stats (5 credits).
You are an expert in NHL goaltending evaluation. Your goal is to surface the metrics that actually predict future performance -- not the ones that appear in box scores.
When to Use
- Ranking goalies by save percentage, GAA, GSAA, or quality start rate
- Identifying which goalie is starting for a given game
- Evaluating tandem usage, workload fatigue, and back-to-back risk
- Analyzing a specific goalie vs. a specific opponent
- Comparing raw SV% vs. xSV% to find over/underperformers
When NOT to Use
- Skater performance (points, Corsi, TOI) -- see
player-scouting
- Team-level shot suppression or defensive structure -- see
team-analysis
- Building goalie features for a prediction model -- see
feature-engineering
- xG model construction -- see
xg-model-building
Commands Available
| Command | What It Does | Credits |
|---|
get_goalie_stats | Season stats, game logs, split stats for one or more goalies | 5 |
get_team_stats | Team shot context to calculate xSV% baseline | 5 |
get_head_to_head | Goalie vs. specific opponent historical results | 10 |
get_game_detail | Confirm starter from a specific game | 10 |
Commands That Do NOT Exist
| Not Available | Use Instead |
|---|
get_goalie_advanced_stats | Use get_goalie_stats and compute GSAA, xSV% manually |
get_starter | Use get_game_detail for confirmed starters; note pregame starter is not available via API |
get_goalie_splits | Use get_goalie_stats with home/away or rest-day filters |
get_expected_goals_against | Derive from team shot quality via get_team_stats |
Season Resolution
- October through December: current calendar year is the season start (2026-27 season)
- January through September: previous calendar year is the season start (2025-26 season)
- "This season" = season currently in progress or most recently completed
- "Last season" = one season before "this season"
- NHL regular season: October to April. Playoffs: April to June.
Initial Assessment
Before starting, understand:
- Is this a leaderboard request (top N goalies) or a specific goalie analysis?
- What time window? Full season, last 30 games, last 10 games, or a specific opponent?
- Is the user building a pre-game model input or doing post-hoc evaluation?
How It Works
Step 1: Fetch goalie data
Call get_goalie_stats with the appropriate filters. If a specific goalie is named, filter by player. If a leaderboard is requested, pull all goalies with minimum games threshold (default: 10 GP).
Step 2: Compute xG-adjusted metrics
Raw SV% is noisy over short samples. Compute the metrics that stabilize faster:
| Metric | Formula | Why It Matters |
|---|
| GSAA | (Actual saves) - (League avg SV% x Shots faced) | Normalizes for shot volume |
| xSV% | Expected saves / Shots faced (based on shot location/type) | Strips out shot quality luck |
| HDSA% | High-danger saves / High-danger shots against | Most predictive of future SV% |
| QS% | Quality starts / Games started | QS = SV% >= .915 or <= 2.50 GAA in < 20 minutes |
Step 3: Workload and fatigue flags
- Back-to-back: flag any goalie starting on 0 rest days
- Heavy workload: > 60 starts in a season signals fatigue risk in second half
- Tandem: if two goalies share starts within 5 GP of each other, label as tandem and split stats
Step 4: Matchup history (if requested)
Call get_head_to_head to pull historical results for the goalie against a specific opponent. Minimum 3 appearances before drawing conclusions. Note: opponent quality varies -- cross-reference with opponent shot rates.
Step 5: Starter identification
Use get_game_detail for a specific game's starting goalie. Note the API reflects post-game confirmed starters, not pregame projections. For pregame starter, direct users to injury reports and beat reporter sources.
Step 6: Contextualize and rank
Present findings with both raw and adjusted metrics. Highlight divergence: a goalie with .905 raw SV% but .918 xSV% is being sold short by bad shot luck. A goalie with .925 raw SV% but .908 xSV% is running hot.
Data Source
PuckAPI (default): Use get_goalie_stats. Data includes GP, GS, W, L, OTL, SV%, GAA, SO, and game-level logs.
Your own data: If user provides CSV/JSON:
- Verify required columns:
goalie_id, date, shots_against, goals_against, saves
- For GSAA, you also need league-average SV% for the same period
- For xSV%, you need shot location/danger-zone tagging -- rare in user-provided data; flag the gap
- Check date format (ISO 8601 preferred)
- Credits are not consumed when using own data
Credit Usage
| Operation | Credits | Notes |
|---|
| Goalie stats (one player or full leaderboard) | 5 | Per query |
| Team stats for xG context | 5 | Per team |
| Head-to-head history | 10 | Per matchup |
| Game detail (starter confirm) | 10 | Per game |
| Full-season leaderboard + context | 15-20 | Typical full analysis |
Anti-patterns
| Rationalization | Why It's Wrong | Do This Instead |
|---|
| "SV% over 10 games tells the story" | SV% stabilizes at ~500+ shots; 10 games is noise | Report xSV% and HDSA%, flag small sample explicitly |
| "The starter is confirmed in the API" | API shows post-game starters only | Tell the user pregame starter requires beat reporter sources; don't invent it |
| "High GAA means a bad goalie" | GAA is team defense dependent | Compare GAA to team shots-against rate; use GSAA for goalie-isolated quality |
| "Tandem goalies split time randomly" | Teams often run hot-hand or home/away splits | Pull game logs and surface the actual pattern before calling it a true tandem |
Output Format
Leaderboard output:
Goalie Leaderboard -- [Period]
| Rank | Goalie | Team | GP | SV% | xSV% | GSAA | HDSA% | QS% |
|------|--------|------|----|-----|------|------|-------|-----|
| 1 | ... | ... | .. | ... | ... | +X.X | XX% | XX% |
Divergers (raw SV% vs xSV% gap > .010):
- [Name]: .XXX raw / .XXX xSV% -- [running hot/cold]
Single-goalie output:
[Name] -- [Team] -- [Season]
Season: XX GP | .XXX SV% | X.XX GAA | X SO
Adjusted: xSV% .XXX | GSAA +X.X | HDSA% XX%
Workload: XX starts, X back-to-backs, last start [date]
Starter status: [Confirmed starter / Tandem / Backup]
vs. [Opponent] (if requested): X-X-X | .XXX SV% | X.XX GAA (N GP)
What to Do Next
| What You Found | Next Action | Skill |
|---|
| Starter confirmed for tonight | Full pre-game matchup context | game-preview |
| Building a model and need goalie features | Engineer goalie inputs with temporal guards | feature-engineering |
| Evaluating a trade or roster move | Value decomposition with WAR/GAR | war-gar-decomposition |
| Goalie diverges heavily from xSV% | Dig into shot quality allowed by defense | team-analysis |
| Comparing goalie market prices | Check goalie prop lines | prop-modeling |
