Skip to main content
Glama
AsafShai

Fantasy NBA Israel League MCP

by AsafShai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Fantasy NBA Israel League MCP

A Model Context Protocol (MCP) server that provides tools for accessing our Fantasy NBA Israel League statistics and rankings.

Description

This MCP server connects to a specific Fantasy NBA League API (Fantasy NBA Israel League) and provides tools to retrieve team rankings, player statistics, and detailed analytics.

Note: This server is configured for a specific private league and connects to its dedicated API endpoint. It is not a general-purpose tool for any Fantasy NBA league - it's designed specifically for our league's data structure and API.

Related MCP server: Sport5 Fantasy League MCP Server

Features

  • Get Average League Rankings: Retrieve team rankings with detailed statistics

    • Sort in ascending or descending order

    • Detailed stats per category (FG%, FT%, 3PM, AST, REB, STL, BLK, PTS, GP)

    • Total points and rank for each team

  • Get Teams: Retrieve list of all teams in the league

  • Get Average Stats: Get team statistics in a user-friendly format with stats mapped by category

    • Option to retrieve raw or normalized (0-1 scale) data

    • Includes games played (GP) for each team

  • Get Team Details: Retrieve comprehensive details for a specific team

    • Team statistics (totals and averages)

    • Complete roster with player stats including minutes played

    • ESPN team page URL

    • Shot chart stats and ranking information

    • Category ranks across all statistical categories

  • Get All Players: Retrieve all players in the league with comprehensive statistics

    • Includes minutes played and games played for each player

  • Get League Shots Stats: Retrieve league-wide shooting statistics for all teams

Prerequisites

Before using this MCP server, you'll need:

  1. uv or uvx: A fast Python package installer and runner

    • Install from https://docs.astral.sh/uv/

    • On macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

    • On Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

  2. An MCP-compatible client: Choose one of the following or similar:

Usage

As an MCP Server

This server works with any MCP-compatible client (Claude Desktop, Cursor, Cline, VSCode with GitHub Copilot Chat, etc.). Add the following configuration to your client's MCP settings file:

{
  "mcpServers": {
    "fantasynbaleague": {
      "command": "uvx",
      "args": ["fantasy-nba-israel-mcp@latest"]
    }
  }
}

Common configuration file locations:

  • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

  • Cursor: .cursor/mcp.json in your project or global settings

  • Cline: Use the MCP settings UI or edit cline_mcp_settings.json

  • VSCode: .vscode/mcp.json in your workspace

Local Development

For local development and testing, you can run the MCP server in development mode:

uv run mcp dev fantasy_nba_israel_mcp/server.py

This will start an interactive MCP inspector where you can test your tools.

Standalone Testing

from fantasy_nba_israel_mcp import mcp

# Run the MCP server
if __name__ == "__main__":
    mcp.run()

Or run directly:

python -m fantasy_nba_israel_mcp

Available Tools

getAveragesLeagueRankings

Get the average league rankings from the API.

Parameters:

  • order (str, optional): Sort order for rankings

    • "desc" = best to worst (top teams first) - Default

    • "asc" = worst to best (bottom teams first)

Returns: A list of teams with their rankings, total points, and stats per category.

Example Response:

[
  {
    "team": {
      "team_id": 1,
      "team_name": "Team Name"
    },
    "fg_percentage": 0.456,
    "ft_percentage": 0.789,
    "three_pm": 12.5,
    "ast": 24.3,
    "reb": 45.6,
    "stl": 8.2,
    "blk": 5.4,
    "pts": 112.3,
    "gp": 55,
    "total_points": 36,
    "rank": 1
  }
]

getTeams

Get the list of all teams in the league.

Parameters: None

Returns: A list of teams with their IDs and names.

Example Response:

[
  {
    "team_id": 1,
    "team_name": "First team example"
  },
  {
    "team_id": 2,
    "team_name": "Another team name"
  }
]

getAverageStats

Get average stats for all teams in a user-friendly format with stats mapped by category name.

Parameters:

  • use_normalized (bool, optional): If true, returns normalized data (0-1 scale). If false, returns raw stat values. Default is false.

Returns: A list of teams with their stats mapped by category name.

Example Response:

[
  {
    "team": {
      "team_id": 1,
      "team_name": "First team example"
    },
    "stats": {
      "FG%": 0.48532033,
      "FT%": 0.80961071,
      "3PM": 1.71184371,
      "AST": 4.28449328,
      "REB": 6.75579976,
      "STL": 1.13919414,
      "BLK": 0.72405372,
      "PTS": 17.5970696,
      "GP": 55
    }
  }
]

getTeamDetails

Get comprehensive details for a specific team including statistics, roster, and rankings.

Parameters:

  • team_id (int): The ID of the team to get details for

Returns: Comprehensive team information including team stats, ESPN URL, shot chart, rankings, and full roster.

Example Response:

{
  "team": {
    "team_id": 1,
    "team_name": "Team Name"
  },
  "espn_url": "https://fantasy.espn.com/basketball/team?leagueId=123&teamId=1",
  "shot_chart": {
    "team": {"team_id": 1, "team_name": "Team Name"},
    "fgm": 14,
    "fga": 23,
    "fg_percentage": 0.608,
    "ftm": 7,
    "fta": 12,
    "ft_percentage": 0.583,
    "gp": 2
  },
  "raw_averages": {
    "fg_percentage": 0.608,
    "ft_percentage": 0.583,
    "three_pm": 0.5,
    "ast": 4.5,
    "reb": 5.5,
    "stl": 1.0,
    "blk": 0.5,
    "pts": 18.0,
    "gp": 2,
    "team": {"team_id": 1, "team_name": "Team Name"}
  },
  "ranking_stats": {
    "team": {"team_id": 1, "team_name": "Team Name"},
    "fg_percentage": 12.0,
    "ft_percentage": 5.0,
    "three_pm": 5.0,
    "ast": 8.0,
    "reb": 7.0,
    "stl": 6.0,
    "blk": 9.0,
    "pts": 9.0,
    "gp": 2,
    "total_points": 61.0,
    "rank": 6
  },
  "category_ranks": {
    "FG%": 12,
    "FT%": 5,
    "3PM": 5,
    "AST": 8,
    "REB": 7,
    "STL": 6,
    "BLK": 9,
    "PTS": 9
  },
  "players": [
    {
      "player_name": "LeBron James",
      "pro_team": "LAL",
      "positions": ["SF", "PF"],
      "stats": {
        "pts": 25.4,
        "reb": 7.3,
        "ast": 7.4,
        "stl": 1.3,
        "blk": 0.5,
        "fgm": 9.5,
        "fga": 18.5,
        "ftm": 4.8,
        "fta": 6.3,
        "fg_percentage": 0.513,
        "ft_percentage": 0.762,
        "three_pm": 2.1,
        "minutes": 35.2,
        "gp": 55
      },
      "team_id": 1
    }
  ]
}

getAllPlayers

Get all players in the league with comprehensive statistics.

Parameters: None

Returns: A list of all players with their stats and team association.

Example Response:

[
  {
    "player_name": "LeBron James",
    "pro_team": "LAL",
    "positions": ["SF", "PF"],
    "team_id": 1,
    "stats": {
      "pts": 25.4,
      "reb": 7.3,
      "ast": 7.4,
      "stl": 1.3,
      "blk": 0.5,
      "fgm": 9.5,
      "fga": 18.5,
      "ftm": 4.8,
      "fta": 6.3,
      "fg_percentage": 0.513,
      "ft_percentage": 0.762,
      "three_pm": 2.1,
      "minutes": 35.2,
      "gp": 55
    }
  }
]

getLeagueShotsStats

Get league-wide shooting statistics for all teams.

Parameters: None

Returns: League-wide shooting statistics with field goal and free throw data for each team.

Example Response:

{
  "shots": [
    {
      "team": {
        "team_id": 1,
        "team_name": "Team Name"
      },
      "fgm": 14,
      "fga": 23,
      "fg_percentage": 0.608,
      "ftm": 7,
      "fta": 12,
      "ft_percentage": 0.583,
      "gp": 2
    },
    {
      "team": {
        "team_id": 2,
        "team_name": "Another Team"
      },
      "fgm": 12,
      "fga": 20,
      "fg_percentage": 0.600,
      "ftm": 8,
      "fta": 10,
      "ft_percentage": 0.800,
      "gp": 2
    }
  ]
}

Requirements

  • Python >= 3.10

  • httpx >= 0.28.1

  • mcp[cli] >= 1.18.0

Development

To run the server locally for development and testing:

# Install dependencies
uv sync

# Run in development mode with MCP inspector
uv run mcp dev fantasy_nba_israel_mcp/server.py

The MCP inspector will provide an interactive interface to test all your tools.

Author

Asaf Shai (asafshai211@gmail.com)

Support

For issues and questions, please open an issue on the GitHub repository.

Available Tools

5 tools
getAveragesLeagueRankingsA
Get the average league rankings from the API.

IMPORTANT - SCORING SYSTEM EXPLANATION:
This is a ROTISSERIE (ROTO) fantasy league. Teams earn ranking points in 8 categories.

CRITICAL: Do NOT confuse "ranking points" with "rank position"!
- Category values (fg_percentage, ast, reb, etc.) = POINTS earned (higher is better)
- The "rank" field = actual position/place in standings (1 = first place)

HOW RANKING POINTS WORK:
- In each category, teams are ranked 1st to Nth (where N = number of teams)
- Best team in a category gets N points, second-best gets N-1, worst gets 1
- Example in 12-team league: 1st place = 12 pts, 2nd = 11 pts, ..., 12th = 1 pt
- total_points = sum of points from all 8 categories
- Overall "rank" is determined by total_points (highest total = rank 1)

EXAMPLE in a 12-team league:
{
    "team": {"team_name": "Best Team"},
    "ast": 12.0,           // Earned 12 pts (1st place in assists)
    "reb": 11.0,           // Earned 11 pts (2nd place in rebounds)
    "stl": 8.0,            // Earned 8 pts (5th place in steals)
    ...other categories...
    "total_points": 73.0,  // Sum of all 8 category points
    "rank": 1,             // Overall standing: 1st place
    "GP": 55               // Games played (informational only, not ranked)
}

Args:
    order: Sort order for rankings.
           - "desc" = best to worst (top teams first, "from top to bottom", "מלמעלה למטה")
           - "asc" = worst to best (bottom teams first, "from bottom to top", "מלמטה למעלה")
           Default is "desc".

Returns:
    A list of teams with their rankings, total points, and stats per category.
    Each item in the list is a dictionary with the following keys: {
        "team": {
            "team_id": <team_id>,
            "team_name": <team_name>
        },
        "fg_percentage": <ranking_points_for_field_goal_percentage>,
        "ft_percentage": <ranking_points_for_free_throw_percentage>,
        "three_pm": <ranking_points_for_three_pointers_made>,
        "ast": <ranking_points_for_assists>,
        "reb": <ranking_points_for_rebounds>,
        "stl": <ranking_points_for_steals>,
        "blk": <ranking_points_for_blocks>,
        "pts": <ranking_points_for_points>,
        "total_points": <sum_of_all_category_ranking_points>,
        "rank": <overall_position_1_is_first_place>,
        "GP": <games_played_not_ranked>
    }
    
NOTES:
- Higher values in categories = better performance (more ranking points earned)
- "rank" field is opposite: lower number = better (1 is first place)
- GP (games played) is informational only, not used in scoring
- When referring to steals in Hebrew, use חטיפות (not גניבות)
- If you refer to comparing teams, distinguish between rank and total points, so f.e someone can be 1st place 70 total points and another team can be 2nd place 69 total points.
- In that case, the difference is 2 points, not 1 place.
ParametersJSON Schema
NameRequiredDescriptionDefault
orderNodesc

TDQS

A4.2/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It excels by detailing the scoring system, clarifying critical distinctions (e.g., ranking points vs. rank position), providing an example output, and noting language-specific considerations (Hebrew terms). This gives the agent a comprehensive understanding of how the tool behaves and what to expect from its results.

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

Conciseness3/5

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

The description is front-loaded with the core purpose but becomes lengthy due to extensive explanations of the scoring system, example, and notes. While all content is relevant and earns its place, the structure could be more streamlined—some details (e.g., Hebrew translations, specific comparison examples) might be overly verbose for a tool description, reducing overall conciseness.

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

Completeness5/5

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

Given the complexity of the rotisserie scoring system, no annotations, and no output schema, the description provides exceptional completeness. It thoroughly explains the data model, scoring logic, parameter usage, and return structure, ensuring the agent has all necessary context to invoke the tool correctly and interpret results without relying on external documentation.

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

Parameters5/5

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

The input schema has 0% description coverage and only one parameter ('order') with minimal schema details. The description compensates fully by explaining the parameter's semantics: it defines the sort order options ('desc' for best to worst, 'asc' for worst to best), provides default behavior, and includes multilingual clarifications. This adds significant value beyond the bare schema.

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

Purpose4/5

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 the average league rankings from the API.' It specifies the verb ('Get') and resource ('average league rankings'), making it understandable. However, it doesn't explicitly differentiate from sibling tools like 'getAverageStats' or 'getTeams', which might also retrieve statistical data, leaving some ambiguity about when to choose this specific tool.

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

Usage Guidelines3/5

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

The description provides implied usage context by explaining the scoring system and data structure, suggesting it's for retrieving rotisserie fantasy league rankings. However, it lacks explicit guidance on when to use this tool versus alternatives like 'getAverageStats' or 'getTeams', and doesn't mention any prerequisites or exclusions, leaving the agent to infer the best scenario for its use.

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

getAverageStatsA
Get the average statistics (actual performance numbers) for all teams from the API.

IMPORTANT: This returns ACTUAL PERFORMANCE STATS, NOT ranking points!
- This is different from getAveragesLeagueRankings() which returns ranking points
- Use this endpoint to see actual per-game averages (e.g., 25.3 assists per game)
- Use getAveragesLeagueRankings() to see rotisserie ranking points (e.g., 12 points earned)

Args:
    use_normalized: If True, returns normalized data (0-1 scale) for comparison.
                   If False, returns raw statistical values (e.g., 45.6% FG, 12.3 AST).
                   Default is False.

Returns:
    A list of teams with their actual statistical averages per game.
    Each item in the list is a dictionary with the following structure:
    {
        "team": {
            "team_id": <team_id>,
            "team_name": <team_name>
        },
        "stats": {
            "FG%": <field_goal_percentage_as_decimal>,
            "FT%": <free_throw_percentage_as_decimal>,
            "3PM": <three_pointers_made_per_game>,
            "AST": <assists_per_game>,
            "REB": <rebounds_per_game>,
            "STL": <steals_per_game>,
            "BLK": <blocks_per_game>,
            "PTS": <points_per_game>,
            "GP": <games_played>
        }
    }
    
NOTES:
- Percentages are decimals (0.456 = 45.6%)
- All counting stats (3PM, AST, REB, STL, BLK, PTS) are per-game averages
- When use_normalized=True, all values are scaled 0-1 for heatmap visualization
- GP (games played) is a total count, not an average
ParametersJSON Schema
NameRequiredDescriptionDefault
use_normalizedNo

TDQS

A4.7/5.0
Behavior4/5

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

No annotations are provided, so the description carries the full burden. It effectively discloses behavioral traits: it describes the return format (list of teams with dictionaries), explains data types (percentages as decimals, counting stats as per-game averages, GP as total count), and details the effect of the use_normalized parameter (scales values 0-1 for heatmap visualization). It doesn't mention rate limits or authentication needs, but covers core functionality well.

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

Conciseness4/5

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

The description is appropriately sized and front-loaded, starting with the core purpose and key distinction from siblings. Each section (Args, Returns, NOTES) adds value without redundancy. It could be slightly more concise in the Returns section, but overall, sentences earn their place by clarifying critical details.

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

Completeness5/5

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

Given the complexity (statistical data with normalization options) and lack of annotations or output schema, the description is highly complete. It covers the tool's purpose, usage guidelines, parameter semantics, return structure, and data formatting notes, providing all necessary context for an AI agent to invoke it correctly without relying on external documentation.

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

Parameters5/5

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

With 0% schema description coverage and only one parameter, the description fully compensates by adding rich semantic details. It explains the use_normalized parameter's purpose ('returns normalized data (0-1 scale) for comparison' vs. 'raw statistical values'), provides examples (e.g., '45.6% FG, 12.3 AST'), and specifies the default value (False), going well beyond the minimal schema.

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

Purpose5/5

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

The description clearly states the tool 'gets average statistics (actual performance numbers) for all teams from the API,' specifying both the verb ('get') and resource ('average statistics for all teams'). It explicitly distinguishes this from the sibling tool getAveragesLeagueRankings by emphasizing it returns 'ACTUAL PERFORMANCE STATS, NOT ranking points,' providing clear differentiation.

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

Usage Guidelines5/5

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

The description provides explicit guidance on when to use this tool versus alternatives. It states: 'Use this endpoint to see actual per-game averages (e.g., 25.3 assists per game)' and 'Use getAveragesLeagueRankings() to see rotisserie ranking points (e.g., 12 points earned),' clearly defining the context and naming the alternative tool.

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

getLeagueShotsStatsA
Get league-wide shooting statistics (field goals and free throws) for all teams.

This endpoint provides CUMULATIVE TOTALS (not per-game averages) for shooting stats.
Useful for understanding overall team shooting efficiency across the season.

Returns:
    A dictionary containing league-wide shooting statistics: {
        "shots": [
            {
                "team": {
                    "team_id": <team_id>,
                    "team_name": <team_name>
                },
                "fgm": <total_field_goals_made>,
                "fga": <total_field_goals_attempted>,
                "fg_percentage": <calculated_field_goal_percentage_as_decimal>,
                "ftm": <total_free_throws_made>,
                "fta": <total_free_throws_attempted>,
                "ft_percentage": <calculated_free_throw_percentage_as_decimal>,
                "gp": <games_played>
            }
        ]
    }

NOTES:
- fgm, fga, ftm, fta are TOTALS across all games, not per-game averages
- fg_percentage and ft_percentage are calculated from totals (fgm/fga, ftm/fta)
- Percentages are returned as decimals (e.g., 0.456 = 45.6%)
- The list contains one entry per team with their complete shooting profile
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the data format (cumulative totals, not per-game averages), calculation methods (percentages derived from totals), output format (dictionary with detailed team statistics), and data representation (percentages as decimals). It doesn't mention potential limitations like data freshness or error handling, but covers the core behavior well.

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

Conciseness4/5

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

The description is well-structured with clear sections: purpose statement, key behavioral notes, return format, and detailed notes. Each sentence adds value - none are redundant. While somewhat detailed due to the output specification, the information is necessary given the lack of output schema. The front-loaded purpose statement immediately communicates the tool's function.

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

Completeness4/5

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

Given the tool's complexity (statistical data with calculations), no annotations, and no output schema, the description provides substantial context. It explains the data nature (cumulative vs. averages), calculation methodology, output structure, and data representation. The main gap is the lack of information about data sources or update frequency, but for a read-only statistical tool, the description is quite comprehensive.

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

Parameters4/5

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

The input schema has 0 parameters with 100% coverage, so the baseline would be 4 even without parameter information in the description. The description correctly states there are no parameters needed ('This endpoint provides...' implies no filtering parameters), which aligns perfectly with the empty schema. No additional parameter semantics are needed or provided.

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

Purpose5/5

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

The description clearly states the tool's purpose: 'Get league-wide shooting statistics (field goals and free throws) for all teams.' It specifies the verb ('Get'), resource ('league-wide shooting statistics'), and scope ('for all teams'), distinguishing it from sibling tools like getTeamDetails (team-specific) or getAveragesLeagueRankings (averages-focused).

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

Usage Guidelines4/5

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

The description provides clear context for when to use this tool: 'Useful for understanding overall team shooting efficiency across the season.' It distinguishes itself by emphasizing cumulative totals rather than averages, which helps differentiate from tools like getAverageStats. However, it doesn't explicitly state when NOT to use it or name specific alternatives beyond the general distinction.

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

getTeamDetailsA
Get comprehensive details for a specific team from the API.

This endpoint combines multiple data types for a single team:
1. Raw statistical averages (actual performance numbers)
2. Ranking points (rotisserie scoring system)
3. Category ranks (position in each category, 1=best)
4. Player roster with individual stats

IMPORTANT - Understanding the Data Sections:

"raw_averages" = Actual statistical performance (e.g., 45.6% FG, 12.3 assists per game)
"ranking_stats" = Rotisserie points earned in each category (see explanation below)
"category_ranks" = Ordinal position in each category (1=1st place, 2=2nd place, etc.)
"shot_chart" = Raw totals for field goals and free throws (not averages)

RANKING STATS EXPLANATION (Same as getAveragesLeagueRankings):
This is a ROTISSERIE (ROTO) fantasy league. Teams earn ranking points in 8 categories.

CRITICAL: Do NOT confuse "ranking points" with "category ranks"!
- ranking_stats values (e.g., ast: 12.0) = POINTS earned (higher is better)
- category_ranks values (e.g., AST: 1) = position/place (lower is better, 1 = first)

HOW RANKING POINTS WORK:
- In each category, teams are ranked 1st to Nth (where N = number of teams)
- Best team in a category gets N points, second-best gets N-1, worst gets 1
- Example in 12-team league: 1st place = 12 pts, 2nd = 11 pts, ..., 12th = 1 pt
- total_points = sum of points from all 8 categories
- Overall "rank" is determined by total_points (highest total = rank 1)

Args:
    team_id: The ID of the team to get details for. Use getTeams() to see all team IDs.

Returns:
    A dictionary containing comprehensive team information: {
        "team": {
            "team_id": <team_id>,
            "team_name": <team_name>
        },
        "espn_url": <espn_team_page_url_string>,
        
        "shot_chart": {
            "team": {"team_id": <id>, "team_name": <name>},
            "fgm": <total_field_goals_made>,
            "fga": <total_field_goals_attempted>,
            "fg_percentage": <calculated_field_goal_percentage_as_decimal>,
            "ftm": <total_free_throws_made>,
            "fta": <total_free_throws_attempted>,
            "ft_percentage": <calculated_free_throw_percentage_as_decimal>,
            "gp": <games_played>
        },
        
        "raw_averages": {
            "fg_percentage": <average_field_goal_percentage_as_decimal>,
            "ft_percentage": <average_free_throw_percentage_as_decimal>,
            "three_pm": <average_three_pointers_made_per_game>,
            "ast": <average_assists_per_game>,
            "reb": <average_rebounds_per_game>,
            "stl": <average_steals_per_game>,
            "blk": <average_blocks_per_game>,
            "pts": <average_points_per_game>,
            "gp": <games_played>,
            "team": {"team_id": <id>, "team_name": <name>}
        },
        
        "ranking_stats": {
            "team": {"team_id": <id>, "team_name": <name>},
            "fg_percentage": <ranking_points_earned_in_fg_percentage>,
            "ft_percentage": <ranking_points_earned_in_ft_percentage>,
            "three_pm": <ranking_points_earned_in_three_pointers>,
            "ast": <ranking_points_earned_in_assists>,
            "reb": <ranking_points_earned_in_rebounds>,
            "stl": <ranking_points_earned_in_steals>,
            "blk": <ranking_points_earned_in_blocks>,
            "pts": <ranking_points_earned_in_points>,
            "gp": <games_played_not_ranked>,
            "total_points": <sum_of_all_8_category_ranking_points>,
            "rank": <overall_standing_1_is_first_place>
        },
        
        "category_ranks": {
            "FG%": <ranking_points_earned_in_fg_percentage>,
            "FT%": <ranking_points_earned_in_ft_percentage>,
            "3PM": <ranking_points_earned_in_three_pointers>,
            "AST": <ranking_points_earned_in_assists>,
            "REB": <ranking_points_earned_in_rebounds>,
            "STL": <ranking_points_earned_in_steals>,
            "BLK": <ranking_points_earned_in_blocks>,
            "PTS": <ranking_points_earned_in_points>
        },
        
        "players": [
            {
                "player_name": <player_full_name_string>,
                "pro_team": <nba_team_abbreviation_string>,
                "positions": <list_of_eligible_positions>,
                "stats": {
                    "pts": <average_points_per_game>,
                    "reb": <average_rebounds_per_game>,
                    "ast": <average_assists_per_game>,
                    "stl": <average_steals_per_game>,
                    "blk": <average_blocks_per_game>,
                    "fgm": <average_field_goals_made_per_game>,
                    "fga": <average_field_goals_attempted_per_game>,
                    "ftm": <average_free_throws_made_per_game>,
                    "fta": <average_free_throws_attempted_per_game>,
                    "fg_percentage": <field_goal_percentage_as_decimal>,
                    "ft_percentage": <free_throw_percentage_as_decimal>,
                    "three_pm": <average_three_pointers_made_per_game>,
                    "minutes": <average_minutes_per_game>,
                    "gp": <total_games_played>
                },
                "team_id": <fantasy_team_id>
            }
        ]
    }
    
EXAMPLE - Understanding the Different Data Types:
If a team shows:
- raw_averages.ast: 25.3 → Team averages 25.3 assists per game (actual performance)
- ranking_stats.ast: 12.0 → Team earned 12 ranking points in assists (1st place in 12-team league)
- category_ranks.AST: 1 → Team is ranked 1st in assists category

NOTES:
- Higher ranking_stats values = more points earned = better
- Lower category_ranks values = better position (1 is first place)
- raw_averages are the actual statistical performance
- GP (games played) is informational only, not used in ranking calculations
- When referring to steals in Hebrew, use חטיפות (not גניבות)
ParametersJSON Schema
NameRequiredDescriptionDefault
team_idYes

TDQS

A4.6/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the data structure, including key distinctions (e.g., ranking points vs. category ranks, raw totals vs. averages), and provides an example to illustrate differences. However, it lacks explicit information about rate limits, authentication requirements, or error handling, which would be needed for a perfect score.

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

Conciseness3/5

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

The description is well-structured with clear sections (e.g., 'IMPORTANT', 'HOW RANKING POINTS WORK', 'EXAMPLE'), but it is excessively long (over 500 words) with redundant explanations (e.g., repeating ranking stats details). Some content, like the Hebrew translation note, is unnecessary for tool selection. While informative, it could be more concise without losing critical information.

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

Completeness5/5

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

Given the complexity of the tool (returns multiple nested data types), no annotations, and no output schema, the description provides exceptional completeness. It details all return sections with field explanations, includes an example to clarify data interpretation, and explains domain-specific concepts (rotisserie scoring). This fully compensates for the lack of structured metadata.

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

Parameters5/5

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

The schema has 0% description coverage (parameter 'team_id' has no description in schema), so the description must fully compensate. It does so by explaining: 'team_id: The ID of the team to get details for. Use getTeams() to see all team IDs.' This provides clear semantics, source guidance, and practical usage instructions beyond the bare schema type.

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

Purpose5/5

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

The description clearly states the tool's purpose: 'Get comprehensive details for a specific team from the API.' It specifies the verb ('Get'), resource ('team details'), and scope ('comprehensive'), distinguishing it from siblings like getTeams (list teams) or getAverageStats (league-wide averages). The detailed breakdown of data sections further clarifies what 'comprehensive' entails.

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

Usage Guidelines5/5

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

The description provides explicit guidance on when to use this tool: 'Use getTeams() to see all team IDs' to obtain the required team_id parameter. It distinguishes this tool from siblings by explaining that it combines multiple data types (raw averages, ranking stats, etc.) for a single team, unlike getAveragesLeagueRankings (league-wide rankings) or getAverageStats (league averages). The 'IMPORTANT' and 'CRITICAL' sections further clarify usage context.

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

getTeamsA
Get the list of all teams in the fantasy league.

Use this endpoint to discover team IDs for use with other endpoints like getTeamDetails().

Returns:
    A list of teams with their team_id and team_name.
    Each item in the list is a dictionary with the following keys: {
        "team_id": <integer_team_identifier>,
        "team_name": <string_team_name>
    }
    
NOTES:
- Team IDs are required for getTeamDetails(team_id)
- Team names may contain emojis or special characters
- The list includes all active teams in the league
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. It discloses that the list includes all active teams and notes about team names (emojis/special characters), which adds useful context. However, it lacks details on potential limitations like pagination, rate limits, or error handling, leaving some behavioral aspects unclear.

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

Conciseness4/5

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

The description is well-structured with clear sections (purpose, usage, returns, notes) and is front-loaded with key information. It could be slightly more concise by integrating the 'Returns' section more seamlessly, but overall it's efficient with minimal waste.

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

Completeness4/5

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

Given the tool's low complexity (0 parameters, no output schema), the description is quite complete. It explains the purpose, usage, return format, and additional notes. However, without annotations or output schema, it could benefit from more behavioral details (e.g., response size limits), slightly lowering the score.

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

Parameters4/5

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

The input schema has 0 parameters with 100% coverage, so the baseline is high. The description does not need to explain parameters, and it correctly states there are no inputs, as implied by the empty schema. This earns a 4 for clarity in a parameterless context.

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

Purpose4/5

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 the list of all teams in the fantasy league.' It specifies the verb ('Get') and resource ('teams'), but does not explicitly differentiate from sibling tools like getTeamDetails, which is why it doesn't reach a 5.

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

Usage Guidelines5/5

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

The description provides explicit usage guidance: 'Use this endpoint to discover team IDs for use with other endpoints like getTeamDetails().' It clearly indicates when to use this tool (to get IDs for other tools) and references an alternative (getTeamDetails), meeting the criteria for a 5.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv1.0.0
    • First observedgetAveragesLeagueRankings
    • First observedgetAverageStats
    • First observedgetLeagueShotsStats
    • First observedgetTeamDetails
    • First observedgetTeams
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored across 5 tools

Disambiguation4/5

The tools are mostly distinct with clear purposes: getAveragesLeagueRankings (rotisserie ranking points), getAverageStats (actual performance averages), getLeagueShotsStats (cumulative shooting totals), getTeamDetails (comprehensive team data), and getTeams (team list). However, getAveragesLeagueRankings and getTeamDetails both provide ranking points, which could cause confusion about which to use for ranking data, though their scopes differ (league-wide vs. single team).

Naming Consistency3/5

The naming is mixed but readable: getAveragesLeagueRankings, getAverageStats, getLeagueShotsStats, getTeamDetails, and getTeams. Most start with 'get' followed by a noun phrase, but there's inconsistency in pluralization (Averages vs. Average) and structure (e.g., 'LeagueRankings' vs. 'LeagueShotsStats'). It's not chaotic but lacks a strict pattern like verb_noun throughout.

Tool Count5/5

With 5 tools, this is well-scoped for a fantasy NBA league server. Each tool serves a distinct purpose: retrieving league rankings, stats, shooting data, team details, and team list. The count is appropriate, avoiding bloat while covering core functionalities like data access and analysis.

Completeness4/5

The tool set covers key aspects of a fantasy league: league-wide rankings, stats, shooting data, team details, and team listing. Minor gaps exist, such as no tools for updating league settings, managing teams, or accessing player-specific data beyond team rosters, but agents can work around these for basic querying and analysis tasks.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • NBA Player Stats MCP Server

    ziyadmir
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides comprehensive NBA player statistics from basketball-reference.com, delivering detailed stats including career summaries, season comparisons, advanced metrics, and shooting analytics.
    3
    MIT

  • Sport5 Fantasy League MCP

    benshabbat
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables full automation of Sport5 Fantasy League management including team analysis, player searches, automatic transfers, captain selection, and optimization recommendations. Supports Hebrew interface and provides comprehensive fantasy football team management through natural language commands.
    -

  • nba-stats-mcp

    labeveryday
    A
    license
    B
    quality
    D
    maintenance
    Provides comprehensive NBA statistics via Model Context Protocol, enabling queries for player stats, game scores, team info, and advanced analytics through natural language.
    21
    10
    MIT