Provides live access to Premier League data, including teams, rosters, matches, standings, player registrations, and schedule-strength analytics.
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., "@jk-mcp-epl What are the current Premier League standings?"
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.
MCP server that gives Claude live access to Premier League data — teams, matches, standings, rosters, richer player data from Pulselive/Opta, and schedule-strength analytics.
Related MCP server: matchday-mcp
AI assistants like Claude are knowledgeable, but they have a hard cutoff date — they cannot tell you today's Premier League standings, last night's scores, or which teams are fighting for the title, European places, or against relegation. This project fixes that.
It is an MCP server — a plugin that gives Claude direct access to live Premier League data: scores, standings, rosters, derived schedule-strength analytics, and richer per-player registrations from the Pulselive/Opta feed that powers premierleague.com. Once installed, you can ask Claude natural-language questions about the Premier League and get accurate, up-to-date answers. No subscription, no API key, and no programming required to use it.
This is the v1 scaffold: two data sources — ESPN's public API for the normalized league feed, and footballapi.pulselive.com (used unauthenticated, requires an Origin: https://www.premierleague.com header) for Opta-cross-referenced player data. Cup competitions (FA Cup, Carabao Cup) and per-half / xG stats are on the roadmap.
The v1 surface is twelve read-only, idempotent tools split across three tiers.
Tool | Description |
| List all 20 Premier League clubs with IDs and abbreviations |
| Details for a specific team |
| Team's active roster — jersey, position, age, citizenship |
| Match scores for a single day, a date range, or the current matchweek |
| Every match for a team in the current season — past + upcoming |
| One match's full details — score, venue, attendance, goals, cards, subs |
| Current standings — single 20-team table ordered by points |
| Recent Premier League news articles |
Tool | Description |
| Full player registry from the Opta-powered feed — Opta id, shirt number, positional detail (e.g. "Right Winger" vs generic "M"), current-club affiliation, nationality, DoB, loan flag |
Pure functions over live standings + team schedules, exposing schedule-strength context the raw table does not.
Tool | Description |
| Team's average opponent points-per-game across matches already played |
| Team's W-L-T split across current top / middle / bottom standings tiers |
| Team's raw PPG alongside an opponent-quality-adjusted PPG |
Deferred to v2+:
FA Cup (eng.fa) and Carabao Cup (eng.league_cup) — ESPN slugs already available
UEFA competitions (Champions League, Europa) — cross-competition tool surface
Per-half and home/away split standings from Pulselive
xG / shots / advanced Opta stats (Pulselive exposes them; needs an LLM-friendly formatter)
Season lookup by year (currently get_players defaults to the most recent completed season)
git clone https://github.com/jedi-knights/jk-mcp-epl.git
cd jk-mcp-epl
uv syncRun the server in stdio mode (the default — used by Claude Code and Claude Desktop):
uv run python -m epl.serverRun in HTTP mode (for networked or deployed access):
MCP_TRANSPORT=streamable-http uv run python -m epl.serverStandings, scores, rosters:
Who is leading the Premier League right now?
Show me every Premier League result from this past weekend.
Who is on Arsenal's roster?
When does Liverpool play next?
Show me the full Pulselive player registry for Manchester City — who's on loan?
Schedule strength:
Which Premier League team has played the toughest schedule so far?
Show me Arsenal's record against the current top 6 teams.
Compare Manchester City and Liverpool on adjusted points-per-game.
All configuration is via environment variables. None are required for local use.
Variable | Default | Description |
|
| Transport mode: |
|
| Bind address (HTTP transport only) |
|
| TCP port (HTTP transport only) |
|
| URL path (HTTP transport only) |
|
| ESPN API base URL |
|
|
|
| unset | Bootstrap the OpenTelemetry SDK |
| unset | Require RS256 bearer tokens on streamable-http |
| unset | Auth-server origin (required when auth is on) |
| unset | This server's public URL for the |
Install from your local clone globally so the server is available in every project:
claude mcp add --scope user epl -- uv run --directory /path/to/jk-mcp-epl python -m epl.serverReplace /path/to/jk-mcp-epl with the absolute path to your clone. Verify with claude mcp list.
Drop --scope user to register only for the current project, or commit a .mcp.json to the repo root for collaborators:
{
"mcpServers": {
"epl": {
"command": "uv",
"args": ["run", "--directory", "/path/to/jk-mcp-epl", "python", "-m", "epl.server"]
}
}
}Add the following to your Claude Desktop configuration file.
Location:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"epl": {
"command": "uv",
"args": [
"run",
"--directory", "/path/to/jk-mcp-epl",
"python", "-m", "epl.server"
]
}
}
}If uv is not on Claude Desktop's PATH, use the absolute path (which uv will show it). Fully quit and relaunch Claude Desktop after saving — a window close is not enough.
Build the image:
docker build -t jk-mcp-epl:latest .Run in stdio mode (for MCP clients that spawn a subprocess):
docker run -i --rm jk-mcp-epl:latestRun in HTTP mode:
docker run --rm -p 8000:8000 \
-e MCP_TRANSPORT=streamable-http \
jk-mcp-epl:latestuv syncAll common workflows are invoke tasks. Run uv run inv --list to see everything.
Task | Alias | Description |
|
| Run ruff linter and format check |
|
| Auto-fix lint violations and reformat |
|
| Run the full test suite |
|
| Run tests with coverage report (threshold: 90%) |
|
| Check cyclomatic complexity (max 7) |
|
| Build wheel and sdist into |
|
| Build the Docker image |
|
| Remove build and coverage artifacts |
src/epl/
├── server.py # entry point, transport selection, logging setup
├── adapters/
│ ├── inbound/
│ │ ├── mcp_adapter.py # FastMCP server, health endpoints, tool registration
│ │ ├── formatters.py # domain → LLM-readable text
│ │ ├── authorization.py # inbound authz port implementations
│ │ └── tools/
│ │ ├── espn.py # 8 ESPN-backed tools
│ │ └── analytics.py # 3 schedule-strength analytics tools
│ └── outbound/
│ ├── espn_adapter.py # ESPN HTTP client
│ ├── parsers.py # ESPN JSON → domain models
│ ├── retry_adapter.py # transient-failure retry decorator
│ └── caching_adapter.py # in-process TTL cache
├── application/
│ ├── service.py # EPLService — use cases, orchestration
│ ├── _helpers.py # input validation
│ └── _analytics_helpers.py # pure math for schedule-strength tools
├── domain/
│ ├── models.py # Team, Match, Standing, etc.
│ └── exceptions.py # EPLNotFoundError, UpstreamAPIError
├── ports/
│ ├── inbound.py # Authorizer protocol
│ └── outbound.py # EPLAPIPort protocol
├── observability/ # OpenTelemetry bootstrap (opt-in)
└── security/ # JWKS token verifierThe dependency direction flows inward: adapters → ports → domain. Nothing in domain/ imports from adapters or a framework.
Fork the repository and clone your fork
Create a feature branch: git checkout -b feature/your-feature
Make your changes following the existing patterns (hexagonal architecture, TDD, conventional commits)
Verify the full check suite passes: uv run inv lint && uv run inv check-complexity && uv run inv coverage
Open a pull request against main
All CI checks (lint, complexity, tests, coverage ≥ 90%) must pass before merge.
MIT — see LICENSE.
Get a team's raw points-per-game alongside an opponent-quality-adjusted PPG.
Adjusted PPG scales raw PPG by avg_opponent_ppg / league_average_ppg,
so values above raw PPG indicate the team has earned points against a
tougher schedule than league average.
Args: team_id: ESPN numeric team ID.
| Name | Required | Description | Default |
|---|---|---|---|
| team_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=True, destructive=False, and idempotent=True, so the safety profile is clear. The description adds behavioral context by explaining the adjustment formula (avg_opponent_ppg / league_average_ppg) and how to interpret values relative to raw PPG. This goes beyond what annotations provide and helps the agent reason about the computation.
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 front-loaded with the main purpose, followed by a compact formula explanation and an arguments line. Every sentence adds value, and the structure is clean. The 'Args' block is redundant with the schema but serves as a useful inline reminder given that the schema lacks descriptions.
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 explains what the tool returns (raw and adjusted PPG) and the reasoning behind the adjustment. With an output schema present, return values do not need to be spelled out. It does not cover error conditions or rate limits, but for a simple read-only tool this is adequate. The description is complete enough for an agent to invoke it 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?
The input schema only defines team_id as a string with no description (0% coverage). The description compensates by stating 'team_id: ESPN numeric team ID', which clarifies the expected format and meaning. This is sufficient for the single parameter, though it could also mention that the team must exist in ESPN systems.
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 uses a specific verb+resource ('Get a team's raw points-per-game alongside an opponent-quality-adjusted PPG') and clearly distinguishes this from sibling tools like get_standings or get_strength_of_schedule. It names the exact metric and includes a concise definition.
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 implies the primary use case: retrieving a team's PPG with an adjustment for opponent quality. It does not explicitly discuss exclusions or alternatives, but the formula explanation gives context for when this metric is relevant. A clear alternative comparison is missing, so it does not fully reach a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information for a single Premier League match.
Returns the score, venue, attendance, and a chronological list of key events (goals, substitutions, cards). Use the match ID returned by get_scoreboard or get_team_schedule.
Args: match_id: ESPN numeric event ID (e.g. "401853883").
| Name | Required | Description | Default |
|---|---|---|---|
| match_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by specifying the exact content returned (score, venue, attendance, chronological events) and explaining that match_id is an ESPN numeric event ID. This goes beyond the annotations without contradicting them.
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 and well-structured: it leads with the purpose, then lists return content, then provides usage guidance, and finally explains the parameter format. Every sentence adds value and there is no redundant wording.
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 single parameter, rich annotations, and the presence of an output schema, the description is complete enough. It covers the tool's function, required input format, and how to obtain the match ID. There are no significant gaps for an agent to invoke the 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?
The input schema only defines match_id as a string with no description. The description compensates by clarifying that it is an ESPN numeric event ID, providing an example ('401853883'). This gives the agent actionable guidance for supplying the parameter 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 'Get detailed information for a single Premier League match' and enumerates the specific return fields (score, venue, attendance, key events). This distinguishes it from sibling tools like get_scoreboard or get_team_schedule, which provide broader match lists, by focusing on a single match's details.
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 gives clear context that this tool is for single-match details and instructs the agent to obtain the match_id from get_scoreboard or get_team_schedule. While it does not explicitly state when not to use it, the prerequisite and scope provide sufficient guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent Premier League news articles.
Returns each article's headline, publication date, summary, and link to the full ESPN story.
Args: limit: Maximum number of articles to return (default 10).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (read-only, non-destructive). The description adds value by revealing the return contents (headline, date, summary, ESPN link) and mentions the 'recent' filter, which aligns with openWorldHint. 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 concise, front-loaded with the purpose, and every sentence serves a purpose. The Args block is cleanly structured and directly tied to the schema.
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 simple tool with one optional parameter and an output schema, the description is complete. It provides enough detail for an agent to select and invoke the tool correctly, without unnecessary extras.
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?
Despite the schema having zero description coverage, the tool description explicitly documents the 'limit' parameter with its default value and meaning, fully compensating for the schema's lack of detail.
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's function: 'Get recent Premier League news articles.' It uses a specific verb and resource, and no sibling tool covers news, so it is fully 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?
The context is clear: this is the only news-related tool among siblings, so usage is unambiguous. However, there is no explicit mention of when not to use it or alternatives, slightly lowering the score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Premier League player registrations from the Pulselive/Opta feed.
Richer than ESPN's roster: carries the Opta player id, shirt number, detailed positional label (e.g. "Centre-back" vs "Right-back"), current-club affiliation, nationality, date of birth, and loan flag. Defaults to the most recent completed season — the current season may not have full registrations until the transfer window closes.
Args: season_year: Currently ignored (see roadmap). Reserved for a future per-year season lookup. limit: Maximum number of players to return (default 50, max 500).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| season_year | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds critical behavioral details beyond that: season_year is ignored, there is a default to the most recent completed season with a caveat about transfer windows, and limit has a max of 500. These insights are not derivable from annotations or schema and help the agent anticipate response behavior. 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 well-structured: it opens with the core purpose, then enriches with data quality details, adds a season-caveat note, and ends with a clear Args section. Every sentence contributes meaningful information without redundancy or fluff.
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's simplicity (two optional params, no nested objects) and the presence of an output schema, the description covers all necessary context: purpose, data source, key behavioral caveats, and parameter semantics. It is complete for an agent to select and invoke the tool correctly without further clarification.
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 fully compensates. It explicitly states that season_year is ignored and reserved for future use, and that limit has a default of 50 and a maximum of 500, explaining the parameter semantics that the schema (types and defaults) does not convey.
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 'Get Premier League player registrations from the Pulselive/Opta feed,' specifying the verb, resource, and data source. It differentiates itself from sibling tools like get_roster by emphasizing the richer data (Opta player id, detailed positional labels, loan flag, etc.), making its purpose unmistakable.
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 useful context: it defaults to the most recent completed season, warns that the current season may be incomplete until the transfer window closes, and notes that season_year is currently ignored. However, it does not explicitly contrast with alternatives like get_roster beyond a general comparison, nor does it state when not to use this tool in favor of another.
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 W-L-T splits against current top-tier, middle, and bottom-tier teams.
Tiers are derived from the live league standings: top tier_size,
bottom tier_size, and everyone in between. Lets you ask "how does
this team do against the top of the table?" without scanning every
result manually.
Args: team_id: ESPN numeric team ID. tier_size: Number of teams in each of the top and bottom tiers. Defaults to 5. Must be at least 1, and 2*tier_size must not exceed the league size.
| Name | Required | Description | Default |
|---|---|---|---|
| team_id | Yes | ||
| tier_size | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 safety profile is covered. The description adds valuable behavioral detail: tiers are derived from live league standings, and tier_size has constraints (minimum 1, 2*tier_size <= league size). This goes beyond the annotations and helps the agent understand how the tool behaves at runtime.
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 and well-structured. The first sentence states the purpose, followed by a brief explanation of tier derivation, a use-case rationale, and an Args section. Every sentence contributes unique information; there is no redundancy or verbosity.
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 only 2 parameters, an output schema, and clear annotations, the description fully covers the tool's behavior. It explains the tier logic, constraints, and provides a comparison to manual scanning, which together give an agent complete context for selection and 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?
With 0% schema description coverage, the description must fully explain parameters. It does: team_id is identified as an ESPN numeric team ID, and tier_size is explained with its default value and validation constraints. This adds rich meaning beyond the bare schema 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 opens with a specific verb and resource: 'Get a team's W-L-T splits against current top-tier, middle, and bottom-tier teams.' This clearly states what the tool does and uniquely distinguishes it from sibling tools like get_standings or get_team_schedule by focusing on opponent-tier splits. The purpose is precise and not tautological.
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 a clear contextual use case: 'Lets you ask "how does this team do against the top of the table?" without scanning every result manually.' This implies when to use the tool, but it does not explicitly name alternative tools or state when not to use it. Because it gives meaningful usage context without exclusions, it earns a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the active roster for an Premier League team.
Returns each player's jersey number, name, position, citizenship, and age. Use the team ID returned by get_teams.
Args: team_id: ESPN numeric team ID (e.g. "18418" for Atlanta United FC).
| Name | Required | Description | Default |
|---|---|---|---|
| team_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds useful context by specifying the return fields and clarifying that it returns the active roster only. It does not cover edge cases like invalid team IDs, but that is acceptable for a simple read operation.
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 compact and front-loaded: purpose in the first sentence, return fields in the second, prerequisite in the third, and a single-parameter Args block. There is no superfluous content.
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 simple one-parameter read tool with an output schema and strong annotations, the description covers purpose, return contents, parameter semantics, and prerequisite. It is complete enough for an agent to select and invoke the 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 description coverage is 0%, so the description compensates with an Args section explaining team_id as an ESPN numeric team ID with an example. However, the example ('18418' for Atlanta United FC) conflicts with the stated Premier League context, making it slightly misleading.
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 opens with a specific verb and resource: 'Get the active roster for an Premier League team.' It then enumerates the returned fields (jersey number, name, position, citizenship, age), clearly distinguishing it from sibling team-related tools like get_team or get_team_schedule.
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?
It gives a clear prerequisite: use the team ID returned by get_teams. However, it does not explicitly state when not to use this tool or compare it to alternatives such as get_players, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Premier League match scores and status for a date or date range.
With no arguments, returns matches for the current matchweek. With
date only, returns matches for that single day. With both date
and end_date, returns every match in the inclusive range.
Args:
date: Optional start date in YYYYMMDD format (e.g. "20260418").
end_date: Optional end date in YYYYMMDD format. Requires date.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | ||
| end_date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: the inclusive date range semantics, the dependency of end_date on date, and the default behavior without arguments. It does not contradict annotations and enriches the understanding of the tool's behavior.
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 compact and well-structured. The first sentence states the core purpose, followed by concise paragraphs explaining behavior and an Args list. Each sentence carries meaningful information without redundancy. The Args section repeats some prose but in a scannable format, which is acceptable.
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 simple two-parameter design, strong annotations, and presence of an output schema, the description covers the essential invocation semantics thoroughly. It explains all argument modes and the date format. It does not discuss return structure, but that is complemented by the output schema. A small gap is the lack of explicit cross-referencing to sibling tools, hence a 4 rather than 5.
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?
The input schema provides param names and types but no descriptions (0% schema coverage). The description fully compensates by explaining the format (YYYYMMDD), optionality, the relationship between date and end_date, and the resulting behavior for each combination. This is essential information 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?
The description opens with a clear, specific statement: 'Get Premier League match scores and status for a date or date range.' It uses an action verb, identifies the resource (match scores/status), and specifies the scope. The subsequent sentences clarify behavior for different argument combinations, distinguishing it from sibling tools like get_teams or get_standings.
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 clear context on how to invoke the tool with no arguments, with date only, and with both date and end_date. It does not explicitly name alternatives or say when not to use this tool, but the detailed argument behavior serves as practical guidance. A brief mention of get_match_details for single-match queries would have elevated it to 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current Premier League standings.
Returns the eight-team table ordered by points descending, with win/loss/tie record, goals for, goals against, and goal differential.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 valuable context about the return shape (eight-team table, ordered by points, with specific statistics) and notes 'current', indicating dynamic data that aligns with openWorldHint. No contradictions 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 two sentences, front-loading the primary action and then detailing the return format without redundancy. Every word contributes to clarity, making it appropriately concise.
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 simple tool (no params, rich annotations, and an output schema), the description covers the purpose and output specifics, making it complete for an agent to invoke correctly. The output schema would handle return structure details, so the description need not repeat them.
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?
The tool has zero parameters, and the schema coverage is 100%. The description does not add parameter-specific details (as none exist), but it enriches the overall understanding of the tool's output, which is sufficient given the baseline for no-parameter tools.
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 'Get the current Premier League standings' with a specific verb and resource, and distinguishes itself from sibling tools like get_teams and get_scoreboard by focusing on standings data. It also specifies the eight-team table format, adding clarity.
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 clear context for when to use this tool: to retrieve current standings. It does not explicitly mention alternatives or exclusions, but the specificity makes its intended use obvious. A slight improvement would be naming contrasting tools, but it's not necessary here.
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 strength of schedule based on opponents already faced.
Returns the average current points-per-game of every opponent the team has played in completed matches, plus a per-opponent breakdown. Useful early in the season for "who has played the tougher schedule so far?" questions.
Args: team_id: ESPN numeric team ID (e.g. "18418" for Atlanta United FC).
| Name | Required | Description | Default |
|---|---|---|---|
| team_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral context by specifying it computes average points-per-game of opponents in completed matches and returns a per-opponent breakdown, going beyond what annotations provide.
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 and front-loaded with the core purpose, followed by return details and a use case. It avoids fluff and includes only valuable information, with the Args section providing a clear parameter explanation.
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 single-parameter, read-only tool with a full output schema and rich annotations, the description is complete. It covers purpose, scope, parameter format, and suggests when to use it, leaving no 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?
Schema coverage is 0%, but the description fully compensates by explaining team_id as an 'ESPN numeric team ID' with a concrete example ('18418' for Atlanta United FC). This gives the agent all necessary context to supply the parameter 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 a specific verb and resource: 'Get a team's strength of schedule based on opponents already faced.' It further defines the output as average points-per-game plus a per-opponent breakdown, distinguishing it from sibling tools like get_standings or get_team_schedule.
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 gives explicit usage context: 'Useful early in the season for "who has played the tougher schedule so far?" questions.' It does not mention exclusions or alternatives explicitly, but the context is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details for a specific Premier League team.
Returns full team information including display name, abbreviation, and location. Use the numeric ID returned by get_teams.
Args: team_id: ESPN numeric team ID (e.g. "18418" for Atlanta United FC).
| Name | Required | Description | Default |
|---|---|---|---|
| team_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context: that it returns full team information and that the ID originates from get_teams, which is a cross-tool dependency. No contradictions with annotations exist.
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 and well-structured: a clear one-sentence purpose, a one-sentence return summary, and a compact Args block. Every sentence adds value with no redundancy or fluff.
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 single-parameter read-only tool with an output schema available, the description is complete. It states the purpose, input source, and key return fields. Sibling tool names provide sufficient surrounding context, and the description covers all necessary operational details.
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%, but the description fully compensates by explaining that team_id is an ESPN numeric team ID and providing a concrete example. It also instructs how to obtain the ID (from get_teams), making the single parameter's meaning and source completely clear.
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's purpose: getting details for a specific Premier League team. It lists the returned fields (display name, abbreviation, location) and explicitly distinguishes itself from the sibling get_teams by requiring a numeric team ID, making the scope and resource unambiguous.
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 clear context by instructing to use the numeric ID returned by get_teams, implying the complementary relationship between the two tools. It does not explicitly list when-not-to-use scenarios, but the purpose and pointer to get_teams offer sufficient practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all active Premier League teams.
Returns a numbered list of teams with their ID, full name, abbreviation, and home city. Use the ID or abbreviation with get_team to retrieve detailed information about a specific team.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by specifying the return format (numbered list with ID, full name, abbreviation, home city) and the 'active' filter. It does not contradict annotations and provides useful behavioral context.
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 only two sentences, front-loaded with the core purpose, and every sentence contributes meaning. It is an excellent example of minimal yet complete writing.
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 zero-parameter, read-only list tool with an output schema, the description fully covers what the tool returns and how it fits with sibling tools. The output format is explicitly described, making it complete for the tool's complexity.
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 the description bears no burden for explaining parameters. The schema coverage is trivially 100% and thus baseline for zero parameters is 4, which is appropriate.
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's purpose: 'Get all active Premier League teams.' It uses a specific verb and resource, and the focus on active teams distinguishes it from sibling tools like get_standings or get_team.
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?
Provides explicit guidance on when to use this tool and what to do next: 'Use the ID or abbreviation with get_team to retrieve detailed information about a specific team.' This clearly points to the alternative for more detail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all matches for a single Premier League team in the current season.
Returns scheduled, in-progress, and completed matches for the team — with opponent, date, score (if played), and status.
Args: team_id: ESPN numeric team ID (e.g. "18418" for Atlanta United FC).
| Name | Required | Description | Default |
|---|---|---|---|
| team_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context by specifying that returned matches include scheduled, in-progress, and completed ones, with opponent, date, score, and status. However, it does not mention potential pagination limits or error behavior.
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 two sentences plus an Args block. The main action is front-loaded, and every sentence adds meaningful information without fluff. The structure is clean and scannable.
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's simplicity (one parameter, output schema exists), the description is nearly complete. It states the scope (current season), defines the parameter, and lists the return fields. It could mention how to handle other seasons or invalid team IDs, but these are minor gaps for a low-complexity tool.
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?
The schema only defines team_id as a string with 0% description coverage. The description compensates fully by explaining 'ESPN numeric team ID' and providing a concrete example ('18418' for Atlanta United FC). This is exactly the kind of parameter clarity agents need.
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's function: 'Get all matches for a single Premier League team in the current season.' This specific verb+resource combination distinguishes it from siblings like get_scoreboard (league-wide) and get_match_details (specific match).
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 implies when to use the tool (when you need a team's schedule) but does not explicitly discuss alternatives or exclusions. Sibling tools exist for other types of match data, but the description alone offers no direct comparison.
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.0get_adjusted_points_per_gameget_match_detailsget_newsget_playersget_results_by_opponent_tierget_rosterget_scoreboardget_standingsget_strength_of_scheduleget_teamget_team_scheduleget_teamsScored across 12 tools
Most tools have clearly distinct purposes, but get_roster and get_players both return player information and get_scoreboard vs get_team_schedule could be confused for team-specific date queries. Descriptions adequately differentiate them, but a few boundaries are close.
All tools follow a consistent get_<noun> pattern in snake_case. Multi-word nouns are used consistently, making the API predictable and easy to navigate.
12 tools is well-scoped for a Premier League data server, covering team, match, player, news, standings, and advanced analytics without redundancy. Each tool earns its place.
The tool set covers core domains well: teams, matches, rosters, players, news, standings, and analytics. Minor gaps exist like individual player stats or detailed match events beyond key events, but these are workable.
Teamfight Tactics data & AI coaching for Claude and ChatGPT — 19 tools, built-in Riot key.
Football fixtures, standings, and odds intelligence for AI agents.
Live SEO workflow tools for Claude Code, Codex, and AI agents.
GA4, Google Ads and Search Console in Claude. Read-only OAuth, multi-account for agencies.
