This server has fundamental quality gaps across all definition dimensions. All 7 tools lack proper parameter descriptions, the input schema shows bare enum values in descriptions (e.g., 'The hitting stat to rank by (PERCENTILE_OVERALL, RUNS, HOME_RUNS...)') but these are not formal enum constraints in the schema itself. Tool descriptions are present but generic and under 100 characters, missing context about when to use each tool and what they return. No output schemas are documented anywhere in the source code. Parameter names like 'stat' are vague, 'stat' could mean many things without the description context. The server exposes raw fantasy baseball API endpoints via tool names and parameters without abstracting complexity for chat-friendly interaction. Error handling is minimal (catches exceptions and returns None or generic strings). No pagination, rate limiting, or result limits are visible despite tools that clearly return large result sets (get_hitter_projections, get_starting_pitcher_projections likely return hundreds of players). Tool composition is reasonable (one responsibility per tool) but documentation is insufficient to guide LLM selection.
Tools (7)
add_favorite_playerwrite38/100
Add a player to your favorites list
get_fantasy_team_summaryread only37/100
Get summary of your fantasy baseball team and current matchup status
get_hitter_projectionsread only37/100
Get hitting projections for all hitters
get_hitter_rankingsread only42/100
Get hitter rankings by a specified stat
get_relief_pitcher_rankingsread only42/100
Get relief pitcher rankings by a specified stat
get_starting_pitcher_projectionsread only37/100
Get starting pitcher projections for all starting pitchers
No output schemas documented for any tool. LLMs cannot plan downstream calls or understand what data to extract. All 7 tools have zero visibility into return types.
Tools returning large result sets (projections, rankings) have no pagination, limit, or offset parameters. Source code shows no result limiting, get_hitter_projections likely returns hundreds of players, blowing context windows.
get_hitter_projections
Recommendations
Add output schema documentation to all 7 tools. Example for get_hitter_projections: 'Returns an array of objects with fields: playerId (string), firstName (string), lastName (string), team (string), position (string), runs (number), homeRuns (number), rbis (number), stolenBases (number), onBasePercentage (number), percentile grades (number 0-100).'
Convert 'stat' parameter in ranking tools to a formal enum constraint in JSON Schema. Change from free-form string to type: 'string' with enum: ['PERCENTILE_OVERALL', 'RUNS', 'HOME_RUNS', 'RBIS', 'STOLEN_BASES', 'OBP', 'NONE'] for hitters; ['PERCENTILE_OVERALL', 'QUALITY_STARTS', 'ERA', 'WHIP', 'KS_PER_NINE', 'SAVES', 'HOLDS'] for pitchers.
Add pagination to projection and ranking tools. Add optional parameters: limit (integer, default 20, range 1-100) and offset (integer, default 0). Return total_count and has_more fields. Document expected result set sizes and recommend pagination for large queries.
Expand tool descriptions to 100-200 characters. Example: 'Get hitting performance projections for all hitters in the league. Returns expected stats including runs, home runs, RBIs, stolen bases, and on-base percentage with percentile grades. Use this to evaluate hitter strength before drafting or trades.'
Improve error handling in makeFantasyBaseballGetRequest and makeFantasyBaseballPostRequest. Return structured error objects with error code, user-friendly message, and recovery guidance. E.g., '{'error': 'not_found', 'message': 'Player not found', 'recovery': 'Try search_players() or check player_id format'}'.
Error handling is minimal. makeFantasyBaseballGetRequest catches all exceptions generically and returns None, and makeFantasyBaseballPostRequest returns raw exception text.
Parameter 'player_id' in add_favorite_player has vague type (string) and description that does not explain format or how to obtain it. No guidance on whether it's a numeric ID, UUID, or username.
Tool descriptions are generic (30-40 chars). State WHAT the tool does, WHEN to use it, and any prerequisites.' Current descriptions lack context about when to call each ranking/projection tool or what data they surface.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are visible in the tool definitions. add_favorite_player is a write operation and should be marked destructive; others should be marked read-only.
API responses are formatted as unstructured strings via formatHitterProjections, formatStartingPitcherRanking, etc. This forces LLMs to parse text, wastes tokens, and is error-prone.
Add tool annotations to FastMCP tool decorators. Mark get_* tools with readOnlyHint=True. Mark add_favorite_player with destructiveHint=True and idempotentHint=True (if repeated calls are safe).
Return structured JSON objects instead of formatted strings. Modify formatHitterProjections to return dict with typed fields. LLMs can extract and chain data more reliably.
Document add_favorite_player's player_id parameter format. Specify whether it's a numeric ID, UUID, email, or username. Provide an example: 'player_id is the integer ID assigned by the API, e.g., 12345. To find a player_id, use search_players() first.'
Add a search_players(query: string) tool to help LLMs find player_id values. This reduces friction for add_favorite_player and enables the agent to resolve names to IDs without manual lookup.
Implement timeout handling. Current code has 30s timeout but no explicit error message. Add: 'if response times out, return {'error': 'timeout', 'message': 'Fantasy Baseball API did not respond in 30 seconds', 'recovery': 'Try again in a moment or check service status'}'.