Update to BirdieAPI

{
  "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.",
  "included_files": [],
  "name": "course-fit",
  "skill_md_contents": "---\nname: course-fit\ndescription: \"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.\"\nmetadata:\n  version: 1.0.0\n  author: BirdieAPI\n---\n\n# Course Fit\n\n> **Default data tool:** BirdieAPI (`birdieapi-tool`).\n> `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.\n\nYou 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.\n\n## When to Use\n\n- \"How has Scottie Scheffler done at the Masters?\"\n- \"Who has the best record at Pebble Beach since 2010?\"\n- Comparing a field's course records before a tournament\n- Deciding how much weight course history gets in a model\n- Checking whether a hot player has a poor record at this venue\n\n## When NOT to Use\n\n- Current form or the rating -- see `strokes-vs-field`\n- Hole difficulty and setup -- see `hole-scoring`\n- Final probabilities -- see `outright-model`\n\n## Commands Available\n\n| Command | What It Does | Credits |\n|---------|-------------|---------|\n| `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 |\n| `get_course` | Par and yards per hole, how each hole played, for one tournament's course | 2 |\n| `list_tournaments` | Find the tournament id and `course_id` values | 1 |\n| `get_ratings` | The player's overall rating for the baseline | 2 |\n| `get_player_results` | Raw rounds if you want your own course filter | 5 |\n\n## Commands That Do NOT Exist\n\n| Not Available | Use Instead |\n|--------------|-------------|\n| `get_course_fit`, `get_fit_score` | Compute it from `get_course_history` and `get_ratings` as below |\n| A whole field's course history in one call | One `get_course_history` call per player; shortlist first |\n| `get_course_stats_by_year` | `get_course` per edition |\n| `get_course_conditions`, `get_weather` | Not available |\n\n## How It Works\n\n**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`.\n\n**Step 2: Pull the record.**\n\n```\nget_course_history {\"player_id\": \"9478\", \"tournament_id\": \"401580344\"}\n```\n\nReal response (trimmed), Scottie Scheffler at the Masters:\n\n```\nsummary: starts 7, wins 2, top_tens 5, made_cut 7, average_finish 7.9, vs_field 2.78\neditions: 2026  finish 2   vs_field 3.30   rounds 70 74 65 68\n          2025  finish 4   vs_field 2.68   rounds 68 71 72 69\n          2024  finish 1   vs_field 4.57   rounds 66 72 71 68\n          2023  finish T10 vs_field 2.01\n          2022  finish 1   vs_field 4.36\n          2021  finish T18 vs_field 1.23\n```\n\nHere `vs_field` is the player's average strokes versus the field per round at that event. Seven starts is 28 rounds.\n\n**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):\n\n```\nget_ratings {\"limit\": 50}\n```\n\nA simple fit measure for player `i` at event `e`:\n\n```\nfit_raw = mean(event vs_field) - overall level at the time of those rounds\n```\n\nFor a fair \"overall level\" use the rating as it stood before each edition (`get_ratings` with `as_of` per year), not today's rating. Using today's rating for a 2021 start leaks the future.\n\n**Step 4: Shrink.** Course history is a small sample. Blend it toward zero:\n\n```\nfit = n_rounds / (n_rounds + k) * fit_raw\n```\n\n`k` is the number of rounds at which course history deserves half weight. Do not hard-code one. Treat `k` as a parameter, fit it with `walk-forward-validation`, and report the value used. A starting assumption of a few dozen rounds is a guess, not a finding.\n\n**Step 5: Check what the fit is made of.** A record can come from the course's design (long par 5s, firm greens) or from a few hot weeks. Use `get_course` to profile the holes and `hole-scoring` to see whether the player's par-type split lines up with what the course rewards. If a course has four reachable par 5s and the player's `sg_par5` is elite, that is a mechanism. A good record with no mechanism is lower confidence.\n\n**Step 6: Treat course changes as breaks.** A course can be redesigned, or a tournament can move venues. `courses` is listed per edition; if the venue changed, split the record at the change. Do not mix.\n\n## How much does course history matter\n\nSay what is known and what is not. In general, course-specific skill exists in golf but is small relative to general skill, which is why shrinkage is the right default. The size for a given course and tour should be measured, not assumed: run the shrinkage fit on past editions with `walk-forward-validation` and see whether adding `fit` improves out-of-sample log loss on winners or on finishing scores. If it does not, drop it.\n\n## Credit Usage\n\n| Operation | Credits | Notes |\n|-----------|---------|-------|\n| One player's record at one event | 5 | |\n| Ten-player shortlist | 50 | |\n| Whole field of 90 | 450 | do not; shortlist by rating first |\n| Baseline ratings at one date | 2 | |\n\n## Anti-patterns\n\n| What the Model Might Do | Why It's Wrong | Do This Instead |\n|---------------------|---------------|-----------------|\n| Rank players by average finish at the course | Finish depends on field size and luck | Use `vs_field` per round |\n| Add course history without a baseline | It double-counts general skill | Subtract the overall level first |\n| Use today's rating as the baseline for a 2019 start | Leakage | `as_of` before each edition |\n| Trust 2 starts | 8 rounds is noise | Shrink and show `n_rounds` |\n| Ignore a venue move | Different course | Split the record |\n| Call a player a \"course horse\" on one win | One week of luck | Require multiple editions |\n\n## Output Format\n\n```\nScottie Scheffler at the Masters (Augusta National), 7 starts\nWins 2, top tens 5, average finish 7.9, strokes versus the field +2.78 a round.\nBaseline rating before each start: see get_ratings as_of.\nShrunk fit estimate: +X.XX a round (n = 28 rounds, k = <value used>)\n```\n\n## What to Do Next\n\n| What You Found | Next Action | Skill |\n|----------------|-------------|-------|\n| A fit number per golfer | Feed it into a win model | `outright-model` |\n| A mechanism question | Look at hole splits | `hole-scoring` |\n| Fit used as a feature | Check for leakage | `feature-engineering` |\n| Want to validate the weight | Out-of-sample test | `walk-forward-validation` |\n"
}