| name | team-analysis |
| description | Evaluates teams via standings, stats, division/conference rankings, season trends, and strength of schedule. Use when user asks how a team is doing, where they stand in the division, what their record is, how they compare to other teams, or wants to understand conference/playoff positioning. Do not use for individual player stats -- see player-scouting. Do not use for goalie performance -- see goalie-analysis. Do not use for building model features from team stats -- see feature-engineering. |
| metadata | {"version":"1.0.0","author":"PuckAPI"} |
Team Analysis
Default data tool: PuckAPI (puckapi-tool).
Use get_standings for current standings and playoff positioning (2 credits), get_team_stats for offensive/defensive metrics (5 credits), list_teams to resolve team names and IDs (1 credit).
For user's own team data CSV, skip the tool and work with the file directly.
You are an expert at evaluating teams in context -- standings, performance metrics, schedule difficulty, and trend interpretation. Your goal is to give the user a clear picture of where a team stands and why.
When to Use
- "How are the [team] doing this season?"
- "Where do the [team] stand in the [division/conference]?"
- "What's [team]'s record?"
- "Who's leading the [division/conference]?"
- "How does [team A] compare to [team B]?"
- "What's [team]'s goals-for / goals-against this season?"
- "Which teams are in a playoff spot right now?"
- "How hard has [team]'s schedule been?"
When NOT to Use
- Individual player stats or performance -- see
player-scouting
- Goalie save percentage or goals-against average -- see
goalie-analysis
- Building model features from team stats -- see
feature-engineering
- Predicting a specific game outcome -- see
game-preview
Commands Available
| Command | What It Does | Credits |
|---|
get_standings | Current standings by division and conference, includes points, record, pointPct, goalDiff, corsiPct, fenwickPct | 2 |
get_team_stats | Team-level offensive and defensive stats for a season | 5 |
list_teams | All teams with IDs, cities, names -- use to resolve team identity | 1 |
Commands That Do NOT Exist
| Not Available | Use Instead |
|---|
get_power_rankings | Derive from get_standings + get_team_stats |
get_sos (strength of schedule) | Compute from opponents' standings records manually |
get_team_advanced_stats | Use get_team_stats and compute advanced metrics (Corsi, Fenwick, PDO) |
get_team_trends | Pull get_team_stats for multiple date ranges and compare |
get_playoff_odds | Not available; derive from standings + games remaining |
get_conference_standings | Use get_standings filtered by conference |
Season Resolution
- October through December: current calendar year is the season start (2025-26 season)
- January through September: previous calendar year is the season start (2025-26 season, referenced as 2025)
- "This season" = season currently in progress or most recently completed
- "Last season" = one full season prior
- NHL regular season: October to April. Playoffs: April to June.
- Standings mid-season reflect games played to date, not projected final standings
Initial Assessment
Before querying, understand:
- Single team or comparison? One team snapshot vs. comparing multiple teams vs. full division/conference view.
- What metric matters? Points/record, goals for/against, special teams, head-to-head within division?
- What season? This season, last season, or multi-year trend?
How It Works
Step 1: Resolve the team(s)
If the team name is ambiguous (e.g., "the Leafs" vs. "Toronto"), use list_teams to confirm ID before pulling stats. This costs 1 credit (cheapest endpoint) and prevents silent wrong results.
Step 2: Choose the right query
| User want | Tool | What to pull |
|---|
| Current standing / record | get_standings | Points, GP, W-L-OT, pointPct, goalDiff, conference rank |
| Offensive/defensive stats | get_team_stats | GF/G, GA/G, goalDiff, corsiPct, fenwickPct, xGF, xGA |
| Division or conference view | get_standings | All teams in division/conference |
| Team comparison | get_team_stats for each | Side-by-side stat table |
Step 3: Read standings correctly
NHL standings require specific interpretation. Always apply these rules:
Points (PTS): Primary sort. 2 points for a win (including OT/SO), 1 point for an OT/SO loss.
Points percentage (pointPct): GP-adjusted metric. Use this for cross-team comparisons when teams have played different numbers of games. pointPct = PTS / (GP * 2).
Goal differential (goalDiff): Goals for minus goals against. A quick proxy for team quality beyond record.
Note: ROW (regulation + overtime wins) is used as a tiebreaker in official NHL standings but is not returned by the PuckAPI API. Use wins and pointPct for comparisons.
Playoff cut line: NHL top 3 in each division qualify automatically; wildcard spots go to next 2 best records per conference regardless of division. A team can be 4th in their division but still make playoffs via wildcard.
Step 4: Compute simple SOS (optional)
If the user asks about schedule difficulty:
- Pull opponents' current points percentage (P%) using
get_standings
- Average opponents' P% = raw SOS estimate
- Note: past SOS and future SOS can diverge significantly mid-season
Step 5: Identify trends
For trend questions ("they've been hot lately"), pull get_team_stats for two windows -- full season and last N games -- and compare goalsForPerGame, goalsAgainstPerGame, corsiPct, and fenwickPct. Flag meaningful divergence.
Data Source
PuckAPI (default): Use puckapi-tool endpoints above.
Your own data: If user provides standings or stats CSV:
- Verify required columns:
team, gp, wins, losses, ot_losses, points for standings; gf, ga for stats
- Compute derived metrics yourself: P% = PTS / (GP*2), GF/G = GF/GP
- Compute derived metrics: goalDiff = GF - GA, pointPct = PTS / (GP * 2)
- Credits are not consumed when working with user's own data
Credit Usage
| Operation | Credits | Notes |
|---|
| Full standings (one call) | 2 | All teams, all divisions |
| Team stats (one team, one season) | 5 | Per query |
| Team list / ID resolution | 1 | One-time cost per session |
| Two-team comparison | 10 | One get_team_stats call per team |
| Full division comparison (8 teams) | 40 | One call per team for stats |
Cost note: Standings are 2 credits for the full league snapshot. Pull stats per-team only when needed -- don't pull all 32 teams if the user wants one division.
Anti-patterns
| Rationalization | Why It's Wrong | Do This Instead |
|---|
| "Points are enough to compare teams" | Teams may have played different numbers of games mid-season | Use P% (points percentage) for fair comparison |
| "Wins = wins, goal diff is a detail" | Goal differential and points percentage reveal team quality beyond win-loss record | Always report goalDiff and pointPct alongside points for standings questions |
| "I'll pull team stats and derive standings" | Stats don't include standings context (division rank, wildcard position) | Pull get_standings directly; don't reconstruct what the API provides |
| "The team is 8th -- they missed the playoffs" | NHL has wildcard; 4th-in-division can still qualify | Always check conference-wide wildcard standings before calling a team eliminated |
| "SOS is too complex, I'll skip it" | Schedule difficulty materially affects record interpretation | At minimum, note whether the team has played an above/below average schedule |
Output Format
Single team snapshot
[Team] -- [Season]
Record: [W-L-OT] | Points: [N] (pointPct: .XXX) | Goal Diff: [+/-N]
Division rank: [N]th in [Division] | Conference rank: [N]th in [Conference]
Playoff position: [In/Out/On bubble -- wildcard [N]]
Offense: [GF/G] goals/game ([Rank]th in league) | xGF: [N]
Defense: [GA/G] goals allowed/game ([Rank]th in league) | xGA: [N]
Corsi%: [N]% | Fenwick%: [N]%
Division standings table
[Division] Standings -- [Date]
Rank | Team | GP | W | L | OT | PTS | P% | Goal Diff
1. | ...
...
-- Playoff line --
4. | ...
Team comparison
[Team A] [Team B]
Record W-L-OT W-L-OT
Points N (P%) N (P%)
Goal Diff +/-N +/-N
GF/G N N
GA/G N N
Corsi% N% N%
Fenwick% N% N%
xGF N N
xGA N N
What to Do Next
| What You Found | Next Action | Skill |
|---|
| Team looks interesting, want to preview their next game | Pull matchup context, odds, trends | game-preview |
| Want to build model features from team stats | Encode GF/G, GA/G, SOS as features | feature-engineering |
| Want to know key players driving the stats | Break down by player | player-scouting |
| Want goalie stats contributing to GA/G | Goalie-specific analysis | goalie-analysis |
| Team has a favorable schedule ahead, want to find betting edges | Compare model vs market | edge-detection |
