From 85bf8c15bd4033b4217d28f6715595fae9a38b87 Mon Sep 17 00:00:00 2001
From: HivemindOverlord <80588752+HivemindOverlord@users.noreply.github.com>
Date: Fri, 6 Feb 2026 16:03:19 -0600
Subject: [PATCH] fix: improve tool descriptions with explicit cross-references
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update descriptions on manage_gameobject, find_gameobjects, and
manage_components to use explicit "NOT for X — use Y tool" phrasing
and include full resource URIs. This helps LLMs route to the correct
tool instead of guessing based on parameter names.

Each tool now clearly states:
- What it does (positive)
- What it does NOT do and which tool/resource to use instead (negative)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 Server/src/services/tools/find_gameobjects.py  | 8 +++++++-
 Server/src/services/tools/manage_components.py | 8 +++++++-
 Server/src/services/tools/manage_gameobject.py | 8 ++++----
 3 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/Server/src/services/tools/find_gameobjects.py b/Server/src/services/tools/find_gameobjects.py
index 5cbf8eb57..2f98801e6 100644
--- a/Server/src/services/tools/find_gameobjects.py
+++ b/Server/src/services/tools/find_gameobjects.py
@@ -15,7 +15,13 @@
 
 
 @mcp_for_unity_tool(
-    description="Search for GameObjects in the scene. Requires search_term (name, tag, layer name, component type, or path). Returns instance IDs only (paginated). Use mcpforunity://scene/gameobject/{id} resource to get full GameObject data."
+    description=(
+        "Search for GameObjects in the scene by name, tag, layer, component type, or path. "
+        "Returns instance IDs only (paginated). "
+        "Then use mcpforunity://scene/gameobject/{id} resource for full data, "
+        "or mcpforunity://scene/gameobject/{id}/components for component details. "
+        "For CRUD operations (create/modify/delete), use manage_gameobject instead."
+    )
 )
 async def find_gameobjects(
     ctx: Context,
diff --git a/Server/src/services/tools/manage_components.py b/Server/src/services/tools/manage_components.py
index 2c5c0c94d..4f26c75ff 100644
--- a/Server/src/services/tools/manage_components.py
+++ b/Server/src/services/tools/manage_components.py
@@ -14,7 +14,13 @@
 
 
 @mcp_for_unity_tool(
-    description="Manages components on GameObjects (add, remove, set_property). For reading component data, use the mcpforunity://scene/gameobject/{id}/components resource."
+    description=(
+        "Add, remove, or set properties on components attached to GameObjects. "
+        "Actions: add, remove, set_property. Requires target (instance ID or name) and component_type. "
+        "For READING component data, use the mcpforunity://scene/gameobject/{id}/components resource "
+        "or mcpforunity://scene/gameobject/{id}/component/{name} for a single component. "
+        "For creating/deleting GameObjects themselves, use manage_gameobject instead."
+    )
 )
 async def manage_components(
     ctx: Context,
diff --git a/Server/src/services/tools/manage_gameobject.py b/Server/src/services/tools/manage_gameobject.py
index fa0dca647..036b9d004 100644
--- a/Server/src/services/tools/manage_gameobject.py
+++ b/Server/src/services/tools/manage_gameobject.py
@@ -42,9 +42,9 @@ def _normalize_component_properties(value: Any) -> tuple[dict[str, dict[str, Any
     description=(
         "Performs CRUD operations on GameObjects. "
         "Actions: create, modify, delete, duplicate, move_relative. "
-        "To FIND GameObjects, use the find_gameobjects tool instead. "
-        "To manage COMPONENTS (add/remove/set_property), use the manage_components tool instead. "
-        "To READ component data, use the mcpforunity://scene/gameobject/{id}/components resource."
+        "NOT for searching — use the find_gameobjects tool to search by name/tag/layer/component/path. "
+        "NOT for component management — use the manage_components tool (add/remove/set_property) "
+        "or mcpforunity://scene/gameobject/{id}/components resource (read)."
     ),
     annotations=ToolAnnotations(
         title="Manage GameObject",
@@ -121,7 +121,7 @@ async def manage_gameobject(
     if action is None:
         return {
             "success": False,
-            "message": "Missing required parameter 'action'. Valid actions: create, modify, delete, duplicate, move_relative. For finding GameObjects use find_gameobjects tool. For component operations use manage_components tool."
+            "message": "Missing required parameter 'action'. Valid actions: create, modify, delete, duplicate, move_relative. To SEARCH for GameObjects use the find_gameobjects tool. To manage COMPONENTS use the manage_components tool."
         }
 
     # --- Normalize vector parameters with detailed error handling ---