fix(crewai-tools): address review — drop utr listing, numeric player_id, tour enum, docs

- Remove 'utr' from the rankings systems: the API's /rankings listing
  mode does not serve it (utr is a rating, not a ranking).
- Type player_id as int to match the API's integer path parameter and
  avoid pydantic v2's refusal to coerce int input to a str field.
- Constrain tour to the API's enum (atp, wta, challenger, itf, juniors).
- Document tour/limit/offset in both the package README and the docs
  page; note the rankings action's PRO-plan requirement in the schema.
- Add docstrings and tests for the new validation behavior.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: bensynapse

docs/edge/en/tools/search-research/livetennistool.mdx

@@ -24,13 +24,18 @@ LIVETENNIS_API_KEY=your_api_key   # Free key at livetennisapi.com
 | `action` | What it returns | Plan |
 |---|---|---|
 | `live_matches` | Matches in play with current scores (optional `tour` filter) | Free |
-| `upcoming_matches` | Matches starting soon | Free |
-| `fixtures` | Scheduled matches | Free |
+| `upcoming_matches` | Matches starting soon (optional `tour` filter) | Free |
+| `fixtures` | Scheduled matches (optional `tour` filter) | Free |
 | `search_players` | Player search by name (requires `search`) | Free |
-| `player_profile` | Single player detail, including current ranking (requires `player_id`) | Free |
-| `rankings` | Published ranking table (requires `system`: `atp`, `wta`, `itf_jt`, `itf_mt`, `itf_wt`, `utr`) | PRO |
+| `player_profile` | Single player detail, including current ranking (requires `player_id`, the numeric id from `search_players`) | Free |
+| `rankings` | Published ranking table (requires `system`: `atp`, `wta`, `itf_jt`, `itf_mt`, `itf_wt`; UTR has no listing — it is a rating, not a ranking) | PRO |
 | `usage` | Your API quota vs. consumption | Free |
 
+### Parameters
+
+- `tour` — optional filter for `live_matches`, `upcoming_matches` and `fixtures`: one of `atp`, `wta`, `challenger`, `itf`, `juniors`. Omit for all tours.
+- `limit` / `offset` — pagination for the list actions (`live_matches`, `upcoming_matches`, `fixtures`, `search_players`, `rankings`). The API default is 50 results.
+
 ## Basic Usage
 
 ```python
@@ -59,7 +64,7 @@ print(tool.run(action="live_matches", tour="atp"))
 
 # Find a player, then load their profile
 players = tool.run(action="search_players", search="alcaraz")
-profile = tool.run(action="player_profile", player_id="<id from search>")
+profile = tool.run(action="player_profile", player_id=12345)  # numeric id from the search result
 ```
 
 ## Error Handling

lib/crewai-tools/src/crewai_tools/tools/live_tennis_tool/README.md

@@ -8,14 +8,19 @@ The tool is scoped to REST endpoints, most of which are available on the free ti
 
 | `action` | Endpoint | Plan | Notes |
 |---|---|---|---|
-| `live_matches` | `GET /matches?status=live` | Free | Matches in play with current scores |
-| `upcoming_matches` | `GET /matches?status=upcoming` | Free | Matches starting soon |
-| `fixtures` | `GET /fixtures` | Free | Scheduled matches |
+| `live_matches` | `GET /matches?status=live` | Free | Matches in play with current scores; optional `tour` |
+| `upcoming_matches` | `GET /matches?status=upcoming` | Free | Matches starting soon; optional `tour` |
+| `fixtures` | `GET /fixtures` | Free | Scheduled matches; optional `tour` |
 | `search_players` | `GET /players?search=` | Free | Requires `search` |
-| `player_profile` | `GET /players/{id}` | Free | Requires `player_id`; includes current ranking |
-| `rankings` | `GET /rankings?system=` | PRO | Requires `system` (`atp`, `wta`, `itf_jt`, `itf_mt`, `itf_wt`, `utr`) |
+| `player_profile` | `GET /players/{id}` | Free | Requires `player_id` (numeric id from `search_players`); includes current ranking |
+| `rankings` | `GET /rankings?system=` | PRO | Requires `system` (`atp`, `wta`, `itf_jt`, `itf_mt`, `itf_wt`); UTR has no listing (it is a rating, not a ranking) |
 | `usage` | `GET /usage` | Free | Your quota vs. consumption; exempt from quota |
 
+### Parameters
+
+- `tour` — optional filter for `live_matches`, `upcoming_matches` and `fixtures`: one of `atp`, `wta`, `challenger`, `itf`, `juniors`. Omit for all tours.
+- `limit` / `offset` — pagination for the list actions (`live_matches`, `upcoming_matches`, `fixtures`, `search_players`, `rankings`). The API default is 50 results.
+
 The free tier is keyed and rate-limited to 30 requests/minute and 100 requests/day. Completed-match history is a paid feature and is not part of this tool. The API also offers a WebSocket push feed and model win probability on its top tier; this tool intentionally sticks to the polling REST surface.
 
 ## Environment Variables
@@ -38,7 +43,7 @@ print(tool.run(action="live_matches", tour="atp"))
 
 # Find a player, then load their profile
 players = tool.run(action="search_players", search="alcaraz")
-profile = tool.run(action="player_profile", player_id="<id from search>")
+profile = tool.run(action="player_profile", player_id=12345)  # numeric id from the search result
 ```
 
 ## With an Agent

lib/crewai-tools/src/crewai_tools/tools/live_tennis_tool/live_tennis_tool.py

@@ -5,7 +5,6 @@
 import json
 import os
 from typing import Any
-from urllib.parse import quote
 
 from crewai.tools import BaseTool, EnvVar
 from pydantic import BaseModel, Field, ValidationError
@@ -48,6 +47,12 @@ class LiveTennisTool(BaseTool):
     )
 
     def _run(self, **kwargs: Any) -> str:
+        """Validate the arguments, call the API, and return the response.
+
+        Returns the endpoint's JSON as a string on success, or a readable
+        error message (missing key, invalid arguments, 401/403/429/other
+        HTTP errors, network failure) so an agent can recover.
+        """
         api_key = os.environ.get(API_KEY_ENV_VAR, "").strip()
         if not api_key:
             return (
@@ -116,7 +121,7 @@ def _build_request(params: LiveTennisToolSchema) -> tuple[str, dict[str, Any]]:
             query["search"] = params.search
             return "/players", query
         if params.action == "player_profile":
-            return f"/players/{quote(str(params.player_id), safe='')}", {}
+            return f"/players/{params.player_id}", {}
         if params.action == "rankings":
             query["system"] = params.system
             return "/rankings", query

lib/crewai-tools/src/crewai_tools/tools/live_tennis_tool/schemas.py

@@ -16,8 +16,17 @@
     "rankings",
     "usage",
 ]
+"""Operations the tool can perform, each mapping to one REST endpoint."""
 
-RankingSystem = Literal["atp", "wta", "itf_jt", "itf_mt", "itf_wt", "utr"]
+RankingSystem = Literal["atp", "wta", "itf_jt", "itf_mt", "itf_wt"]
+"""Ranking systems with a published rank-ordered listing.
+
+UTR is intentionally absent: the API's ``/rankings`` listing mode does not
+serve it ("`utr` has no listing — it is a rating, not a ranking").
+"""
+
+Tour = Literal["atp", "wta", "challenger", "itf", "juniors"]
+"""Valid ``tour`` filter values; an unrecognised value is a 400 from the API."""
 
 
 class LiveTennisToolSchema(BaseModel):
@@ -31,14 +40,15 @@ class LiveTennisToolSchema(BaseModel):
             "'fixtures' (scheduled matches), 'search_players' (find players by "
             "name, requires 'search'), 'player_profile' (single player detail "
             "including current ranking, requires 'player_id'), 'rankings' "
-            "(published ranking table, requires 'system'), 'usage' (your API "
-            "quota and consumption)."
+            "(published ranking table, requires 'system'; needs a PRO-plan "
+            "API key), 'usage' (your API quota and consumption)."
         ),
     )
-    tour: str | None = Field(
+    tour: Tour | None = Field(
         default=None,
         description=(
-            "Optional tour filter for match and fixture actions, e.g. 'atp' or 'wta'."
+            "Optional tour filter for match and fixture actions: 'atp', 'wta', "
+            "'challenger', 'itf' or 'juniors'. Omit for all tours."
         ),
     )
     search: str | None = Field(
@@ -48,18 +58,18 @@ class LiveTennisToolSchema(BaseModel):
             "'search_players' action."
         ),
     )
-    player_id: str | None = Field(
+    player_id: int | None = Field(
         default=None,
         description=(
-            "Player id as returned by 'search_players'. Required for the "
-            "'player_profile' action."
+            "Numeric player id as returned by 'search_players'. Required for "
+            "the 'player_profile' action."
         ),
     )
     system: RankingSystem | None = Field(
         default=None,
         description=(
             "Ranking system for the 'rankings' action: 'atp', 'wta', 'itf_jt', "
-            "'itf_mt', 'itf_wt' or 'utr'."
+            "'itf_mt' or 'itf_wt'. The rankings listing needs a PRO-plan key."
         ),
     )
     limit: int | None = Field(
@@ -75,13 +85,12 @@ class LiveTennisToolSchema(BaseModel):
 
     @model_validator(mode="after")
     def _validate_action_arguments(self) -> LiveTennisToolSchema:
+        """Ensure the arguments each action depends on are present."""
         if self.action == "search_players" and not (
             self.search and self.search.strip()
         ):
             raise ValueError("'search' is required for the 'search_players' action.")
-        if self.action == "player_profile" and not (
-            self.player_id and self.player_id.strip()
-        ):
+        if self.action == "player_profile" and self.player_id is None:
             raise ValueError("'player_id' is required for the 'player_profile' action.")
         if self.action == "rankings" and self.system is None:
             raise ValueError("'system' is required for the 'rankings' action.")