Merge pull request #733 from dsarno/fix/694-rebased

fix: improve tool descriptions with explicit cross-references (rebased #694)

Author: dsarno

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,

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,

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 ---