From d940373f6b3c4ed25d55bcb519a5c8fa3e55c526 Mon Sep 17 00:00:00 2001
From: jxxghp <jxxghp@gmail.com>
Date: Mon, 25 May 2026 16:40:43 +0800
Subject: [PATCH] =?UTF-8?q?=E5=B0=86=E6=89=80=E6=9C=89agent=E5=B7=A5?=
 =?UTF-8?q?=E5=85=B7=E7=9A=84explanation=E5=AD=97=E6=AE=B5=E6=94=B9?=
 =?UTF-8?q?=E4=B8=BA=E5=8F=AF=E9=80=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

修复Pydantic验证错误：QueryTransferHistoryInput的explanation字段为必需，但用户未提供。
修改了74个工具文件，将explanation字段从必需改为可选，默认值为None。
---
 app/agent/tools/impl/add_custom_filter_rule.py     | 6 ++----
 app/agent/tools/impl/add_download.py               | 2 +-
 app/agent/tools/impl/add_rule_group.py             | 6 ++----
 app/agent/tools/impl/add_subscribe.py              | 6 ++----
 app/agent/tools/impl/ask_user_choice.py            | 6 ++----
 app/agent/tools/impl/browse_webpage.py             | 6 ++----
 app/agent/tools/impl/delete_custom_filter_rule.py  | 6 ++----
 app/agent/tools/impl/delete_download.py            | 6 ++----
 app/agent/tools/impl/delete_download_history.py    | 6 ++----
 app/agent/tools/impl/delete_rule_group.py          | 6 ++----
 app/agent/tools/impl/delete_subscribe.py           | 6 ++----
 app/agent/tools/impl/delete_transfer_history.py    | 6 ++----
 app/agent/tools/impl/execute_command.py            | 4 +---
 app/agent/tools/impl/get_recommendations.py        | 6 ++----
 app/agent/tools/impl/get_search_results.py         | 6 ++----
 app/agent/tools/impl/install_plugin.py             | 6 ++----
 app/agent/tools/impl/list_directory.py             | 2 +-
 app/agent/tools/impl/list_slash_commands.py        | 6 ++----
 app/agent/tools/impl/modify_download.py            | 6 ++----
 app/agent/tools/impl/query_builtin_filter_rules.py | 6 ++----
 app/agent/tools/impl/query_custom_filter_rules.py  | 6 ++----
 app/agent/tools/impl/query_custom_identifiers.py   | 6 ++----
 app/agent/tools/impl/query_directory_settings.py   | 2 +-
 app/agent/tools/impl/query_download_tasks.py       | 2 +-
 app/agent/tools/impl/query_downloaders.py          | 2 +-
 app/agent/tools/impl/query_episode_schedule.py     | 2 +-
 app/agent/tools/impl/query_installed_plugins.py    | 6 ++----
 app/agent/tools/impl/query_library_exists.py       | 2 +-
 app/agent/tools/impl/query_library_latest.py       | 6 ++----
 app/agent/tools/impl/query_market_plugins.py       | 6 ++----
 app/agent/tools/impl/query_media_detail.py         | 2 +-
 app/agent/tools/impl/query_personas.py             | 6 ++----
 app/agent/tools/impl/query_plugin_capabilities.py  | 6 ++----
 app/agent/tools/impl/query_plugin_config.py        | 6 ++----
 app/agent/tools/impl/query_plugin_data.py          | 6 ++----
 app/agent/tools/impl/query_popular_subscribes.py   | 2 +-
 app/agent/tools/impl/query_rule_groups.py          | 6 ++----
 app/agent/tools/impl/query_schedulers.py           | 2 +-
 app/agent/tools/impl/query_site_userdata.py        | 6 ++----
 app/agent/tools/impl/query_sites.py                | 6 ++----
 app/agent/tools/impl/query_subscribe_history.py    | 6 ++----
 app/agent/tools/impl/query_subscribe_shares.py     | 2 +-
 app/agent/tools/impl/query_subscribes.py           | 6 ++----
 app/agent/tools/impl/query_system_settings.py      | 6 ++----
 app/agent/tools/impl/query_transfer_history.py     | 2 +-
 app/agent/tools/impl/query_workflows.py            | 2 +-
 app/agent/tools/impl/recognize_media.py            | 2 +-
 app/agent/tools/impl/reload_plugin.py              | 6 ++----
 app/agent/tools/impl/run_scheduler.py              | 6 ++----
 app/agent/tools/impl/run_slash_command.py          | 6 ++----
 app/agent/tools/impl/run_workflow.py               | 6 ++----
 app/agent/tools/impl/scrape_metadata.py            | 6 ++----
 app/agent/tools/impl/search_media.py               | 2 +-
 app/agent/tools/impl/search_person.py              | 2 +-
 app/agent/tools/impl/search_person_credits.py      | 2 +-
 app/agent/tools/impl/search_subscribe.py           | 2 +-
 app/agent/tools/impl/search_torrents.py            | 2 +-
 app/agent/tools/impl/search_web.py                 | 6 ++----
 app/agent/tools/impl/send_local_file.py            | 6 ++----
 app/agent/tools/impl/send_message.py               | 6 ++----
 app/agent/tools/impl/send_voice_message.py         | 6 ++----
 app/agent/tools/impl/switch_persona.py             | 8 +++-----
 app/agent/tools/impl/test_site.py                  | 2 +-
 app/agent/tools/impl/transfer_file.py              | 6 ++----
 app/agent/tools/impl/uninstall_plugin.py           | 6 ++----
 app/agent/tools/impl/update_custom_filter_rule.py  | 6 ++----
 app/agent/tools/impl/update_custom_identifiers.py  | 6 ++----
 app/agent/tools/impl/update_persona_definition.py  | 6 ++----
 app/agent/tools/impl/update_plugin_config.py       | 6 ++----
 app/agent/tools/impl/update_rule_group.py          | 6 ++----
 app/agent/tools/impl/update_site.py                | 6 ++----
 app/agent/tools/impl/update_site_cookie.py         | 6 ++----
 app/agent/tools/impl/update_subscribe.py           | 6 ++----
 app/agent/tools/impl/update_system_settings.py     | 6 ++----
 74 files changed, 128 insertions(+), 236 deletions(-)

diff --git a/app/agent/tools/impl/add_custom_filter_rule.py b/app/agent/tools/impl/add_custom_filter_rule.py
index d1388306..36d6a0e5 100644
--- a/app/agent/tools/impl/add_custom_filter_rule.py
+++ b/app/agent/tools/impl/add_custom_filter_rule.py
@@ -19,10 +19,8 @@ from app.schemas.types import SystemConfigKey
 class AddCustomFilterRuleInput(BaseModel):
     """新增自定义过滤规则工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     rule_id: str = Field(
         ...,
         description="Unique custom rule ID. Only letters and numbers are allowed.",
diff --git a/app/agent/tools/impl/add_download.py b/app/agent/tools/impl/add_download.py
index fbd909bc..ec3c48c0 100644
--- a/app/agent/tools/impl/add_download.py
+++ b/app/agent/tools/impl/add_download.py
@@ -22,7 +22,7 @@ from app.utils.crypto import HashUtils
 
 class AddDownloadInput(BaseModel):
     """添加下载工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     torrent_url: List[str] = Field(
         ...,
         description="One or more torrent_url values. Supports refs from get_search_results (`hash:id`) and magnet links."
diff --git a/app/agent/tools/impl/add_rule_group.py b/app/agent/tools/impl/add_rule_group.py
index 506515c9..c77cb3d4 100644
--- a/app/agent/tools/impl/add_rule_group.py
+++ b/app/agent/tools/impl/add_rule_group.py
@@ -23,10 +23,8 @@ from app.schemas.types import SystemConfigKey
 class AddRuleGroupInput(BaseModel):
     """新增过滤规则组工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     name: str = Field(..., description="New rule group name.")
     rule_string: str = Field(
         ...,
diff --git a/app/agent/tools/impl/add_subscribe.py b/app/agent/tools/impl/add_subscribe.py
index 2debf9fa..ac624627 100644
--- a/app/agent/tools/impl/add_subscribe.py
+++ b/app/agent/tools/impl/add_subscribe.py
@@ -14,10 +14,8 @@ from app.schemas.types import MediaType, MessageChannel
 class AddSubscribeInput(BaseModel):
     """添加订阅工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     title: str = Field(
         ...,
         description="The title of the media to subscribe to (e.g., 'The Matrix', 'Breaking Bad')",
diff --git a/app/agent/tools/impl/ask_user_choice.py b/app/agent/tools/impl/ask_user_choice.py
index 5c2b3b05..ccc589c0 100644
--- a/app/agent/tools/impl/ask_user_choice.py
+++ b/app/agent/tools/impl/ask_user_choice.py
@@ -38,10 +38,8 @@ class UserChoiceOptionInput(BaseModel):
 class AskUserChoiceInput(BaseModel):
     """按钮选择工具输入。"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why the agent needs the user to choose from buttons",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why the agent needs the user to choose from buttons",)
     message: str = Field(
         ...,
         description="Question or prompt shown to the user together with the buttons",
diff --git a/app/agent/tools/impl/browse_webpage.py b/app/agent/tools/impl/browse_webpage.py
index 2d80d53b..4d2dd029 100644
--- a/app/agent/tools/impl/browse_webpage.py
+++ b/app/agent/tools/impl/browse_webpage.py
@@ -38,10 +38,8 @@ class BrowserAction(str, Enum):
 class BrowseWebpageInput(BaseModel):
     """浏览器操作工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this browser action is being performed",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this browser action is being performed",)
     action: str = Field(
         ...,
         description=(
diff --git a/app/agent/tools/impl/delete_custom_filter_rule.py b/app/agent/tools/impl/delete_custom_filter_rule.py
index d7ed9a93..412c99d6 100644
--- a/app/agent/tools/impl/delete_custom_filter_rule.py
+++ b/app/agent/tools/impl/delete_custom_filter_rule.py
@@ -19,10 +19,8 @@ from app.schemas.types import SystemConfigKey
 class DeleteCustomFilterRuleInput(BaseModel):
     """删除自定义过滤规则工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     rule_id: str = Field(..., description="Custom rule ID to delete.")
 
 
diff --git a/app/agent/tools/impl/delete_download.py b/app/agent/tools/impl/delete_download.py
index bba14e5c..b41adb59 100644
--- a/app/agent/tools/impl/delete_download.py
+++ b/app/agent/tools/impl/delete_download.py
@@ -12,10 +12,8 @@ from app.log import logger
 class DeleteDownloadInput(BaseModel):
     """删除下载任务工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     hash: str = Field(
         ..., description="Task hash (can be obtained from query_download_tasks tool)"
     )
diff --git a/app/agent/tools/impl/delete_download_history.py b/app/agent/tools/impl/delete_download_history.py
index bd249ac1..08473cbf 100644
--- a/app/agent/tools/impl/delete_download_history.py
+++ b/app/agent/tools/impl/delete_download_history.py
@@ -13,10 +13,8 @@ from app.log import logger
 class DeleteDownloadHistoryInput(BaseModel):
     """删除下载历史记录工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     history_id: int = Field(
         ..., description="The ID of the download history record to delete"
     )
diff --git a/app/agent/tools/impl/delete_rule_group.py b/app/agent/tools/impl/delete_rule_group.py
index af1388a1..65dceca2 100644
--- a/app/agent/tools/impl/delete_rule_group.py
+++ b/app/agent/tools/impl/delete_rule_group.py
@@ -18,10 +18,8 @@ from app.schemas.types import SystemConfigKey
 class DeleteRuleGroupInput(BaseModel):
     """删除过滤规则组工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     name: str = Field(..., description="Rule group name to delete.")
 
 
diff --git a/app/agent/tools/impl/delete_subscribe.py b/app/agent/tools/impl/delete_subscribe.py
index 720f2d60..9d28af8e 100644
--- a/app/agent/tools/impl/delete_subscribe.py
+++ b/app/agent/tools/impl/delete_subscribe.py
@@ -15,10 +15,8 @@ from app.schemas.types import EventType
 class DeleteSubscribeInput(BaseModel):
     """删除订阅工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     subscribe_id: int = Field(
         ...,
         description="The ID of the subscription to delete (can be obtained from query_subscribes tool)",
diff --git a/app/agent/tools/impl/delete_transfer_history.py b/app/agent/tools/impl/delete_transfer_history.py
index e384c2d0..9bda344e 100644
--- a/app/agent/tools/impl/delete_transfer_history.py
+++ b/app/agent/tools/impl/delete_transfer_history.py
@@ -12,10 +12,8 @@ from app.log import logger
 class DeleteTransferHistoryInput(BaseModel):
     """删除整理历史记录工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     history_id: int = Field(
         ..., description="The ID of the transfer history record to delete"
     )
diff --git a/app/agent/tools/impl/execute_command.py b/app/agent/tools/impl/execute_command.py
index 69d58927..af19343f 100644
--- a/app/agent/tools/impl/execute_command.py
+++ b/app/agent/tools/impl/execute_command.py
@@ -141,9 +141,7 @@ class _CommandOutput:
 class ExecuteCommandInput(BaseModel):
     """执行 Shell 命令工具的输入参数模型。"""
 
-    explanation: str = Field(
-        ..., description="Clear explanation of why this command action is needed"
-    )
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this command action is needed")
     action: Optional[Literal["start", "read", "wait", "write", "kill", "run"]] = Field(
         "start",
         description=(
diff --git a/app/agent/tools/impl/get_recommendations.py b/app/agent/tools/impl/get_recommendations.py
index 684be683..253e1113 100644
--- a/app/agent/tools/impl/get_recommendations.py
+++ b/app/agent/tools/impl/get_recommendations.py
@@ -14,10 +14,8 @@ from app.schemas.types import MediaType, media_type_to_agent
 class GetRecommendationsInput(BaseModel):
     """获取推荐工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     source: Optional[str] = Field(
         "tmdb_trending",
         description="Recommendation source: "
diff --git a/app/agent/tools/impl/get_search_results.py b/app/agent/tools/impl/get_search_results.py
index f3d6936f..3b341788 100644
--- a/app/agent/tools/impl/get_search_results.py
+++ b/app/agent/tools/impl/get_search_results.py
@@ -20,10 +20,8 @@ from ._torrent_search_utils import (
 class GetSearchResultsInput(BaseModel):
     """获取搜索结果工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     site: Optional[List[str]] = Field(None, description="Site name filters")
     season: Optional[List[str]] = Field(None, description="Season or episode filters")
     free_state: Optional[List[str]] = Field(None, description="Promotion state filters")
diff --git a/app/agent/tools/impl/install_plugin.py b/app/agent/tools/impl/install_plugin.py
index a2609c4c..2f460df1 100644
--- a/app/agent/tools/impl/install_plugin.py
+++ b/app/agent/tools/impl/install_plugin.py
@@ -18,10 +18,8 @@ from app.log import logger
 class InstallPluginInput(BaseModel):
     """安装插件工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     plugin_id: str = Field(
         ...,
         description="Exact plugin ID to install. Use query_market_plugins first to find the correct plugin_id.",
diff --git a/app/agent/tools/impl/list_directory.py b/app/agent/tools/impl/list_directory.py
index 412754bb..50c2eb21 100644
--- a/app/agent/tools/impl/list_directory.py
+++ b/app/agent/tools/impl/list_directory.py
@@ -16,7 +16,7 @@ from app.utils.string import StringUtils
 
 class ListDirectoryInput(BaseModel):
     """查询文件系统目录内容工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     path: str = Field(..., description="Directory path to list contents (e.g., '/home/user/downloads' or 'C:/Downloads')")
     storage: Optional[str] = Field("local", description="Storage type (default: 'local' for local file system, can be 'smb', 'alist', etc.)")
     sort_by: Optional[str] = Field("name", description="Sort order: 'name' for alphabetical sorting, 'time' for modification time sorting (default: 'name')")
diff --git a/app/agent/tools/impl/list_slash_commands.py b/app/agent/tools/impl/list_slash_commands.py
index 86706bc8..0ff52563 100644
--- a/app/agent/tools/impl/list_slash_commands.py
+++ b/app/agent/tools/impl/list_slash_commands.py
@@ -12,10 +12,8 @@ from app.log import logger
 class ListSlashCommandsInput(BaseModel):
     """查询所有可用斜杠命令工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
 
 
 class ListSlashCommandsTool(MoviePilotTool):
diff --git a/app/agent/tools/impl/modify_download.py b/app/agent/tools/impl/modify_download.py
index 488b49d8..884b5fdd 100644
--- a/app/agent/tools/impl/modify_download.py
+++ b/app/agent/tools/impl/modify_download.py
@@ -12,10 +12,8 @@ from app.log import logger
 class ModifyDownloadInput(BaseModel):
     """修改下载任务工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     hash: str = Field(
         ..., description="Task hash (can be obtained from query_download_tasks tool)"
     )
diff --git a/app/agent/tools/impl/query_builtin_filter_rules.py b/app/agent/tools/impl/query_builtin_filter_rules.py
index 2c1f0868..d52570e9 100644
--- a/app/agent/tools/impl/query_builtin_filter_rules.py
+++ b/app/agent/tools/impl/query_builtin_filter_rules.py
@@ -17,10 +17,8 @@ from app.log import logger
 class QueryBuiltinFilterRulesInput(BaseModel):
     """查询内置过滤规则工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     rule_ids: Optional[List[str]] = Field(
         None,
         description="Optional list of built-in rule IDs to query. If omitted, return all built-in rules.",
diff --git a/app/agent/tools/impl/query_custom_filter_rules.py b/app/agent/tools/impl/query_custom_filter_rules.py
index 21a6b63c..cebe6413 100644
--- a/app/agent/tools/impl/query_custom_filter_rules.py
+++ b/app/agent/tools/impl/query_custom_filter_rules.py
@@ -18,10 +18,8 @@ from app.log import logger
 class QueryCustomFilterRulesInput(BaseModel):
     """查询自定义过滤规则工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     rule_ids: Optional[List[str]] = Field(
         None,
         description="Optional list of custom rule IDs to query. If omitted, return all custom rules.",
diff --git a/app/agent/tools/impl/query_custom_identifiers.py b/app/agent/tools/impl/query_custom_identifiers.py
index 81a600bb..92cc6252 100644
--- a/app/agent/tools/impl/query_custom_identifiers.py
+++ b/app/agent/tools/impl/query_custom_identifiers.py
@@ -14,10 +14,8 @@ from app.schemas.types import SystemConfigKey
 class QueryCustomIdentifiersInput(BaseModel):
     """查询自定义识别词工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
 
 
 class QueryCustomIdentifiersTool(MoviePilotTool):
diff --git a/app/agent/tools/impl/query_directory_settings.py b/app/agent/tools/impl/query_directory_settings.py
index 1671efbe..b5486c00 100644
--- a/app/agent/tools/impl/query_directory_settings.py
+++ b/app/agent/tools/impl/query_directory_settings.py
@@ -12,7 +12,7 @@ from app.log import logger
 
 class QueryDirectorySettingsInput(BaseModel):
     """查询系统目录设置工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     directory_type: Optional[str] = Field("all",
                                           description="Filter directories by type: 'download' for download directories, 'library' for media library directories, 'all' for all directories")
     storage_type: Optional[str] = Field("all",
diff --git a/app/agent/tools/impl/query_download_tasks.py b/app/agent/tools/impl/query_download_tasks.py
index 8b262431..75aa1215 100644
--- a/app/agent/tools/impl/query_download_tasks.py
+++ b/app/agent/tools/impl/query_download_tasks.py
@@ -15,7 +15,7 @@ from app.schemas.types import TorrentStatus, media_type_to_agent
 
 class QueryDownloadTasksInput(BaseModel):
     """查询下载工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     downloader: Optional[str] = Field(None,
                                       description="Name of specific downloader to query (optional, if not provided queries all configured downloaders)")
     status: Optional[str] = Field("all",
diff --git a/app/agent/tools/impl/query_downloaders.py b/app/agent/tools/impl/query_downloaders.py
index f78feed7..55fde2af 100644
--- a/app/agent/tools/impl/query_downloaders.py
+++ b/app/agent/tools/impl/query_downloaders.py
@@ -13,7 +13,7 @@ from app.schemas.types import SystemConfigKey
 
 class QueryDownloadersInput(BaseModel):
     """查询下载器工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
 
 
 class QueryDownloadersTool(MoviePilotTool):
diff --git a/app/agent/tools/impl/query_episode_schedule.py b/app/agent/tools/impl/query_episode_schedule.py
index 592dcd84..dde2985c 100644
--- a/app/agent/tools/impl/query_episode_schedule.py
+++ b/app/agent/tools/impl/query_episode_schedule.py
@@ -12,7 +12,7 @@ from app.log import logger
 
 class QueryEpisodeScheduleInput(BaseModel):
     """查询剧集上映时间工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     tmdb_id: int = Field(..., description="TMDB ID of the TV series (can be obtained from search_media tool)")
     season: int = Field(..., description="Season number to query")
     episode_group: Optional[str] = Field(None, description="Episode group ID (optional)")
diff --git a/app/agent/tools/impl/query_installed_plugins.py b/app/agent/tools/impl/query_installed_plugins.py
index 4b51b75b..95a263c8 100644
--- a/app/agent/tools/impl/query_installed_plugins.py
+++ b/app/agent/tools/impl/query_installed_plugins.py
@@ -20,10 +20,8 @@ from app.log import logger
 class QueryInstalledPluginsInput(BaseModel):
     """查询已安装插件工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     query: Optional[str] = Field(
         None,
         description="Optional keyword to filter installed plugins by plugin ID, name, description, or author.",
diff --git a/app/agent/tools/impl/query_library_exists.py b/app/agent/tools/impl/query_library_exists.py
index 74460884..d865318a 100644
--- a/app/agent/tools/impl/query_library_exists.py
+++ b/app/agent/tools/impl/query_library_exists.py
@@ -76,7 +76,7 @@ def _build_tv_server_result(existing_seasons: OrderedDict, total_seasons: Ordere
 
 class QueryLibraryExistsInput(BaseModel):
     """查询媒体库工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     tmdb_id: Optional[int] = Field(None, description="TMDB ID (can be obtained from search_media tool). Either tmdb_id or douban_id must be provided.")
     douban_id: Optional[str] = Field(None, description="Douban ID (can be obtained from search_media tool). Either tmdb_id or douban_id must be provided.")
     media_type: Optional[str] = Field(None, description="Allowed values: movie, tv")
diff --git a/app/agent/tools/impl/query_library_latest.py b/app/agent/tools/impl/query_library_latest.py
index ff03c737..a042b5f5 100644
--- a/app/agent/tools/impl/query_library_latest.py
+++ b/app/agent/tools/impl/query_library_latest.py
@@ -17,10 +17,8 @@ PAGE_SIZE = 20
 class QueryLibraryLatestInput(BaseModel):
     """查询媒体服务器最近入库影片工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     server: Optional[str] = Field(
         None,
         description="Media server name (optional, if not specified queries all enabled media servers)",
diff --git a/app/agent/tools/impl/query_market_plugins.py b/app/agent/tools/impl/query_market_plugins.py
index 950d22b1..3ed5edeb 100644
--- a/app/agent/tools/impl/query_market_plugins.py
+++ b/app/agent/tools/impl/query_market_plugins.py
@@ -20,10 +20,8 @@ from app.log import logger
 class QueryMarketPluginsInput(BaseModel):
     """查询插件市场工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     query: Optional[str] = Field(
         None,
         description="Optional keyword to filter plugin market results by plugin ID, name, description, or author.",
diff --git a/app/agent/tools/impl/query_media_detail.py b/app/agent/tools/impl/query_media_detail.py
index 749624d5..26c01054 100644
--- a/app/agent/tools/impl/query_media_detail.py
+++ b/app/agent/tools/impl/query_media_detail.py
@@ -17,7 +17,7 @@ SEASON_PREVIEW_LIMIT = 100
 
 class QueryMediaDetailInput(BaseModel):
     """查询媒体详情工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     tmdb_id: Optional[int] = Field(None, description="TMDB ID of the media (movie or TV series, can be obtained from search_media tool)")
     douban_id: Optional[str] = Field(None, description="Douban ID of the media (alternative to tmdb_id)")
     media_type: str = Field(..., description="Allowed values: movie, tv")
diff --git a/app/agent/tools/impl/query_personas.py b/app/agent/tools/impl/query_personas.py
index 02a015d0..8b7680c2 100644
--- a/app/agent/tools/impl/query_personas.py
+++ b/app/agent/tools/impl/query_personas.py
@@ -13,10 +13,8 @@ from app.log import logger
 class QueryPersonasInput(BaseModel):
     """查询人格工具的输入参数模型。"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     query: Optional[str] = Field(
         None,
         description=(
diff --git a/app/agent/tools/impl/query_plugin_capabilities.py b/app/agent/tools/impl/query_plugin_capabilities.py
index 69b42022..47f358e5 100644
--- a/app/agent/tools/impl/query_plugin_capabilities.py
+++ b/app/agent/tools/impl/query_plugin_capabilities.py
@@ -13,10 +13,8 @@ from app.log import logger
 class QueryPluginCapabilitiesInput(BaseModel):
     """查询插件能力工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     plugin_id: Optional[str] = Field(
         None,
         description="Optional plugin ID to query capabilities for a specific plugin. "
diff --git a/app/agent/tools/impl/query_plugin_config.py b/app/agent/tools/impl/query_plugin_config.py
index 7ed6af76..0cfc9b8b 100644
--- a/app/agent/tools/impl/query_plugin_config.py
+++ b/app/agent/tools/impl/query_plugin_config.py
@@ -14,10 +14,8 @@ from app.log import logger
 class QueryPluginConfigInput(BaseModel):
     """查询插件配置工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     plugin_id: str = Field(
         ...,
         description="The plugin ID to query. Use query_installed_plugins first to discover valid plugin IDs.",
diff --git a/app/agent/tools/impl/query_plugin_data.py b/app/agent/tools/impl/query_plugin_data.py
index 29875868..e456c466 100644
--- a/app/agent/tools/impl/query_plugin_data.py
+++ b/app/agent/tools/impl/query_plugin_data.py
@@ -18,10 +18,8 @@ from app.log import logger
 class QueryPluginDataInput(BaseModel):
     """查询插件数据工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     plugin_id: str = Field(
         ...,
         description="The plugin ID to query. Use query_installed_plugins first to discover valid plugin IDs.",
diff --git a/app/agent/tools/impl/query_popular_subscribes.py b/app/agent/tools/impl/query_popular_subscribes.py
index 203e77b1..0086e682 100644
--- a/app/agent/tools/impl/query_popular_subscribes.py
+++ b/app/agent/tools/impl/query_popular_subscribes.py
@@ -17,7 +17,7 @@ MAX_PAGE_SIZE = 50
 
 class QueryPopularSubscribesInput(BaseModel):
     """查询热门订阅工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     media_type: str = Field(..., description="Allowed values: movie, tv")
     page: Optional[int] = Field(1, description="Page number for pagination (default: 1)")
     count: Optional[int] = Field(30, description="Number of items per page (default: 30, max: 50)")
diff --git a/app/agent/tools/impl/query_rule_groups.py b/app/agent/tools/impl/query_rule_groups.py
index 1376e070..b91e765f 100644
--- a/app/agent/tools/impl/query_rule_groups.py
+++ b/app/agent/tools/impl/query_rule_groups.py
@@ -18,10 +18,8 @@ from app.log import logger
 class QueryRuleGroupsInput(BaseModel):
     """查询规则组工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     group_names: Optional[List[str]] = Field(
         None,
         description="Optional list of rule group names to query. If omitted, return all rule groups.",
diff --git a/app/agent/tools/impl/query_schedulers.py b/app/agent/tools/impl/query_schedulers.py
index 5d872b7d..fe3cb66c 100644
--- a/app/agent/tools/impl/query_schedulers.py
+++ b/app/agent/tools/impl/query_schedulers.py
@@ -11,7 +11,7 @@ from app.log import logger
 
 class QuerySchedulersInput(BaseModel):
     """查询定时服务工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
 
 
 class QuerySchedulersTool(MoviePilotTool):
diff --git a/app/agent/tools/impl/query_site_userdata.py b/app/agent/tools/impl/query_site_userdata.py
index 5fa0c621..7e48c343 100644
--- a/app/agent/tools/impl/query_site_userdata.py
+++ b/app/agent/tools/impl/query_site_userdata.py
@@ -23,10 +23,8 @@ def _preview_list(value, limit: int = SITE_USERDATA_DETAIL_PREVIEW_LIMIT) -> tup
 class QuerySiteUserdataInput(BaseModel):
     """查询站点用户数据工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     site_id: int = Field(
         ...,
         description="The ID of the site to query user data for (can be obtained from query_sites tool)",
diff --git a/app/agent/tools/impl/query_sites.py b/app/agent/tools/impl/query_sites.py
index a9aef571..4c2e1bbe 100644
--- a/app/agent/tools/impl/query_sites.py
+++ b/app/agent/tools/impl/query_sites.py
@@ -13,10 +13,8 @@ from app.log import logger
 class QuerySitesInput(BaseModel):
     """查询站点工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     status: Optional[str] = Field(
         "all",
         description="Filter sites by status: 'active' for enabled sites, 'inactive' for disabled sites, 'all' for all sites",
diff --git a/app/agent/tools/impl/query_subscribe_history.py b/app/agent/tools/impl/query_subscribe_history.py
index a2a54cb1..c8d3c5e0 100644
--- a/app/agent/tools/impl/query_subscribe_history.py
+++ b/app/agent/tools/impl/query_subscribe_history.py
@@ -17,10 +17,8 @@ PAGE_SIZE = 20
 class QuerySubscribeHistoryInput(BaseModel):
     """查询订阅历史工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     media_type: Optional[str] = Field(
         "all", description="Allowed values: movie, tv, all"
     )
diff --git a/app/agent/tools/impl/query_subscribe_shares.py b/app/agent/tools/impl/query_subscribe_shares.py
index bb0e5d0a..b644b01d 100644
--- a/app/agent/tools/impl/query_subscribe_shares.py
+++ b/app/agent/tools/impl/query_subscribe_shares.py
@@ -14,7 +14,7 @@ MAX_PAGE_SIZE = 50
 
 class QuerySubscribeSharesInput(BaseModel):
     """查询订阅分享工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     name: Optional[str] = Field(None, description="Filter shares by media name (partial match, optional)")
     page: Optional[int] = Field(1, description="Page number for pagination (default: 1)")
     count: Optional[int] = Field(30, description="Number of items per page (default: 30, max: 50)")
diff --git a/app/agent/tools/impl/query_subscribes.py b/app/agent/tools/impl/query_subscribes.py
index f33196a4..ffaa4e44 100644
--- a/app/agent/tools/impl/query_subscribes.py
+++ b/app/agent/tools/impl/query_subscribes.py
@@ -47,10 +47,8 @@ QUERY_SUBSCRIBE_OUTPUT_FIELDS = [
 class QuerySubscribesInput(BaseModel):
     """查询订阅工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     status: Optional[str] = Field(
         "all",
         description="Filter subscriptions by status: 'R' for enabled subscriptions, 'S' for paused ones, 'all' for all subscriptions",
diff --git a/app/agent/tools/impl/query_system_settings.py b/app/agent/tools/impl/query_system_settings.py
index 25bbca8c..6e705bca 100644
--- a/app/agent/tools/impl/query_system_settings.py
+++ b/app/agent/tools/impl/query_system_settings.py
@@ -19,10 +19,8 @@ from app.log import logger
 class QuerySystemSettingsInput(BaseModel):
     """查询系统设置工具的输入参数模型。"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     setting_key: Optional[str] = Field(
         None,
         description=(
diff --git a/app/agent/tools/impl/query_transfer_history.py b/app/agent/tools/impl/query_transfer_history.py
index c257f129..adcc80c0 100644
--- a/app/agent/tools/impl/query_transfer_history.py
+++ b/app/agent/tools/impl/query_transfer_history.py
@@ -15,7 +15,7 @@ from app.utils.jieba import cut as jieba_cut
 
 class QueryTransferHistoryInput(BaseModel):
     """查询整理历史记录工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     title: Optional[str] = Field(None, description="Search by title (optional, supports partial match)")
     status: Optional[str] = Field("all",
                                   description="Filter by status: 'success' for successful transfers, 'failed' for failed transfers, 'all' for all records (default: 'all')")
diff --git a/app/agent/tools/impl/query_workflows.py b/app/agent/tools/impl/query_workflows.py
index 2003eda9..0b5bd215 100644
--- a/app/agent/tools/impl/query_workflows.py
+++ b/app/agent/tools/impl/query_workflows.py
@@ -13,7 +13,7 @@ from app.log import logger
 
 class QueryWorkflowsInput(BaseModel):
     """查询工作流工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     state: Optional[str] = Field("all", description="Filter workflows by state: 'W' for waiting, 'R' for running, 'P' for paused, 'S' for success, 'F' for failed, 'all' for all workflows (default: 'all')")
     name: Optional[str] = Field(None, description="Filter workflows by name (partial match, optional)")
     trigger_type: Optional[str] = Field("all", description="Filter workflows by trigger type: 'timer' for scheduled, 'event' for event-triggered, 'manual' for manual, 'all' for all types (default: 'all')")
diff --git a/app/agent/tools/impl/recognize_media.py b/app/agent/tools/impl/recognize_media.py
index c8c82ee8..90d11a3c 100644
--- a/app/agent/tools/impl/recognize_media.py
+++ b/app/agent/tools/impl/recognize_media.py
@@ -15,7 +15,7 @@ from app.schemas.types import media_type_to_agent
 
 class RecognizeMediaInput(BaseModel):
     """识别媒体信息工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     title: Optional[str] = Field(None, description="The title of the torrent/media to recognize (required for torrent recognition)")
     subtitle: Optional[str] = Field(None, description="The subtitle or description of the torrent (optional, helps improve recognition accuracy)")
     path: Optional[str] = Field(None, description="The file path to recognize (required for file recognition, mutually exclusive with title)")
diff --git a/app/agent/tools/impl/reload_plugin.py b/app/agent/tools/impl/reload_plugin.py
index a13d20b6..e7f3b758 100644
--- a/app/agent/tools/impl/reload_plugin.py
+++ b/app/agent/tools/impl/reload_plugin.py
@@ -16,10 +16,8 @@ from app.log import logger
 class ReloadPluginInput(BaseModel):
     """重载插件工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     plugin_id: str = Field(
         ...,
         description="The plugin ID to reload so the latest saved config takes effect.",
diff --git a/app/agent/tools/impl/run_scheduler.py b/app/agent/tools/impl/run_scheduler.py
index 73fbb030..d7fbb25d 100644
--- a/app/agent/tools/impl/run_scheduler.py
+++ b/app/agent/tools/impl/run_scheduler.py
@@ -11,10 +11,8 @@ from app.log import logger
 class RunSchedulerInput(BaseModel):
     """运行定时服务工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     job_id: str = Field(
         ...,
         description="The ID of the scheduled job to run (can be obtained from query_schedulers tool)",
diff --git a/app/agent/tools/impl/run_slash_command.py b/app/agent/tools/impl/run_slash_command.py
index 5fdd379d..c6aa2592 100644
--- a/app/agent/tools/impl/run_slash_command.py
+++ b/app/agent/tools/impl/run_slash_command.py
@@ -14,10 +14,8 @@ from app.schemas.types import EventType, MessageChannel
 class RunSlashCommandInput(BaseModel):
     """运行斜杠命令工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     command: str = Field(
         ...,
         description="The slash command to execute, e.g. '/cookiecloud'. "
diff --git a/app/agent/tools/impl/run_workflow.py b/app/agent/tools/impl/run_workflow.py
index 16afed6e..b73e4a43 100644
--- a/app/agent/tools/impl/run_workflow.py
+++ b/app/agent/tools/impl/run_workflow.py
@@ -14,10 +14,8 @@ from app.log import logger
 class RunWorkflowInput(BaseModel):
     """执行工作流工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     workflow_id: int = Field(
         ..., description="Workflow ID (can be obtained from query_workflows tool)"
     )
diff --git a/app/agent/tools/impl/scrape_metadata.py b/app/agent/tools/impl/scrape_metadata.py
index 9b6fe829..fd8a77cd 100644
--- a/app/agent/tools/impl/scrape_metadata.py
+++ b/app/agent/tools/impl/scrape_metadata.py
@@ -15,10 +15,8 @@ from app.schemas import FileItem
 class ScrapeMetadataInput(BaseModel):
     """刮削媒体元数据工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     path: str = Field(
         ...,
         description="Path to the file or directory to scrape metadata for (e.g., '/path/to/file.mkv' or '/path/to/directory')",
diff --git a/app/agent/tools/impl/search_media.py b/app/agent/tools/impl/search_media.py
index 35086623..480149e5 100644
--- a/app/agent/tools/impl/search_media.py
+++ b/app/agent/tools/impl/search_media.py
@@ -13,7 +13,7 @@ from app.schemas.types import MediaType, media_type_to_agent
 
 class SearchMediaInput(BaseModel):
     """搜索媒体工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     title: str = Field(..., description="The title of the media to search for (e.g., 'The Matrix', 'Breaking Bad')")
     year: Optional[str] = Field(None, description="Release year of the media (optional, helps narrow down results)")
     media_type: Optional[str] = Field(None,
diff --git a/app/agent/tools/impl/search_person.py b/app/agent/tools/impl/search_person.py
index 1c3974c0..7bc40d37 100644
--- a/app/agent/tools/impl/search_person.py
+++ b/app/agent/tools/impl/search_person.py
@@ -12,7 +12,7 @@ from app.log import logger
 
 class SearchPersonInput(BaseModel):
     """搜索人物工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     name: str = Field(..., description="The name of the person to search for (e.g., 'Tom Hanks', '周杰伦')")
 
 
diff --git a/app/agent/tools/impl/search_person_credits.py b/app/agent/tools/impl/search_person_credits.py
index 16d50c98..1e263efd 100644
--- a/app/agent/tools/impl/search_person_credits.py
+++ b/app/agent/tools/impl/search_person_credits.py
@@ -14,7 +14,7 @@ from app.log import logger
 
 class SearchPersonCreditsInput(BaseModel):
     """搜索演员参演作品工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     person_id: int = Field(..., description="The ID of the person/actor to search for credits (e.g., 31 for Tom Hanks in TMDB)")
     source: str = Field(..., description="The data source: 'tmdb' for TheMovieDB, 'douban' for Douban, 'bangumi' for Bangumi")
     page: Optional[int] = Field(1, description="Page number for pagination (default: 1)")
diff --git a/app/agent/tools/impl/search_subscribe.py b/app/agent/tools/impl/search_subscribe.py
index 8a3e1e6f..760e01ae 100644
--- a/app/agent/tools/impl/search_subscribe.py
+++ b/app/agent/tools/impl/search_subscribe.py
@@ -14,7 +14,7 @@ from app.schemas.types import media_type_to_agent
 
 class SearchSubscribeInput(BaseModel):
     """搜索订阅缺失剧集工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     subscribe_id: int = Field(..., description="The ID of the subscription to search for missing episodes (can be obtained from query_subscribes tool)")
     manual: Optional[bool] = Field(False, description="Whether this is a manual search (default: False)")
     filter_groups: Optional[List[str]] = Field(None,
diff --git a/app/agent/tools/impl/search_torrents.py b/app/agent/tools/impl/search_torrents.py
index 87759d1e..4c75fba1 100644
--- a/app/agent/tools/impl/search_torrents.py
+++ b/app/agent/tools/impl/search_torrents.py
@@ -19,7 +19,7 @@ from ._torrent_search_utils import (
 
 class SearchTorrentsInput(BaseModel):
     """搜索种子工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     tmdb_id: Optional[int] = Field(None, description="TMDB ID (can be obtained from search_media tool). Either tmdb_id or douban_id must be provided.")
     douban_id: Optional[str] = Field(None, description="Douban ID (can be obtained from search_media tool). Either tmdb_id or douban_id must be provided.")
     media_type: Optional[str] = Field(None, description="Allowed values: movie, tv")
diff --git a/app/agent/tools/impl/search_web.py b/app/agent/tools/impl/search_web.py
index fbd551a4..5862d395 100644
--- a/app/agent/tools/impl/search_web.py
+++ b/app/agent/tools/impl/search_web.py
@@ -19,10 +19,8 @@ SEARCH_TIMEOUT = 20
 class SearchWebInput(BaseModel):
     """搜索网络内容工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     query: str = Field(
         ..., description="The search query string to search for on the web"
     )
diff --git a/app/agent/tools/impl/send_local_file.py b/app/agent/tools/impl/send_local_file.py
index ae971c45..11fa3ddb 100644
--- a/app/agent/tools/impl/send_local_file.py
+++ b/app/agent/tools/impl/send_local_file.py
@@ -15,10 +15,8 @@ from app.schemas.types import MessageChannel
 class SendLocalFileInput(BaseModel):
     """发送本地附件工具输入。"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why sending this local file helps the user",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why sending this local file helps the user",)
     file_path: str = Field(
         ...,
         description="Absolute path to the local image or file to send to the user",
diff --git a/app/agent/tools/impl/send_message.py b/app/agent/tools/impl/send_message.py
index 8aa59196..cdd77f6e 100644
--- a/app/agent/tools/impl/send_message.py
+++ b/app/agent/tools/impl/send_message.py
@@ -11,10 +11,8 @@ from app.log import logger
 class SendMessageInput(BaseModel):
     """发送消息工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     message: Optional[str] = Field(
         None,
         description="The message content to send to the user (should be clear and informative)",
diff --git a/app/agent/tools/impl/send_voice_message.py b/app/agent/tools/impl/send_voice_message.py
index 45d38a39..5bd1e423 100644
--- a/app/agent/tools/impl/send_voice_message.py
+++ b/app/agent/tools/impl/send_voice_message.py
@@ -15,10 +15,8 @@ from app.schemas import Notification, NotificationType
 class SendVoiceMessageInput(BaseModel):
     """发送语音消息工具输入。"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why a voice reply is the best fit in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why a voice reply is the best fit in the current context",)
     message: str = Field(
         ...,
         description="The spoken content to send back to the user",
diff --git a/app/agent/tools/impl/switch_persona.py b/app/agent/tools/impl/switch_persona.py
index 2300d84d..8181d328 100644
--- a/app/agent/tools/impl/switch_persona.py
+++ b/app/agent/tools/impl/switch_persona.py
@@ -1,7 +1,7 @@
 """切换当前激活人格工具。"""
 
 import json
-from typing import Type
+from typing import Type, Optional
 
 from pydantic import BaseModel, Field
 
@@ -13,10 +13,8 @@ from app.log import logger
 class SwitchPersonaInput(BaseModel):
     """切换人格工具的输入参数模型。"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     persona_id: str = Field(
         ...,
         description=(
diff --git a/app/agent/tools/impl/test_site.py b/app/agent/tools/impl/test_site.py
index 203f5a25..c3e00ecf 100644
--- a/app/agent/tools/impl/test_site.py
+++ b/app/agent/tools/impl/test_site.py
@@ -12,7 +12,7 @@ from app.log import logger
 
 class TestSiteInput(BaseModel):
     """测试站点连通性工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     site_identifier: int = Field(..., description="Site ID to test (can be obtained from query_sites tool)")
 
 
diff --git a/app/agent/tools/impl/transfer_file.py b/app/agent/tools/impl/transfer_file.py
index cc5ddd2f..57d917a9 100644
--- a/app/agent/tools/impl/transfer_file.py
+++ b/app/agent/tools/impl/transfer_file.py
@@ -13,10 +13,8 @@ from app.schemas import FileItem, MediaType
 class TransferFileInput(BaseModel):
     """整理文件或目录工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     file_path: str = Field(
         ...,
         description="Path to the file or directory to transfer (e.g., '/path/to/file.mkv' or '/path/to/directory')",
diff --git a/app/agent/tools/impl/uninstall_plugin.py b/app/agent/tools/impl/uninstall_plugin.py
index 1b64a0be..4978b1c8 100644
--- a/app/agent/tools/impl/uninstall_plugin.py
+++ b/app/agent/tools/impl/uninstall_plugin.py
@@ -17,10 +17,8 @@ from app.log import logger
 class UninstallPluginInput(BaseModel):
     """卸载插件工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     plugin_id: str = Field(
         ...,
         description="Exact plugin ID to uninstall. Use query_installed_plugins first to find the correct plugin_id.",
diff --git a/app/agent/tools/impl/update_custom_filter_rule.py b/app/agent/tools/impl/update_custom_filter_rule.py
index 9d126486..7f204901 100644
--- a/app/agent/tools/impl/update_custom_filter_rule.py
+++ b/app/agent/tools/impl/update_custom_filter_rule.py
@@ -22,10 +22,8 @@ from app.schemas.types import SystemConfigKey
 class UpdateCustomFilterRuleInput(BaseModel):
     """更新自定义过滤规则工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     current_rule_id: str = Field(
         ..., description="Existing custom rule ID to update."
     )
diff --git a/app/agent/tools/impl/update_custom_identifiers.py b/app/agent/tools/impl/update_custom_identifiers.py
index cf4c0892..4d1ba840 100644
--- a/app/agent/tools/impl/update_custom_identifiers.py
+++ b/app/agent/tools/impl/update_custom_identifiers.py
@@ -14,10 +14,8 @@ from app.schemas.types import SystemConfigKey
 class UpdateCustomIdentifiersInput(BaseModel):
     """更新自定义识别词工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     identifiers: List[str] = Field(
         ...,
         description=(
diff --git a/app/agent/tools/impl/update_persona_definition.py b/app/agent/tools/impl/update_persona_definition.py
index 678c76fe..81d9e56b 100644
--- a/app/agent/tools/impl/update_persona_definition.py
+++ b/app/agent/tools/impl/update_persona_definition.py
@@ -13,10 +13,8 @@ from app.log import logger
 class UpdatePersonaDefinitionInput(BaseModel):
     """更新人格定义工具的输入参数模型。"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     persona_id: str = Field(
         ...,
         description=(
diff --git a/app/agent/tools/impl/update_plugin_config.py b/app/agent/tools/impl/update_plugin_config.py
index fd0185d9..85804107 100644
--- a/app/agent/tools/impl/update_plugin_config.py
+++ b/app/agent/tools/impl/update_plugin_config.py
@@ -14,10 +14,8 @@ from app.log import logger
 class UpdatePluginConfigInput(BaseModel):
     """修改插件配置工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     plugin_id: str = Field(
         ...,
         description="The plugin ID to update. Use query_plugin_config first to inspect the current config.",
diff --git a/app/agent/tools/impl/update_rule_group.py b/app/agent/tools/impl/update_rule_group.py
index dcf19ef2..0ddc5402 100644
--- a/app/agent/tools/impl/update_rule_group.py
+++ b/app/agent/tools/impl/update_rule_group.py
@@ -24,10 +24,8 @@ from app.schemas.types import SystemConfigKey
 class UpdateRuleGroupInput(BaseModel):
     """更新过滤规则组工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     current_name: str = Field(..., description="Existing rule group name to update.")
     new_name: Optional[str] = Field(
         None,
diff --git a/app/agent/tools/impl/update_site.py b/app/agent/tools/impl/update_site.py
index d29355e2..42e800bb 100644
--- a/app/agent/tools/impl/update_site.py
+++ b/app/agent/tools/impl/update_site.py
@@ -17,10 +17,8 @@ from app.utils.string import StringUtils
 class UpdateSiteInput(BaseModel):
     """更新站点工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     site_id: int = Field(
         ...,
         description="The ID of the site to update (can be obtained from query_sites tool)",
diff --git a/app/agent/tools/impl/update_site_cookie.py b/app/agent/tools/impl/update_site_cookie.py
index aa73f028..631f4ae3 100644
--- a/app/agent/tools/impl/update_site_cookie.py
+++ b/app/agent/tools/impl/update_site_cookie.py
@@ -13,10 +13,8 @@ from app.log import logger
 class UpdateSiteCookieInput(BaseModel):
     """更新站点Cookie和UA工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     site_identifier: int = Field(
         ...,
         description="Site ID to update Cookie and User-Agent for (can be obtained from query_sites tool)",
diff --git a/app/agent/tools/impl/update_subscribe.py b/app/agent/tools/impl/update_subscribe.py
index 11411292..e3964b4f 100644
--- a/app/agent/tools/impl/update_subscribe.py
+++ b/app/agent/tools/impl/update_subscribe.py
@@ -16,10 +16,8 @@ from app.schemas.types import EventType
 class UpdateSubscribeInput(BaseModel):
     """更新订阅工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     subscribe_id: int = Field(
         ...,
         description="The ID of the subscription to update (can be obtained from query_subscribes tool)",
diff --git a/app/agent/tools/impl/update_system_settings.py b/app/agent/tools/impl/update_system_settings.py
index ef34f388..cd7ae3d6 100644
--- a/app/agent/tools/impl/update_system_settings.py
+++ b/app/agent/tools/impl/update_system_settings.py
@@ -25,10 +25,8 @@ SettingValue = Optional[Union[list, dict, bool, int, float, str]]
 class UpdateSystemSettingsInput(BaseModel):
     """更新系统设置工具的输入参数模型。"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     setting_key: str = Field(
         ...,
         description=(