fix: remove vestigial find/component params from manage_gameobject (#693)

* fix: remove vestigial find/component params from manage_gameobject tool

The manage_gameobject tool retained parameters (search_term, find_all,
search_in_children, search_inactive, component_name, page_size, cursor,
max_components, include_properties, includeNonPublicSerialized) from
when it was a monolith tool. These params now belong to the separate
find_gameobjects tool, manage_components tool, and gameobject_components
resource.

Their presence on manage_gameobject caused LLMs to hallucinate
non-existent actions (e.g. action="find", action="get_components"),
leading to ~46 failed tool calls in a single session.

Also tightens search_method Literal to only values relevant for target
resolution (by_id, by_name, by_path) and improves the tool description
to explicitly cross-reference the correct tools and resources.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: update search_method Literal and docstring per review

Expand search_method to include by_tag, by_layer, by_component and
clarify that Unity infers the method when omitted.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

---------

Co-authored-by: HivemindOverlord <[email protected]>
Co-authored-by: Claude Opus 4.6 <[email protected]>

Author: 3 people

Server/src/services/tools/manage_gameobject.py

@@ -1,4 +1,3 @@
-import json
 from typing import Annotated, Any, Literal
 
 from fastmcp import Context
@@ -8,7 +7,7 @@
 from services.tools import get_unity_instance_from_context
 from transport.unity_transport import send_with_unity_instance
 from transport.legacy.unity_connection import async_send_command_with_retry
-from services.tools.utils import coerce_bool, parse_json_payload, coerce_int, normalize_vector3
+from services.tools.utils import coerce_bool, parse_json_payload, normalize_vector3
 from services.tools.preflight import preflight
 
 
@@ -40,7 +39,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. "
+        "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."
+    ),
     annotations=ToolAnnotations(
         title="Manage GameObject",
         destructiveHint=True,
@@ -51,11 +56,14 @@ async def manage_gameobject(
     action: Annotated[Literal["create", "modify", "delete", "duplicate",
                               "move_relative"], "Action to perform on GameObject."] | None = None,
     target: Annotated[str,
-                      "GameObject identifier by name or path for modify/delete/component actions"] | None = None,
-    search_method: Annotated[Literal["by_id", "by_name", "by_path", "by_tag", "by_layer", "by_component"],
-                             "How to find objects. Used with 'find' and some 'target' lookups."] | None = None,
+                      "GameObject identifier by name, path, or instance ID for modify/delete/duplicate actions"] | None = None,
+    search_method: Annotated[
+        Literal["by_id", "by_name", "by_path", "by_tag", "by_layer", "by_component"],
+        "How to resolve 'target'. If omitted, Unity infers: instance ID -> by_id, "
+        "path (contains '/') -> by_path, otherwise by_name."
+    ] | None = None,
     name: Annotated[str,
-                    "GameObject name for 'create' (initial name) and 'modify' (rename) actions ONLY. For 'find' action, use 'search_term' instead."] | None = None,
+                    "GameObject name for 'create' (initial name) and 'modify' (rename) actions."] | None = None,
     tag: Annotated[str,
                    "Tag name - used for both 'create' (initial tag) and 'modify' (change tag)"] | None = None,
     parent: Annotated[str,
@@ -67,7 +75,7 @@ async def manage_gameobject(
     scale: Annotated[list[float] | dict[str, float] | str,
                      "Scale as [x, y, z] array, {x, y, z} object, or JSON string"] | None = None,
     components_to_add: Annotated[list[str],
-                                 "List of component names to add"] | None = None,
+                                 "List of component names to add during 'create' or 'modify'"] | None = None,
     primitive_type: Annotated[str,
                               "Primitive type for 'create' action"] | None = None,
     save_as_prefab: Annotated[bool | str,
@@ -87,30 +95,6 @@ async def manage_gameobject(
                                     `{"MyScript": {"playerHealth": {"find": "Player", "component": "HealthComponent"}}}` assigns Component
                                     Example set nested property:
                                     - Access shared material: `{"MeshRenderer": {"sharedMaterial.color": [1, 0, 0, 1]}}`"""] | None = None,
-    # --- Parameters for 'find' ---
-    search_term: Annotated[str,
-                           "Search term for 'find' action ONLY. Use this (not 'name') when searching for GameObjects."] | None = None,
-    find_all: Annotated[bool | str,
-                        "If True, finds all GameObjects matching the search term (accepts true/false or 'true'/'false')"] | None = None,
-    search_in_children: Annotated[bool | str,
-                                  "If True, searches in children of the GameObject (accepts true/false or 'true'/'false')"] | None = None,
-    search_inactive: Annotated[bool | str,
-                               "If True, searches inactive GameObjects (accepts true/false or 'true'/'false')"] | None = None,
-    # -- Component Management Arguments --
-    component_name: Annotated[str,
-                              "Component name for 'add_component' and 'remove_component' actions"] | None = None,
-    # Controls whether serialization of private [SerializeField] fields is included
-    includeNonPublicSerialized: Annotated[bool | str,
-                                          "Controls whether serialization of private [SerializeField] fields is included (accepts true/false or 'true'/'false')"] | None = None,
-    # --- Paging/safety for get_components ---
-    page_size: Annotated[int | str,
-                         "Page size for get_components paging."] | None = None,
-    cursor: Annotated[int | str,
-                      "Opaque cursor for get_components paging (offset)."] | None = None,
-    max_components: Annotated[int | str,
-                              "Hard cap on returned components per request (safety)."] | None = None,
-    include_properties: Annotated[bool | str,
-                                  "If true, include serialized component properties (bounded)."] | None = None,
     # --- Parameters for 'duplicate' ---
     new_name: Annotated[str,
                         "New name for the duplicated object (default: SourceName_Copy)"] | None = None,
@@ -157,33 +141,15 @@ async def manage_gameobject(
     # --- Normalize boolean parameters ---
     save_as_prefab = coerce_bool(save_as_prefab)
     set_active = coerce_bool(set_active)
-    find_all = coerce_bool(find_all)
-    search_in_children = coerce_bool(search_in_children)
-    search_inactive = coerce_bool(search_inactive)
-    includeNonPublicSerialized = coerce_bool(includeNonPublicSerialized)
-    include_properties = coerce_bool(include_properties)
     world_space = coerce_bool(world_space, default=True)
 
-    # --- Normalize integer parameters ---
-    page_size = coerce_int(page_size, default=None)
-    cursor = coerce_int(cursor, default=None)
-    max_components = coerce_int(max_components, default=None)
-
     # --- Normalize component_properties with detailed error handling ---
     component_properties, comp_props_error = _normalize_component_properties(
         component_properties)
     if comp_props_error:
         return {"success": False, "message": comp_props_error}
 
     try:
-        # Validate parameter usage to prevent silent failures
-        if action in ["create", "modify"]:
-            if search_term is not None:
-                return {
-                    "success": False,
-                    "message": f"For '{action}' action, use 'name' parameter, not 'search_term'."
-                }
-
         # Prepare parameters, removing None values
         params = {
             "action": action,
@@ -204,16 +170,6 @@ async def manage_gameobject(
             "layer": layer,
             "componentsToRemove": components_to_remove,
             "componentProperties": component_properties,
-            "searchTerm": search_term,
-            "findAll": find_all,
-            "searchInChildren": search_in_children,
-            "searchInactive": search_inactive,
-            "componentName": component_name,
-            "includeNonPublicSerialized": includeNonPublicSerialized,
-            "pageSize": page_size,
-            "cursor": cursor,
-            "maxComponents": max_components,
-            "includeProperties": include_properties,
             # Parameters for 'duplicate'
             "new_name": new_name,
             "offset": offset,

Server/tests/integration/test_tool_signatures_paging.py

@@ -19,15 +19,23 @@ def test_manage_scene_signature_includes_paging_params():
     assert "include_transform" in names
 
 
-def test_manage_gameobject_signature_includes_paging_params():
+def test_manage_gameobject_signature_excludes_vestigial_params():
+    """Paging/find/component params were removed — they belong to separate tools."""
     import services.tools.manage_gameobject as mod
 
     sig = inspect.signature(mod.manage_gameobject)
     names = list(sig.parameters.keys())
 
-    assert "page_size" in names
-    assert "cursor" in names
-    assert "max_components" in names
-    assert "include_properties" in names
+    # These params now live on find_gameobjects / manage_components / gameobject_components resource
+    assert "page_size" not in names
+    assert "cursor" not in names
+    assert "max_components" not in names
+    assert "include_properties" not in names
+    assert "search_term" not in names
+    assert "find_all" not in names
+    assert "search_in_children" not in names
+    assert "search_inactive" not in names
+    assert "component_name" not in names
+    assert "includeNonPublicSerialized" not in names