DocsUsing it Choosing a tool

Choosing a tool

The tool reference is exhaustive. This page is the map: question in, tool out.

The tool reference lists every tool with every argument. This page is the shorter thing an agent reads first: given the shape of a question, which tool answers it, in what order, and the handful of conventions that hold everywhere.

Question shape to tool

The question sounds like	Call
How am I doing? Start here.	`players_summary`
Over a window, or since X compared with before	`battles_performance` (`from`/`to`, `before_after`, `group_by: "week"`)
What decks do I play, and how do they do?	`battles_decks`, then `battles_query({ deck_hash })` to drill
Show me the battles themselves; the workhorse	`battles_query` (filters, cursor, `verbosity: "compact"`)
What day is it in the game? Season, war day, when it rolls	`game_clock`
My clan today: standings, who still has decks	`war_current` (`decks_today` can guide a nudge only while `race_finished_at` is null)
Every current member's W/L/D over a short window	`clans_standings({ days: 1, min_battles: 1 })`, or explicit `from`/`to`; trophy swing and streaks require a selected member's `battles_performance`
Which clanmates played this exact deck?	`battles_decks` for a `deck_hash`, then `battles_query({ deck_hash })` without `player_tag`, and compare the returned tags with `clans_roster`; this is exact deck evidence, not a playstyle similarity score
Which game-mode leaderboard ids can I read?	`rankings_players({ board: "mode", location: "list" })`, then pass a returned `location` to read its board
Who has gone quiet?	`clans_roster`, reading `last_seen_in_game` beside `last_recorded_battle`
What did every member do this week, and the weeks before?	`clans_participation` (battles, ranked, donations, war days per member per week, in one call)
How has the clan moved over the season: score, war trophies, members, the members' trophies?	`clans_timeline` (one point per game day, with the aggregates over the members' rows)
How has each member's trophies or rank moved day by day?	`clans_members_timeline` (every member's day series in one call; compact for first, last and delta)
Scout the bracket	`war_rivals`, then `war_current({ clan_tag, live: true })` or `clans_roster({ clan_tag, live: true })` for one rival
What is the meta, for a clan or the corpus?	`battles_meta_decks` / `battles_meta_cards` with a `segment`
Rarest badge, who holds one	`badges_rarity`, `badges_holders`
A name to a tag, or tags to names	`players_search`, `players_names`
What happened since I last looked?	`elixir_timeline` (items in order and an entry per subject, then drill with the data tools)
How is this documented?	`elixir_docs`, `elixir_examples`, `elixir_updates`, `elixir_changelog`

Every recorded-data tool is unlimited within the daily call budget. The tools that spend the live lane are live_fetch and the 7 with a live flag; everything else reads the record.

Three sequences

How am I doing. players_summary for the headline (trophies, the fixed last 30 days, the most-played deck), then battles_performance with a window or before_after for the comparison the person actually asked about, then battles_decks if the answer is about decks. Read meta.freshness_seconds before quoting a number.

Scout a bracket. game_clock to know whether it is a battle day, then war_current once for your own standings and the five clans in the race, then war_rivals for what the record knows about each rival, then, for the one that matters, war_current({ clan_tag, live: true }) or clans_roster({ clan_tag, live: true }): a fresh read of any clan, recorded or not — served at once if one is in hand, otherwise queued while the record answers with live_status.state: "pending" and when to call again. If a rival's recorded roster returns not_recorded, follow its exact clans_roster({ clan_tag, live: true }) retry hint; live_pending means wait retry_after_s and repeat, not that the roster is unobtainable. A live read records that observation but does not start an ongoing clan watch.

Name to tag to drill. players_search({ query }) resolves a name (your nicknames and clanmates rank first), then any player tool with the tag. In the other direction, players_names resolves up to 100 tags without the live lane, and players_profile({ live: true }) fetches one the corpus has never named.

Conventions on one screen

Omit player_tag to mean the caller: a person's primary player, or whoever on_behalf_of maps to on an agent connection. Omit clan_tag to mean the recorded clan. Nothing is looked up first.
The segment tools default to the corpus. battles_meta_decks, battles_meta_cards, battles_trends, cards_synergy, badges_rarity and badges_holders take a nested segment: { player_tag | clan_tag | collection }; omit the whole object for everything recorded.
Windows are from/to, ISO instants or YYYY-MM-DD resolved in the account's timezone; a date-only to covers that whole day. days and weeks are sugar; season on the meta tools bounds one season. Every windowed response echoes applied.window with a source of argument, default, unbounded, season or fixed; see Windows and timezones and Seasons.
verbosity: "compact" is the one size control. It drops the bulk and keeps identities and counts; a result over the delivery cap answers result_too_large naming the arguments that narrow it.
Every response carries notes[] and docs. The notes are one-sentence caveats to repeat with the numbers; docs is a page#section for elixir_docs where the formulas live.
live: true asks for a fresh read on players_profile, clans_roster, war_current, battles_query and the board tools: served at once if a read inside the API's cache window is in hand, otherwise queued while the record answers now with live_status.state: "pending" and when to call again. live_fetch is the raw catch-all and the last resort; it refuses a battle log, which never fits the cap.
timezone on any windowed tool names an IANA zone for that call's date-only bounds and local labels, for agents serving people in several zones.
Errors are a closed set with a hint naming the next call; check the body, not only the transport flag. The codes are on the Protocol reference.
A heavy aggregation can return query_timeout rather than a partial answer. Retry after a few seconds, or narrow from/to; lowering limit only reduces output, not scan cost. Keep the request id if it persists.