Cito API

player_rankings_history

Read-only

Tennis player ranking trajectory: every published ranking date for one player, plus career-high and weeks at No.1.

When to use:

"Show Alcaraz's ranking over time"; career-high rank and when it was reached; how a player climbed; plotting a rank chart.

Prefer over: standings (latest snapshot only); rankings_movers (week-over-week delta for a whole tour); player_profile (has career-high but no per-date series).

Do not use when: the current top-N table → standings with game tennis.

Tennis-only. Rows arrive oldest-first (chronological), which is the order a chart wants; the newest entries are the tail. limit keeps the most RECENT N rows (the route itself ignores ?limit=, so the bound is applied here) — hasMore and oldestReturned/newestReturned say exactly which window came back, and omittedOlder counts the rows left behind at the old end.

Parallel-safe: yes. Upstream cost: 1.

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": {
      "game": "<game>",
      "playerId": "<playerId>"
    },
    "name": "player_rankings_history"
  }
}

Input Schema

Name	Required	Description
`game`	Yes	Game title: lol \| cs2 \| dota2 \| cod \| ufc \| tennis \| valorant. Example: "cs2".
`limit`	No	Max history rows (default 20, max 500).
`since`	No	Only rows on or after this date (YYYY-MM-DD).
`playerId`	Yes	Tennis player id, e.g. "atp_207989" or "wta_214544".

Output Schema

Name	Required	Description
`ok`	Yes	true if the tool succeeded
`data`	No	Result payload when ok is true; null on error
`meta`	Yes
`error`	No
`partial`	No
`pagination`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedNov 14, 2026

changedInput schema / properties / game / description

Previous value: -"Game title: lol | cs2 | dota2 | cod | ufc | tennis. Example: \"cs2\"."New value: +"Game title: lol | cs2 | dota2 | cod | ufc | tennis | valorant. Example: \"cs2\"."

changedInput schema / properties / game / enum

Previous value: -[
-  "lol",
-  "cs2",
-  "dota2",
-  "cod",
-  "ufc",
-  "tennis"
-]New value: +[
+  "lol",
+  "cs2",
+  "dota2",
+  "cod",
+  "ufc",
+  "tennis",
+  "valorant"
+]

removedInput schema / properties / page

Removed value: -{
-  "default": 1,
-  "description": "Page from the newest end (1 = the most recent limit rows).",
-  "minimum": 1,
-  "type": "integer"
-}

Changed1 schema field changedNov 3, 2026

addedInput schema / properties / page

Added value: +{
+  "default": 1,
+  "description": "Page from the newest end (1 = the most recent limit rows).",
+  "minimum": 1,
+  "type": "integer"
+}

AddedSep 12, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations cover only read-only/no-destroy, but the description discloses real behavioral quirks beyond them: rows are chronological oldest-first, limit keeps the most RECENT N because the upstream route ignores ?limit=, and hasMore/oldestReturned/newestReturned/omittedOlder describe the returned window. It also states parallel-safety and upstream cost, which matter for call planning.

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 one-line purpose followed by labeled when-to-use / prefer-over / do-not-use blocks, then behavioral notes — easy to scan. Slightly verbose in the parenthetical asides (e.g. 'which is the order a chart wants') and the windowing sentence is dense, but nothing is truly wasted.

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 4-parameter read tool with an output schema, the description covers selection, ordering, truncation semantics, and the flags that describe the returned window. Nothing an agent needs to call this correctly or interpret the window is missing.

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, but the description adds genuinely non-obvious meaning about limit — that it truncates from the newest end rather than the start of the series. game restrictions (tennis-only) are reinforced too; since and playerId add nothing beyond the schema.

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 (per-date ranking trajectory for one tennis player) plus the derived facts returned (career-high, weeks at No.1), and explicitly separates it from standings, rankings_movers and player_profile. An agent can route between these 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 Guidelines5/5

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

Gives concrete when-to-use phrasings, an explicit 'prefer over' list with a stated reason for each alternative (standings = latest snapshot, movers = week-over-week delta for a whole tour), and a 'do not use when' case that routes to standings. Full when/when-not/alternatives coverage.

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

All Cito API tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?