livetennisapi-mcp

Player record and splits

player_stats

Read-onlyIdempotent

Get a tennis player's win-loss record across completed singles matches, with splits by surface, venue, level, season and tiebreaks. Supports custom date windows.

Instructions

One player's record over completed singles matches from 2023 onward, by default the last 365 days. It gives W/L overall, over the last 12 months and by surface, venue, level and season. It also gives tiebreaks, deciding sets, the record after winning or losing the first set, comebacks, withdrawals and the last N matches. Every count carries its sample size, and a percentage on an empty sample is null, never 0. On ULTRA it adds serve_return: measured serve and return statistics summed over the window. Singles only, so a doubles-team id is refused. For 1968 to 2022 use get_archive_career. Requires the PRO plan (serve_return requires ULTRA).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "player_id": "<player_id>"
    },
    "name": "player_stats"
  }
}

Input Schema

Name	Required	Description
`to`	No	Window end: YYYY-MM-DD (the whole of that day) or a UTC ISO-8601 instant. Default now.
`from`	No	Window start: YYYY-MM-DD (start of that day) or a UTC ISO-8601 instant. Default to minus 365 days.
`last`	No	How many recent matches to list, newest first (1-50, default 20).
`level`	No	The match tour. A match with no stated tour matches no level.
`surface`	No	hard, clay or grass read the match surface; indoor keeps matches stated indoor, on any surface.
`player_id`	Yes	Player id, as returned by search_players.

Output Schema

Name	Required	Description
`ok`	Yes	True when the request succeeded, including when the answer is an empty list. False for a missing or rejected key, a plan that does not include this data, an unknown id, a rate limit or a network error. The message then says what to do. check_api_status is the exception: it is true whenever the API answered, and reports API key problems in the message.
`sets`	No	Set-based record: sample, tiebreaks, deciding_sets, after_winning_first_set, after_losing_first_set, comebacks, sets.
`player`	No	The player.
`recent`	No	The last N matches, newest first.
`window`	No	The window applied, UTC.
`message`	Yes	Human-readable summary of the result, safe to relay to the user verbatim.
`overall`	No	W/L over the window.
`by_level`	No	W/L keyed by match tour, or unknown.
`by_venue`	No	W/L keyed indoor, outdoor, unknown.
`by_season`	No	W/L keyed by UTC calendar year.
`by_surface`	No	W/L keyed hard, clay, grass, unknown.
`withdrawals`	No	Retired / walkover / default, each as given (this player) and received (the opponent).
`serve_return`	No	ULTRA only, null below: summed serve and return statistics, each ratio as numerator/denominator/pct with its match count.
`last_12_months`	No	W/L over the 12 months ending at the window end.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.6.5Nov 1, 2026

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish the read-only, idempotent, safe profile, and the description adds substantive context beyond them: tier gating (PRO/ULTRA), the ULTRA-only serve_return block, refusal of doubles-team ids, and the null-vs-zero convention for empty samples. Sample-size disclosure per count is the kind of behavioral detail an agent cannot get from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the object and scope, then progressively adds splits, semantics, tier gates, and the archive cross-reference. It is dense but nearly every clause carries information; the enumeration of stat families is slightly listy but justified for a stats tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter, plan-gated stats endpoint with an output schema, the description covers scope, defaults, exclusions, tier behavior, and edge-case value semantics. Return formatting is delegated to the output schema appropriately, so nothing an agent needs to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already documents defaults, enum semantics (including that indoor keeps any surface), and the 1-50 range for `last`. The description's 'last N matches' and the mention of surface/venue/level/season splits add only modest framing beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (one player's record over completed singles matches) with a clear temporal scope (2023 onward, default last 365 days) and enumerates the splits it returns. It also explicitly disambiguates from the archive sibling: 'For 1968 to 2022 use get_archive_career.' An agent can distinguish this from get_player, get_h2h, and get_archive_career without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit alternative and the condition that selects it (pre-2023 → get_archive_career), plus plan prerequisites (PRO required, serve_return requires ULTRA) and a hard exclusion (doubles-team ids refused). It stops short of routing against other adjacent siblings such as get_player or get_charting_player, so usage is clear but not fully exhaustive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.