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

Read comparable before ranking: where a response carries it (clans_standings, battles_decks), false means two rows were played in different modes or against different level gaps, and the note names them.

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

Four 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 reading 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 record has never named.

How have I moved. players_timeline for the series itself (trophies by default; metrics picks Path of Legends, a lifetime counter or the clan rank; one point per game day with day, kind and the stamps that wrote it), then battles_performance({ group_by: "week" }) for the win rate and mode split behind each stretch of it (clipped weeks say partial), and battles_decks for the mean_level_gap behind each deck, so a move can be read beside the card levels it was made with. Read applied.window.crosses on every one: a season roll resets the seasonal trophies and the ranked standing, so the two sides of it are not one series.

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 primary player's current clan (an agent's: the clan it acts for); when that clan is not recorded, or there is none, the call is refused with the fixing call in the hint, never answered for another clan. Nothing is looked up first.
• Segment tools name a subject. battles_trends, cards_card and badges_* require "mine" (your clan), {player_tag} or {clan_tag}. A clan read describes its current members. There is no record segment.
• Windows are from/to, ISO instants or YYYY-MM-DD resolved in the account's timezone; a date-only to covers that whole day. The daily series (players_timeline, clans_timeline, clans_members_timeline) run on game days and floor an instant to its day, saying so. days and weeks are sugar; season (current, previous, 2026-08 or 135) bounds one season on every windowed tool, elixir_timeline included, and is the default on cards_card. Every windowed response echoes applied.window with a source of argument, default, unbounded, season or fixed, the season it starts in and crosses, every season roll inside it (a note fires when there is one); see Windows and timezones and Seasons.
• verbosity: "compact" is the one size control, accepted on every tool. It drops the bulk and keeps identities and counts (a tool with one size says so in a note); 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: 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 stores nothing, and 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.

Two tools read Clan, each for one kind of connection. A person's own connection uses clans_my_view for that person's own view (the policy summary, their standing line, the Actions waiting for them), for a player they have verified; see Your own view. An assigned agent with an explicit private-context grant uses clans_context for its clan’s declared war intent and policy revision. It accepts no clan tag; game reads and clan assignment alone do not grant this private access. See Agent context.