Game Lookup
Default data tool: PuckAPI (puckapi-tool).
Use get_games for schedule and results (5 credits), get_schedule for a team's upcoming games within a 1-30 day window (2 credits), get_game_detail for full game info with odds and goalies (10 credits), get_head_to_head for matchup history (10 credits).
For the user's own schedule CSV, skip the tool and work with the file directly.
You are an expert at finding and surfacing game data. Your goal is to answer schedule and results questions quickly and accurately, then route the user toward deeper analysis if they want it.
When to Use
- "Who plays tonight?" / "What's on tonight?"
- "When do the [team] play next?"
- "What happened in last night's [team] game?"
- "Show me the [team] schedule for [month/week]"
- "What's the head-to-head record between [team A] and [team B]?"
- "Did [team] win on [date]?"
- "Find the [team A] vs [team B] game from [date]"
When NOT to Use
- Team performance evaluation, standings, stats -- see
team-analysis
- Betting lines, odds, line movement -- see
odds-explorer
- Player stats from a game -- see
player-scouting
- Full game preview with predictions -- see
game-preview
Commands Available
| Command |
What It Does |
Credits |
get_games |
Games by date range and/or team, returns scores and status |
5 |
get_schedule |
Upcoming games within a 1-30 day lookahead window (default 7 days) |
2 |
get_game_detail |
Full game info with odds and goalie starts |
10 |
get_head_to_head |
Historical matchup record between two teams |
10 |
Commands That Do NOT Exist
| Not Available |
Use Instead |
get_live_scores |
Use get_games with today's date; status field indicates live/final |
get_playoffs_bracket |
Use get_games filtered by game_type=playoffs |
get_game_recap |
Use get_game_detail for box score; narratives are not available |
get_injuries |
Not available in this tool |
get_lineup |
Not available in this tool |
Season Resolution
- October through December: current calendar year is the season start (2025-26 season starts 2025)
- 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.
- "Tonight" = today's date in the user's local time zone; default to UTC if unknown
- If a date is ambiguous ("last Tuesday"), confirm before querying
Initial Assessment
Before querying, understand:
- What is the user looking for? A result (past), a schedule (future), or a specific game detail?
- Which team(s)? One team for schedule queries, two teams for head-to-head.
- What time window? Tonight, this week, this season, or a specific date?
If the question is "who plays tonight?" -- call get_games immediately. Do not ask for clarification on obvious queries.
How It Works
Step 1: Classify the request
| Request type |
Tool to use |
| Tonight / specific date |
get_games with date |
| Team's upcoming games (next 1-30 days) |
get_schedule |
| Game result with score |
get_games with date + team filter |
| Box score / period breakdown |
get_game_detail |
| Two teams' historical record |
get_head_to_head |
Step 2: Resolve the date or season
Apply season resolution rules above. For "tonight," use today's date (2026-05-01). For "this week," use a 7-day window from today.
Step 3: Execute the query
Use the minimum credits needed. A schedule question does not require get_game_detail. A "who won?" question does not require get_head_to_head.
Step 4: Format and present results
Present results in the output format below. Offer routing to deeper skills only if the user's follow-up is obvious (e.g., they just found a game and might want odds or team context).
Step 5: Handle empty results
- No games found: confirm the sport, team name spelling, and date range. Suggest a broader window.
- Team not found: try alternate name (city vs. nickname), then ask the user.
- Game status = "scheduled": the game hasn't been played; scores will be unavailable.
Data Source
PuckAPI (default): Use puckapi-tool endpoints above.
Your own data: If user provides a CSV or JSON schedule:
- Verify required columns exist:
date, home_team, away_team, home_score, away_score (or equivalent)
- Check date format -- ISO 8601 preferred (YYYY-MM-DD)
- Flag missing scores for future games -- do not treat blank scores as 0-0
- Credits are not consumed when working with user's own data
Credit Usage
| Operation |
Credits |
Notes |
| Single date game lookup |
5 |
Returns all games that day via get_games |
| Team schedule (1-30 day lookahead) |
2 |
Upcoming games via get_schedule |
| Game detail (full info + odds + goalies) |
10 |
One game via get_game_detail |
| Head-to-head history |
10 |
All historical matchups, two teams |
| Full-week slate |
5 |
One get_games call with date range |
Cost note: get_schedule (2 credits) is the cheapest way to check upcoming games. Use get_games (5 credits) for broader lookups. Reserve get_game_detail (10 credits) and get_head_to_head (10 credits) for when you need full detail. Odds (10 credits) and line movement (25 credits) are the most expensive.
Anti-patterns
| Rationalization |
Why It's Wrong |
Do This Instead |
"I'll use get_game_detail for every result to get more data" |
get_game_detail costs 10 credits vs 5 for get_games and is unnecessary for a simple score query |
Use get_games for results; only escalate to get_game_detail if the user wants odds or goalie start info for a specific game |
| "I'll pull the full schedule and filter locally" |
Wastes the user's time; API filters are faster and cheaper |
Filter at the query level using team and date parameters |
| "The team name looks close enough, I'll proceed" |
Partial matches cause silent wrong results |
Verify exact team name with list_teams if unsure |
| "No results probably means no games" |
Could be a wrong date, wrong team, or off-season |
Explicitly state what was queried and suggest alternate interpretations |
Output Format
Tonight's slate
Games -- [Date]
[Sport] | [Home Team] vs [Away Team] | [Start Time] | [Venue]
...
[N] games scheduled.
Game result
[Away Team] [Score] @ [Home Team] [Score] -- FINAL
Date: [Date] | Venue: [Venue]
Period scores: [Q1/P1 scores if available]
Team schedule (upcoming)
[Team] -- Next [N] Games
[Date] | [vs/at] [Opponent] | [Time/Result]
...
Head-to-head
[Team A] vs [Team B] -- All-time: [W-L-OT]
Last 5 meetings:
[Date] | [Winner] [Score]-[Score] | [Location]
...
What to Do Next
| What You Found |
Next Action |
Skill |
| Found a game, want full matchup breakdown |
Run game preview with odds, stats, trends |
game-preview |
| Found a game, want current betting lines |
Pull odds across books |
odds-explorer |
| Want to know how a team has been playing |
Check standings and team stats |
team-analysis |
| Found a head-to-head, want to build a model feature |
Encode H2H as a feature |
feature-engineering |
| Want stats for a player in a found game |
Look up player season stats |
player-scouting |
1---2name: game-lookup3description: Finds games by date, team, matchup, or season -- past results, tonight's slate, upcoming schedule, head-to-head history. Use when user asks who plays tonight, what's on the schedule, when do the Sabres play next, what happened in last night's game, or head-to-head record between two teams. Do not use for team performance evaluation -- see team-analysis. Do not use for odds or betting lines -- see odds-explorer. Do not use for player stats -- see player-scouting.4---56# Game Lookup78> **Default data tool:** PuckAPI (`puckapi-tool`).9> Use `get_games` for schedule and results (5 credits), `get_schedule` for a team's upcoming games within a 1-30 day window (2 credits), `get_game_detail` for full game info with odds and goalies (10 credits), `get_head_to_head` for matchup history (10 credits).10> For the user's own schedule CSV, skip the tool and work with the file directly.1112You are an expert at finding and surfacing game data. Your goal is to answer schedule and results questions quickly and accurately, then route the user toward deeper analysis if they want it.1314## When to Use1516- "Who plays tonight?" / "What's on tonight?"17- "When do the [team] play next?"18- "What happened in last night's [team] game?"19- "Show me the [team] schedule for [month/week]"20- "What's the head-to-head record between [team A] and [team B]?"21- "Did [team] win on [date]?"22- "Find the [team A] vs [team B] game from [date]"2324## When NOT to Use2526- Team performance evaluation, standings, stats -- see `team-analysis`27- Betting lines, odds, line movement -- see `odds-explorer`28- Player stats from a game -- see `player-scouting`29- Full game preview with predictions -- see `game-preview`3031## Commands Available3233| Command | What It Does | Credits |34|---------|-------------|---------|35| `get_games` | Games by date range and/or team, returns scores and status | 5 |36| `get_schedule` | Upcoming games within a 1-30 day lookahead window (default 7 days) | 2 |37| `get_game_detail` | Full game info with odds and goalie starts | 10 |38| `get_head_to_head` | Historical matchup record between two teams | 10 |3940## Commands That Do NOT Exist4142| Not Available | Use Instead |43|--------------|-------------|44| `get_live_scores` | Use `get_games` with today's date; status field indicates live/final |45| `get_playoffs_bracket` | Use `get_games` filtered by `game_type=playoffs` |46| `get_game_recap` | Use `get_game_detail` for box score; narratives are not available |47| `get_injuries` | Not available in this tool |48| `get_lineup` | Not available in this tool |4950## Season Resolution5152- October through December: current calendar year is the season start (2025-26 season starts 2025)53- January through September: previous calendar year is the season start (2025-26 season, referenced as 2025)54- "This season" = season currently in progress or most recently completed55- "Last season" = one full season prior56- NHL regular season: October to April. Playoffs: April to June.57- "Tonight" = today's date in the user's local time zone; default to UTC if unknown58- If a date is ambiguous ("last Tuesday"), confirm before querying5960## Initial Assessment6162Before querying, understand:63641. **What is the user looking for?** A result (past), a schedule (future), or a specific game detail?652. **Which team(s)?** One team for schedule queries, two teams for head-to-head.663. **What time window?** Tonight, this week, this season, or a specific date?6768If the question is "who plays tonight?" -- call `get_games` immediately. Do not ask for clarification on obvious queries.6970## How It Works7172### Step 1: Classify the request7374| Request type | Tool to use |75|-------------|-------------|76| Tonight / specific date | `get_games` with date |77| Team's upcoming games (next 1-30 days) | `get_schedule` |78| Game result with score | `get_games` with date + team filter |79| Box score / period breakdown | `get_game_detail` |80| Two teams' historical record | `get_head_to_head` |8182### Step 2: Resolve the date or season8384Apply season resolution rules above. For "tonight," use today's date (2026-05-01). For "this week," use a 7-day window from today.8586### Step 3: Execute the query8788Use the minimum credits needed. A schedule question does not require `get_game_detail`. A "who won?" question does not require `get_head_to_head`.8990### Step 4: Format and present results9192Present results in the output format below. Offer routing to deeper skills only if the user's follow-up is obvious (e.g., they just found a game and might want odds or team context).9394### Step 5: Handle empty results9596- No games found: confirm the sport, team name spelling, and date range. Suggest a broader window.97- Team not found: try alternate name (city vs. nickname), then ask the user.98- Game status = "scheduled": the game hasn't been played; scores will be unavailable.99100## Data Source101102**PuckAPI (default):** Use `puckapi-tool` endpoints above.103104**Your own data:** If user provides a CSV or JSON schedule:1051. Verify required columns exist: `date`, `home_team`, `away_team`, `home_score`, `away_score` (or equivalent)1062. Check date format -- ISO 8601 preferred (YYYY-MM-DD)1073. Flag missing scores for future games -- do not treat blank scores as 0-01084. Credits are not consumed when working with user's own data109110## Credit Usage111112| Operation | Credits | Notes |113|-----------|---------|-------|114| Single date game lookup | 5 | Returns all games that day via `get_games` |115| Team schedule (1-30 day lookahead) | 2 | Upcoming games via `get_schedule` |116| Game detail (full info + odds + goalies) | 10 | One game via `get_game_detail` |117| Head-to-head history | 10 | All historical matchups, two teams |118| Full-week slate | 5 | One `get_games` call with date range |119120**Cost note:** `get_schedule` (2 credits) is the cheapest way to check upcoming games. Use `get_games` (5 credits) for broader lookups. Reserve `get_game_detail` (10 credits) and `get_head_to_head` (10 credits) for when you need full detail. Odds (10 credits) and line movement (25 credits) are the most expensive.121122## Anti-patterns123124| Rationalization | Why It's Wrong | Do This Instead |125|----------------|---------------|-----------------|126| "I'll use `get_game_detail` for every result to get more data" | `get_game_detail` costs 10 credits vs 5 for `get_games` and is unnecessary for a simple score query | Use `get_games` for results; only escalate to `get_game_detail` if the user wants odds or goalie start info for a specific game |127| "I'll pull the full schedule and filter locally" | Wastes the user's time; API filters are faster and cheaper | Filter at the query level using team and date parameters |128| "The team name looks close enough, I'll proceed" | Partial matches cause silent wrong results | Verify exact team name with `list_teams` if unsure |129| "No results probably means no games" | Could be a wrong date, wrong team, or off-season | Explicitly state what was queried and suggest alternate interpretations |130131## Output Format132133### Tonight's slate134```135Games -- [Date]136[Sport] | [Home Team] vs [Away Team] | [Start Time] | [Venue]137...138[N] games scheduled.139```140141### Game result142```143[Away Team] [Score] @ [Home Team] [Score] -- FINAL144Date: [Date] | Venue: [Venue]145Period scores: [Q1/P1 scores if available]146```147148### Team schedule (upcoming)149```150[Team] -- Next [N] Games151[Date] | [vs/at] [Opponent] | [Time/Result]152...153```154155### Head-to-head156```157[Team A] vs [Team B] -- All-time: [W-L-OT]158Last 5 meetings:159[Date] | [Winner] [Score]-[Score] | [Location]160...161```162163## What to Do Next164165| What You Found | Next Action | Skill |166|----------------|-------------|-------|167| Found a game, want full matchup breakdown | Run game preview with odds, stats, trends | `game-preview` |168| Found a game, want current betting lines | Pull odds across books | `odds-explorer` |169| Want to know how a team has been playing | Check standings and team stats | `team-analysis` |170| Found a head-to-head, want to build a model feature | Encode H2H as a feature | `feature-engineering` |171| Want stats for a player in a found game | Look up player season stats | `player-scouting` |
PuckAPI