CFDB

Get the full events timeline for one match, ordered by minute: goals (including penalties/own goals), cards, and substitutions, each with the player, minute, event type, and which side (home/away) it belongs to. Requires 'fixture_id'.

Get one match's lineups: for each team, 'starting_xi' and 'substitutes', each player with id, name, general position (their usual position, not necessarily what they played specifically in this match), is_captain, rating, and minutes_played. Two real limits, never guessed around: there is no tactical formation (e.g. '4-3-3') anywhere in CFDB because it isn't stored — and no per-match jersey number (only each player's current squad number exists, via team.squad, which may differ from what they wore in an older match); neither field is in this response at all. Both lists empty means lineup data hasn't been loaded for this match (only recently-finished live-schema matches get lineups fetched), not that the match had no lineup. Requires 'fixture_id'.

Get results or the schedule for one matchday of a league. Kickoff times are Chile local time (America/Santiago). Requires 'when' ('upcoming' or 'previous'); 'league_name' is optional. Each team's 'streak' includes that team's own result in this match when the match is finished (when='previous'); for a scheduled match (when='upcoming') there's no result yet, so 'streak' is the streak going into the match instead. Each match's 'status' is 'scheduled', 'live', 'finished', 'postponed', 'cancelled', or 'unknown' — no in-play minute/clock is available.

Get a knowledge-synthesis preview for one upcoming match: facts, recent form for both teams, current league standing, 'context.{home,away}_next_opponent_after_this_match' and 'context.{home,away}_previous_opponent_before_this_match' — each team's neighboring fixture relative to THIS match specifically, not necessarily the team's real current next/previous match (if asking 'what's Colo-Colo's next match' as of right now, use team.fixture(when='next') instead — these two fields answer 'who did/will they play around the time of this specific match'), rule-derived insights (win/loss streaks, table position), and 'press_context' — up to 2 press-sourced notes (stakes, injuries, narrative context) from distinct outlets when available (empty list otherwise; only populated within a few days of the match once the offline press loader has run). CFDB has no dedicated injury-tracking tool or field — injury mentions, when present at all, are incidental content inside these press notes. An empty or missing 'press_context' means no press coverage was loaded for this match (injuries or otherwise) — never read it as 'no injuries'; say coverage isn't available rather than implying a clean bill of health. Each press_context entry has 'scraped_at' (when CFDB captured it — always present) and 'published_at' (the article's own date, often null). Standings/points/goal-count figures mentioned inside a press note's narrative_context are a snapshot from that capture time, not live — this tool's own 'facts'/standings fields (and league.standings/player.top_scorers directly) are always more current; prefer those over a number quoted in press narrative when they disagree. 'context.pre_match_streak' gives each team's win/loss streak going INTO this match ({'home': {...}, 'away': {...}}, each {'type': 'W'|'L'|'D'|null, 'length': int}) — explicitly pre-match; match.report exposes the corresponding 'post_match_streak' for a finished fixture, and the two must never be confused. All kickoff times are Chile local time (America/Santiago). Requires 'fixture_id'.

Get a post-match recap for one finished match: result headline, everything match.dossier returns, plus 'events' — the full goals/cards/substitutions timeline (same shape as match.events, no separate call needed), 'player_ratings' — every player from BOTH teams who has a real match rating on file, already sorted highest-to-lowest, each entry {player_id, name, team_id, team_name, rating, goals, assists} (goals/assists counted from this same match's real events); empty list if no player in the match has a rating loaded yet. Use this one field for every 'destacado'/'figura'/rating-related question about this match instead of calling player.match_stats per-player: for the overall standout, take player_ratings[0]; for one team's standout ('la figura de la U'), filter to that team_id first, then take its first entry — if that filtered list is empty, say that team has no rating data for this match rather than guessing one from the goal timeline, even when the other team's entries exist; for a top-N ranking, take the first N entries (per team or overall, matching what was asked); for 'quién rindió peor', take the last entry (again per team if asked that way). And 'press_context' — up to 2 press-sourced notes (reactions, incidents, why the result happened) from distinct outlets when available (empty list otherwise; only populated within a day of the match once the offline post-match press loader has run), each with 'scraped_at' (when CFDB captured it). 'context.post_match_streak' gives each team's REAL win/loss streak AFTER this match ({'home': {...}, 'away': {...}}, each {'type': 'W'|'L'|'D'|null, 'length': int}) — this match's own result is already folded in, so a loss correctly shows type='L', even if the team arrived on a long win streak (that pre-match streak is still available separately as 'context.pre_match_streak', inherited from match.dossier, but never use it to describe the team's CURRENT streak in a report — only post_match_streak is current after the final whistle). Same caution applies to 'context.{home,away}_next_opponent_after_this_match' (inherited from match.dossier) when reporting on an OLD match: it names the team's next fixture after THAT specific match, which by the time you're reading the report may already be in the past too — never read it as 'their next match as of today'; use team.fixture(when='next') for that. Fails with reason 'not_finished' if the match hasn't been played yet. Requires 'fixture_id'.

Search for matches by date (exact or range), team(s), competition, and/or exact season label — all filters are combinable, at least one is required. Transparently searches both CFDB's historical archive (1933-2023) and live data (2024-present) in one call — the caller never needs to know which source a given date falls into. This tool itself never returns goalscorers for either era — for goal-by-goal detail, chain into match.events/match.report (only for 'live' rows, using their fixture_id) or historical.matches (for 'historical' rows, using the result's competition_name/season_label — historical goal detail is per-season, not looked up per match; it exists for many but not all loaded matches, empty means not loaded, never assume a historical match has no recorded scorers just because fixture_id is null here). Each result is tagged 'source': 'historical' or 'live'; 'fixture_id' is null for historical rows. Every result also has 'status' ('scheduled', 'live', 'finished', 'postponed', 'cancelled', or 'unknown' — historical rows are always 'finished'); a 'scheduled' match's 'home_score'/'away_score' are always null, never a placeholder 0-0 — the match hasn't been played yet. There is no in-play minute/clock available (CFDB doesn't poll live match state at that granularity), so 'live' only means the match has started and isn't finished, nothing more precise. Results are paginated with 'limit' (default 50, max 200) and 'offset' (default 0); 'total_found', 'has_more', and 'truncated' make omitted rows explicit. Complements, not a replacement for, team.fixture/match.matchday_results/historical.matches/team.h2h, which stay better suited to their specific use cases.

Scan one matchday for narrative angles: win/loss streaks (3+ games), winless streaks (5+ games without a win, includes draws), relegation-zone teams (bottom 2 of the current table — a simple proxy based on this season's table only, NOT Chile's official 3-season rolling-average relegation calculation, which CFDB does not compute), teams ≥10 points off the league leader, and goal-scoring milestones (a player reaching a multiple of 5 season goals — only surfaced for 'previous' matchdays, since future matches have no goals yet). Requires 'when' ('upcoming' or 'previous'); 'league_name' is optional.

A coverage/audit snapshot of what CFDB actually has on file — real counts, not estimates: total matches (historical vs. live, with/without an exact date, with goal-by-goal detail), a breakdown by competition (matches and seasons/editions per competition, both historical and live), and player/coach/team profile completeness (how many have a position, date of birth, nationality, external profile, career history, etc.). Also 'most_recently_finished_live_match_at' as an approximate freshness signal (NOT an exact ingestion log — CFDB doesn't store one; see the response's own 'note'). Deliberately does NOT judge any season as 'complete' or 'partial' — this project has too many real, individually-documented partial-coverage cases for a cheap heuristic to get right; use historical.season_summary for that, per-season. ONLY call this tool when a user specifically asks about CFDB's own coverage, size, or data completeness (e.g. 'how many matches do you have', 'do you have player nationality data', a request to verify a coverage claim) — it is not part of answering a normal football question, and calling it for every unrelated query wastes a call for no benefit. Takes no arguments.

Compare two players' current-season stats (matches played, minutes, goals, assists, cards — same fields as player.season_stats, one call per player) plus 'insights' — multiple comparative lines (goals, assists, minutes played, and rating when both players have it), including an explicit warning when the two players' minutes played differ by 300+ (their numbers aren't directly comparable at that point). Optional 'league_name' scopes both players' stats to one competition, same as player.season_stats. Requires 'player_a_name' and 'player_b_name'.

Get one player's performance in one specific match (not a season average — use player.season_stats for that): is_starter, minutes_played, is_captain, and a curated set of match stats (rating, passes, accurate_passes, key_passes, shots_total, shots_on_target, tackles, interceptions, duels_won, successful_dribbles, fouls, saves, goals_conceded). Does NOT include goals/assists/yellow_cards for this match — use match.events for those. Any stat field can be null if the underlying data feed didn't record it for that match — never assume 0. Fails with reason 'not_found' if the player has no recorded appearance in that fixture. Requires 'fixture_id' and 'player_id' (get player ids from match.events or team.squad).

Get a player's basic profile: position, nationality, date of birth, and current team (team_id + name). Position/date_of_birth return null when not on file — never fabricated. Also includes 'external_profile' — full name, place of birth, height (cm), preferred foot, an external profile link, and club career history (populated only for players loaded before this pipeline switched sources — always empty for newly processed profiles because the current profile source doesn't expose transfer history), or null when no confident match was found (resolved by an exact name match against the external profile source; if more than one player shares that name, narrowed by current club membership; ambiguous matches are skipped, never guessed; only populated once the offline player profile loader has run for this player). Requires 'player_name'.

Get a player's current-season stats (matches played, minutes, goals, assists, cards). Assists are inferred from goal-event data and may undercount. Also includes 'advanced_stats' — a curated set of season stats (rating, accurate_passes_percentage, key_passes, shots_total, shots_on_target, big_chances_created, tackles, interceptions, duels_won, successful_dribbles, fouls, saves, goals_conceded), or null when not yet migrated for this player+competition, or null when the player has current-season advanced stats in more than one competition (e.g. league + cup) and no 'league_name' was given — in that case, 'advanced_stats_available_leagues' lists which competitions have data, so you can retry with 'league_name'. Any individual advanced_stats field can itself be null if the underlying data feed never recorded it — never assume 0. Requires 'player_name'; optional 'league_name' to narrow scope.

Get a season player ranking by a single stat: 'goals', 'assists', 'rating', 'accurate_passes_percentage', 'duels_won', or 'tackles'. Requires 'stat'. Optional 'league_name' (defaults to the server's default league); two independent, combinable position filters -- 'position_group' (coarse: 'GK'/'DEF'/'MID'/'FWD') and 'position' (exact: e.g. 'Left Back', 'Central Midfield' -- use this one for a specific role like 'left-backs' or 'wingers', not just position_group's broad DEF/MID/FWD split); use either alone or both together (AND). Both have real, partial coverage -- a filtered ranking may come back shorter than top_n or empty, which reflects real data coverage, not a missing feature, never fill the gap with a guess. Also 'seasons_back' (0=current season, up to 2 seasons back), 'top_n' (default 10, max 10). 'rating' and 'accurate_passes_percentage' exclude players under 450 minutes played that season and return an 'insufficient_sample' error if nobody clears that floor; the other stats have no floor. Every row includes 'matches_played' and both 'position_group'/'position' regardless of which stat or filter was requested.

Get a player's suspension risk from accumulated yellow cards this season (4 = risk, 5 = automatic suspension per Chilean football rules; no reset-after-serving logic), scoped to a single competition — suspension accumulation is per-competition, never blended. If the player has current-season appearances in more than one competition (league, cup, etc.) and no 'league_name' is given, returns a 'competition_required' error listing 'available_competitions' instead of guessing which one; retry with 'league_name' set to one of those. Requires 'player_name'.

Get a league's current-season top scorer ranking: rank, player (id + name), team (id + name), and goal count, sorted descending. Requires 'league_name'; optional 'top_n' (default 10).

Compare two teams' current-season standing, with an interpretive insight (not just numbers side by side). Requires 'team_a_name' and 'team_b_name'.

Get a team's next or last match, with the full fixture detail already included — no follow-up call needed. Kickoff time is Chile local time (America/Santiago). Each team's 'streak' includes that team's own result in this match when it's finished ('when'='last'); for a scheduled match ('when'='next') there's no result yet, so 'streak' is the streak going into the match instead. 'status' is 'scheduled', 'live', 'finished', 'postponed', 'cancelled', or 'unknown' — no in-play minute/clock is available. Requires 'team_name' and 'when' ('next' or 'last').

Get a team's recent form (last N finished matches, default 5) and current win/loss streak. Kickoff times are Chile local time (America/Santiago). Requires 'team_name'.

Get head-to-head history between two teams, blending live matches (current schema) with CFDB's historical archive (back to 1933 where loaded) into one pre-counted win/draw summary. Each match is tagged 'domain': 'live' or 'historical', and 'date_precision': 'exact' (real match_date/starting_at) or 'season_only' (no exact date on file for this historical match -- 'starting_at' is null, but 'season_label' names the season it happened in, e.g. '1958'; the match list is still ordered using that season as a fallback, so a 'season_only' match sorts into roughly the right position, but its exact rank relative to other matches in the SAME season is not knowable from this data -- never state a precise chronological position like 'match #200' across date_precision boundaries, only 'around/during season X'). Optional 'competition_name' scopes results to one competition (e.g. only league matches, excluding cup ties) — resolved independently against live and historical competition names, which may use different naming (e.g. 'Chilean Cup' vs 'Copa Chile'); if the competition isn't found in one source but is in the other, results come from whichever source matched. Also returns 'biggest_win_team_a'/'biggest_win_team_b' (the largest-margin win each side has recorded against the other, with a 'margin' field; null if that team has never won). 'matches' is capped to 'limit' (default 5, most recent first) — check 'matches_truncated' for whether more exist. The aggregate counts (team_a_wins/team_b_wins/draws/total) always reflect the FULL matching record regardless of 'limit' — for 'how many times have they played' or a full historical reconciliation, read 'total', never len(matches). Optional 'date_from'/'date_to' scope both the returned matches AND the aggregate counts to a date range (excludes 'season_only' undated historical matches when set). Requires 'team_a_name' and 'team_b_name'.

Get one team's stat profile in one specific match: a curated set of match stats (possession_percentage, successful_passes_percentage, shots_total, shots_on_target, corners, fouls, tackles, duels_won, interceptions, big_chances_created). This is the team-level counterpart to player.match_stats. Does NOT include goals (use match.matchday_results/team.fixture for the score) or cards (use match.events). Any stat field can be null if the underlying data feed didn't record it for that match — never assume 0. Fails with reason 'not_found' if no stats are recorded for that team in that fixture. Requires 'fixture_id' and 'team_id'.

Get a team's profile: current coach (null if none on file), 'rivals' (all historic rivals on file, deterministically ordered, possibly empty), legacy singular 'rival' (populated only when exactly one rival is on file; null when there are none or several, because CFDB does not guess which is primary), 'founded' — the team's founding year, null until manually loaded for that team (no automated feed provides this; a small, curated set of teams have it, not all), and 'external_profile' — stadium name, stadium city, and a short narrative bio, all sourced from a single Wikipedia article per team and manually curated (never auto-refreshed), or null when not yet loaded for that team. Requires 'team_name'.

Get a team's squad for one specific season/year — 'team_name' is matched case/accent-insensitively; 'season_label' must still match exactly (e.g. '2000', 'Apertura 2002' — check historical.season_summary for the exact label). Coverage is partial: only the current canonical season is auto-populated (from live squad membership); every other season, historical or canonical, returns an empty roster until it has been loaded by hand. An empty roster means 'not loaded yet', not 'no players'.

Get a team's current roster: each player's id, name, position (may be null when not on file), 'joined_at' (may be null — not always on file), and 'last_seen_at' — the date of that player's most recent match appearance for this specific team, so you can judge how current the listing actually is for that player (a player last seen a while ago may be injured/out of favor rather than genuinely gone). Membership is auto-derived from match appearances and excludes anyone with no appearance for the team in the last ~200 days — not a live, minute-by-minute transfer feed. Requires 'team_name'.

Get a team's current position in its league table (points, played, wins/draws/losses, goal difference, position). For a competition split into groups (e.g. Copa Chile's group stage), position/total_teams are scoped to the team's own group, not the whole competition, and a 'group_name' field is included. Requires 'team_name'; optional 'league_name' to disambiguate a team that plays in more than one current competition. 'group_fixtures_remaining' is how many of this team's own group/table matches are scheduled but not yet finished — 0 does NOT necessarily mean the group/season has concluded, only that CFDB has no more of its matches loaded yet; never assume 'group is over' or 'team has qualified' from played==total_teams-based math alone, check this field (or call match.search/team.fixture for the next round) instead.

Get a season team ranking by a single stat: 'possession_percentage', 'successful_passes_percentage', 'shots_total', 'duels_won', 'tackles', or 'big_chances_created'. Requires 'stat'. Optional 'league_name' (defaults to the server's default league), 'seasons_back' (0=current season, up to 2 seasons back), 'top_n' (default 10, max 10). Only counts finished matches. 'possession_percentage' and 'successful_passes_percentage' are per-match averages and exclude teams under 3 finished matches that season (returns 'insufficient_sample' if nobody clears that floor); the other stats are season totals with no floor.

Get how many times a team has won a competition, blending CFDB's historical records with finished current-schema seasons (same table-based-competition scope as league.champion_history). 'league_name' is optional — a question like 'how many titles does X have' is ambiguous in scope (one competition vs. every official title), so omitting 'league_name' returns 'total_official_titles' plus an 'included_competitions' list naming exactly which competitions that total covers (Primera División, Copa Chile, Supercopa, Copa de la Liga — NOT Liguilla Pre-Libertadores/Pre-Sudamericana, which have their own real titles via league_name='Liguilla Pre-Libertadores' but aren't summed into this total) plus a 'by_competition' breakdown, instead of silently picking one competition or implying a grand total across every title CFDB knows about. Pass 'league_name' only when the user actually specified a competition. 'team_name' accepts common nicknames/abbreviations ('la U', 'el Cacique', 'U de Chile') via the same alias resolution team.fixture uses; an unresolved or misspelled name returns a not_found error, never a false '0 titles'. Requires 'team_name'.