FPL Analytics MCP has 12 well-named tools with consistent verb_noun patterns (get_, search_, compute rankings). All tools have descriptions (avg ~100 chars, within baseline 34-392). Input schemas are present with type definitions and parameter descriptions. However, output schemas are NOT documented, the code shows return types (PlayerRanking, list[dict], etc.) but the tool definitions lack explicit output schema documentation. Error handling is minimal; no recovery guidance or actionable error messages. No tool annotations (readOnlyHint, destructiveHint). Parameter descriptions are adequate but lack format constraints (e.g., position enum values 1-4 are mentioned in text but not formalized). The 'format' parameter pattern (summary vs detailed) is repeated across 6 tools but not consistently constrained as an enum.

• Add explicit output schemas to all tool definitions. Document the structure of PlayerRanking, LiveGameweek, Fixture, and other return types as JSON Schema objects with field descriptions. This enables LLMs to plan multi-step workflows.
• Formalize enum constraints in input schemas. Convert 'format' parameter to enum: ['summary', 'detailed']. Convert position to enum: [1, 2, 3, 4] with descriptions. Convert metric to enum: ['total_points', 'form', 'selected_by_percent', 'points_per_game'].
• Add tool annotations. Mark all 12 tools with readOnlyHint: true since they only fetch data. This signals to LLMs that these tools are safe to retry and have no side effects.
• Implement error handling with recovery guidance. Catch FPLClientError and return structured errors like: {'error': 'Player not found', 'player_id': <id>, 'suggestion': 'Try search_players() with a partial name'}. Categorize errors as retryable (network timeout) vs user-fixable (invalid player_id).
• Add numeric constraints to parameter descriptions. E.g., 'gameweek: integer, 1-38' and 'limit: integer, 1-100 (default 20)'. This prevents LLMs from passing absurd values like gameweek=999 or limit=10000.