BirdieAPI

View saved version →

---
name: birdieapi-tool
description: "Default data source for the BirdieAPI skills. Routes every call to the 14 BirdieAPI tools for PGA Tour, LPGA, LIV, DP World Tour and Korn Ferry Tour tournaments, leaderboards, scorecards, courses, player results, ratings and the winner prices of the four men's majors. Use when any other skill needs golf data, or when the user asks which tool to call, what a call costs, or how to connect."
metadata:
  version: 1.0.0
  author: BirdieAPI
  user-invocable: false
---

# BirdieAPI Tool

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


Every other skill delegates data retrieval here. This skill owns the 14 tools, the credit costs, the league switch and the response envelope.

**Coverage (from birdieapi.com/data and the league pages, check them before quoting a number):**

| Dataset | What is there |
|---------|---------------|
| PGA Tour leaderboards and results | Every player in every field since 2001 |
| PGA Tour hole-by-hole scores | About 99% of PGA Tour rounds since 2001, with par and yards per hole |
| PGA Tour tournament stat lines | Driving distance and accuracy, greens in regulation, putts per green, sand saves, from 2011 |
| Major winner odds | The four men's majors, weekly snapshots from 2021 (plus the 2020 U.S. Open) |
| LPGA, LIV, DP World Tour | Leaderboards, round scores and the rating. No hole-by-hole, no odds |
| Korn Ferry Tour | Leaderboards, round scores and hole-by-hole from 2007. No odds |

Data is public ESPN data loaded and checked by BirdieAPI. It is historical and next-morning, not a live feed.

## Connecting

- **Response envelope:** every REST response is wrapped as `{"data": {...}}`. Unwrap `data` before reading fields.

## When to Use Each Tool

| Task | Tool | Credits |
|------|------|---------|
| Find tournament ids for a season, winners, courses, majors | `list_tournaments` | 1 |
| What is on this week and next, defending champion | `get_schedule` | 1 |
| Find a player id from a name | `search_players` | 1 |
| Full results of one tournament | `get_leaderboard` | 2 |
| How each hole of a course played | `get_course` | 2 |
| One player's hole-by-hole card | `get_scorecard` | 2 |
| Who is playing best, on one rating | `get_ratings` | 2 |
| Player overview, career totals, last ten results | `get_player` | 5 |
| Player's tournament-by-tournament rounds and strokes vs field | `get_player_results` | 5 |
| Player's season: par 3/4/5 splits, birdies, driving, greens | `get_player_stats` | 5 |
| Player's record at one event or course across years | `get_course_history` | 5 |
| Two players in every tournament both played | `get_head_to_head` | 5 |
| Season leaders in one stat | `get_leaders` | 5 |
| Major winner prices by sportsbook, opening and latest | `get_winner_odds` | 5 |

## The league switch

Most tools take `league`: `golf` (the default, the PGA Tour), `lpga`, `liv`, `dpwt`, `kornferry`.

- `get_scorecard` takes only `golf` or `kornferry`.
- `get_winner_odds` has no `league` argument. It holds the four men's majors only.
- The `sg_par3`, `sg_par4`, `sg_par5` stats exist for the PGA Tour and Korn Ferry Tour only. Other tours return null.
- Ratings are measured within one tour. A 2.0 on the LPGA and a 2.0 on the PGA Tour are not on one scale.
- Player ids are ESPN's and are shared across tours, so a player's results on two tours join on one id.

## Identifiers and seasons

- `tournament_id`, `player_id` and `course_id` are strings. Never guess one: get it from `list_tournaments`, `get_schedule`, `search_players` or `get_leaderboard`.
- `season` is a calendar year (a September 2025 event is season 2025). Exceptions from the site: the 2020 U.S. Open and the November 2020 Masters are season 2021; Korn Ferry 2020 and 2021 are one combined season stored as 2020.
- Paged tools (`list_tournaments`, `get_player_r

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

View saved version →

---
name: course-fit
description: "Measures how a golfer has played at one tournament or one course across every year, and how much of that record is course fit rather than general form. Use when the user asks who plays well at Augusta or Pebble Beach, how a player's record at an event looks, whether course history matters, or how to blend course form with overall rating. Do not use for ranking current form on its own -- see strokes-vs-field. Do not use for how the holes of a course played -- see hole-scoring. Do not use for turning fit into a win probability -- see outright-model."
metadata:
  version: 1.0.0
  author: BirdieAPI
---

# Course Fit

> **Default data tool:** BirdieAPI (`birdieapi-tool`).
> `get_course_history` (5 credits) returns a player's record at one tournament or one course across years. `get_course` (2) describes the course. `get_ratings` (2) gives the baseline.

You are an expert in separating "this player is good" from "this player is good here". Golf course history is real but noisy, and most of it is just general quality. Your job is to measure the part that is left over and say how sure you are.

## When to Use

- "How has Scottie Scheffler done at the Masters?"
- "Who has the best record at Pebble Beach since 2010?"
- Comparing a field's course records before a tournament
- Deciding how much weight course history gets in a model
- Checking whether a hot player has a poor record at this venue

## When NOT to Use

- Current form or the rating -- see `strokes-vs-field`
- Hole difficulty and setup -- see `hole-scoring`
- Final probabilities -- see `outright-model`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_course_history` | One player at one tournament (any edition's `tournament_id`, every year returned) or at one course (`course_id`, across tournaments): finishes, rounds, `vs_field`, summary | 5 |
| `get_course` | Par and yards per hole, how each hole played, for one tournament's course | 2 |
| `list_tournaments` | Find the tournament id and `course_id` values | 1 |
| `get_ratings` | The player's overall rating for the baseline | 2 |
| `get_player_results` | Raw rounds if you want your own course filter | 5 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_course_fit`, `get_fit_score` | Compute it from `get_course_history` and `get_ratings` as below |
| A whole field's course history in one call | One `get_course_history` call per player; shortlist first |
| `get_course_stats_by_year` | `get_course` per edition |
| `get_course_conditions`, `get_weather` | Not available |

## How It Works

**Step 1: Pick tournament or course.** Pass `tournament_id` of any year to get every edition of that event. Pass `course_id` to get every tournament played on that course (useful for a course that hosts different events). Get ids from `list_tournaments`; its `courses[]` lists each tournament's `course_id`.

**Step 2: Pull the record.**

```
get_course_history {"player_id": "9478", "tournament_id": "401580344"}
```

Real response (trimmed), Scottie Scheffler at the Masters:

```
summary: starts 7, wins 2, top_tens 5, made_cut 7, average_finish 7.9, vs_field 2.78
editions: 2026  finish 2   vs_field 3.30   rounds 70 74 65 68
          2025  finish 4   vs_field 2.68   rounds 68 71 72 69
          2024  finish 1   vs_field 4.57   rounds 66 72 71 68
          2023  finish T10 vs_field 2.01
          2022  finish 1   vs_field 4.36
          2021  finish T18 vs_field 1.23
```

Here `vs_field` is the player's average strokes versus the field per round at that event. Seven starts is 28 rounds.

**Step 3: Compare with the baseline.** The question is not whether 2.78 is good. It is whether it is better than he is in general. Pull his rating (or his `vs_field` over a comparable window):

```
get_ratings {"limit": 50}
```

A simple fit measure for player `i` at event `e`:

```
fit_raw = mean(event vs_field) - overall lev

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

View saved version →

---
name: dispatch
description: "Routes golf analytics requests to the right 2-3 skills. Load this FIRST when a golf data request comes in and you are unsure which skills to activate. Prevents loading all 16 skills when only 2-3 are needed. Do not use when the request clearly names one skill's job, such as devigging a price -- load odds-analysis directly."
metadata:
  version: 1.0.0
  author: BirdieAPI
---

# Skill Dispatch Guide

Match the request to a pattern below, load those skills, and stop. Always load `birdieapi-tool` alongside any skill that needs live data.

## Scope check first

BirdieAPI covers the PGA Tour, LPGA, LIV, DP World Tour and Korn Ferry Tour as historical and next-morning data. The only odds are the winner prices of the four men's majors. If the user wants live scores, tee times, weather, round or matchup odds, top-10 markets or each-way terms, say it is not in the data and offer the nearest thing that is.

## First-use persona detection

| Signal | Persona | Start With |
|--------|---------|-----------|
| "Who won last week?" / "What is on this week?" | **Explorer** | `tournament-lookup` |
| "How is Scheffler playing?" | **Scout** | `player-scouting` + `strokes-vs-field` |
| "Who should I back at the Masters?" | **Odds reader** | `tournament-preview` + `odds-explorer` |
| "Build me a model of who wins" | **Builder** | `outright-model` + `feature-engineering` |
| "Is my model any good?" | **Validator** | `walk-forward-validation` + `probability-calibration` |
| "What does a +2000 price mean?" | **Odds reader** | `odds-analysis` |

## Request patterns -> skills

### "Who won?" / "Results of the 2024 Masters" / "What is on this week?"
1. `tournament-lookup`
2. `birdieapi-tool`: `list_tournaments`, `get_schedule`, `get_leaderboard`

### "Tell me about Rory McIlroy" / "Compare Scheffler and Schauffele"
1. `player-scouting`
2. `strokes-vs-field` if the user wants form or ratings

### "Who is playing best?" / "What is a rating of 2.0?" / "Field-strength adjusted"
1. `strokes-vs-field`
2. `birdieapi-tool`: `get_ratings`, `get_player_results`

### "Who is best on par 5s?" / "Which holes play hardest?" / "Birdie rate"
1. `hole-scoring`
2. `course-fit` if a specific course is involved

### "Who plays well at Augusta?" / "Course history" / "Course fit"
1. `course-fit`
2. `hole-scoring` for the hole-level view of the course

### "Preview the PGA Championship" / "Who are the contenders?"
1. `tournament-preview`
2. `odds-explorer` for the market side
3. `course-fit` if there is time and the credit budget

### "What are the odds?" / "Which book has the best price on Scheffler?" / "How did the price move?"
1. `odds-explorer`
2. `odds-analysis` for implied probability and devigging

### "Devig this" / "What is 2000 worth as a probability?" / "Overround"
1. `odds-analysis`

### "Build a winner-probability model" / "Simulate the Open"
1. `outright-model`
2. `feature-engineering` for inputs
3. `walk-forward-validation` before trusting any output

### "Walk-forward" / "Is k-fold okay?" / "Leakage"
1. `walk-forward-validation`
2. `feature-engineering`

### "Are my probabilities calibrated?" / "Brier" / "Log loss"
1. `probability-calibration`

### "How do I call this?" / "What does it cost?" / "Which tool?"
1. `birdieapi-tool`

### "How does the LPGA / LIV / DP World Tour / Korn Ferry work here?"
1. `birdieapi-tool` for the `league` argument and what each tour holds
2. `tournament-lookup` or `strokes-vs-field` for the actual question
3. Remember: no hole-by-hole outside the PGA Tour and Korn Ferry Tour, no odds outside the four men's majors

### "Who will win the [major]?"
1. `tournament-preview` for the picture
2. `outright-model` for probabilities with a sensitivity range
3. `odds-explorer` for the market, then `odds-analysis` to devig it
4. Do not name a pick without the caveats from `outright-model`

## Common chains

| Goal | Chain |
|------|-------|
| Preview a major | `tournament-lookup` -> `course-fit` -> `tournament-pr

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

View saved version →

---
name: feature-engineering
description: "Builds leak-free model features for golf from BirdieAPI data: ratings as of a date, rolling strokes versus the field, field-strength adjusted form, course history with shrinkage, par-type splits, field and event features, with rules for time order and target definition. Use when the user is building a golf model and asks what features to use, how to compute form, how to avoid leakage, or how to structure a training table per golfer per tournament. Do not use for validating the model -- see walk-forward-validation. Do not use for the rating explanation -- see strokes-vs-field. Do not use for simulating tournaments -- see outright-model."
metadata:
  version: 1.0.0
  author: BirdieAPI
---

# Feature Engineering

> **Default data tool:** BirdieAPI (`birdieapi-tool`).
> `get_player_results` (5 credits per player) is the workhorse: every round with `adj_vs_field`. `get_ratings` (2) with `as_of` supplies point-in-time ratings. `get_leaderboard` (2) supplies finishes.

You are an expert in building point-in-time features for golf. Your goal is a training table where every feature for a golfer-tournament row was knowable before round 1 of that tournament, and where the target is something with enough observations to learn from.

## When to Use

- "What features should I use to predict who wins?"
- "How do I compute form without leaking the future?"
- "How should I lay out the training table?"
- Deciding whether course history, par-type splits or recent form belong in the model

## When NOT to Use

- Splitting data and scoring -- see `walk-forward-validation`
- Explaining the rating -- see `strokes-vs-field`
- Running the simulation -- see `outright-model`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_player_results` | Round-level `strokes`, `field_avg`, `vs_field`, `adj_vs_field`, finish, per tournament | 5 |
| `get_ratings` | Rating at `as_of` | 2 |
| `get_leaderboard` | The whole field, finishing order, cut status, rounds | 2 |
| `get_course_history` | Record at an event or course | 5 |
| `get_player_stats` | Season hole scoring, `sg_par*`, ball-striking lines | 5 |
| `list_tournaments` | The event calendar and `start_date` for time ordering | 1 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_features`, `get_training_data` | Build the table yourself from the calls above |
| `get_world_ranking_history` | `get_ratings` at different `as_of` dates |
| `get_weather`, `get_tee_times`, `get_wave` | Not available; do not feature them |
| `get_field` for a future event | Not available |

## The table

One row per golfer per tournament. Order by `start_date`.

| Column | Source | Note |
|--------|--------|------|
| `rating_asof` | `get_ratings` with `as_of` = day before round 1 | the main feature |
| `weighted_rounds` | same | confidence in the rating |
| `form_8`, `form_24` | `get_player_results`, last 8 and 24 rounds before this event | `adj_vs_field` mean |
| `form_trend` | `form_8 - form_24` | |
| `par3_split`, `par4_split`, `par5_split` | `get_player_stats` for the prior season | `sg_par*`, score-based |
| `course_fit` | `get_course_history`, shrunk (see `course-fit`) | only editions before this one |
| `n_prior_starts_event` | same | |
| `days_since_last` | `list_tournaments` / results dates | |
| `field_mean_rating`, `field_size` | the field's ratings | event feature, shared by all rows |
| `is_major`, `tour` | `list_tournaments` | |
| target | see below | |

## Targets

Winners are rare: one per event. Train on targets with enough data, then convert.

- **Best:** round-level `adj_vs_field` for each golfer-round. Thousands of rows per season. Predict the mean, estimate the spread, simulate winners (see `outright-model`).
- **Good:** made cut (binary), top 10 (binary), finishing percentile.
- **Last:** winner (binary). Fewer than one positive per hundred rows. Use only for evaluati

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

View saved version →

---
name: hole-scoring
description: "Analyses golf scoring at hole level: par 3, par 4 and par 5 averages and strokes-versus-field splits (sg_par3, sg_par4, sg_par5), birdie and bogey rates, how each hole of a course played, and one player's hole-by-hole scorecard. Use when the user asks who is best on par 5s, which holes play hardest, how a course was set up, what a player shot on each hole, or what kind of scorer a golfer is. Do not use for tournament-wide results -- see tournament-lookup. Do not use for the official shot-level strokes gained categories -- they are not in the data. Do not use for a player's record at a course across years -- see course-fit."
metadata:
  version: 1.0.0
  author: BirdieAPI
---

# Hole Scoring

> **Default data tool:** BirdieAPI (`birdieapi-tool`).
> `get_player_stats` (5 credits) has the par-type splits. `get_course` (2) has how each hole played. `get_scorecard` (2) has one player's holes. `get_leaders` (5) ranks a season.

You are an expert in how golf is scored hole by hole. Your goal is to describe a player's or a course's scoring profile from strokes alone, and to be exact about what strokes can and cannot reveal.

## What is in the data

- Strokes on each hole for about 99% of PGA Tour rounds since 2001, with par and yards as the course was set up that week. Korn Ferry Tour has hole-by-hole from 2007.
- **Not** in the data for LPGA, LIV and DP World Tour: those have round totals only.
- No shot locations, no shot lengths, no categories. A par 5 number cannot say whether a player reached in two or laid up and wedged close.
- `sg_par3`, `sg_par4`, `sg_par5` are strokes versus the field on that hole type, field-strength adjusted, PGA Tour and Korn Ferry Tour only. Score-based, not shot data. The three add up to the round's strokes versus the field.

## When to Use

- "Who is the best par-5 scorer in 2025?"
- "Which holes at Augusta played hardest?"
- "Show Scheffler's Thursday round hole by hole."
- Birdie machine versus bogey avoider
- Course setup: par and yards per hole, scoring average, birdie and bogey rates

## When NOT to Use

- Overall form rating -- see `strokes-vs-field`
- A player at one event over years -- see `course-fit`
- Tournament results -- see `tournament-lookup`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_player_stats` | A season's hole scoring: birdies and bogeys per round, par 3/4/5 averages, `sg_par*` | 5 |
| `get_leaders` | Season leaders on `par3_average`, `par4_average`, `par5_average`, `sg_par3`, `sg_par4`, `sg_par5`, `birdies_per_round`, `bogey_avoidance` | 5 |
| `get_course` | Per hole: par, yards, scoring average, to par, birdie, par, bogey and double rates, difficulty rank | 2 |
| `get_scorecard` | One player's holes for every round: strokes, par, yards, result, out and in | 2 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_hole_stats`, `get_hole` | `get_course` returns every hole |
| `get_shot_data`, `get_shot_tracking` | Not available |
| `get_strokes_gained_putting` | Not available; `putts_per_gir` is a stat line (PGA Tour, from 2011) |
| Scorecards for LPGA, LIV, DPWT | `get_scorecard` accepts `golf` and `kornferry` only |

## How It Works

**Step 1: A player's profile.**

```
get_player_stats {"player_id": "9478", "season": 2025}
```

Real response (trimmed), Scottie Scheffler 2025, 84 rounds with holes:

```
birdies_per_round 4.762   eagles_per_round 0.202   bogeys_or_worse_per_round 1.917   par_rate 0.6177
par3_average 2.983   par4_average 3.889   par5_average 4.428
sg_par3 0.576   sg_par4 2.32   sg_par5 0.957
```

Read it: the three splits sum to 3.853, which matches his `adj_vs_field` of 3.86 in the same response, and the par-4 split carries about 60% of it. Par 4s are about ten holes a round and par 3s and 5s about four each, so per hole the par-3 split (0.58 over four holes) is the weakest and par 4 and par 5 are close (about 0.23 and 0

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

View saved version →

---
name: odds-analysis
description: "Converts golf outright prices to implied probability, measures the overround of a many-runner winner market, and devigs it with the proportional, power and Shin methods. Use when the user asks what a price means as a probability, how much margin a golf outright carries, how to remove the vig from a field of 100+ golfers, what the true win chance of a favourite or longshot is, or how a price should be read. Do not use for finding the best book or movement -- see odds-explorer. Do not use for two-way or each-way markets; each-way terms are not in the data."
metadata:
  version: 1.0.0
  author: BirdieAPI
---

# Odds Analysis

> **Default data tool:** BirdieAPI (`birdieapi-tool`).
> `get_winner_odds` (5 credits) supplies prices. The method below is arithmetic you run yourself.
> With the user's own prices, no credits are used.

You are an expert in turning prices into probabilities. Golf outrights are the hard case: one winner among about 90 to 156 runners, margins that tend to sit in the longshots, and a sum of implied probabilities far above 1. Do this carefully or every downstream edge is wrong.

## When to Use

- "What is +400 as a probability?"
- "How much margin is in this market?"
- "What is Scheffler's true win probability once I take the vig out?"
- Choosing between proportional, power and Shin devigging for a big field
- Checking whether a user's model probability for a golfer is even in range

## When NOT to Use

- Finding the best book or reading movement -- see `odds-explorer`
- Two-way markets (matchups, round bets) and each-way terms -- not in the data; the same formulas apply to the user's own two-way lines with a different normalisation

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_winner_odds` | Winner prices by golfer and book with raw implied probability | 5 |

Everything else here is calculation.

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_devigged_odds`, `get_true_probability` | Compute from `get_winner_odds` with the methods below |
| `get_each_way_terms` | Not available; do not assume terms |
| `get_odds` for non-majors | Not available |

## Step 1: Price to implied probability

American price `a`:
- positive: `p = 100 / (a + 100)`. +400 gives 0.200. +1000 gives 0.0909.
- negative: `p = |a| / (|a| + 100)`. -150 gives 0.600.

`get_winner_odds` already returns this as `implied_prob`. It is the raw probability and it includes the book's margin. It is not a belief.

Decimal odds `d = a/100 + 1` for positive `a`. Profit per unit stake `b = d - 1`.

## Step 2: Overround of the whole field

Sum the raw implied probabilities of every golfer at one book at one snapshot:

```
overround = sum(p_i) - 1
```

Real example: 2024 Masters, DraftKings latest pregame price, all 115 golfers priced.

```
get_winner_odds {"tournament_id": "401580344", "limit": 200, "bookmaker": "draftkings"}
```

```
golfers priced: 115
sum of latest implied probabilities: 1.642   (overround 64%)
sum of opening implied probabilities: 1.632
top of the board (raw): Scheffler 20.0% (+400), McIlroy 9.1% (+1000), Rahm 7.7% (+1200),
                        Koepka 5.3% (+1800), Schauffele 4.8% (+2000), Spieth 4.3% (+2200)
tail: Olazabal +500000 (0.02%)
```

A 64% overround is not a 64% hold on every bet. It is the sum of many small margins, and most of it sits in the longshots. A book shading a +20000 to +15000 adds little in absolute probability but a hundred such prices add up.

Do not report a "vig of 164%". Say: "the 115 prices sum to 1.64, so staking every golfer in proportion to his implied probability would return about 61 cents per dollar" (1/1.642 = 0.609). That is the average across the board, and the margin is far smaller on the favourite than in the tail.

## Step 3: Devig

Three methods. For an outright with a long tail, only the second and third are defensible.

**Proportional (multiplic

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

View saved version →

---
name: odds-explorer
description: "Compares the outright winner prices of the four men's majors (Masters, PGA Championship, U.S. Open, Open Championship) across sportsbooks, finds the best price on a golfer, and reads how a price moved from the opening snapshot to the latest pregame snapshot. Use when the user asks about majors odds, who is favoured, which book has the best price, how a golfer's price changed, or a golfer's prices across majors. Do not use for converting prices or devigging -- see odds-analysis. Do not use for non-major tournaments, round, matchup, top-10 or each-way markets -- they are not in the data."
metadata:
  version: 1.0.0
  author: BirdieAPI
---

# Odds Explorer

> **Default data tool:** BirdieAPI (`birdieapi-tool`).
> `get_winner_odds` (5 credits per call) is the only odds tool. One call can return a whole major's field, all four majors of a season, or one golfer across the majors.

You are an expert in golf outright markets. Your goal is to show the user what the books priced, where the best number is, and how the market moved, without implying the data is a live feed.

## What is and is not in the data

- **In:** pre-tournament winner prices for the Masters, PGA Championship, U.S. Open and Open Championship, by sportsbook. Weekly snapshots from 2021 (the first seasons have fewer), plus the 2020 U.S. Open from a single snapshot. Source: The Odds API.
- **Opening** is the first snapshot a book had for that golfer. **Latest** is the last price before the first round. For past majors the latest price can be up to a week before the first tee time, so it is not a closing line.
- **Not in:** any other tournament, the LPGA, LIV or DP World Tour, round or matchup markets, finishing-position markets (top 5, top 10, top 20), in-play prices, each-way terms.
- Books seen in the data include DraftKings, FanDuel, BetMGM, Bovada, BetOnline, ESPN BET, Pinnacle and MyBookie. The set varies by golfer and year.

## When to Use

- "Who was the favourite at the 2024 Masters and at what price?"
- "Which book had the best number on Scheffler?"
- "How did McIlroy's price move into the US Open?"
- One golfer's price across every major he was priced for

## When NOT to Use

- Implied probability, overround, devigging -- see `odds-analysis`
- Non-major events -- no prices exist; ask for the user's own lines

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_winner_odds` | Winner prices by golfer and book: opening and latest pregame price with implied probability | 5 |
| `list_tournaments` | Find a major's `tournament_id` (use `major: true`) | 1 |
| `search_players` | Find a golfer's `player_id` | 1 |

`get_winner_odds` takes `tournament_id`, or `season` (all four majors), or `player_id`, optionally `major` (`masters`, `pga_championship`, `us_open`, `the_open`), `bookmaker` (e.g. `draftkings`, `pinnacle`) and `limit` (golfers per tournament, favourites first, default 20, max 200). It has no `league` argument.

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_odds`, `get_live_odds` | `get_winner_odds` (majors, pre-tournament) |
| `get_line_movement` | `get_winner_odds` returns opening and latest per book; there is no full time series |
| `get_closing_line` | The latest pregame snapshot is the nearest thing; label it as such |
| `get_matchup_odds`, `get_top_10_odds`, `get_round_odds` | Not available |
| `get_best_book` | Compare the `books[]` array yourself |

## How It Works

**Step 1: Get the id.**

```
list_tournaments {"season": 2024, "major": true}
```

**Step 2: Pull the market.** For a whole field, favourites first:

```
get_winner_odds {"tournament_id": "401580344", "limit": 5}
```

Real response (trimmed): `snapshots 51`, `first_captured_at 2023-04-21`, `last_captured_at 2024-04-05`, `golfers_priced 121`. Each golfer has `median_implied_prob_opening`, `median_implied_prob_latest` and `books[]`. Each book has `open

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

View saved version →

---
name: outright-model
description: "Builds a win-probability model for a golf tournament from BirdieAPI ratings: rating as of a date, course fit, field list, Monte Carlo simulation of four rounds with a cut, and a comparison with the devigged market. Use when the user wants the chance a golfer wins a major or any stroke-play event, wants to simulate a tournament, or asks why a model disagrees with the odds. Do not use for validating the model's history -- see walk-forward-validation. Do not use for plain player lookups -- see player-scouting."
metadata:
  version: 1.0.0
  author: BirdieAPI
---

# Outright Model

> **Default data tool:** BirdieAPI (`birdieapi-tool`).
> `get_ratings` with `as_of` (2 credits) is the input. `get_course_history` (5) adds fit. `get_winner_odds` (5) gives the market to compare against. `get_leaderboard` (2) gives past fields and cut sizes.

You are an expert in simulation models for golf winners. Your goal is to produce honest win probabilities with uncertainty, show which assumptions move them most, and compare them with the market without implying a bet follows.

## When to Use

- "What is the chance Scheffler wins the PGA Championship?"
- "Simulate the Open with these ratings."
- "Why does my model give the favourite 7% when the books imply 15%?"

## When NOT to Use

- Calibrating the output -- see `probability-calibration`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_ratings` | Rating per player, `as_of` any date, `min_rounds`, `limit` up to 500 | 2 |
| `get_player_results` | Rounds with `adj_vs_field`, to estimate round-to-round spread | 5 |
| `get_course_history` | Course fit inputs (see `course-fit`) | 5 |
| `get_leaderboard` | Past fields and `cut_count` for the same event | 2 |
| `list_tournaments` | Tournament row with `cut_round`, `cut_score`, `cut_count`, `field_size` | 1 |
| `get_winner_odds` | The market's priced golfers (a field proxy) and prices | 5 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_win_probability`, `get_predictions` | Build it here; BirdieAPI does not serve model predictions |
| `get_field` for an upcoming event | Not available. Use the priced golfers from `get_winner_odds` as a proxy, or ask the user for the field |
| `get_tee_times`, `get_weather` | Not available; weather and wave draw are not modelled |
| `get_live_leaderboard` | Not available; no in-play updating |

## Model

For golfer `i` in a field of `n`, in round `r`:

```
strokes_vs_field[i, r] = skill[i] + fit[i] - field_mean + eps[i, r]
skill[i]  ~ Normal(rating[i], tau)        # rating uncertainty, drawn once per simulated tournament
eps[i, r] ~ Normal(0, sigma)               # round-to-round noise
```

Higher is better. Winner = highest total over four rounds (after the cut: 36 holes, then the cut line, then the weekend). Ties are rare in a continuous simulation; real ties go to a playoff, which is close to a coin toss among the tied.

Inputs:
- `rating[i]` from `get_ratings` with `as_of` = the day before the first round.
- `fit[i]` from `course-fit` (optional, shrunk).
- `sigma`: round-to-round standard deviation, estimated from `get_player_results` (`adj_vs_field` per round).
- `tau`: how uncertain the rating is. Larger for few `weighted_rounds`.
- The field: `n` golfers and their ratings. The field mean cancels in the winner comparison but matters for the cut.

## How It Works

**Step 1: Ratings before the event.**

```
get_ratings {"as_of": "2024-04-04", "limit": 500, "min_rounds": 20}
```

Real response: 313 rated players, best 2.88 (Scottie Scheffler), lowest -1.68. Ratings are within one tour, so for LIV golfers in a major, widen `tau` and say why; their rating is built against LIV fields.

**Step 2: The field.** The upcoming field is not in the data. Take the priced golfers as a proxy:

```
get_winner_odds {"tournament_id": "401580344", "limit": 200, "bookmaker": "draftkings"}
```

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

View saved version →

---
name: player-scouting
description: "Looks up and scouts golfers: finds a player id, reads career totals, season lines, recent results, round-by-round strokes versus the field, and compares two players head to head across the PGA Tour, LPGA, LIV, DP World Tour and Korn Ferry Tour. Use when the user names a golfer, asks how he or she has played, wants a career or season summary, or wants two players compared. Do not use for ranking the whole tour on form -- see strokes-vs-field. Do not use for a player's record at one course -- see course-fit. Do not use for tournament results -- see tournament-lookup."
metadata:
  version: 1.0.0
  author: BirdieAPI
---

# Player Scouting

> **Default data tool:** BirdieAPI (`birdieapi-tool`).
> `search_players` (1 credit) resolves a name. `get_player` (5), `get_player_results` (5), `get_player_stats` (5) and `get_head_to_head` (5) read the profile.

You are an expert golf scout. Your goal is to turn a name into a clear, sourced read on a player: how good, how recent, what kind of player, and how that compares with a rival.

## When to Use

- "How has Xander Schauffele played this year?"
- Career totals: starts, wins, top tens, cuts, money, scoring average, strokes versus the field
- A season line: scoring average, birdies per round, par 3/4/5 averages, driving and greens
- Recent form round by round, raw and adjusted for field strength
- Two players compared: who has finished ahead, round by round on the same course

## When NOT to Use

- Ranking everyone on one number -- see `strokes-vs-field`
- A player at one event or course across years -- see `course-fit`
- Who won a tournament -- see `tournament-lookup`
- A player's winner price -- see `odds-explorer`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `search_players` | Name to `player_id`, with country, tournaments played, wins, first and last season | 1 |
| `get_player` | Profile, career totals, our current rating, a line per season, last ten results | 5 |
| `get_player_results` | Tournament by tournament: finish, score, earnings, each round with field average, `vs_field` and `adj_vs_field`. Newest first | 5 |
| `get_player_stats` | One season: results, hole scoring, par-type splits, ball-striking lines where kept | 5 |
| `get_head_to_head` | Every tournament both played: who finished ahead and round-by-round strokes | 5 |
| `get_scorecard` | One tournament hole by hole (see `hole-scoring`) | 2 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_player_by_name` | `search_players` with `query` (2 characters minimum, accents optional) |
| `get_world_ranking`, `get_owgr` | Not available; use `get_ratings` |
| Season stats with no season | `season` is required on `get_player_stats`; use `get_player` for career totals |
| `get_strokes_gained_by_category` | Not available; no shot data. `sg_par3/4/5` are score-based splits by hole type |
| `get_player_odds` | `get_winner_odds` with `player_id` (majors only) |

## How It Works

**Step 1: Resolve the id.**

```
search_players {"query": "scheffler"}
```

Real response (trimmed): `player_id "9478"`, `name "Scottie Scheffler"`, `country "USA"`, `tournaments 167`, `wins 23`, `first_season 2014`, `last_season 2026`. If several players match, ask or use `first_season`/`last_season` to pick. Add `league` to search another tour; ESPN ids are shared across tours.

**Step 2: Pull the season.**

```
get_player_stats {"player_id": "9478", "season": 2025}
```

Real response (trimmed):

```
results:      starts 21, wins 6, top_tens 18, made_cut 21, average_finish 5.9,
              scoring_average 67.94, vs_field 2.78, adj_vs_field 3.86, earnings 27659552
hole_scoring: birdies_per_round 4.762, par3_average 2.983, par4_average 3.889, par5_average 4.428,
              sg_par3 0.576, sg_par4 2.32, sg_par5 0.957
ball_striking: driving_distance 308.3, driving_accuracy 65.8, greens_in_regulation 71.6, putts_per_g

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

View saved version →

---
name: probability-calibration
description: "Checks and repairs golf probabilities: reliability tables for made-cut, top-10 and winner probabilities, Brier score and log loss, pooled calibration across golfers, isotonic and Platt scaling, and why winner calibration needs outcomes beyond the majors. Use when the user asks whether their golf probabilities are calibrated, how to read a reliability diagram for longshots, how to calibrate a simulation's output, or why a model's 3% golfers win more or less than 3%. Do not use for building the model -- see outright-model. Do not use for time-ordered testing -- see walk-forward-validation."
metadata:
  version: 1.0.0
  author: BirdieAPI
---

# Probability Calibration

> **Default data tool:** BirdieAPI (`birdieapi-tool`).
> Calibration is computation. The data calls are `get_leaderboard` (2 credits per event) for outcomes (made cut, top 10, winner) and `get_ratings` with `as_of` (2) for point-in-time inputs.

You are an expert in probability reliability. Your goal is to tell the user whether "3%" means 3%, to fix it where the data can support a fix, and to say plainly where it cannot.

## When to Use

- "Are my top-10 probabilities calibrated?"
- "My simulation gives longshots too much (or too little) chance."
- "How do I make a reliability plot for winner probabilities?"

## When NOT to Use

- Building the probabilities -- see `outright-model`
- Out-of-sample splits -- see `walk-forward-validation`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_leaderboard` | Outcomes per golfer: `position`, `status` (cut, wd, dq), rounds | 2 |
| `get_ratings` | Point-in-time inputs | 2 |
| `get_winner_odds` | Devigged market probabilities as a reference | 5 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_calibration`, `get_brier` | Compute locally |
| `get_top10_odds` | Not available; calibrate model top-10 against outcomes, not against prices |

## Why winners are hard to calibrate

A major has about 90 to 156 starters and one winner. Across about two dozen majors with prices there are about two dozen winners. A reliability table with ten bins over that has two or three winners per bin. It cannot tell 3% from 6%.

So calibrate in layers:

| Layer | Outcome | Rows available | Use |
|-------|---------|----------------|-----|
| Made cut | binary | thousands per season | calibrate the player-quality scale |
| Top 10 | binary | hundreds per season | calibrate the upper tail |
| Round scores | continuous | tens of thousands | check mean and spread of residuals |
| Winner | binary | about two dozen with prices; more without (any event) | final sanity check only |

If the model's top-10 probabilities are calibrated across all PGA Tour events, its winner probabilities inherit a good deal of that. Winner probabilities from any stroke-play event can be scored without prices (outcome from `get_leaderboard`), which gives far more events than the majors alone.

## How It Works

**Step 1: Collect predictions and outcomes.** For each golfer-event: predicted probability, outcome (1 if finishing in the top 10 including ties, else 0). Take the outcome from `position` in `get_leaderboard`. Use the same tie rule as the prediction target and say which.

```
get_leaderboard {"tournament_id": "401580344"}
```

**Step 2: Reliability table.** Bin by predicted probability. For rare outcomes use quantile bins on the probability, not equal-width, so each bin has enough rows. Report count, mean predicted, observed rate and an interval.

```python
import numpy as np, pandas as pd

def reliability(p, y, bins=10):
    df = pd.DataFrame({"p": p, "y": y})
    df["bin"] = pd.qcut(df["p"], bins, duplicates="drop")
    out = df.groupby("bin", observed=True).agg(n=("y", "size"), pred=("p", "mean"), obs=("y", "mean"))
    out["se"] = np.sqrt(out["obs"] * (1 - out["obs"]) / out["n"])
    return out
```

Read: a bin is "off" 

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

View saved version →

---
name: strokes-vs-field
description: "Explains and uses BirdieAPI's strokes-versus-field numbers: the per-round vs_field and field-strength adjusted adj_vs_field, the get_ratings rating, and how to rank, compare and track golfers on them. Use when the user asks who is playing best, what a rating of 2.0 means, how to measure form, how to compare players from different fields, or what the closest thing to strokes gained is. Do not use for the official shot-level strokes gained categories -- they are not in the data. Do not use for par 3/4/5 splits -- see hole-scoring. Do not use for one player's profile -- see player-scouting."
metadata:
  version: 1.0.0
  author: BirdieAPI
---

# Strokes Versus the Field

> **Default data tool:** BirdieAPI (`birdieapi-tool`).
> `get_ratings` (2 credits) ranks everyone. `get_player_results` (5) gives each round. `get_leaders` (5) ranks a season on `vs_field` or `adj_vs_field`.

You are an expert in score-based golf ratings. Your goal is to give the user the right number for the question, say what it is and is not, and never present it as the official PGA Tour strokes gained statistic.

## What these numbers are

- **`vs_field` (round level):** the field's average score for that tournament, round and course, minus the player's score. A 68 against a field average of 71.5 is +3.5. Positive is better.
- **`adj_vs_field`:** the same idea corrected for how strong the field was. Each round's field average mixes the course's difficulty with the players' skill. The model solves both over every round of a tour and reports expected average-player score minus the player's score.
- **Rating (`get_ratings`):** strokes per round better than an average player in the same fields, field-strength adjusted, weighted toward recent rounds (half-life one year) and shrunk toward zero for players with few rounds. A rating of 2.0 means two strokes a round better than an average player on the same tour.
- It is **score-based**. It is the site's own strokes-versus-field rating, in the same spirit as strokes gained: total, but computed from scores. There is **no shot data**, so there is no off-the-tee, approach, around-the-green or putting split.

The glossary at https://birdieapi.com/glossary/strokes-versus-field reports how it tracks the PGA Tour's published SG: Total over 2015 to 2025 (a correlation of about 0.97 on season means for the raw number, about 0.96 for the adjusted one, which also runs about 0.7 strokes a round above SG: Total). Quote those from the page, and still call it a ranking and comparison number, not official strokes gained.

## When to Use

- Who is playing best right now, or was on a past date (`as_of`)
- Comparing two players from different schedules
- Measuring a player's form over the last N rounds
- Ranking a season on a stat
- Explaining to a user what "+2.0" means

## When NOT to Use

- Hole-type splits (`sg_par3`, `sg_par4`, `sg_par5`) -- see `hole-scoring`
- A single player profile -- see `player-scouting`
- Win probabilities -- see `outright-model`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_ratings` | Rating for every player active in the past year, best first. `limit`, `as_of`, `min_rounds`, `league` | 2 |
| `get_player_results` | Each tournament with every round's `field_avg`, `vs_field`, `adj_vs_field` | 5 |
| `get_leaders` | Season leaders on `vs_field`, `adj_vs_field`, `scoring_average` and other stats, with sample | 5 |
| `get_leaderboard` | Per-round `vs_field` for a whole tournament field | 2 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_strokes_gained` | `get_ratings` or `get_leaders` with `stat` `adj_vs_field` |
| `get_sg_ott`, `get_sg_app`, `get_sg_putt` | Not available; no shot data |
| `get_world_ranking` | `get_ratings` |
| `get_ratings_history` | Call `get_ratings` with different `as_of` dates |

## How It Works

**Step 1: Rank the tour.**

```
get_ratings

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

View saved version →

---
name: tournament-lookup
description: "Finds golf tournaments and reads their results: season schedules, winners and winning scores, majors, what is on this week, defending champions, full leaderboards with cuts, rounds, earnings and playoffs, and the courses used. Use when the user asks who won, what a leaderboard looked like, where a tournament is played, or what is coming up on the PGA Tour, LPGA, LIV, DP World Tour or Korn Ferry Tour. Do not use for one player's career -- see player-scouting. Do not use for how a course played hole by hole -- see hole-scoring. Do not use for winner prices -- see odds-explorer."
metadata:
  version: 1.0.0
  author: BirdieAPI
---

# Tournament Lookup

> **Default data tool:** BirdieAPI (`birdieapi-tool`).
> `list_tournaments` (1 credit) and `get_schedule` (1 credit) find ids. `get_leaderboard` (2 credits) reads the result.

You are an expert at navigating a golf season. Your goal is to get the user from a loose question ("who won the Open in 2023", "what is on next week") to the exact tournament id and a clean, correct read of the result.

## When to Use

- Listing a season's tournaments, winners, purses, courses and field sizes
- Finding every major in a season, or the latest completed events
- What is being played now and next, and who is defending
- A full leaderboard: finishing position (T5), cut, withdrew, score to par, strokes, each round, earnings, season points, playoff
- Which course or courses a tournament used, and the cut line

## When NOT to Use

- A player's career, season or results list -- see `player-scouting`
- How individual holes played, or a player's hole-by-hole card -- see `hole-scoring`
- Pre-tournament winner prices -- see `odds-explorer`
- Ranking players by form -- see `strokes-vs-field`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `list_tournaments` | A season's tournaments (ascending) or the latest (descending), filter by `status` and `major` | 1 |
| `get_schedule` | Tournaments in play or starting in the next `days` (default 30), with courses and defending champion | 1 |
| `get_leaderboard` | Every player in a tournament in finishing order, with rounds and strokes versus the field | 2 |
| `get_course` | Par and yards per hole and how each hole played (use after you have the id) | 2 |

All four take `league` (`golf`, `lpga`, `liv`, `dpwt`, `kornferry`); the default is `golf`.

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_tournament`, `get_event` | `list_tournaments` (the row has winner, purse, cut, courses); `get_leaderboard` for the field |
| `get_live_leaderboard` | Not available; data is next-morning |
| `get_tee_times`, `get_pairings`, `get_weather` | Not available |
| `get_team_results` | LIV has individual results only; team scores are not in the data |
| `search_tournaments` | `list_tournaments` with `season`, `status`, `major` |

## How It Works

**Step 1: Resolve the tournament id.** Ids are strings like `"401580344"`. Never guess one.

```
list_tournaments {"season": 2024, "major": true}
```

Each row has `tournament_id`, `name`, `start_date`, `status`, `major`, `purse`, `field_size`, `cut_round`, `cut_score`, `cut_count`, `winner_name`, `winning_to_par`, `winning_strokes` and `courses[]` (with `course_id`, `par`, `yards`, `host`).

For "what is on now", use the schedule instead:

```
get_schedule {"days": 14}
```

Rows carry `status` (`live` or `scheduled`) and `defending_champion`.

**Step 2: Read the leaderboard.**

```
get_leaderboard {"tournament_id": "401580344", "limit": 5}
```

Real response shape (trimmed, 2024 Masters):

```
tournament: Masters Tournament, field_size 89, cut_count 50, winner Scottie Scheffler (-11, 277)
players[0]: position 1, status finished, to_par -11, total_strokes 277, earnings 3600000, cup_points 750
  rounds: R1 66 (vs_field 7.43), R2 72 (3.08), R3 71 (3.3), R4 68 (4.48)
```

`vs_field` on a round is the fiel

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

View saved version →

---
name: tournament-preview
description: "Builds a pre-tournament preview for a golf event: the course and its setup, the field's best players on rating and recent form, course record for the contenders, par-type strengths that suit the holes, and for the four men's majors the winner prices side by side. Use when the user asks for a preview of the Masters, PGA Championship, U.S. Open, Open Championship or any PGA Tour, LPGA, DP World Tour or Korn Ferry event, who the contenders are, or what to watch. Do not use for a single lookup -- see tournament-lookup or player-scouting."
metadata:
  version: 1.0.0
  author: BirdieAPI
---

# Tournament Preview

> **Default data tool:** BirdieAPI (`birdieapi-tool`).
> A preview is a compound skill that loads several tools. Budget about 40 to 60 credits. State the plan and the cost before pulling.

You are an expert golf analyst writing a preview. Your goal is a one-page read of who is playing well, who has a record here, what the course rewards, and (for majors) what the market thinks, with every claim sourced to a call and every caveat stated.

## When to Use

- "Preview this week's event."
- "Who are the contenders at the PGA Championship?"
- "Does the course suit a long hitter?" (the data supports par-type and hole-level reads, not driving distance by shot)

## When NOT to Use

- One fact (who won, a player's id) -- see `tournament-lookup`, `player-scouting`
- Win probabilities -- see `outright-model`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_schedule` | The event, dates, course, defending champion | 1 |
| `list_tournaments` | A prior edition's `tournament_id`, and cut data | 1 |
| `get_course` | The course as set up in a prior edition (par, yards, how each hole played) | 2 |
| `get_ratings` | Who is playing best, with `as_of` for a past preview | 2 |
| `get_course_history` | Contenders' record at the event | 5 each |
| `get_player_stats` | Par-type splits and ball-striking lines for a contender | 5 each |
| `get_head_to_head` | Two contenders against each other | 5 |
| `get_winner_odds` | Majors only: prices by book | 5 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_field`, `get_entry_list` | Not available for an upcoming event; use the priced golfers (majors) or ask the user |
| `get_tee_times`, `get_pairings`, `get_weather` | Not available; say so |
| `get_preview`, `get_picks` | Compose it from the calls above |
| `get_odds` for non-majors | Not available; ask for the user's lines |

## How It Works

**Step 1: Identify the event and the course.**

```
get_schedule {"days": 14}
```

Rows give `tournament_id`, `start_date`, `status`, `courses[]` and `defending_champion`. For a past preview, use `list_tournaments` with the season.

**Step 2: Describe the course from the last edition.** The current week's setup is not published before play, so use the most recent edition on the same course.

```
get_course {"tournament_id": "401580344"}
```

Real response (2024 Masters): Augusta National, par 72, 7,555 yards, 298 rounds, scoring average 73.91. Hole 11 (par 4, 520 yards) ranked 1 in difficulty with a bogey rate of 0.2852; hole 13 (par 5, 545 yards) played to 4.758 with a birdie rate of 0.3624. Summarise: the hardest five holes, the number of par 5s that played under par, and the spread between the easiest and hardest. See `hole-scoring`.

**Step 3: Who is playing well.**

```
get_ratings {"as_of": "2024-04-04", "limit": 30}
```

Use `as_of` the day before play for a past preview so nothing after the event leaks in. For a live preview omit `as_of`. Real top of the list for the 2024 Masters:

```
1  Scottie Scheffler  2.88 (119 weighted rounds)
2  Jon Rahm           2.58 (114)
3  Xander Schauffele  2.48 (115)
4  Rory McIlroy       2.41 (91)
5  Patrick Cantlay    2.19 (101)
```

**Step 4: Course record for the top 6 to 10.**

```
get_course_history {"player_id": "9478", "to

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

View saved version →

---
name: walk-forward-validation
description: "Validates golf models in time order: expanding-window splits by tournament date, tournament-grouped evaluation, point-in-time ratings, metrics for round scores, made cut, top 10 and winner probabilities, a market baseline, and significance checks with the small number of majors. Use when the user asks how to test a golf model, whether k-fold is okay, how to split by season, how to avoid leakage, or how to compare a model with devigged winner odds. Do not use for building features -- see feature-engineering. Do not use for probability reliability plots -- see probability-calibration."
metadata:
  version: 1.0.0
  author: BirdieAPI
---

# Walk-Forward Validation

> **Default data tool:** BirdieAPI (`birdieapi-tool`).
> Validation is computation on data you already pulled. The calls that matter are `get_ratings` with `as_of` (2 credits per date), `get_leaderboard` (2) and `get_winner_odds` (5) for the market baseline.

You are an expert in honest model evaluation. Golf makes it easy to fool yourself: one winner per event, a few dozen majors with prices, strong dependence within a tournament and ratings that quietly include the future if you let them. Your goal is a test whose number you would stand behind.

## When to Use

- "Can I use k-fold cross-validation on golf results?" (No.)
- "How do I split train and test?"
- "Does my model beat the market?"
- "How many majors do I need before this is meaningful?"

## When NOT to Use

- Feature construction -- see `feature-engineering`
- Reliability diagrams and scaling -- see `probability-calibration`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_ratings` | Point-in-time rating via `as_of` | 2 |
| `get_leaderboard` | Outcomes: finish, cut status, rounds | 2 |
| `get_winner_odds` | Market baseline for majors from 2021 | 5 |
| `list_tournaments` | The calendar and `major` flag, for ordering and subsets | 1 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_predictions` | Not served; the model is yours |
| `get_historical_odds` for non-majors | Not available; only majors have prices |
| `get_closing_line` | The latest pregame snapshot, which can be a week early for past majors |

## Rules

1. **Time order only.** Train on events before a date, test on events after. Never shuffle, never k-fold.
2. **Group by tournament.** All rows of one tournament go in the same fold. Within an event, results are dependent (one winner, shared course and weather).
3. **Point-in-time inputs.** Ratings with `as_of` the day before round 1. Season stats from the prior season. Course history from earlier editions.
4. **Freeze choices before testing.** Features, hyperparameters, `sigma` and `tau` are set on the training window.
5. **Compare against baselines.** At least the rating alone, and the devigged market where it exists.

## How It Works

**Step 1: Build the event list.**

```
list_tournaments {"season": 2023, "status": "final"}
```

Repeat per season and sort by `start_date`. Add `"major": true` for the majors only.

**Step 2: Choose a scheme.** An expanding window by season is the default:

| Fold | Train | Test |
|------|-------|------|
| 1 | 2015-2020 | 2021 |
| 2 | 2015-2021 | 2022 |
| 3 | 2015-2022 | 2023 |
| 4 | 2015-2023 | 2024 |
| 5 | 2015-2024 | 2025 |

Rating-based models need little training data. The window mostly serves to fit `sigma`, `tau`, the shrinkage constant `k` from `course-fit` and any blend weight with the market.

**Step 3: Pick metrics by target.**

| Target | Metric | Notes |
|--------|--------|-------|
| Round `adj_vs_field` | RMSE, MAE | baseline: the golfer's rating |
| Made cut | log loss, AUC | thousands of rows |
| Top 10 | log loss, Brier | hundreds of positives |
| Winner | log loss over the field | one positive per event |

For winners, the score of one event is `-log(p_winner)`. Average over events.

```python
im

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