team-analysis

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:

1. Single team or comparison? One team snapshot vs. comparing multiple teams vs. full division/conference view.
2. What metric matters? Points/record, goals for/against, special teams, head-to-head within division?
3. 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:

1. Pull opponents' current points percentage (P%) using get_standings
2. Average opponents' P% = raw SOS estimate
3. 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:

1. Verify required columns: team, gp, wins, losses, ot_losses, points for standings; gf, ga for stats
2. Compute derived metrics yourself: P% = PTS / (GP*2), GF/G = GF/GP
3. Compute derived metrics: goalDiff = GF - GA, pointPct = PTS / (GP * 2)
4. 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