World Cup Pool

get_current_time

Return the server's current wall-clock time. Use this when reasoning about elapsed time (e.g. current minute of a live match, time remaining until a deadline) — don't guess the time.

create_pool

Create a brand-new World Cup pool. Atomically: creates a platform group with the caller as owner, claims the caller as the pool's agent admin, and writes the initial pool/config blob. `name` becomes the group's display name; optional `config` patches the default settings (escalating_points, free, allow_late_entry, start_round). Returns the new group_id and the resolved pool config.

get_pool

Get an overview of the active pool: name, scoring config, the pinned manager note, members, all entries (across members), the pool manager, the caller's role (member / pool_admin / agent_admin), and the next kickoff deadline. Call this once at the start of a session to ground every downstream decision.

list_matches

List World Cup fixtures with optional filters. Each match comes back with its status (scheduled | live | final) derived from kickoff time and whether a result has been recorded. Use this to ground pick submissions, look up upcoming deadlines, or surface 'what's on now'.

list_groups

Return the tournament's group composition: each group letter with its 4 teams (code, name, flag, rank). Use this to answer 'which group is X in?', to seed bracket projections, or to compute group standings without crawling the full fixture list.

list_results

List World Cup match results. Live matches (result row exists, no winner yet, kickoff has passed) come back with status=live and a live_minute field computed against the server clock. Use this for 'what's the score', 'who won', and 'who's still playing'.

get_my_entry

Return the caller's pool entry / entries (entry id, name, emoji). If there are no entries, the caller hasn't created one yet — direct them to the SPA's Entries page to set up name + emoji.

create_my_entry

Create a new entry in the pool for the caller. An entry is a lineup of picks — one member can hold multiple entries (e.g. their own pick set plus a hedge or a kid's set). Provide a display name and optional emoji. Returns the new entry's id.

update_my_entry

Update the caller's own entry — display name or emoji. Pass only the fields you want to change; others are preserved. Refuses to touch entries owned by another member (managers go through set_picks_for_entry for pick overrides; member metadata edits stay self-only).

delete_my_entry

Delete one of the caller's entries — removes the entry metadata AND every saved pick row for that entry. Irreversible. Refuses to touch entries owned by another member. Returns counts of what was removed.

get_my_picks

Return the caller's submitted picks, optionally filtered to a specific round or to matches whose kickoff is still in the future (upcoming_only=true). Picks are grouped by round_id.

list_picks

List picks across every entry in the pool, with the kickoff lockout enforced server-side: the caller's own picks are always included, but other entries' picks for a given match are only included once that match has kicked off. Filter to one round (`round_id`) and/or one match (`match_id`) to keep responses small. Returns a flat list — one row per (entry, match) pair that the caller is allowed to see.

save_my_picks

Save or update the caller's picks for one round. Pass round_id and a picks map { match_id: choice } where choice is home / away / draw / np (explicit no-pick = 0 points) or null (delete the pick — only meaningful in merge mode against an existing pick on a still-open match). Any pick whose match has already kicked off is rejected — the agent should propose the next still-open match instead. By default the existing picks for that round are merged with the new ones (RFC 7396); pass replace=true to wholesale-replace.

get_my_bonus_picks

Return the caller's bonus picks (champion + golden_boot) for the active pool. Empty row if they haven't saved any picks yet — never errors on absence. Pass entry_id to disambiguate when the caller owns multiple entries.

list_bonus_picks

List bonus picks (champion + golden_boot) across every entry in the pool, with the first-kickoff lockout enforced server-side: the caller's own bonus picks are always included, but other entries' picks are sealed until the tournament's first match has kicked off. Sealed rows carry has_picks=true/false so the agent can answer 'who hasn't picked yet?' without leaking content.

save_my_bonus_picks

Save the caller's pre-tournament bonus picks: champion (ISO 3-letter team code, worth 2 points if correct) and golden_boot (player id from the seeded golden-boot-candidates roster, worth 3 points if correct). Both pick fields lock at the tournament-wide first kickoff. Pass either or both fields to update; pass null to clear an individual field. Partial updates merge with the existing row.

get_standings

Compute the pool's current standings using the canonical scoring rules (flat or escalating per pool/config.escalating_points). Optionally filter to a single round. Results for matches whose kickoff hasn't happened yet are silently dropped — pre-seeded or in-progress final scores for future matches do NOT move the displayed leaderboard. Pass ``as_of`` (ISO 8601 UTC) to project standings forward — e.g. the SPA threads its mock clock here so test-panel timelines line up with the server's gate. Each row carries ``avg_lead_seconds`` (average lead time of picks before kickoff); points-ties are broken by lead time descending so early-bird picks rank ahead. This is the same engine the SPA's Standings page consumes, so chat and SPA answers always agree.

set_pool_config

Update pool configuration. Pass a patch object — only the fields you want to change. manager_user_id and created_at are silently ignored (they can't be changed through this surface). Always echo the resulting config back to the user for confirmation before considering the change done.

set_pool_note

Set the pool's pinned manager note (HTML body). Stamps updated_at and updated_by automatically. Manager-only.

set_pool_banner

Set or clear the pool's short banner pinned to the top of the home page. Distinct from the pinned note: the banner is one short urgent line with an optional safe-href link. Pass an empty `text` to clear the banner. Manager-only.

set_picks_for_entry

Manager override: write picks on behalf of any entry in the pool, even after kickoff. Use sparingly — for absent members or to fix data-entry mistakes. Always confirm the override with the user first, naming the affected entry and round.

refresh_standings

Force a fresh recomputation of the pool's standings, dropping any cached values first. Returns the recomputed leaderboard. Pool-manager only — the cache is normally kept fresh automatically on every pick / result / config / schedule change, so reach for this only when you suspect something is stale or you want to confirm a result write took effect.

set_schedule

Replace the tournament schedule wholesale for a given year. Use this for the initial seed and for full re-imports. For incremental edits (add R16 matches once teams qualify, fix one kickoff time, remove a stray match), use patch_schedule instead. Always show the parsed schedule to the maintainer for confirmation before calling this — never write directly from raw input.

patch_schedule

Incrementally edit the schedule's matches array. `add` appends new matches (e.g. R16 fixtures once group stage is decided). `update` merges fields into existing matches by id (rescheduled kickoff, venue correction, fill in TBD teams). `remove` drops matches by id (cleanup of a wrongly-added match). Always echo the resulting diff back to the maintainer for confirmation before calling.

set_match_result

Write or update a single match result. For final scores, pass winner ('home'/'away'/'draw') plus the two scores. For an in-progress (live) match, leave winner=null and pass the current scores — the SPA shows status=live and the agent can compute the minute from kickoff + get_current_time. Always confirm with the maintainer (proposed diff vs current state) before calling.

set_match_results

Batch-write multiple match results in one call — the workhorse for ingesting a screenshot, file, or bullet-point list. Each entry is validated independently; the response includes a per-match status so the maintainer can see which writes landed and which failed. Always show the parsed batch to the maintainer for confirmation before calling this.

delete_match_result

Delete a match result row entirely. Use this to recover from a data-entry mistake — e.g. you wrote a result for the wrong match. Standings recompute from the remaining rows. Confirm with the maintainer before calling.

set_bonus_results

Write the tournament's Golden Boot winner. Pass golden_boot (player id from the seeded roster, awards 3 points to matching picks). Champion is NOT set here — it's auto-derived from whichever team won the ``final`` round match, so once set_match_result has posted the final's winner, the +2 champion bonus lands automatically. Pass null to clear a previously-set golden boot. Confirm with the maintainer before calling.

set_golden_boot_candidates

Seed or replace the Golden Boot candidate roster for the given year. Pass the full players array — wholesale replace. Each player needs id (stable slug), name, team (ISO 3-letter code), and optional club. The SPA bundles a fallback so this is optional in dev.

patch_golden_boot_candidates

Incrementally edit the Golden Boot candidate roster: add new players, update existing ones by id, or remove ids. Use this instead of set_golden_boot_candidates when you only want to touch a few rows. Always echo the diff back to the maintainer for confirmation before calling.