fantasy-football-manager

Overview Schema Source Related Servers Discussions Admin

import_league_snapshot

Destructive

Import a complete league snapshot to update your league state. Replaces the current snapshot revision to keep draft history, rosters, and rules consistent, while preserving pending moves until reconciliation.

Instructions

Validate and save a complete league snapshot supplied by the caller.

Use the ESPN companion to fetch live observations or load_demo for fictional data. Replacement requires the current snapshot revision and preserves observation order and confirmed draft history. Pending browser submissions, HTTP submissions, and queued waivers retain their original context and rules until reconciliation resolves them. Changing the league, selected team, or season resets configuration to defaults. Records the import, increments the snapshot revision, and invalidates unexecuted proposals and monitor results. Returns status='imported', revision, config_revision, and config_reset, or an error without replacing state.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`snapshot`	Yes	Complete league observation. Use fantasy://schema/snapshot for fields, defaults, and rules. This is replacement data, not a patch.
`expected_revision`	No	Current snapshot revision from get_team or get_capabilities. Omit only for the first import into empty state.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.1.2Sep 10, 2026

addedInput schema / properties / snapshot / properties / players / items / properties / espn

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "acquisition_status": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Acquisition Status"
+        },
+        "bye_verified": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Bye Verified"
+        },
+        "droppable": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Droppable"
+        },
+        "eligible_slots": {
+          "items": {
+            "type": "integer"
+          },
+          "title": "Eligible Slots",
+          "type": "array"
+        },
+        "injured": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Injured"
+        },
+        "pending_transaction_ids": {
+          "items": {
+            "type": "string"
+          },
+          "title": "Pending Transaction Ids",
+          "type": "array"
+        },
+        "roster_locked": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Roster Locked"
+        },
+        "trade_locked": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Trade Locked"
+        },
+        "waiver_process_date": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Waiver Process Date"
+        }
+      },
+      "title": "ESPNPlayerState",
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / snapshot / properties / source / properties / http

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "acquisition_limit": {
+          "anyOf": [
+            {
+              "minimum": -1,
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Acquisition Limit"
+        },
+        "acquisition_type": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Acquisition Type"
+        },
+        "acquisitions_period": {
+          "anyOf": [
+            {
+              "minimum": 0,
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Acquisitions Period"
+        },
+        "acquisitions_season": {
+          "anyOf": [
+            {
+              "minimum": 0,
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Acquisitions Season"
+        },
+        "final_period": {
+          "maximum": 18,
+          "minimum": 1,
+          "title": "Final Period",
+          "type": "integer"
+        },
+        "latest_period": {
+          "maximum": 18,
+          "minimum": 1,
+          "title": "Latest Period",
+          "type": "integer"
+        },
+        "league_id": {
+          "title": "League Id",
+          "type": "string"
+        },
+        "matchup_acquisition_limit": {
+          "anyOf": [
+            {
+              "minimum": -1,
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Matchup Acquisition Limit"
+        },
+        "minimum_bid": {
+          "anyOf": [
+            {
+              "minimum": 0,
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Minimum Bid"
+        },
+        "ownership_verified": {
+          "title": "Ownership Verified",
+          "type": "boolean"
+        },
+        "pending_transactions": {
+          "items": {
+            "additionalProperties": true,
+            "type": "object"
+          },
+          "title": "Pending Transactions",
+          "type": "array"
+        },
+        "pending_transactions_known": {
+          "default": false,
+          "title": "Pending Transactions Known",
+          "type": "boolean"
+        },
+        "recent_transactions": {
+          "items": {
+            "additionalProperties": true,
+            "type": "object"
+          },
+          "title": "Recent Transactions",
+          "type": "array"
+        },
+        "roster_url": {
+          "title": "Roster Url",
+          "type": "string"
+        },
+        "season": {
+          "title": "Season",
+          "type": "integer"
+        },
+        "team_id": {
+          "title": "Team Id",
+          "type": "string"
+        },
+        "team_transaction_locked": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Team Transaction Locked"
+        },
+        "transaction_period": {
+          "maximum": 18,
+          "minimum": 1,
+          "title": "Transaction Period",
+          "type": "integer"
+        },
+        "uses_faab": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Uses Faab"
+        },
+        "uses_undroppable_list": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Uses Undroppable List"
+        },
+        "week": {
+          "title": "Week",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "league_id",
+        "team_id",
+        "season",
+        "week",
+        "roster_url",
+        "ownership_verified",
+        "transaction_period",
+        "latest_period",
+        "final_period"
+      ],
+      "title": "ESPNHTTPObservation",
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

Changed6 schema fields changedv0.1.1Sep 9, 2026

addedInput schema / properties / expected_revision / description

Added value: +"Current snapshot revision from get_team or get_capabilities. Omit only for the first import into empty state."

changedInput schema / properties / snapshot / additionalProperties
```
Previous value: -trueNew value: +false
```

addedInput schema / properties / snapshot / description

Added value: +"Complete league observation. Use fantasy://schema/snapshot for fields, defaults, and rules. This is replacement data, not a patch."

addedInput schema / properties / snapshot / properties

Added value: +{
+  "budget": {
+    "anyOf": [
+      {
+        "additionalProperties": false,
+        "properties": {
+          "balance": {
+            "minimum": 0,
+            "title": "Balance",
+            "type": "integer"
+          },
+          "pending_amount": {
+            "anyOf": [
+              {
+                "minimum": 0,
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "title": "Pending Amount"
+          },
+          "pending_moves": {
+            "anyOf": [
+              {
+                "minimum": 0,
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "title": "Pending Moves"
+          },
+          "roster_moves_week": {
+            "default": 0,
+            "minimum": 0,
+            "title": "Roster Moves Week",
+            "type": "integer"
+          },
+          "spent_season": {
+            "default": 0,
+            "minimum": 0,
+            "title": "Spent Season",
+            "type": "integer"
+          },
+          "spent_week": {
+            "default": 0,
+            "minimum": 0,
+            "title": "Spent Week",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "balance"
+        ],
+        "title": "Budget",
+        "type": "object"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "description": "Selected team's current FAAB balance, spending, and pending commitments. Acquisitions require known budget and move counts."
+  },
+  "league_id": {
+    "description": "Stable league identifier from the observation provider.",
+    "maxLength": 120,
+    "minLength": 1,
+    "title": "League Id",
+    "type": "string"
+  },
+  "phase": {
+    "default": "season",
+    "description": "Use draft for pick analysis or season for weekly roster analysis.",
+    "enum": [
+      "draft",
+      "season"
+    ],
+    "title": "Phase",
+    "type": "string"
+  },
+  "picks": {
+    "description": "Complete ordered draft history, starting at pick 1 with no gaps. Draft rosters must match these picks.",
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "pick_no": {
+          "maximum": 1280,
+          "minimum": 1,
+          "title": "Pick No",
+          "type": "integer"
+        },
+        "player_id": {
+          "title": "Player Id",
+          "type": "string"
+        },
+        "slot": {
+          "maximum": 32,
+          "minimum": 1,
+          "title": "Slot",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "pick_no",
+        "player_id",
+        "slot"
+      ],
+      "title": "Pick",
+      "type": "object"
+    },
+    "title": "Picks",
+    "type": "array"
+  },
+  "players": {
+    "description": "Unique available and rostered player identities. Projections must already use the league's scoring system.",
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "adp": {
+          "default": 999,
+          "exclusiveMinimum": 0,
+          "title": "Adp",
+          "type": "number"
+        },
+        "availability": {
+          "default": "UNKNOWN",
+          "title": "Availability",
+          "type": "string"
+        },
+        "bye": {
+          "anyOf": [
+            {
+              "maximum": 18,
+              "minimum": 1,
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Bye"
+        },
+        "eligible_positions": {
+          "items": {
+            "type": "string"
+          },
+          "title": "Eligible Positions",
+          "type": "array"
+        },
+        "id": {
+          "maxLength": 120,
+          "minLength": 1,
+          "title": "Id",
+          "type": "string"
+        },
+        "locked": {
+          "default": false,
+          "title": "Locked",
+          "type": "boolean"
+        },
+        "name": {
+          "maxLength": 160,
+          "minLength": 1,
+          "title": "Name",
+          "type": "string"
+        },
+        "position": {
+          "enum": [
+            "QB",
+            "RB",
+            "WR",
+            "TE",
+            "DST",
+            "K"
+          ],
+          "title": "Position",
+          "type": "string"
+        },
+        "projection": {
+          "anyOf": [
+            {
+              "minimum": 0,
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Full-season fantasy projection. Draft data requires a value except for verified opponent picks retained as identities.",
+          "title": "Projection"
+        },
+        "team": {
+          "default": "",
+          "title": "Team",
+          "type": "string"
+        },
+        "weekly_ceiling": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Weekly Ceiling"
+        },
+        "weekly_floor": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Weekly Floor"
+        },
+        "weekly_projection": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Weekly Projection"
+        }
+      },
+      "required": [
+        "id",
+        "name",
+        "position"
+      ],
+      "title": "Player",
+      "type": "object"
+    },
+    "maxItems": 10000,
+    "minItems": 1,
+    "title": "Players",
+    "type": "array"
+  },
+  "rules": {
+    "additionalProperties": false,
+    "description": "League roster rules. Draft rounds equal starter slots plus bench slots. Injured reserve slots are separate.",
+    "properties": {
+      "bench": {
+        "default": 5,
+        "maximum": 30,
+        "minimum": 0,
+        "title": "Bench",
+        "type": "integer"
+      },
+      "caps": {
+        "additionalProperties": {
+          "type": "integer"
+        },
+        "title": "Caps",
+        "type": "object"
+      },
+      "flex_eligible": {
+        "items": {
+          "type": "string"
+        },
+        "title": "Flex Eligible",
+        "type": "array"
+      },
+      "ir": {
+        "default": 2,
+        "maximum": 10,
+        "minimum": 0,
+        "title": "Ir",
+        "type": "integer"
+      },
+      "rounds": {
+        "default": 14,
+        "maximum": 40,
+        "minimum": 1,
+        "title": "Rounds",
+        "type": "integer"
+      },
+      "slot": {
+        "default": 1,
+        "maximum": 32,
+        "minimum": 1,
+        "title": "Slot",
+        "type": "integer"
+      },
+      "snake": {
+        "default": true,
+        "title": "Snake",
+        "type": "boolean"
+      },
+      "starters": {
+        "additionalProperties": {
+          "type": "integer"
+        },
+        "title": "Starters",
+        "type": "object"
+      },
+      "teams": {
+        "default": 14,
+        "maximum": 32,
+        "minimum": 2,
+        "title": "Teams",
+        "type": "integer"
+      }
+    },
+    "title": "Rules",
+    "type": "object"
+  },
+  "schema_version": {
+    "const": 1,
+    "default": 1,
+    "title": "Schema Version",
+    "type": "integer"
+  },
+  "season": {
+    "description": "Season year for this league context.",
+    "maximum": 2100,
+    "minimum": 2020,
+    "title": "Season",
+    "type": "integer"
+  },
+  "source": {
+    "additionalProperties": false,
+    "description": "Observation provenance and freshness. Timestamps require a UTC offset and must describe the actual observation.",
+    "properties": {
+      "browser": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "autopick_enabled": {
+                "anyOf": [
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "title": "Autopick Enabled"
+              },
+              "current_pick": {
+                "anyOf": [
+                  {
+                    "maximum": 1281,
+                    "minimum": 1,
+                    "type": "integer"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "title": "Current Pick"
+              },
+              "draft_complete": {
+                "default": false,
+                "title": "Draft Complete",
+                "type": "boolean"
+              },
+              "league_id": {
+                "title": "League Id",
+                "type": "string"
+              },
+              "page_url": {
+                "maxLength": 2048,
+                "title": "Page Url",
+                "type": "string"
+              },
+              "team_id": {
+                "title": "Team Id",
+                "type": "string"
+              }
+            },
+            "required": [
+              "page_url",
+              "league_id",
+              "team_id"
+            ],
+            "title": "BrowserObservation",
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null
+      },
+      "complete": {
+        "default": true,
+        "description": "True only when the observation contains the complete required league context and draft history.",
+        "title": "Complete",
+        "type": "boolean"
+      },
+      "locks_scope": {
+        "description": "Extent of verified player locks. ESPN browser observations without this field default to selected_team.",
+        "enum": [
+          "league",
+          "selected_team"
+        ],
+        "title": "Locks Scope",
+        "type": "string"
+      },
+      "locks_verified": {
+        "default": false,
+        "description": "True only when current player lock states have been verified for locks_scope.",
+        "title": "Locks Verified",
+        "type": "boolean"
+      },
+      "notes": {
+        "items": {
+          "type": "string"
+        },
+        "title": "Notes",
+        "type": "array"
+      },
+      "observed_at": {
+        "description": "Timestamp when the source was observed, with a UTC offset.",
+        "format": "date-time",
+        "title": "Observed At",
+        "type": "string"
+      },
+      "projections_observed_at": {
+        "anyOf": [
+          {
+            "format": "date-time",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Timestamp when projections were observed, with a UTC offset. Draft, lineup, and acquisition checks require a known fresh timestamp.",
+        "title": "Projections Observed At"
+      },
+      "provider": {
+        "maxLength": 80,
+        "minLength": 1,
+        "title": "Provider",
+        "type": "string"
+      },
+      "synthetic": {
+        "default": false,
+        "description": "True only for fictional observations. Demo actions also require provider='synthetic'.",
+        "title": "Synthetic",
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "provider",
+      "observed_at"
+    ],
+    "title": "Source",
+    "type": "object"
+  },
+  "team_id": {
+    "description": "Selected team's ID. Its draft slot must match rules.slot.",
+    "maxLength": 120,
+    "minLength": 1,
+    "title": "Team Id",
+    "type": "string"
+  },
+  "teams": {
+    "description": "Every league team, with unique IDs and draft slots. Roster IDs must reference known players with unique ownership.",
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "maxLength": 120,
+          "minLength": 1,
+          "title": "Id",
+          "type": "string"
+        },
+        "lineup": {
+          "additionalProperties": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "title": "Lineup",
+          "type": "object"
+        },
+        "name": {
+          "maxLength": 160,
+          "minLength": 1,
+          "title": "Name",
+          "type": "string"
+        },
+        "reserve_ids": {
+          "items": {
+            "type": "string"
+          },
+          "title": "Reserve Ids",
+          "type": "array"
+        },
+        "roster_ids": {
+          "items": {
+            "type": "string"
+          },
+          "title": "Roster Ids",
+          "type": "array"
+        },
+        "slot": {
+          "maximum": 32,
+          "minimum": 1,
+          "title": "Slot",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "id",
+        "name",
+        "slot"
+      ],
+      "title": "Team",
+      "type": "object"
+    },
+    "maxItems": 32,
+    "minItems": 2,
+    "title": "Teams",
+    "type": "array"
+  },
+  "week": {
+    "default": 1,
+    "description": "Scoring week used by weekly projections and season actions.",
+    "maximum": 18,
+    "minimum": 1,
+    "title": "Week",
+    "type": "integer"
+  }
+}

addedInput schema / properties / snapshot / required

Added value: +[
+  "league_id",
+  "team_id",
+  "season",
+  "source",
+  "rules",
+  "players",
+  "teams"
+]

changedInput schema / properties / snapshot / title

Previous value: -"Snapshot"New value: +"LeagueSnapshot"

First observedv0.1.0Sep 8, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark the tool as destructive, and the description adds substantial behavioral detail: it preserves observation order and draft history, retains pending submissions until reconciliation, resets configuration on league/team/season changes, increments the revision, and invalidates proposals and monitor results. It also states the atomic failure mode: 'an error without replacing state.'

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Seven sentences, front-loaded with the tool's purpose, and every subsequent sentence covers a distinct behavioral or failure characteristic. There is no filler, repetition, or schema duplication.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex, destructive mutation with nested inputs, the description covers preconditions, state invariants, side effects, config reset behavior, and error atomicity. An output schema exists, so return-value details are not a gap; the description even names the key response fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameter details are already documented in the input schema. The main prose mentions 'current snapshot revision' as a precondition, matching expected_revision, but does not add new format, syntax, or usage information beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Validate and save a complete league snapshot supplied by the caller.' It distinguishes itself from sibling tools by naming the ESPN companion and load_demo for how data should be obtained, making the tool's role as the importer clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete usage context: use the ESPN companion for live observations or load_demo for fictional data, and use the current snapshot revision for replacement. It does not formally state 'do not use this for fetching live data', but the alternative paths and precondition are explicit enough for an agent to choose correctly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server