Update to BirdieAPI

{
  "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.",
  "included_files": [],
  "name": "strokes-vs-field",
  "skill_md_contents": "---\nname: strokes-vs-field\ndescription: \"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.\"\nmetadata:\n  version: 1.0.0\n  author: BirdieAPI\n---\n\n# Strokes Versus the Field\n\n> **Default data tool:** BirdieAPI (`birdieapi-tool`).\n> `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`.\n\nYou 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.\n\n## What these numbers are\n\n- **`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.\n- **`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.\n- **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.\n- 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.\n\nThe 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.\n\n## When to Use\n\n- Who is playing best right now, or was on a past date (`as_of`)\n- Comparing two players from different schedules\n- Measuring a player's form over the last N rounds\n- Ranking a season on a stat\n- Explaining to a user what \"+2.0\" means\n\n## When NOT to Use\n\n- Hole-type splits (`sg_par3`, `sg_par4`, `sg_par5`) -- see `hole-scoring`\n- A single player profile -- see `player-scouting`\n- Win probabilities -- see `outright-model`\n\n## Commands Available\n\n| Command | What It Does | Credits |\n|---------|-------------|---------|\n| `get_ratings` | Rating for every player active in the past year, best first. `limit`, `as_of`, `min_rounds`, `league` | 2 |\n| `get_player_results` | Each tournament with every round's `field_avg`, `vs_field`, `adj_vs_field` | 5 |\n| `get_leaders` | Season leaders on `vs_field`, `adj_vs_field`, `scoring_average` and other stats, with sample | 5 |\n| `get_leaderboard` | Per-round `vs_field` for a whole tournament field | 2 |\n\n## Commands That Do NOT Exist\n\n| Not Available | Use Instead |\n|--------------|-------------|\n| `get_strokes_gained` | `get_ratings` or `get_leaders` with `stat` `adj_vs_field` |\n| `get_sg_ott`, `get_sg_app`, `get_sg_putt` | Not available; no shot data |\n| `get_world_ranking` | `get_ratings` |\n| `get_ratings_history` | Call `get_ratings` with different `as_of` dates |\n\n## How It Works\n\n**Step 1: Rank the tour.**\n\n```\nget_ratings {\"limit\": 5}\n```\n\nReal response (trimmed, as of 2026-10-04):\n\n```\n1  Scottie Scheffler    3.31   weighted_rounds 133.1\n2  Rory McIlroy         2.39   weighted_rounds  96.8\n3  Tommy Fleetwood      2.19   weighted_rounds 119.8\n4  Xander Schauffele    2.18   weighted_rounds 122.5\n5  Collin Morikawa      2.05   weighted_rounds 114.9\n```\n\n`weighted_rounds` is the decay-weighted sample behind the rating. A rating on 30 weighted rounds is much softer than one on 130. Raise `min_rounds` to drop thin ratings (default 20).\n\n**Step 2: Rank on a past date.** Use `as_of` to avoid hindsight:\n\n```\nget_ratings {\"as_of\": \"2024-04-01\", \"limit\": 3}\n```\n\n\n**Step 3: Look at the rounds.**\n\n```\nget_player_results {\"player_id\": \"9478\", \"season\": 2025, \"limit\": 2}\n```\n\nReal round (Hero World Challenge, 20-player field): strokes 66, `field_avg` 69.05, `vs_field` 3.05, `adj_vs_field` 4.46. The adjusted number is higher because that field is stronger than an average tour field, so beating it counts for more. The raw number alone would understate the round.\n\n**Step 4: Form.** Use `adj_vs_field` and weight recent rounds. A simple form figure:\n\n```python\nimport numpy as np\ndef form(rounds, half_life=8):\n    # rounds: adj_vs_field values, oldest first\n    w = 0.5 ** (np.arange(len(rounds))[::-1] / half_life)\n    return float(np.sum(w * rounds) / np.sum(w))\n```\n\nReport the number of rounds. Eight rounds is two tournaments; the standard deviation of a golfer's single round is large (typically 2 to 3 strokes), so form on eight rounds has a standard error near 1 stroke. Estimate the standard deviation from the user's own `get_player_results` pull rather than quoting a constant.\n\n**Step 5: Compare within a tour only.** LPGA, LIV, DP World Tour, Korn Ferry and the PGA Tour each rate against their own fields. A 3.18 on the LPGA (Jeeno Thitikul, Nelly Korda in the live check) is not comparable to a 3.31 on the PGA Tour. For cross-tour questions use shared events, such as the majors, via `get_head_to_head`.\n\n**Step 6: Leaders.**\n\n```\nget_leaders {\"stat\": \"adj_vs_field\", \"season\": 2025, \"limit\": 10, \"min\": 40}\n```\n\n`min` is the minimum rounds (default 40) for round-based stats. Report `sample` beside each name.\n\n## Pitfalls\n\n| Pitfall | Why it bites |\n|---------|--------------|\n| Using raw `vs_field` across events | A weak field flatters it; use `adj_vs_field` |\n| Treating the rating as skill with no error | It is shrunk, decayed and noisy; show `weighted_rounds` |\n| Mixing seasons without `as_of` | Today's rating is leaked into the past |\n| Comparing LIV and PGA Tour ratings | Different fields; players with majors in both can be compared on those |\n| Calling it \"strokes gained\" | It is a score-based strokes-versus-field rating |\n| Reading 0.1-stroke gaps as real | Rank ties inside the noise band |\n\n## Credit Usage\n\n| Operation | Credits | Notes |\n|-----------|---------|-------|\n| Top-50 ratings | 2 | one call |\n| Ratings at five past dates | 10 | for a trend |\n| One player's season of rounds | 5 | |\n| Season leaders on one stat | 5 | |\n\n## Output Format\n\n```\nRatings as of 2026-10-04 (PGA Tour, strokes versus the field per round, field-strength adjusted)\n1. Scottie Scheffler  +3.31  (133 weighted rounds)\n2. Rory McIlroy       +2.39  (97)\nScore-based, not shot-level strokes gained. Measured within the PGA Tour.\n```\n\n## What to Do Next\n\n| What You Found | Next Action | Skill |\n|----------------|-------------|-------|\n| A ranked list | Turn into win probabilities | `outright-model` |\n| Form and rating for a player | Full scouting note | `player-scouting` |\n| Want hole-type detail | Par 3/4/5 splits | `hole-scoring` |\n| Inputs for a model | Build features | `feature-engineering` |\n"
}