Improve MCP tool selection guidance

platform/mcp/patches/mcp_radarr.py

@@ -0,0 +1,38 @@
+"""Radarr action-routed MCP tool with model-oriented routing guidance."""
+
+import json
+from typing import Any
+
+from agent_utilities.mcp_utilities import dispatch, run_blocking
+from fastmcp import FastMCP
+from pydantic import Field
+
+from arr_mcp.auth import get_radarr_client
+
+
+def register_radarr_tools(mcp: FastMCP) -> None:
+    @mcp.tool(tags={"radarr"})
+    async def radarr_action(
+        action: str = Field(
+            description=(
+                "Choose one Radarr operation. Common read choices include get_movie for the "
+                "movie library and get_system_status/get_health for Radarr diagnostics. Use "
+                "list_actions only when an unusual Radarr operation is genuinely required. "
+                "Never guess a modifying action and never change Radarr without explicit user approval."
+            )
+        ),
+        params_json: str = Field(
+            default="{}",
+            description=(
+                "JSON object encoded as a string containing only parameters required by the "
+                "selected Radarr action. Use \"{}\" for actions without parameters; never "
+                "invent movie IDs, paths, profile IDs or monitoring settings."
+            ),
+        ),
+    ) -> Any:
+        """USE ONLY for movies managed by Radarr: inspect the movie library, wanted/queue/history state, releases, profiles, or Radarr health. DO NOT use for TV episodes (use Sonarr), public-web research, media playback, filesystem copying, or direct downloads. Prefer read actions; any mutation requires explicit user approval."""
+        client = get_radarr_client()
+        kwargs = {k: v for k, v in json.loads(params_json).items() if v is not None}
+        return await run_blocking(
+            dispatch, client, action, kwargs, service="arr-radarr"
+        )

platform/mcp/patches/mcp_sonarr.py

@@ -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",