Tools: Battles
The Battles tools your agent sees through Elixir MCP: what each one answers, what it takes, and which capability it needs.
Battles
10 of the 55 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": which of your cards carry. perspective "opponent": which enemy cards beat you (the nemesis question). Duels are excluded (no single deck).
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. |
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. |
mode |
string | no | Mode group: ladder (Trophy Road), ranked (Path of Legends), war, casual, challenge, tournament. Omit for every mode. (casual · challenge · ladder · ranked · tournament · war) |
Compare players battles_compare
Side-by-side of 2-4 recorded tags (any recorded player): latest snapshot topline plus a shared performance window.
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. |
Deck performance battles_decks
Battles grouped by exact deck identity (deck_hash): per-deck record, first/last used, win rate, share of battles. Deck identity is the exact card set played (some event modes field more or fewer than 8). Unbounded by default and says so in applied.window; pass a deck_hash to battles_query or battles_performance to drill in.
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. |
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. |
mode |
string | no | Mode group: ladder (Trophy Road), ranked (Path of Legends), war, casual, challenge, tournament. Omit for every mode. (casual · challenge · 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 |
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 | |
total_battles_in_window |
integer | no | |
decks |
array | 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). |
Level Curve & Pilot Score battles_levels
The Level Curve and Pilot Score: win rate by deck-average level gap across the recorded corpus, binned where the data lives, never extrapolated. Pass player_tag (or on_behalf_of) for a Pilot Score: actual minus the level-expected win rate, with a monthly trend and an experience cohort. Descriptive, with sample sizes on every bin and score. verbosity compact omits the curve rows.
Read-only ·
requires cr:read
| Argument | Type | Required | Notes |
|---|---|---|---|
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. |
player_tag |
string | no | Score this player against the curve (Pilot Score + monthly trend). Omit for the curve alone. |
days |
integer | no | Window for the curve and the score, ending now. |
mode |
string | no | Mode group: ladder (Trophy Road), ranked (Path of Legends), war, casual, challenge, tournament. Omit for every mode. (casual · challenge · ladder · ranked · tournament · war) |
verbosity |
string | no | compact: omits the curve rows; the score and methodology are unchanged. (full · compact) |
trophy_band |
string | no | Both participants must have starting trophies in this band; conditions the curve and the scored observations on the same population. (under_5000 · 5000_8000 · 8000_11000 · 11000_13000 · 13000_plus) |
Meta cards (observed) battles_meta_cards
Observed card meta for a segment: the whole corpus (default), or segment.clan_tag / segment.player_tag / segment.collection. Per card AND form (forms never merge): usage share among decided player-battle observations, distinct players, raw and shrunk win rates. Default window: the current season to date; season selects another. What the recorded data shows, with sample sizes; never a tier list.
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. |
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), ranked (Path of Legends), war, casual, challenge, tournament. Omit for every mode. (casual · challenge · ladder · ranked · tournament · war) |
min_battles |
integer | no | Decided observations a card needs to be listed. |
sort |
string | no | (usage · shrunk_win_rate) |
limit |
integer | no |
Meta decks (observed) battles_meta_decks
Observed deck meta for a segment: the whole corpus (default), or segment.clan_tag / segment.player_tag / segment.collection. Per exact deck identity: decided player-battle observations (not unique matches), record, distinct players, usage share, raw and shrunk win rates. Default window: the current season to date; season selects another. No tier lists: what the recorded data shows, with sample sizes.
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. |
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), ranked (Path of Legends), war, casual, challenge, tournament. Omit for every mode. (casual · challenge · ladder · ranked · tournament · war) |
min_battles |
integer | no | Decided observations a deck needs to be listed. |
sort |
string | no | (battles · shrunk_win_rate · players) |
limit |
integer | no |
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, 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. 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. |
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. |
mode |
string | no | Mode group: ladder (Trophy Road), ranked (Path of Legends), war, casual, challenge, tournament. Omit for every mode. (casual · challenge · 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) |
limit |
integer | no |
Performance windows battles_performance
Computed record over a window: W/L/D, win rate, crowns for/against, net trophies, three-crown rate, streaks. 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 and group_by 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. |
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. |
last_n_battles |
integer | no | Sample the most recent N battles instead of a window. |
mode |
string | no | Mode group: ladder (Trophy Road), ranked (Path of Legends), war, casual, challenge, tournament. Omit for every mode. (casual · challenge · 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). mode: per named game mode, event modes included. Overrides before_after and compare_*. (week · mode) |
before_after |
string | no | Date splitting two windows: [from..date) vs [date..to], e.g. before vs after a deck change. |
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 | |
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; the recorded log is otherwise within an hour for anyone recently asked about.
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. |
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. |
mode |
string | no | Mode group: ladder (Trophy Road), ranked (Path of Legends), war, casual, challenge, tournament. Omit for every mode. (casual · challenge · 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. |
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. |
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). |
game_mode |
string | no | Case-insensitive substring of the game's mode name ('chaos', 'crazy'); discover names with battles_performance group_by: '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'. |
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 |
|---|---|---|---|
player_tag |
string | no | Clash Royale tag, e.g. #20JJJ2CCRU. |
battle_id |
string | no | |
deck_hash |
string | no | |
deck_stats |
object | no | |
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 segment: the whole corpus (default), or segment.clan_tag / segment.player_tag / segment.collection. 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 |
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. |
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), ranked (Path of Legends), war, casual, challenge, tournament. Omit for every mode. (casual · challenge · ladder · ranked · tournament · war) |