Update to AcesAPI

{
  "description": "Head-to-head analysis for two tennis players: wins each, sets won, record by surface and in finals, every meeting with its score, and how much weight a small head-to-head deserves. Use when the user asks who leads a rivalry, how two players match up on a surface, or whether a past result predicts the next one. Do not use for a player's overall profile: see player-scouting. Do not use for win probabilities from ratings: see surface-elo. Do not use for the pre-match brief that combines everything: see match-preview.",
  "included_files": [],
  "name": "head-to-head-analysis",
  "skill_md_contents": "---\nname: head-to-head-analysis\ndescription: \"Head-to-head analysis for two tennis players: wins each, sets won, record by surface and in finals, every meeting with its score, and how much weight a small head-to-head deserves. Use when the user asks who leads a rivalry, how two players match up on a surface, or whether a past result predicts the next one. Do not use for a player's overall profile: see player-scouting. Do not use for win probabilities from ratings: see surface-elo. Do not use for the pre-match brief that combines everything: see match-preview.\"\nmetadata:\n  version: 1.0.0\n  author: AcesAPI\n---\n\n# Head-to-Head Analysis\n\n> **Default data tool:** AcesAPI (`acesapi-tool`).\n> `get_head_to_head` (3 credits) returns the whole record: summary and every meeting. `search_players` (1) resolves the two ids. `get_player_matches` with `opponent_id` (5) adds ratings at the time of each meeting.\n\nYou read a rivalry honestly. A head-to-head is a tiny sample, often confounded by surface, age and form at the time. Report the record, then say how much it should move a forecast, which is usually very little once ratings are known.\n\n## When to Use\n\n- \"Who leads Sinner against Alcaraz?\"\n- \"How do they split on clay?\"\n- \"Has she ever beaten her in a final?\"\n- \"Does the head-to-head matter for tomorrow?\"\n\n## When NOT to Use\n\n- One player only: see `player-scouting`\n- The probability from ratings: see `surface-elo`\n- A full pre-match brief with prices: see `match-preview`\n\n## Commands Available\n\n| Command | What It Does | Credits |\n|---------|-------------|---------|\n| `search_players` | Resolve each name to a `player_id` | 1 |\n| `get_head_to_head` | `summary` (matches, wins, sets, `by_surface`, `in_finals`, walkovers) and `matches[]` | 3 |\n| `get_player_matches` | Use `opponent_id` to get one player's meetings with `rating_before` for each | 5 |\n| `get_match` | Detail on one meeting: sets, tiebreak points, ratings | 2 |\n| `get_ratings` | Current ratings for context | 2 |\n\n## Commands That Do NOT Exist\n\n| Not Available | Use Instead |\n|--------------|-------------|\n| `get_h2h` | `get_head_to_head` |\n| `get_rivalry` | `get_head_to_head` plus the method below |\n| `get_head_to_head_odds` | Not available: pull `get_match` for the upcoming match |\n\n## How It Works\n\n**Step 1: Resolve both ids.** `search_players {\"name\": \"sinner\"}` returns `\"player_id\": \"3623\"`; `search_players {\"name\": \"alcaraz\"}` returns `\"3782\"`. Add `league: \"wta\"` for the WTA. Both players must be on the same tour.\n\n**Step 2: One call.** `get_head_to_head {\"player_id\": \"3623\", \"opponent_id\": \"3782\"}`.\n\nReal output (trimmed), `summary` as returned:\n\n```json\n{\"matches\": 17,\n \"wins\": {\"3623\": 7, \"3782\": 10},\n \"sets_won\": {\"3623\": 25, \"3782\": 26},\n \"by_surface\": {\"clay\": {\"3623\": 2, \"3782\": 3},\n                \"hard\": {\"3623\": 3, \"3782\": 7},\n                \"grass\": {\"3623\": 2, \"3782\": 0}},\n \"in_finals\": {\"3623\": 4, \"3782\": 5},\n \"walkovers\": 0}\n```\n\nKeys of `wins` and `by_surface` are `player_id` strings. Map them to names before writing the answer.\n\n**Step 3: Read the matches.** `matches[]` is newest first. In the live response, the latest meeting was the 2026 Monte-Carlo Masters final on clay, `7-6(5) 6-3` for Sinner, and the one before it the 2025 Nitto ATP Finals final (indoor hard), `7-6(4) 7-5` for Sinner. Report recency: a record of 10-7 where the leader lost the last two is a different story from 10-7 the other way.\n\n**Step 4: Weigh it.** Compute the rivalry as a sample, not a fact.\n\n## Method: How Much Should a Head-to-Head Count?\n\nA rivalry record of `a` wins to `b` wins is `n = a + b` observations of a process the ratings already summarize. Use it as a small adjustment:\n\n```\nP_h2h_shrunk = (a + m * P_rating) / (n + m)        # m = prior strength, try 10\n```\n\nwhere `P_rating` is the pre-match probability from `surface-elo` and `m` expresses how many matches' worth of weight the rating gets. At 10-7 and `P_rating = 0.50` with `m = 10`, the shrunk estimate is `(10 + 5) / 27 = 0.56` for the leader, not 10/17 = 0.59. With `n = 3` it barely moves. Pick `m` by out-of-sample log loss; if you cannot test it, state that `m` is a judgment call.\n\nBetter still, check whether the head-to-head adds information beyond ratings: regress the result of each meeting on the pre-match rating gap and a prior-meeting-record feature, in time order (see `walk-forward-validation`). In most datasets the second feature adds little.\n\n## What Makes a Rivalry Misleading\n\n- **Surface mix.** The 17 meetings above are spread over hard (10), clay (5) and grass (2). A hard-court lead says little about a clay match.\n- **Time.** Meetings years ago involved younger versions of both players. Weight recent meetings, or use `rating_before` per meeting to see how mismatched each one was.\n- **Format.** Slam meetings are best of five for men. Finals are a small subset that often involve two players in form.\n- **Retirements and walkovers.** The tool lists walkovers but does not count them as wins. A retirement is counted if sets were recorded; read the `outcome` of the meeting.\n- **Sample size.** With under about 8 meetings, any split is within noise. The Wilson interval for 10 of 17 is roughly 0.36 to 0.78.\n\n## Worked Example\n\nUser: \"How do Sinner and Alcaraz compare on clay?\"\n\n```\n1. get_head_to_head {\"player_id\": \"3623\", \"opponent_id\": \"3782\"}      -> 3 credits\n2. get_ratings {\"surface\": \"clay\", \"limit\": 10}                       -> 2 credits\n```\n\nClay record: Alcaraz 3, Sinner 2. Clay ratings from the live call: Alcaraz 2247 (121 clay matches), Sinner 2209 (106). Rating gap 38 points gives Alcaraz about 55 percent on clay. The record, five matches, agrees in direction and adds almost nothing. The most recent clay meeting went to Sinner, in straight sets. The honest summary: a coin flip with a small lean to Alcaraz, and the head-to-head is too small to change it. Total cost: 5 credits.\n\n## Credit Usage\n\n| Operation | Credits |\n|-----------|---------|\n| Resolve two ids | 2 |\n| Head to head | 3 |\n| Ratings context | 2 to 10 |\n| Per-meeting ratings via `get_player_matches` | 5 |\n\n## Anti-patterns\n\n| What the Model Might Do | Why It's Wrong | Do This Instead |\n|---------------------|---------------|-----------------|\n| Say \"he owns her\" off a 3-1 record | n = 4 | Report the record and say it is a small sample |\n| Mix tours | Ids differ and the players never meet | Same `league` for both |\n| Ignore surface | A grass record does not transfer to clay | Use `by_surface` |\n| Count walkovers as wins | They are not counted by the tool | Use the summary |\n| Use the record as the probability | Ignores everything else | Shrink toward the rating probability |\n\n## Output Format\n\n```\n[A] vs [B]: [a]-[b] overall ([n] matches)\nBy surface: hard [x]-[y], clay [x]-[y], grass [x]-[y]\nIn finals: [x]-[y]\nLast 3: [date] [tournament] [winner] [score] ...\nWeight: [low / moderate], because [sample, surface mix, recency]\n```\n\n## What to Do Next\n\n| What You Found | Next Action | Skill |\n|----------------|-------------|-------|\n| A clear surface split | Check surface ratings | `surface-elo` |\n| A decision on an upcoming match | Build the brief | `match-preview` |\n| A head-to-head feature idea | Add it with a time guard | `feature-engineering` |\n"
}