Match Lookup

Default data tool: AcesAPI (acesapi-tool). Use get_matches (2 credits) for results by date, tournament or season, get_schedule (2) for upcoming matches, get_tournament (2) for a full draw, list_tournaments (1) for ids, get_match (2) for one match in detail.

You find tennis matches and read them correctly. Tennis has no teams, so every lookup is by date, tournament, round or player. Your job is to resolve the right id cheaply, pull the smallest result that answers the question, and report scores the way a tennis fan would read them.

When to Use

• "Who won the Wimbledon final?" "What was the score?"
• "Who plays today?" "What is on the schedule this week?"
• "Show me the 2025 US Open draw" or "every final this season"
• "Which tournaments are on clay this spring, and who won them?"
• "Did the match go five sets?" "Were there tiebreaks?"

When NOT to Use

• A player's career, ratings or form: see player-scouting
• Two players against each other: see head-to-head-analysis
• Lines and prices for a match: see odds-explorer
• Building a full pre-match brief: see match-preview

Commands Available

Commands That Do NOT Exist

How It Works

Step 1: Resolve the target.

Step 2: Pull the narrowest result.

• One day of results: get_matches {"date": "2025-07-13"}
• One tournament's final: get_matches {"tournament_id": "188-2025", "round": "Final"}
• All finals of a season: get_matches {"season": 2025, "round": "Final", "limit": 100}
• The whole draw: get_tournament {"tournament_id": "188-2025"} (draw: "all" adds qualifying, available from 2022)

Step 3: Read the score.

score is a string such as 4-6 6-4 6-4 6-4 or 7-6(5) 6-3. In a set decided by a tiebreak the number in brackets is the loser's tiebreak points. sets[] has the same information as numbers: games1, games2, tiebreak1, tiebreak2, winner (1 or 2). Player 1 and player 2 are positions in the record, not seeds or favorites.

Step 4: Check outcome before counting anything. A real response for a walkover looked like this (trimmed): "outcome": "walkover", "score": "w/o", "sets": []. Retirements, defaults and walkovers have partial or empty set data. Count a match as played only when outcome is completed, and say so when you drop rows.

Step 5: Report. Lead with the answer, then the context: tournament, surface, round, score, and one line on what the score says (straight sets, five sets, tiebreaks, a comeback). get_match gives stats.went_the_distance and stats.winner_lost_first_set directly.

Worked Example

User: "Who won the 2025 Wimbledon final and how?"

1. list_tournaments {"season": 2025, "surface": "grass"}     -> 1 credit, find "188-2025"
2. get_matches {"tournament_id": "188-2025", "round": "Final"} -> 2 credits

Real record (trimmed): Jannik Sinner (seed 1) beat Carlos Alcaraz (seed 2) 4-6 6-4 6-4 6-4, Centre Court, grass. Answer: "Sinner won in four sets after dropping the first (22 games to 18, no tiebreaks). It was the Wimbledon final of 2025 on grass." Total cost: 3 credits.

Season Logic

• "Last season" is the previous calendar year. A tournament edition belongs to the year it starts.
• Two events can share a week. A date query returns all of them; group by tournament before summarizing.
• status values are scheduled, live, final. A match with status: "final" and outcome: "walkover" is final but unplayed.
• Rounds are named as the data lists them (seen in live responses: Round 1 to Round 4, Group Stage, Semifinal, Final). Pass the name exactly; if a filter returns nothing, read round from a get_tournament response. Use round_order to sort them (the Final is 22).
• Draw sizes vary by event (main_draw_matches in list_tournaments shows 27 to 31 for tour events). Do not assume a fixed number of rounds.

Credit Usage

Do not call get_match on every row of a day just to read a score. get_matches already returns score and sets. Use get_match only for ratings, stats or odds.

Anti-patterns

Output Format

[Tournament] [Year], [Surface], [Round]
[Winner] (seed) d. [Loser] (seed)  [score]
[One line: duration of the match in sets, tiebreaks, comeback, upset by seed or rating]

For a day of results, group by tournament and list matches by round_order, newest first.

What to Do Next