Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@NFL Data MCP search for Patrick Mahomes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A standalone, provenance-aware factual NFL data server for MCP clients and downstream
analytics. In the default auto mode, the server retrieves missing or stale data
from nflverse through nflreadpy and keeps a transparent local DuckDB cache.
Public alpha: tool contracts are usable, tested, and versioned, but may change before 1.0. This project is independent and is not affiliated with the NFL.
The factual v0.1 surface provides:
Canonical player search
Player profiles
Complete weekly player and team statistics across offense, defense, special teams, and miscellaneous categories
NFL schedules
Factual scoring events classified by offense, defense, or special teams
Teams, individual games, weekly rosters, injuries, depth charts, and snap counts
Player and team statistical leaderboards
Automatic on-demand retrieval with last-known-good fallback
Friendly team names and current/upcoming/previous season references
Multi-season cache retention
Cache, source, freshness, and as-of provenance
stdio transport
Fantasy scoring, projections, rankings, ADP, recommendations, and league state are intentionally outside this package.
The server requires Python 3.12. The simplest isolated installation uses uv:
uv tool install nfl-data-mcpThis installs three commands:
nfl-data-mcp — start the MCP server over stdio
nfl-data-sync — optionally prefetch datasets
nfl-data-doctor — inspect the local cache
Upgrade or remove it with:
uv tool upgrade nfl-data-mcp
uv tool uninstall nfl-data-mcpThe package is also available from PyPI.
Related MCP server: StatHead
Configure an MCP client to launch the installed nfl-data-mcp executable. GUI
applications often have a smaller PATH than your terminal, so use the absolute
path printed by:
command -v nfl-data-mcpExample Claude Desktop entry:
{
"mcpServers": {
"nfl-data": {
"command": "/absolute/path/to/nfl-data-mcp",
"args": [],
"env": {
"NFL_MCP_MODE": "auto"
}
}
}
}Fully restart the client after changing its configuration or upgrading the package. See docs/client-setup.md for cache paths, offline mode, and troubleshooting.
uv sync --extra dev
source .venv/bin/activate
pytestThe workspace uses Python 3.12. uv will honor .python-version.
Configuration uses NFL_MCP_ environment variables:
export NFL_MCP_DATA_DIR="$PWD/data"
export NFL_MCP_MODE=autoThe default data directory is the operating system's user-data location. For local
development, setting NFL_MCP_DATA_DIR to a repository-local ignored directory is
recommended.
Modes:
auto (default): use fresh cache data, retrieve missing/stale data, and fall back
to stale data with a warning if the source is temporarily unavailable.
offline: only use cached data and never access the network.
snapshot: read only the prepared catalog, with no automatic updates. Use a
dedicated immutable data directory for reproducible simulations.
No manual synchronization is required in normal use:
cp .env.example .env
nfl-data-mcpFor example, an MCP client can ask for the Jets schedule using:
{"season": "upcoming", "team": "Jets"}The first call retrieves that season's schedule. Later calls use the cache until its dataset-specific freshness window expires.
Administrative prefetching is still available:
nfl-data-sync --season 2026 --datasets schedules --allow-network
nfl-data-doctorThe public v0.1 server runs over local stdio only. Remote HTTP transport is deferred until authentication, tenant isolation, and production request limits are implemented.
search_players
get_player
get_player_stats
get_team_stats
find_stat_games
find_stat_seasons
get_schedule
get_game
get_scoring_events
get_game_stats
list_teams
get_team_roster
get_injuries
get_depth_chart
get_snap_counts
get_stat_leaders
list_stat_fields
get_data_status
All tools are read-only and bounded. Use search_players first, then pass the
returned canonical player_id to player-specific tools. Retired players are included
by default; pass active_only=true when only active players should match. Both
statistics tools use the same unit values: offense, defense, special_teams,
miscellaneous, or all.
Statistics can cover one season, an explicit season list, or an entire career:
{
"player_ids": ["00-0034857"],
"seasons": [2022, 2023, 2024],
"unit": "offense",
"aggregation": "season"
}Use seasons="career" with aggregation="career" for a career summary. Use
find_stat_games for questions such as “In what game did this player record his
first interception?” Use find_stat_seasons for questions such as “What was this
player's career-high passing-yard season?” The per-stat rules are documented in
docs/stat-aggregation.md.
get_scoring_events returns factual scoring plays rather than fantasy points. It
identifies the scoring and conceding teams, possession team, event type, scoring
unit, and point value so downstream systems can apply their own D/ST points-allowed
policy. See docs/scoring-events.md.
uv run ruff format --check src tests
uv run ruff check src tests
uv run mypy src
uv run pytest
uv buildEvery response identifies its source snapshot and point-in-time classification.
Metadata also includes mode, cache_status, freshness, and warnings. The cache
is not the server's data boundary: in auto mode it fills itself from the documented
upstream source.
Week-keyed historical records are not automatically claimed to represent everything
known at that historical moment. Unsupported knowledge-time queries fail explicitly
instead of silently returning later-corrected data.
Downloaded NFL data is not included in this repository. Source attribution and licensing requirements still apply to cached data and downstream redistribution. See THIRD_PARTY_NOTICES.md.
The software is licensed under the Apache License 2.0. Runtime data has separate upstream terms documented in THIRD_PARTY_NOTICES.md. See SECURITY.md for vulnerability reporting and CONTRIBUTING.md for development guidelines.
Find career-high, career-low, first, or last season totals for a statistic.
| Name | Required | Description | Default |
|---|---|---|---|
| stat | Yes | ||
| unit | Yes | ||
| limit | No | ||
| order | No | highest | |
| value | No | ||
| season | No | ||
| seasons | No | ||
| entity_id | Yes | ||
| comparison | No | greater_than | |
| entity_type | Yes | ||
| season_type | No | REG |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds no additional behavioral context beyond what is already captured in annotations, such as any limitations or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at one sentence, but for a tool with 11 parameters and no parameter descriptions, it is overly brief. Every word is functional, but the structure lacks additional context or examples that would aid understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high parameter count (11) and zero schema description coverage, the description is insufficient. The existence of an output schema is not mentioned, and the agent has no information on return format or pagination, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description does not explain the meaning of parameters like 'order', 'comparison', 'season', or 'seasons'. The phrase 'career-high, career-low, first, or last' hints at ordering but fails to map to specific parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Find' and the resource 'career-high, career-low, first, or last season totals for a statistic,' which clearly indicates what the tool does. However, it could be more precise about what 'first' or 'last' means in context, and it does not explicitly differentiate from sibling tools like 'get_stat_leaders'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives or when not to use it. There is no mention of prerequisites or suitable scenarios, leaving the agent without decision support for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report local dataset coverage, snapshot versions, and as-of classifications.
| Name | Required | Description | Default |
|---|---|---|---|
| dataset | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only and idempotent. The description adds specificity about the type of report (coverage, versions, classifications) but does not disclose additional behavioral traits such as permissions or resource impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that delivers the core purpose without any redundant words or structural issues.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the optional parameter is unexplained, and no details on what 'local dataset coverage' or 'snapshot versions' entail, the description is insufficient for a complete agent understanding. The presence of an output schema does not compensate for missing parameter context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fails to explain the 'dataset' parameter. It only mentions local dataset coverage without specifying how the parameter influences the output or what valid values are.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports local dataset coverage, snapshot versions, and as-of classifications, providing a specific verb and resource that distinguishes it from sibling tools focused on game stats or players.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus siblings or alternatives. The description implies it is for checking data status but does not provide conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a factual team depth chart for a season and week.
| Name | Required | Description | Default |
|---|---|---|---|
| team | Yes | ||
| week | Yes | ||
| season | Yes | ||
| position | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and not destructive. The description adds no behavioral context beyond a vague 'factual', missing details like whether data is returned for past/future weeks or how depth chart is defined.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key info. No wasted words, but could benefit from slight expansion for clarity without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only data retrieval tool with output schema, the description is minimally adequate. However, it lacks context on data freshness, week values, or team representation (e.g., name vs abbreviation).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description does not explain any parameter meanings, formats, or constraints beyond the parameter names. For example, 'position' accepts string or null but its purpose is unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a 'team depth chart' for a specific season and week, using the verb 'get' and specifying the resource. It distinguishes from sibling tools like get_team_roster (roster vs depth chart) and get_injuries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No mention of prerequisites, limitations, or context such as data availability or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one scheduled or completed NFL game by canonical game ID.
| Name | Required | Description | Default |
|---|---|---|---|
| season | No | ||
| game_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by specifying game state (scheduled or completed), which is useful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no extraneous words, front-loaded with key information. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Core purpose is clear, annotations and output schema exist, but the optional season parameter is not explained. Minor completeness gap given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 2 parameters but 0% description coverage. Description only mentions game_id implicitly, does not explain the optional season parameter or its usage. Schema coverage is low, and description fails to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool gets a single scheduled or completed NFL game by canonical game ID, using specific verb and resource. It distinguishes from sibling tools like get_schedule (list of games) and get_game_stats (statistics for a game).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use for retrieving a specific game by ID, does not explicitly state when not to use or mention alternatives, but context from sibling tools makes differentiation possible. Lacks exclusions but is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a factual player or team box score for one canonical game ID.
| Name | Required | Description | Default |
|---|---|---|---|
| unit | No | all | |
| limit | No | ||
| season | No | ||
| game_id | Yes | ||
| entity_type | No | player |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description adds marginal value. It notes the tool returns 'factual' data and is for a single game ID, which is additional context but does not disclose behaviors like rate limits or pagination beyond limit/default.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and avoids fluff. It is efficient but could be improved by adding brief parameter context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters with 0% schema coverage and no usage guidance, the description is too sparse. It lacks parameter descriptions, error conditions, and connection to sibling tools (e.g., how to obtain a game_id). The presence of an output schema reduces some burden on return values, but overall completeness is low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description bears full burden for parameter explanation. However, it only hints at 'player or team' (entity_type) and does not explain game_id, unit, limit, or season. This leaves the agent guessing about required inputs beyond the required game_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('box score'), and the scope ('for one canonical game ID'). It also mentions it can be player or team, which aligns with the entity_type parameter, making it distinct from sibling tools like get_game or get_stat_leaders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention siblings, prerequisites (e.g., knowing the game ID), or cases where other tools like get_stat_leaders or search_players would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get official injury and practice-report records.
| Name | Required | Description | Default |
|---|---|---|---|
| team | No | ||
| week | Yes | ||
| limit | No | ||
| season | Yes | ||
| player_ids | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds 'official' and 'practice-report' context but does not disclose additional behavioral traits beyond what annotations provide. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is well front-loaded and efficiently communicates the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description lacks essential details such as parameter explanations, usage context, and output format. For a tool with 5 parameters (2 required), this is insufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% with 5 parameters (team, week, limit, season, player_ids). The description provides no explanation of any parameter, failing to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves 'official injury and practice-report records', specifying the verb (Get) and resource. Among sibling tools, no other tool is focused on injuries, so it is well-distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, exclusions, or context that would help an agent decide to use this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get bounded NFL games for a season, week, or team.
| Name | Required | Description | Default |
|---|---|---|---|
| team | No | ||
| week | No | ||
| limit | No | ||
| season | Yes | ||
| season_type | No | REG |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and open-world hints, so the description's burden is reduced. The description adds 'bounded' which hints at pagination or limits, but doesn't explain rate limits, data freshness, or that results may vary per call. It adds minimal behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, very concise. However, it sacrifices informativeness for brevity. It could include critical details while remaining succinct. It doesn't front-load the most important information (e.g., that it returns a list of games).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (1 required) with no schema descriptions, and an output schema exists, the description should at least explain the main use case and the meaning of parameters. It only gives a vague overview. The agent would be left guessing about how to specify team or week, and what the output contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but only mentions 'season, week, or team' as filters. It fails to explain the season_type (default 'REG'), the limit parameter, that team can be null, or the format of season (integer or string). Parameter semantics are severely lacking.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get bounded NFL games' with filters for season, week, or team, which provides a clear verb and resource. However, 'bounded' is ambiguous (could mean paginated or limited), and it does not distinguish this tool from siblings like 'get_game' or 'get_game_stats' that also retrieve game data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. There is no mention of when not to use it, prerequisites, or comparison to sibling tools. The agent receives no decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank players or teams by one factual statistic.
| Name | Required | Description | Default |
|---|---|---|---|
| stat | Yes | ||
| unit | Yes | ||
| limit | No | ||
| weeks | No | ||
| season | Yes | ||
| entity_type | Yes | ||
| season_type | No | REG |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and not destructive. The description adds no behavioral context beyond what annotations provide, but doesn't contradict them. It remains adequate given the annotation richness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence, front-loaded, but too brief to be useful. It does not earn its place because it omits essential information about parameters and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description is insufficient for a tool with 7 parameters. It does not explain how to rank, what data is returned, or how the ranking works, leaving the agent to infer or guess.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. But it provides no details on what 'stat', 'unit', 'entity_type', etc., mean. The agent gets no help beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool ranks players or teams by a statistic, which is specific and distinguishes it from more general data retrieval siblings like get_schedule or get_team_roster. However, 'one factual statistic' is slightly vague and could be more precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., find_stat_seasons or get_game_stats). No mention of limitations, prerequisites, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a team's factual weekly NFL roster.
| Name | Required | Description | Default |
|---|---|---|---|
| team | Yes | ||
| week | Yes | ||
| season | Yes | ||
| positions | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. Description adds minimal behavioral context ('factual weekly NFL roster') but does not elaborate on important traits like data freshness or potential access limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it concise. However, it is too brief to convey essential details, balancing efficiency with under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, 3 required, and no schema descriptions, the description is incomplete. It does not provide parameter formats, optional behaviors, or output expectations (despite output schema existing). The agent may struggle to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description provides no information about the parameters (team, week, season, positions). The agent must infer meaning from names alone, which is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves a team's weekly NFL roster, specifying the verb 'get' and the resource as a team's weekly roster. It distinguishes from siblings like get_depth_chart (different kind of roster) and get_game (which is about games).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Sibling tools exist (e.g., get_depth_chart, get_injuries) but are not mentioned. No context about prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List valid factual statistic names for player/team leader and stat queries.
| Name | Required | Description | Default |
|---|---|---|---|
| unit | Yes | ||
| season | Yes | ||
| entity_type | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's 'List' aligns. It adds the context of returning valid statistic names but does not disclose additional behaviors like error handling or output structure, which is partially mitigated by the existence of an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately communicates the tool's purpose with no unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three required parameters with no schema descriptions, the tool needs more explanation about parameter usage and allowed values. While the output schema exists, the description fails to provide sufficient context for correct invocation, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the three parameters (unit, season, entity_type). For instance, valid values for 'entity_type' (e.g., player or team) are not mentioned, leaving the agent without necessary context to invoke the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'valid factual statistic names', specifying the scope for player/team leader and stat queries. This distinguishes the tool from siblings like 'get_stat_leaders' or 'find_stat_seasons' which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as 'find_stat_seasons' or 'get_stat_leaders'. The context implicitly suggests it as a prerequisite but lacks explicit when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List canonical NFL team abbreviations and metadata.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds 'canonical' and 'metadata', but these are not behavioral traits. Since annotations cover safety, the description adds minimal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an existing output schema, the description is fully complete. No additional information is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100% by default. Baseline is 4, and the description does not need to explain parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists canonical NFL team abbreviations and metadata, using specific verbs and resources. It distinguishes from sibling tools like get_team_roster, which focus on specific teams rather than a complete list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: call this tool to get all team abbreviations and metadata. No alternatives are explicitly mentioned, but given the simplicity and zero parameters, it's clear when to use it. A brief note on when not to use it would improve, but not required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve active or retired player names; set active_only=true to exclude retirees.
| Name | Required | Description | Default |
|---|---|---|---|
| team | No | ||
| limit | No | ||
| query | Yes | ||
| position | No | ||
| active_only | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context about handling retired vs. active players, which complements the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-front-loaded sentence that efficiently conveys the core purpose and a key parameter tip. Every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is short but adequate for a search tool with an output schema. However, it omits context for the team, position, and limit parameters, and does not mention result ordering or pagination, leaving some gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the description provides no information about most parameters. Only active_only is explained; query, team, limit, and position are left undocumented. This fails to add meaning beyond the schema's property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resolves active or retired player names, which is a specific verb+resource combination. It distinguishes from sibling tools like get_team_roster (which lists players by team) by focusing on name resolution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the active_only parameter as a usage tip, but does not provide guidance on when to use this tool versus alternatives like get_team_roster or other sibling tools, nor does it specify any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0find_stat_seasonsget_data_statusget_depth_chartget_gameget_game_statsget_injuriesget_scheduleget_stat_leadersget_team_rosterlist_stat_fieldslist_teamssearch_playersScored across 12 tools
Each tool targets a distinct data aspect: schedule, game, stats, roster, depth chart, injuries, players, teams, status, and stat fields. There is no overlap in purpose.
All tool names follow a verb_noun pattern using snake_case: get_, list_, find_, search_. No mixed conventions or inconsistent styles.
12 tools cover the essential NFL data endpoints well without being excessive. The count is appropriate for a focused sports data server.
The tool surface covers core NFL data needs: schedule, games, stats, rosters, depth charts, injuries, player search, team listing, and metadata. No significant gaps for a read-only data server.
Token-free MCP server for structured RevoGrid Core, Pro, and Enterprise knowledge retrieval.
NFL analytics tools for AI agents: stats, fantasy, injuries, schedules, and advanced analysis.
NBA MCP — player, team, and game data via the BallDontLie API
NFL/NBA/MLB/NHL/PGA + DFS and prediction-market data. Browse free; query with a free API key.
