From 6192b07d4731dd63529fb4e92945d82b016cde05 Mon Sep 17 00:00:00 2001
From: Yufeng He <40085740+universeplayer@users.noreply.github.com>
Date: Tue, 17 Mar 2026 22:10:44 +0800
Subject: [PATCH] Clarify FileUpload/DownloadTool descriptions to fix LLM tool
 selection
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Multiple models (Gemini 3, GPT-5.2, Claude Sonnet, Kimi K2.5) consistently
pick FileDownloadTool when they should pick FileUploadTool. The old
descriptions used "upload/download" which is ambiguous from the LLM's
perspective — it doesn't know which side is "local" vs "remote".

Rewrite descriptions to use explicit directional language:
- Upload: "Transfer FROM host INTO sandbox" + "when user sends a file"
- Download: "Transfer FROM sandbox OUT to host" + "ONLY when user asks
  to retrieve/export"

Also improve parameter descriptions with the same directional clarity.

Fixes #6497
---
 astrbot/core/computer/tools/fs.py | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/astrbot/core/computer/tools/fs.py b/astrbot/core/computer/tools/fs.py
index 31b7f3f513..f2a698f763 100644
--- a/astrbot/core/computer/tools/fs.py
+++ b/astrbot/core/computer/tools/fs.py
@@ -80,14 +80,19 @@
 @dataclass
 class FileUploadTool(FunctionTool):
     name: str = "astrbot_upload_file"
-    description: str = "Upload a local file to the sandbox. The file must exist on the local filesystem."
+    description: str = (
+        "Transfer a file FROM the host machine INTO the sandbox so that sandbox "
+        "code can access it. Use this when the user sends/attaches a file and you "
+        "need to process it inside the sandbox. The local_path must point to an "
+        "existing file on the host filesystem."
+    )
     parameters: dict = field(
         default_factory=lambda: {
             "type": "object",
             "properties": {
                 "local_path": {
                     "type": "string",
-                    "description": "The local file path to upload. This must be an absolute path to an existing file on the local filesystem.",
+                    "description": "Absolute path to the file on the host filesystem that will be copied into the sandbox.",
                 },
                 # "remote_path": {
                 #     "type": "string",
@@ -140,14 +145,18 @@ async def call(
 @dataclass
 class FileDownloadTool(FunctionTool):
     name: str = "astrbot_download_file"
-    description: str = "Download a file from the sandbox. Only call this when user explicitly need you to download a file."
+    description: str = (
+        "Transfer a file FROM the sandbox OUT to the host and optionally send it "
+        "to the user. Use this ONLY when the user asks to retrieve/export a file "
+        "that was created or modified inside the sandbox."
+    )
     parameters: dict = field(
         default_factory=lambda: {
             "type": "object",
             "properties": {
                 "remote_path": {
                     "type": "string",
-                    "description": "The path of the file in the sandbox to download.",
+                    "description": "Path of the file inside the sandbox to copy out to the host.",
                 },
                 "also_send_to_user": {
                     "type": "boolean",