Tools: Players
The Players tools your agent sees through Elixir MCP: what each one answers, what it takes, and which capability it needs.
Players
9 of the 55 tools in the registry. Generated from what tools/list returns, so this is exactly what your agent sees.
Badge holders badges_holders
Who holds a badge: every recorded player in scope (the corpus by default, or a segment) with the named badge, with level and progress where tiered, names not just tags, and their current clan. Names must match the API's badge identifier exactly (badges_rarity lists them); a near-miss is refused with candidates rather than guessed.
Read-only ·
requires cr:read
| Argument | Type | Required | Notes |
|---|---|---|---|
badge |
string | yes | Badge name as the API spells it, e.g. MasteryWitch, BeatingDeathBadge. |
segment |
object | no | Scope: exactly one of player_tag, clan_tag (current members) or collection (a player collection's slug, e.g. 'pros'). OMIT the whole object for the entire recorded corpus. |
min_level |
integer | no | Tiered badges: only holders at this level or above. |
limit |
integer | no |
Badge rarity census badges_rarity
Every badge observed across recorded profiles with its holder count, rarest first: the 'what is the rarest badge' question over the whole recorded population (default) or a segment (clan, collection, one player), with players_considered so the strength of the claim is in the payload. One-off badges are told apart from tiered ones, and tiered badges break down by level.
Read-only ·
requires cr:read
| Argument | Type | Required | Notes |
|---|---|---|---|
segment |
object | no | Scope: exactly one of player_tag, clan_tag (current members) or collection (a player collection's slug, e.g. 'pros'). OMIT the whole object for the entire recorded corpus. |
kind |
string | no | Only this class of badge. (one_off · tiered) |
limit |
integer | no |
Card collection players_collection
Full card collection as last recorded: levels (in-game 1-16 scale), counts, forms, star levels, collection level. evolutionLevel / maxEvolutionLevel are FORM bit fields (1 = Evolution, 2 = Hero, 3 = both), decoded into forms_unlocked / forms_available. verbosity compact keeps id, name, level and forms per card.
Read-only ·
requires cr:read
| Argument | Type | Required | Notes |
|---|---|---|---|
player_tag |
string | no | Player tag like #20JJJ2CCRU. Omit to mean the caller (your primary player, or whoever on_behalf_of maps to). |
on_behalf_of |
string | no | Agent connections: the end user's id on your surface (e.g. discord:1234), mapped once with elixir_identify. Ignored on a personal connection. |
verbosity |
string | no | compact: each card as id, name, level, forms_unlocked only; support_cards likewise. (full · compact) |
Find player by name players_search
Name-to-tag resolution across the whole recorded corpus: case-insensitive substring on last-observed display names AND your private nicknames, nicknames ranked first ("tyler" finds the player you call Tyler). Unknown names return an honest empty list, never a guess. The inverse (tags to names, in bulk) is players_names.
Read-only ·
requires cr:read
| Argument | Type | Required | Notes |
|---|---|---|---|
query |
string | yes | Part of a name or nickname. |
limit |
integer | no |
Player profile players_profile
Latest recorded profile snapshot for a tag: trophies, Path of Legends, league stats, donations, lifetime counters, collection level, clan (with badge and the player's role), attributes (arena, best trophies, favourite card, account age) and current badge state, as of the last profile poll. live: true asks for a fresh read of ANY tag, recorded or not: served if in hand, otherwise queued while the record answers with live_status pending (live_pending if nothing is recorded yet). For tag-to-name only, players_names resolves up to 100 tags without the live lane.
Read-only ·
requires cr:read · reaches the live Clash Royale API, outside the recorded corpus
| Argument | Type | Required | Notes |
|---|---|---|---|
player_tag |
string | no | Player tag like #20JJJ2CCRU. Omit to mean the caller (your primary player, or whoever on_behalf_of maps to). |
on_behalf_of |
string | no | Agent connections: the end user's id on your surface (e.g. discord:1234), mapped once with elixir_identify. Ignored on a personal connection. |
live |
boolean | no | Ask for a read no older than a minute; works for a player nobody records. Served if in hand, otherwise queued while the record answers with live_status pending (live_pending if nothing is recorded yet). |
What comes back (declared outputSchema; fields marked required are always present):
| Field | Type | Required | Notes |
|---|---|---|---|
player_tag |
string | yes | Clash Royale tag, e.g. #20JJJ2CCRU. |
name |
string | null | no | |
applied |
object | no | |
clan |
object | null | no | |
last_seen_in_game |
string | null | no | The game's own lastSeen. |
attributes |
object | yes | |
badges |
array | no | |
snapshot |
object | yes | |
notes |
array | yes | One-sentence caveats to repeat when quoting the numbers. |
docs |
string | yes | page or page#section for elixir_docs / elixir://docs. |
meta |
object | yes | The envelope (docs: responses). |
Player summary players_summary
The headline in one call: current trophies and clan, last-30-days record and win rate, and the most-played deck with its record. Start here for “how am I doing?”; drill in with battles_performance / battles_decks.
Read-only ·
requires cr:read
| Argument | Type | Required | Notes |
|---|---|---|---|
player_tag |
string | no | Player tag like #20JJJ2CCRU. Omit to mean the caller (your primary player, or whoever on_behalf_of maps to). |
on_behalf_of |
string | no | Agent connections: the end user's id on your surface (e.g. discord:1234), mapped once with elixir_identify. Ignored on a personal connection. |
What comes back (declared outputSchema; fields marked required are always present):
| Field | Type | Required | Notes |
|---|---|---|---|
player_tag |
string | yes | Clash Royale tag, e.g. #20JJJ2CCRU. |
name |
string | null | no | |
nickname |
string | no | |
clan |
object | null | no | |
trophies |
integer | null | no | |
trophies_as_of |
string | null | no | YYYY-MM-DD of the snapshot. |
applied |
object | no | |
last_30_days |
object | yes | |
top_deck |
object | null | yes | |
best_deck |
object | null | no | |
notes |
array | yes | One-sentence caveats to repeat when quoting the numbers. |
docs |
string | yes | page or page#section for elixir_docs / elixir://docs. |
meta |
object | yes | The envelope (docs: responses). |
Player timeline players_timeline
Time series from daily snapshots, one point per game day: trophies by default, or any of the day row's metrics (donations and donations_received, the weekly counters; the lifetime block: battle_count, wins, losses, three_crown_wins, star_points, collection_level, king_tower_level, total_donations, the challenge and tournament counters; the Path of Legends standing; the seasonal trophies; arena_id, clan_tag, clan_rank, game_last_seen_at from the roster). Every point carries observed_at, profile_observed_at (null on a roster-only day) and roster_observed_at. progress_key adds the side-mode progress series; kind selects the pre_reset or season_roll row. Granularity week returns the last row of each ISO week.
Read-only ·
requires cr:read
| Argument | Type | Required | Notes |
|---|---|---|---|
player_tag |
string | no | Player tag like #20JJJ2CCRU. Omit to mean the caller (your primary player, or whoever on_behalf_of maps to). |
on_behalf_of |
string | no | Agent connections: the end user's id on your surface (e.g. discord:1234), mapped once with elixir_identify. Ignored on a personal connection. |
metrics |
array | no | Which series to return. |
from |
string | no | YYYY-MM-DD, inclusive. Built from daily snapshots, so only whole days are meaningful; an instant is not accepted. |
to |
string | no | YYYY-MM-DD, inclusive. Built from daily snapshots, so only whole days are meaningful; an instant is not accepted. |
days |
integer | no | Last N days of the series, today included: sugar for from. Or use from/to. |
weeks |
integer | no | Last N weeks of the series, today included: sugar for from. Or use from/to. |
timezone |
string | no | IANA zone (e.g. Europe/Paris) for this call's date-only bounds and local labels. Default: the account's timezone. Agents serving people in several zones pass the asker's. |
granularity |
string | no | week returns the last row of each ISO week. (day · week) |
kind |
string | no | Which row of the day: daily (the day's last observation), pre_reset (the hour before the Monday 00:10 UTC donation reset: the honest weekly donation total) or season_roll (the hour before the season rolls). (daily · pre_reset · season_roll) |
progress_key |
string | no | A Player.progress key as the API spells it (2v2League_202609, seasonal-trophy-road-202609, AutoChess_2026_Season_11, or '' for the Merge Tactics pre-season arena) or 'all': adds progress[] with that bucket's trophies, best_trophies and arena_id per day. A bucket at zero writes no row. |
What comes back (declared outputSchema; fields marked required are always present):
| Field | Type | Required | Notes |
|---|---|---|---|
player_tag |
string | yes | Clash Royale tag, e.g. #20JJJ2CCRU. |
applied |
object | yes | |
snapshots_available_from |
string | null | yes | |
series |
array | yes | |
progress |
array | no | |
notes |
array | yes | One-sentence caveats to repeat when quoting the numbers. |
docs |
string | yes | page or page#section for elixir_docs / elixir://docs. |
meta |
object | yes | The envelope (docs: responses). |
Record coverage elixir_coverage
How complete the record is for a tag: recording start, last successful poll per endpoint, battles captured (including appearances recorded before the tag was tracked), capture estimates over observation intervals ending in the last seven days, and unmeasured_tail_hours since the latest profile snapshot. Use it to caveat answers honestly; missing coverage is unknown, not evidence of absence.
Read-only ·
requires cr:read
| Argument | Type | Required | Notes |
|---|---|---|---|
player_tag |
string | no | Player tag like #20JJJ2CCRU. Omit to mean the caller (your primary player, or whoever on_behalf_of maps to). |
on_behalf_of |
string | no | Agent connections: the end user's id on your surface (e.g. discord:1234), mapped once with elixir_identify. Ignored on a personal connection. |
What comes back (declared outputSchema; fields marked required are always present):
| Field | Type | Required | Notes |
|---|---|---|---|
player_tag |
string | yes | Clash Royale tag, e.g. #20JJJ2CCRU. |
polls |
array | yes | |
battles |
object | yes | |
snapshots |
object | yes | |
observation_intervals |
array | no | |
completeness_last_7_days |
object | no | Measured intervals plus the explicit unmeasured tail after the latest profile snapshot. |
notes |
array | yes | One-sentence caveats to repeat when quoting the numbers. |
docs |
string | yes | page or page#section for elixir_docs / elixir://docs. |
meta |
object | yes | The envelope (docs: responses). |
Resolve tags to names players_names
Bulk tag-to-name resolution from the corpus: up to 100 tags in, for each the last-observed name and where it came from, plus an explicit unknown list. Costs nothing from the live lane; resolving a miss is then a deliberate players_profile({ live: true }) per tag. The inverse of players_search.
Read-only ·
requires cr:read
| Argument | Type | Required | Notes |
|---|---|---|---|
player_tags |
array | yes | One to one hundred player tags. |