MCP tools

get_league_commentary

Read first. This tool checks for the canonical commentary and never starts generation.

Input	Required	Meaning
league	Yes	Public league ID, FPL league URL, or league name.
gameweek	No	A Gameweek from 1 to 38. Omit it for the current available week.

It can return a completed edition, an in-progress job, not_generated, or a request for league selection. At full-time, not_generated can also say the current Gameweek is available to reserve while FPL scoring settles.

generate_weekly_commentary

Create, reserve, or reuse the canonical written edition for the current available Gameweek. Call this only after the user explicitly asks Fantasy Pundit to generate or publish commentary.

Input	Required	Meaning
league	Yes	Public league ID, FPL league URL, or league name.

The operation is non-destructive and idempotent: repeated calls for the same league and Gameweek reuse the same official job or result. A full-time reservation waits until FPL scoring is ready before writing begins; it may start before FPL changes the public Gameweek label. It may consume limited shared generation capacity.

An optional gameweek input guards the current week returned by the preceding read or failed job. If the available week has changed, the call returns FPL_GAMEWEEK_CHANGED before creating work. Read the league again and ask before requesting a different edition. This guard does not allow historical generation.

get_commentary_result

Poll the job returned by generate_weekly_commentary. It never starts another generation.

Input	Required	Meaning
jobId	Yes	Weekly commentary job ID returned by the generation tool.

Continue only while the result is queued or processing, and respect pollAfterSeconds when it is returned. Stop on completed or failed.

Completed response shape

The exact response can grow without breaking clients, so clients should rely on the stable fields they use:

{
  "status": "completed",
  "nextStep": "present_commentary",
  "jobId": "…",
  "league": { "id": "[public league ID]", "name": "Example League" },
  "seasonId": "2026-27",
  "gameweek": 7,
  "commentary": {},
  "share": { "url": "…", "text": "…" },
  "links": { "leagueUrl": "…" }
}

Additional fields may be present. Clients should ignore fields they do not understand.

Next steps and richer clients

Every successful result includes nextStep: present_commentary, poll, ask_to_generate, choose_league, ask_to_retry, or unavailable. A read or status check never grants permission to create an edition. tools/list advertises the full output schema, including commentary, candidates, links and polling delays. Errors use isError: true and structuredContent.error.

The server supports modern 2026-07-28 discovery through server/discover and stateless connections from older 2025 clients. Modern clients with elicitation forms can show league choices in the conversation. Cancelled or unsupported forms fall back to the candidate list; the user can provide an exact ID instead.

MCP Apps clients can show an embedded weekly edition with published text, a Gameweek selector, waiting progress and sharing controls. Choosing a league or Gameweek reads existing commentary. Creation and retries require a button action and guard the displayed Gameweek. The card pauses polling when hidden, respects retry delays and stops automatic checks after five minutes. Text-only clients still receive the same complete result.

Two public resources are available through resources/list and resources/read:

• fantasy-pundit://guide/weekly-commentary: the supported workflow, timing and sharing guidance.
• fantasy-pundit://guide/capabilities: public product availability and supported tools.

The card resource is ui://fantasy-pundit/weekly-edition.html. Hosts discover it through the tools’ UI metadata. It has no external network dependencies and uses the host’s MCP bridge for actions.

Capacity and retry errors

generate_weekly_commentary can return RATE_LIMITED or CAPACITY_REACHED when new work must wait. The structured MCP error includes retryAfterSeconds and resetAt. Wait for that window before trying the same canonical request again; do not create a parallel job or switch to the direct API to bypass the limit.

Existing published editions and the two read-only tools remain available. A direct API fallback returns the same retry fields in its JSON body and also sends the Retry-After response header.