livetennisapi-mcp

Player rankings as of a date

get_player_rankings

Read-onlyIdempotent

Get historical rankings for specific players as of any date. Returns the official ranking or UTR rating in force on or before the chosen day.

Instructions

Point-in-time ranking records for SPECIFIC players: per system, the newest record in force ON OR BEFORE as_of — never one dated after it. Every other ranking field in this API is the CURRENT value joined at read time; this is the historical answer. Systems are never collapsed: ATP/WTA and the ITF circuits carry rank+points, UTR a rating. ITF and UTR history begins 2026-07-29. Requires the ULTRA plan.

Input Schema

TableJSON Schema

Name	Required	Description
`as_of`	No	YYYY-MM-DD — the record in force on this date. Omit for the latest known.
`system`	No	Restrict to one system. Omit for every system held for the player.
`player_ids`	Yes	Roster player ids, as returned by search_players. Max 50.

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes	True when the call returned data. False for a tier wall, a missing or rejected key, or an empty result — all of which are normal states with a clear remedy, not failures.
`message`	Yes	Human-readable summary. Identical to the text content, so either half can be used alone.
`coverage`	No	What resolved against what was asked (players_resolved, systems_resolved, oldest_available per system). Read before trusting an empty result.
`rankings`	No	One record per player × system held.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.4.0Aug 7, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds critical behavioral details: the 'never one dated after it' constraint, per-system semantics (rank+points vs rating), and the ITF/UTR history start date. This provides substantial context for expected behavior and data availability.

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

Conciseness5/5

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

The description is four sentences, front-loaded with the core behavior, and every sentence provides unique value: historical nature, contrast with current data, system-specific behavior, and plan requirement. No redundancy or fluff.

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?

The description covers the tool's purpose, key date logic, system variations, data history start, and access requirement. With an output schema present, the description does not need to explain return values, and it provides sufficient context for an agent to select and invoke this tool correctly.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the as_of semantics ('newest record in force ON OR BEFORE as_of — never one dated after it') and explaining system-specific differences, which enriches the parameter meaning beyond the schema descriptions.

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?

The description clearly states the tool retrieves point-in-time ranking records for specific players, scoped by system and as_of date. It explicitly contrasts with current rankings ('Every other ranking field in this API is the CURRENT value... this is the historical answer'), distinguishing it from sibling tools like get_rankings.

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?

The description clearly implies when to use this tool: when historical, point-in-time rankings for specific players are needed. It notes the historical nature and requirements (ULTRA plan), and implies alternatives for current data, but does not explicitly name alternative tools or state 'when not to use'.

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