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.

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",
  "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.

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.