Tools: Battles
The Battles tools your agent sees through Elixir MCP: what each one answers, what it takes, and which capability it needs.
Battles
7 of the 47 tools in the registry. Generated from what tools/list returns, so this is exactly what your agent sees.
Card performance battles_cards
Per-card win/loss attribution over recorded battles. perspective "mine": the battles where your deck held the card. perspective "opponent": the battles where an opposing deck held it, with your record in them. sort "losses" orders rows by the battles you lost (default "battles"); a row needs at least applied.min_battles (3). Each row carries its battles per mode group and mean_level_gap; modes_in_window and comparable say whether modes with different matchmaking were pooled (pass mode to isolate one). Each round of a Clan Wars duel is one game: that round's cards and result.
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. |
display_name |
string | no | Agent connections, beside on_behalf_of: the asker's display name on your surface. When on_behalf_of is not mapped yet, no_subject carries candidates[]: the clan members whose whole name matches it (case and spacing ignored), so one elixir_identify call follows; nothing is guessed from a partial match. |
perspective |
string | no | (mine · opponent) |
from |
string | no | Start of the window, inclusive: an ISO instant, or YYYY-MM-DD resolving to local midnight in your timezone. |
to |
string | no | End of the window, exclusive: an ISO instant as given; YYYY-MM-DD covers that WHOLE local day. Omit for up to now. |
days |
integer | no | Last N days, ending now: sugar for from. Or use from/to. |
weeks |
integer | no | Last N weeks, ending now: 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. |
season |
string | integer | no | Bound the window to one season: 'current' (to date), 'previous', the month the API names it by (2026-08), or the river race season number (135). from/to/days/weeks given win over it. |
mode |
string | no | Mode group: ladder (Trophy Road to 14,000), ranked (Path of Legends), war, casual (clanmate battles even when tagged), challenge, event (any other battle with an event tag, including the seasonal Trophy Road past 14,000), tournament. Omit for every mode. (casual · challenge · event · ladder · ranked · tournament · war) |
sort |
string | no | battles: most battles first. losses: most battles lost first, then most battles. Either way a row needs applied.min_battles. (battles · losses) |
verbosity |
string | no | This tool has one size: compact is accepted and changes nothing (the response says so in a note). (full · compact) |
What comes back (declared outputSchema; fields marked required are always present):
| Field | Type | Required | Notes |
|---|---|---|---|
applied |
object | yes | |
cards |
array | yes | |
comparable |
boolean | null | yes | |
docs |
string | yes | page or page#section for elixir_docs / elixir://docs. |
meta |
object | yes | The envelope (docs: responses). |
modes_in_window |
object | no | |
notes |
array | yes | One-sentence caveats to repeat when quoting the numbers. |
player_tag |
string | null | yes |
Compare players battles_compare
Side-by-side of 2-4 recorded tags (any recorded player): latest snapshot topline plus a shared performance window. mode reads one mode group; with no mode each player's window carries its per-mode split.
Read-only ·
requires cr:read
| Argument | Type | Required | Notes |
|---|---|---|---|
player_tags |
array | yes | Two to four player tags. |
from |
string | no | Start of the window, inclusive: an ISO instant, or YYYY-MM-DD resolving to local midnight in your timezone. |
to |
string | no | End of the window, exclusive: an ISO instant as given; YYYY-MM-DD covers that WHOLE local day. Omit for up to now. |
days |
integer | no | Last N days, ending now: sugar for from. Or use from/to. |
weeks |
integer | no | Last N weeks, ending now: 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. |
season |
string | integer | no | Bound the window to one season: 'current' (to date), 'previous', the month the API names it by (2026-08), or the river race season number (135). from/to/days/weeks given win over it. |
mode |
string | no | Mode group: ladder (Trophy Road to 14,000), ranked (Path of Legends), war, casual (clanmate battles even when tagged), challenge, event (any other battle with an event tag, including the seasonal Trophy Road past 14,000), tournament. Omit for every mode. (casual · challenge · event · ladder · ranked · tournament · war) |
verbosity |
string | no | This tool has one size: compact is accepted and changes nothing (the response says so in a note). (full · compact) |
What comes back (declared outputSchema; fields marked required are always present):
| Field | Type | Required | Notes |
|---|---|---|---|
applied |
object | yes | |
docs |
string | yes | page or page#section for elixir_docs / elixir://docs. |
meta |
object | yes | The envelope (docs: responses). |
notes |
array | yes | One-sentence caveats to repeat when quoting the numbers. |
players |
array | yes |
Deck performance battles_decks
Battles grouped by exact deck identity (deck_hash), one page at a time (offset, next_offset): each row's cards as one line of names, archetype label, record, win rate, share of battles and the controls that make a win rate readable (modes, dominant_mode, mean_level_gap; comparable says whether rows can be ranked). deck_hash returns that one deck with its cards, tower troop and archetype in full. A duel sits under excluded; duel_decks lists its round decks. Unbounded window by default.
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. |
display_name |
string | no | Agent connections, beside on_behalf_of: the asker's display name on your surface. When on_behalf_of is not mapped yet, no_subject carries candidates[]: the clan members whose whole name matches it (case and spacing ignored), so one elixir_identify call follows; nothing is guessed from a partial match. |
from |
string | no | Start of the window, inclusive: an ISO instant, or YYYY-MM-DD resolving to local midnight in your timezone. |
to |
string | no | End of the window, exclusive: an ISO instant as given; YYYY-MM-DD covers that WHOLE local day. Omit for up to now. |
days |
integer | no | Last N days, ending now: sugar for from. Or use from/to. |
weeks |
integer | no | Last N weeks, ending now: 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. |
season |
string | integer | no | Bound the window to one season: 'current' (to date), 'previous', the month the API names it by (2026-08), or the river race season number (135). from/to/days/weeks given win over it. |
mode |
string | no | Mode group: ladder (Trophy Road to 14,000), ranked (Path of Legends), war, casual (clanmate battles even when tagged), challenge, event (any other battle with an event tag, including the seasonal Trophy Road past 14,000), tournament. Omit for every mode. (casual · challenge · event · ladder · ranked · tournament · war) |
sort |
string | no | win_rate sorting respects min_battles. (battles · wins · win_rate) |
min_battles |
integer | no | Drop decks with fewer battles than this. |
limit |
integer | no | |
offset |
integer | no | Rows of the sorted list to skip: the next page starts at the answer's next_offset (null on the last page). |
deck_hash |
string | no | One deck, from a row's deck_hash: its row with the cards (id, name, form), tower troop and archetype in full, and its duel rounds in duel_decks when it was played in duels. The totals stay the window's. |
archetype |
string | no | Only decks of this archetype: a family (beatdown, control, cycle, bait, bridge spam, siege), a composed label ('Royal Hogs bridge spam', 'Hog Rider cycle'), or a community name ('LavaLoon', 'Log Bait', '2.6 Hog'). Applied over the rows the call would return; applied.archetype echoes what it resolved to. An unknown name is refused with the vocabulary in the hint. |
verbosity |
string | no | compact: rows keep the record, win rate, share, dominant_mode and mean_level_gap; modes and the level detail are dropped. (full · compact) |
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 | Last-observed name; null when the record has none. |
applied |
object | yes | |
total_battles_in_window |
integer | no | Head-to-head battles with a deck in the window, the denominator of share_of_battles; duels have no single deck and sit in excluded (4.1.0). |
total_decks |
integer | no | 9.12.0: decks in the sorted list after min_battles and archetype, over every page. |
next_offset |
integer | null | no | 9.12.0: the offset of the next page; null on the last page. |
excluded |
object | no | Battles in the window outside the rows (4.1.0): duels (no single deck) and any other battle with no recorded deck; total_battles_in_window plus these is battles_performance.battles over the same window. |
comparable |
boolean | no | false when the rows were played in different modes or at level gaps half a level apart, so their win rates do not rank the decks (3.13.0); the first note says which rows clash. |
decks |
array | yes | |
duel_decks |
array | yes | 9.8.0: the decks played in the window's duel rounds (a duel has no single deck, so it is outside decks[]), most rounds first, at most 8: deck_hash (the eight cards' identity; a Clan Wars battle carries no tower troop), card_names (one string), archetype_label, rounds, wins and losses by each round's own crowns, first_used, last_used. |
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). |
Opponents faced battles_opponents
A player's recorded battles grouped by OPPONENT: per opponent the record (W/L/D), first and last meeting, the modes, clan at last meeting, mean_level_gap, and the opponent's name where the service has observed one (name_known). min_battles: 2 answers "who have I faced more than once" in one call; sort: "losses" puts the opponents you lost to most first. Head-to-head only. The discovery half of battles_query's opponent_tag filter.
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. |
display_name |
string | no | Agent connections, beside on_behalf_of: the asker's display name on your surface. When on_behalf_of is not mapped yet, no_subject carries candidates[]: the clan members whose whole name matches it (case and spacing ignored), so one elixir_identify call follows; nothing is guessed from a partial match. |
from |
string | no | Start of the window, inclusive: an ISO instant, or YYYY-MM-DD resolving to local midnight in your timezone. |
to |
string | no | End of the window, exclusive: an ISO instant as given; YYYY-MM-DD covers that WHOLE local day. Omit for up to now. |
days |
integer | no | Last N days, ending now: sugar for from. Or use from/to. |
weeks |
integer | no | Last N weeks, ending now: 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. |
season |
string | integer | no | Bound the window to one season: 'current' (to date), 'previous', the month the API names it by (2026-08), or the river race season number (135). from/to/days/weeks given win over it. |
mode |
string | no | Mode group: ladder (Trophy Road to 14,000), ranked (Path of Legends), war, casual (clanmate battles even when tagged), challenge, event (any other battle with an event tag, including the seasonal Trophy Road past 14,000), tournament. Omit for every mode. (casual · challenge · event · ladder · ranked · tournament · war) |
min_battles |
integer | no | Only opponents met at least this many times (2 = repeats only). |
sort |
string | no | (battles · last_seen · wins · losses) |
limit |
integer | no | |
verbosity |
string | no | This tool has one size: compact is accepted and changes nothing (the response says so in a note). (full · compact) |
What comes back (declared outputSchema; fields marked required are always present):
| Field | Type | Required | Notes |
|---|---|---|---|
applied |
object | yes | |
distinct_opponents |
number | null | yes | |
docs |
string | yes | page or page#section for elixir_docs / elixir://docs. |
matching_opponents |
number | null | yes | |
meta |
object | yes | The envelope (docs: responses). |
notes |
array | yes | One-sentence caveats to repeat when quoting the numbers. |
opponents |
array | yes | |
player_tag |
string | null | yes |
Performance windows battles_performance
Computed record over a window: W/L/D, win rate, crowns for/against, net trophies, three-crown rate, streaks, and trophy_floor when the player stood on an arena floor (losses there cost nothing, so net_trophies is asymmetric). compare_from/compare_to or before_after runs a second window server-side for "since X vs before" questions (before_after wins over compare_*); group_by week is the trend view (buckets the window clips are marked partial) and group_by game_mode the "what have I been playing" view.
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. |
display_name |
string | no | Agent connections, beside on_behalf_of: the asker's display name on your surface. When on_behalf_of is not mapped yet, no_subject carries candidates[]: the clan members whose whole name matches it (case and spacing ignored), so one elixir_identify call follows; nothing is guessed from a partial match. |
from |
string | no | Start of the window, inclusive: an ISO instant, or YYYY-MM-DD resolving to local midnight in your timezone. |
to |
string | no | End of the window, exclusive: an ISO instant as given; YYYY-MM-DD covers that WHOLE local day. Omit for up to now. |
days |
integer | no | Last N days, ending now: sugar for from. Or use from/to. |
weeks |
integer | no | Last N weeks, ending now: 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. |
season |
string | integer | no | Bound the window to one season: 'current' (to date), 'previous', the month the API names it by (2026-08), or the river race season number (135). from/to/days/weeks given win over it. |
last_n_battles |
integer | no | Sample the most recent N battles instead of a window. |
mode |
string | no | Mode group: ladder (Trophy Road to 14,000), ranked (Path of Legends), war, casual (clanmate battles even when tagged), challenge, event (any other battle with an event tag, including the seasonal Trophy Road past 14,000), tournament. Omit for every mode. (casual · challenge · event · ladder · ranked · tournament · war) |
deck_hash |
string | no | Only battles on this exact deck (see battles_decks). |
compare_from |
string | no | Start of the window, inclusive: an ISO instant, or YYYY-MM-DD resolving to local midnight in your timezone. |
compare_to |
string | no | End of the window, exclusive: an ISO instant as given; YYYY-MM-DD covers that WHOLE local day. Omit for up to now. |
group_by |
string | no | week: weekly series (ISO weeks). game_mode: per named game mode (the row's game_mode, not the mode group), one row per event within it (event_tag, event_title). Overrides before_after and compare_*. (week · game_mode) |
before_after |
string | no | Date splitting two windows: [from..date) vs [date..to], e.g. before vs after a deck change. |
verbosity |
string | no | This tool has one size: compact is accepted and changes nothing (the response says so in a note). (full · compact) |
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 | |
window |
object | no | |
compare_window |
object | no | |
before |
object | no | |
after |
object | no | |
split_at |
string | no | ISO 8601 UTC instant. |
by_mode |
array | no | |
weekly |
array | no | |
trophy_floor |
object | no | The Trophy Road floor the player stood on in the window (3.13.0): present when the window holds ladder battles and the arena's floor is known. floored is true when a loss touched it, and then net_trophies counts wins in full and those losses at zero. floor is the floor stood on MOST RECENTLY, with its own on_floor_losses and losses_landing_on_floor; floors[] (6.21.0) is every floor the window stood on, each with its own counts and last time. |
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). |
Query battles battles_query
The workhorse: recorded battles with filters and cursor pagination, both perspectives of every battle. Three addressing modes: player_tag (the usual sweep, defaults to the caller); battle_id alone (ONE battle, both sides); deck_hash alone (corpus-wide battles for that exact deck with a deck_stats aggregate and deliberately no pooled win rate). live: true asks for a battle-log poll no older than a minute (the 'what did they just play' path): served if in hand, otherwise queued while the record answers with live_status pending. Each battle's url is its public page.
Read-only ·
requires cr:read · reaches the live Clash Royale API, outside the record
| 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. |
display_name |
string | no | Agent connections, beside on_behalf_of: the asker's display name on your surface. When on_behalf_of is not mapped yet, no_subject carries candidates[]: the clan members whose whole name matches it (case and spacing ignored), so one elixir_identify call follows; nothing is guessed from a partial match. |
from |
string | no | Start of the window, inclusive: an ISO instant, or YYYY-MM-DD resolving to local midnight in your timezone. |
to |
string | no | End of the window, exclusive: an ISO instant as given; YYYY-MM-DD covers that WHOLE local day. Omit for up to now. |
days |
integer | no | Last N days, ending now: sugar for from. Or use from/to. |
weeks |
integer | no | Last N weeks, ending now: 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. |
season |
string | integer | no | Bound the window to one season: 'current' (to date), 'previous', the month the API names it by (2026-08), or the river race season number (135). from/to/days/weeks given win over it. |
mode |
string | no | Mode group: ladder (Trophy Road to 14,000), ranked (Path of Legends), war, casual (clanmate battles even when tagged), challenge, event (any other battle with an event tag, including the seasonal Trophy Road past 14,000), tournament. Omit for every mode. (casual · challenge · event · ladder · ranked · tournament · war) |
game_mode_id |
integer | no | Exact game mode id from the API. |
opponent_tag |
string | no | Only battles against this tag. |
outcome |
string | no | (win · loss · draw) |
with_card |
integer | no | Card id present in YOUR deck (a duel: in any of its rounds' decks). |
with_cards |
array | no | Card ids ALL present in YOUR deck (any form). Combine with with_card freely; a deck is matched by its played cards, tower troop excluded, and a duel when one of its rounds' decks holds them all. |
against_card |
integer | no | Card id present in an OPPONENT deck. |
deck_hash |
string | no | Exact deck identity (see battles_decks). Without player_tag: corpus-wide. |
battle_id |
string | no | Fetch exactly this battle (both perspectives): its battle_id, the short id at the end of its url, or the url itself. |
game_mode |
string | no | Case-insensitive substring of the game's mode name ('chaos', 'crazy'); discover names with battles_performance group_by: 'game_mode'. |
live |
boolean | no | Ask for a battle-log poll no older than a minute: served from the record if in hand, otherwise queued while the record answers now with live_status pending and retry_after_s. |
cursor |
string | no | Opaque token from a previous response's next_cursor. |
limit |
integer | no | Battles per page; above 25 needs verbosity: 'compact'. A FULL page is large - both sides' decks, tower hitpoints, elixir, the comparison block and a duel's rounds - and around ten battles can reach the 48,000-character result cap on a rich page. The refusal when it does names a limit that fits; compact keeps deck_hash, crowns and the outcome. |
include_total |
boolean | no | Also return total_count across ALL pages (one cheap count query). |
verbosity |
string | no | compact: drops per-card decks, support cards and tower_hp (deck_hash stays); use it for wide sweeps. (full · compact) |
What comes back (declared outputSchema; fields marked required are always present):
| Field | Type | Required | Notes |
|---|---|---|---|
live_status |
object | no | With live: true: whether a fresh read was served or is pending (retry_after_s says when to call again). |
player_tag |
string | no | Clash Royale tag, e.g. #20JJJ2CCRU. |
name |
string | null | no | Last-observed name; null when the record has none. |
battle_id |
string | no | |
deck_hash |
string | no | |
deck_stats |
object | no | With deck_hash alone: the deck's battles in this call's match set (window, mode and filters; every page), with wins, losses, distinct players and first/last use. No pooled win rate by design. |
applied |
object | yes | |
battles |
array | yes | |
total_count |
integer | no | |
next_cursor |
string | null | yes | Opaque; null = end. |
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). |
Segment trends battles_trends
Weekly time series for a named population: segment 'mine' or {clan_tag | player_tag}. Per ISO week: battles, record, aggregate win rate, distinct active players, net trophies, the season the week starts in. Default 12 weeks; weeks, from/to or season set the window; applied.window.crosses marks each season roll inside it. Single-player weekly detail also lives in battles_performance group_by 'week'.
Read-only ·
requires cr:read
| Argument | Type | Required | Notes |
|---|---|---|---|
segment |
yes | The recorded player or clan to read: 'mine' (your clan) or an object naming exactly one of player_tag or clan_tag (current members). Required; corpus access has retired. | |
from |
string | no | Start of the window, inclusive: an ISO instant, or YYYY-MM-DD resolving to local midnight in your timezone. |
to |
string | no | End of the window, exclusive: an ISO instant as given; YYYY-MM-DD covers that WHOLE local day. Omit for up to now. |
days |
integer | no | Last N days, ending now: sugar for from. Or use from/to. |
weeks |
integer | no | How many ISO weeks back (default 12); 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. |
season |
string | integer | no | Bound the window to one season: 'current' (to date), 'previous', the month the API names it by (2026-08), or the river race season number (135). from/to/days/weeks given win over it. |
mode |
string | no | Mode group: ladder (Trophy Road to 14,000), ranked (Path of Legends), war, casual (clanmate battles even when tagged), challenge, event (any other battle with an event tag, including the seasonal Trophy Road past 14,000), tournament. Omit for every mode. (casual · challenge · event · ladder · ranked · tournament · war) |
verbosity |
string | no | This tool has one size: compact is accepted and changes nothing (the response says so in a note). (full · compact) |
What comes back (declared outputSchema; fields marked required are always present):
| Field | Type | Required | Notes |
|---|---|---|---|
applied |
object | yes | |
population |
object | no | On a corpus read only: the recorded population (recorded players and clans) and players_in_window, the recorded players who played in the window (the corpus counts read the recorded players' side of each battle). |
docs |
string | yes | page or page#section for elixir_docs / elixir://docs. |
meta |
object | yes | The envelope (docs: responses). |
notes |
array | yes | One-sentence caveats to repeat when quoting the numbers. |
weeks |
array | yes |