Improve MCP tool selection guidance

2026-08-21 20:34:40 +02:00
parent 6f14f62dd1
commit a194a2941d
8 changed files with 184 additions and 31 deletions
@@ -411,14 +411,14 @@ def register_sonarr_tools(mcp: FastMCP) -> None:
    @mcp.tool(tags={"sonarr"})
    async def sonarr_action(
        action: str = Field(
-            description="Sonarr action. Read with find_series {query}, get_season_summary {series_id, season_number}, or search_releases {series_id, season_number}. To download missing episodes, first call preview_episode_search {series_id, season_number, episode_numbers:[2,3,...]}, show its exact preview to the user, then only after explicit approval call start_episode_search with the same scope plus confirm:true and approval_ticket. Monitoring is never changed."
+            description="Choose one Sonarr operation. Normal choices: find_series to resolve a TV-series name; get_season_summary to list present/missing episodes; search_releases to query Sonarr's configured indexers without downloading; preview_episode_search before any download search; start_episode_search only after the user explicitly approves that exact preview. Use list_actions only for an unusual read operation."
        ),
        params_json: str = Field(
            default="{}",
-            description="JSON string of parameters to pass to the action.",
+            description="JSON object encoded as a string. Common forms: find_series {\"query\":\"Title\"}; get_season_summary/search_releases {\"series_id\":123,\"season_number\":2}; preview_episode_search {\"series_id\":123,\"season_number\":2,\"episode_numbers\":[2,3]}. For start_episode_search reuse the exact preview scope and add confirm:true plus approval_ticket.",
        ),
    ) -> Any:
-        """Query Sonarr through a server-side allowlist (read-only by default; write actions when ARR_MCP_WRITE=1)."""
+        """USE ONLY for TV-series tasks managed by Sonarr: identify a series, inspect missing episodes, search configured indexers, or start an explicitly approved missing-episode search. DO NOT use for movies (use Radarr), public-web research, media playback, filesystem copying, or direct URL downloads. Read-only by default; monitoring is never changed."""
        if action in {"list_actions", "help", "actions"}:
            return {
                "service": "sonarr",