From 85b30d37f77c1c886df0ea9423e7d031d04cd4e9 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 | 10 ++++++++--
 3 files changed, 22 insertions(+), 4 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 ba8c2f973..2590beb8e 100644
--- a/Server/src/services/tools/manage_gameobject.py
+++ b/Server/src/services/tools/manage_gameobject.py
@@ -40,7 +40,13 @@ def _normalize_component_properties(value: Any) -> tuple[dict[str, dict[str, Any
 
 
 @mcp_for_unity_tool(
-    description="Performs CRUD operations on GameObjects. Actions: create, modify, delete, duplicate, move_relative. For finding GameObjects use find_gameobjects tool. For component operations use manage_components tool.",
+    description=(
+        "Performs CRUD operations on GameObjects. "
+        "Actions: create, modify, delete, duplicate, move_relative. "
+        "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",
         destructiveHint=True,
@@ -137,7 +143,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 ---