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-usls Who is leading the USL Super League right now?"
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 USL Super League data — teams, matches, standings, rosters, and schedule-strength analytics — via the ESPN public API.
Related MCP server: sports-pulse-mcp
AI assistants like Claude are knowledgeable, but they have a hard cutoff date — they cannot tell you today's USL Super League standings, last night's scores, or which teams are currently in a playoff position. This project fixes that.
It is an MCP server — a plugin that gives Claude direct access to live USL Super League data: scores, standings, rosters, and derived schedule-strength analytics. Once installed, you can ask Claude natural-language questions about the USL Super 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 — it wraps the ESPN public API only. The league's own site (gainbridgesuperleague.com) exposes match data only through a licensed Opta widget embed, so ESPN is the only clean JSON source. Cup competitions and richer stats are on the roadmap if a stable second-tier feed becomes available.
The v1 surface is eleven read-only, idempotent tools split across two tiers.
Tool | Description |
| List all 8 USL Super 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 8-team table ordered by points |
| Recent USL Super League news articles |
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+:
Player leaderboards and team season aggregates if a stable USL SL Opta feed becomes accessible (today the league's Opta widget is subscription-gated)
Press-release feed from gainbridgesuperleague.com/wp-json/wp/v2/sec_news
Playoff bracket rendering
Related women's competitions the league may add (Concacaf W Champions Cup, USL Cup)
git clone https://github.com/jedi-knights/jk-mcp-usls.git
cd jk-mcp-usls
uv syncRun the server in stdio mode (the default — used by Claude Code and Claude Desktop):
uv run python -m usls.serverRun in HTTP mode (for networked or deployed access):
MCP_TRANSPORT=streamable-http uv run python -m usls.serverStandings, scores, rosters:
Who is leading the USL Super League right now?
Show me every USL Super League result from this past weekend.
Who is on Brooklyn FC's roster?
When does Carolina Ascent play next?
Schedule strength:
Which USL Super League team has played the toughest schedule so far?
Show me Brooklyn FC's record against the current top 3 teams.
Compare Carolina Ascent and DC Power 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 usls -- uv run --directory /path/to/jk-mcp-usls python -m usls.serverReplace /path/to/jk-mcp-usls 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": {
"usls": {
"command": "uv",
"args": ["run", "--directory", "/path/to/jk-mcp-usls", "python", "-m", "usls.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": {
"usls": {
"command": "uv",
"args": [
"run",
"--directory", "/path/to/jk-mcp-usls",
"python", "-m", "usls.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-usls:latest .Run in stdio mode (for MCP clients that spawn a subprocess):
docker run -i --rm jk-mcp-usls:latestRun in HTTP mode:
docker run --rm -p 8000:8000 \
-e MCP_TRANSPORT=streamable-http \
jk-mcp-usls: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/usls/
├── 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 # USLSService — 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 # USLSNotFoundError, UpstreamAPIError
├── ports/
│ ├── inbound.py # Authorizer protocol
│ └── outbound.py # USLSAPIPort 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 USL Super 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 readOnlyHint, idempotentHint, and non-destructive behavior, so the description doesn't need to repeat those. It adds value by specifying exactly what data is returned (score, venue, attendance, chronological events), which goes beyond the annotations. It doesn't mention error conditions or rate limits, but the annotations cover the safety profile.
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 opening sentence, a sentence listing return contents, a usage hint, and an Args block. Every sentence contributes important information, and the format is easy to scan.
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), the presence of an output schema, and strong annotations covering safety and idempotence, the description is complete. It explains how to obtain the required input (match ID from scoreboard/schedule) and what the output covers, leaving no critical 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?
The schema provides only the parameter name and type (match_id: string) with no description. The description compensates by explaining that match_id is an 'ESPN numeric event ID' and provides an example format ('401853883'). This adds meaningful semantics beyond the schema, though it could be even more detailed about accepted formats.
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 detailed information for a single USL Super League match.' It lists specific return contents (score, venue, attendance, chronological key events) and distinguishes itself from sibling tools like get_scoreboard and get_team_schedule 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 explicitly directs the user to use a match ID returned by get_scoreboard or get_team_schedule, which provides clear context for when to use this tool. It doesn't explicitly state exclusions, but the input-source guidance effectively communicates the intended workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent USL Super 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?
The annotations already declare the tool read-only, idempotent, and non-destructive. The description adds context about the response structure, listing the specific article fields returned, which is beyond the annotation coverage. No contradictory behavior is disclosed.
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, starting with the main purpose and then adding details on the return format and parameter. Every sentence is informative and there is no 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, the description covers the purpose, the parameter, and the return structure. The output schema exists to detail return fields, so the description does not need to repeat them, and it doesn't. It is complete for an agent to decide when and how to invoke it.
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 provides only the parameter name, type, and default, with 0% description coverage. The description adds crucial meaning by explaining that 'limit' is the maximum number of articles to return and notes the default of 10, fully compensating for the schema's lack of description.
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 fetches recent USL Super League news articles, with a specific verb and resource. It distinguishes from sibling tools like get_teams and get_standings by focusing on news. The return fields are also listed, making the purpose 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 implies the tool is for news articles but does not explicitly mention alternatives or when not to use it. Sibling tools cover teams, standings, and scores, so usage can be inferred, but no direct guidance is provided.
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 USL Super 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds that it returns specific player fields and emphasizes 'active' roster, providing value beyond the annotations. It doesn't mention auth or rate limits, but for a read-only tool with strong annotations, this is sufficient.
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 purpose, followed by return fields, usage tip, and parameter detail. Every sentence earns its place; no wasted words.
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?
With one required parameter, clear output information, and a hint to obtain the team ID, the description fully covers what is needed to invoke the tool correctly. The output schema exists, so return values are well-defined.
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 has no description for team_id (0% coverage), but the description defines it as 'ESPN numeric team ID' and gives an example for Atlanta United FC. This fully compensates for the missing schema description.
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 active roster for an USL Super League team' with a specific verb and resource, and lists returned player fields. This distinguishes it from sibling tools like get_teams and 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?
It instructs users to use the team ID returned by get_teams, providing a clear prerequisite and linking to a sibling tool. It implies this is for roster queries, but lacks explicit when-not-to-use guidance, so a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get USL Super 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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral nuance beyond these: the default no-argument behavior (current matchweek), the inclusive date range, and the dependency that end_date requires date. This contextualizes the tool's behavior in a way annotations alone cannot.
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 model: a single-sentence summary followed by a compact Args list. No fluff, no repetition. Front-loads the primary purpose and then granularly details each parameter and usage mode. Every sentence earns its place.
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, an output schema, and strong annotations, the description is fully complete. It covers all invocation modes (none, date only, date+end_date), parameter format, and constraints. No gaps remain for an agent to misinterpret.
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 carries full responsibility for parameter meaning. It explicitly explains both parameters: date is an optional start date in YYYYMMDD format with an example, and end_date is optional but requires date. It also clarifies the semantic relationship between parameters, going well beyond the raw schema.
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 USL Super League match scores and status for a date or date range.' This clearly distinguishes it from siblings like get_standings (tables), get_match_details (specific match), and get_team_schedule (team fixtures). The scope and output are 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 behavioral context for when to use the tool: no arguments gives current matchweek, single date gives one day, date range gives inclusive range. It does not explicitly mention alternatives or exclusions, but the scenarios are thoroughly defined, making it clear when this tool should be selected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current USL Super 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?
Annotations already establish this as a safe, read-only, idempotent operation. The description adds behavioral context by noting the current nature of the data and the specific computed statistics (win/loss/tie, goals for/against, differential), which isn't captured by the annotations or input 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?
Two sentences front-load the action and resource, then provide precise details about the return format and ordering. No filler.
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?
With no parameters, an output schema, and strong annotations, the description fully covers the tool's purpose and return semantics. It's self-contained.
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 need not document them. The baseline for 0 params is 4, and the description adds no conflicting information.
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 the USL Super League standings, a specific resource with a clear verb. It differentiates from siblings like get_scoreboard or get_teams by specifying the ordered table with team records and goal stats.
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 use when current standings are needed, but does not explicitly discuss alternatives or exclusion criteria. The clear resource name and context provide reasonable guidance, so a 4 is appropriate.
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 USL Super 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 readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: the league (USL Super League), the return contents (display name, abbreviation, location), and the ESPN ID source. 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 compact: two short paragraphs with the purpose first, then return highlights, then parameter details. Every sentence earns its place; there is no filler or redundancy.
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?
This is a simple read operation with strong annotations, an output schema, and a single parameter. The description covers the league, the specific-team scope, the parameter format/source, and expected return fields. Nothing critical is missing for an agent to select and 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 schema provides no description for team_id (0% coverage), so the description must compensate. It does so excellently by specifying the parameter is an 'ESPN numeric team ID', giving a concrete example ('18418' for Atlanta United FC), and pointing to get_teams as the source.
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 pattern: 'Get details for a specific USL Super League team.' It clearly differentiates from the sibling get_teams by emphasizing 'specific' and referencing the numeric team ID.
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 an explicit prerequisite: 'Use the numeric ID returned by get_teams.' This establishes when to use this tool and ties it directly to its listing sibling. It does not enumerate exclusions for other sibling tools, but the 'specific team' framing makes the intended use unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all active USL Super 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, and idempotentHint, so the safety profile is clear. The description adds value by specifying that it returns a numbered list, the exact fields (ID, full name, abbreviation, home city), and that it only includes active teams—context not present in 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?
Two sentences, front-loaded with the core purpose, followed by return format and cross-reference. No fluff, every sentence earns its place.
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 simplicity (0 params), rich annotations, and existence of an output schema, the description is complete. It covers what the tool does, what it returns, and the next step for detailed lookup.
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, so schema coverage is 100% trivially. The baseline for 0 params is 4; the description doesn't need to elaborate on parameters and doesn't.
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 all active USL Super League teams' with a specific verb (get), resource (teams), and scope (active, USL Super League). It also distinguishes itself from the sibling tool get_team by explaining that get_team is for detailed information on a specific 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?
The description explicitly directs users to use get_team with the ID or abbreviation for detailed info, providing a clear alternative and indicating when to choose this list tool. It implies a workflow: first call get_teams to obtain IDs/abbreviations, then call get_team.
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 USL Super 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, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds value by specifying return statuses (scheduled, in-progress, completed) and fields (opponent, date, score, status), which are not in 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 concise and well-structured: a single sentence stating the primary purpose, a second sentence summarizing return contents, and an Args block for the parameter. No fluff or redundant information, and the main purpose is front-loaded.
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?
With an output schema and comprehensive annotations, the description is sufficiently complete for a simple one-parameter read-only tool. It covers purpose, return fields, and parameter semantics. Minor gaps like defining 'current season' boundaries or potential errors are not critical given the available structured data.
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 provides only a 'team_id' string with no description (0% coverage). The description fully compensates by explaining it is an 'ESPN numeric team ID' and providing an example ('18418' for Atlanta United FC). This gives clear parameter semantics beyond the bare schema.
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 USL Super League team in the current season.' It specifies the resource (matches for a team) and distinguishes from sibling tools like get_scoreboard or get_match_details by focusing on the full season schedule. It also enumerates return components, reinforcing purpose 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 implies usage for retrieving a team's complete schedule but does not explicitly contrast with alternatives such as get_match_details for single matches or get_scoreboard for current games. There are no exclusions or 'use X instead' statements, so the guidance is implied rather than explicit.
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_results_by_opponent_tierget_rosterget_scoreboardget_standingsget_strength_of_scheduleget_teamget_team_scheduleget_teamsScored across 11 tools
Each tool targets a distinct data type or query: team lists vs. details, schedules vs. scoreboards vs. match events, and three separate analytics tools that do not overlap. An agent can easily select the right tool without confusion.
Every tool follows the same get_ prefix with descriptive noun phrases (get_teams, get_standings, get_match_details). This consistent pattern makes the toolset predictable and easy to navigate.
With 11 tools, the server is well-scoped for a sports data API: core retrieval (teams, standings, schedules, scores, rosters, news) plus a few advanced analytics tools. No tool feels redundant or out of place.
The domain of USL Super League data is thoroughly covered: teams, standings, matches, rosters, news, and analytical queries. The read-only nature is consistent with a data feed, and no critical data type appears missing.
ESPN MCP — keyless multi-sport live scores, teams, and news via ESPN's public site API.
Hosted MCP server for live public-data APIs and Skills for AI agents.
MCP server giving Claude AI access to 22+ NYC public-record databases for real estate due diligence
Sports MCP — wraps TheSportsDB API (free tier, test key 3, no auth required)