@atelierai/uco 1.0.7 → 1.0.8

package/vendor/plugin/com.atelierai.unity.copilot/Editor/Scripts/API/Resource/ToolGroups.cs

@@ -1,153 +1,153 @@
-/*
- * Design inspired by MCP for Unity (CoplayDev/unity-mcp), Copyright (c) Coplay Inc., MIT License.
- */
-
-/*
-┌──────────────────────────────────────────────────────────────────┐
-│  Author: Ivan Murzak (https://github.com/IvanMurzak)             │
-│  Repository: GitHub (https://github.com/IvanMurzak/Unity-MCP)    │
-│  Copyright (c) 2025 Ivan Murzak                                  │
-│  Licensed under the Apache License, Version 2.0.                 │
-│  See the LICENSE file in the project root for more information.  │
-└──────────────────────────────────────────────────────────────────┘
-*/
-
-#nullable enable
-using System.Text;
-using com.AtelierAI.Uco.Framework;
-using com.AtelierAI.Uco.Framework.Common;
-using com.AtelierAI.Uco.Framework.Common.Model;
-using com.IvanMurzak.ReflectorNet.Utils;
-using com.AtelierAI.Unity.Copilot.Editor.Utils;
-
-namespace com.AtelierAI.Unity.Copilot.Editor.API
-{
-    using Consts = com.AtelierAI.Uco.Framework.Common.Consts;
-
-    /// <summary>
-    /// Read-only resource that exposes the current tool-group registry
-    /// snapshot at <c>editor://tool-groups</c>. The payload is identical in
-    /// shape to <c>tools-list-groups</c> but delivered through the MCP
-    /// resource channel, which lets clients subscribe / cache it cheaply
-    /// without paying for a tool invocation.
-    /// </summary>
-    [UcoResourceType]
-    public partial class Resource_ToolGroups
-    {
-        public const string ToolGroupsResourceUri = "editor://tool-groups";
-
-        [UcoResource
-        (
-            Name = "Tool Groups",
-            Route = ToolGroupsResourceUri,
-            MimeType = Consts.MimeType.TextJson,
-            ListResources = nameof(ListAll),
-            Description = "Snapshot of every [ToolGroupAttribute] group known to the registry — " +
-                "name, enabled state (soft hint), default-enabled flag, description, and tool ids. " +
-                "Pair with 'tools-set-group-enabled' to flip a group at runtime.",
-            Enabled = true
-        )]
-        public ResponseResourceContent[] Get(string uri)
-        {
-            return MainThread.Instance.Run(() =>
-            {
-                var json = SerializeGroups();
-                return ResponseResourceContent.CreateText(
-                    uri: uri,
-                    mimeType: Consts.MimeType.TextJson,
-                    text: json
-                ).MakeArray();
-            });
-        }
-
-        public ResponseListResource[] ListAll() => new[]
-        {
-            new ResponseListResource(
-                uri: ToolGroupsResourceUri,
-                name: "Tool Groups",
-                enabled: true,
-                mimeType: Consts.MimeType.TextJson)
-        };
-
-        // ---------------------------------------------------------------------
-        // Local minimal JSON serializer.
-        //   We avoid pulling in Newtonsoft / System.Text.Json runtime config
-        //   here because the payload schema is tiny and fully under our control.
-        //   Same approach as Resource_MenuItems / Resource_EditorWindows.
-        // ---------------------------------------------------------------------
-        static string SerializeGroups()
-        {
-            var groups = ToolGroupRegistry.AllGroups();
-            var sb = new StringBuilder(groups.Count * 96 + 16);
-            sb.Append('[');
-            for (var i = 0; i < groups.Count; i++)
-            {
-                if (i > 0) sb.Append(',');
-                var name = groups[i];
-                var enabled = ToolGroupRegistry.IsGroupEnabled(name);
-                var effectiveEnabled = ToolGroupRegistry.IsGroupEffectivelyEnabled(name);
-                var defaultEnabled = ToolGroupRegistry.GetDefaultEnabled(name);
-                var description = ToolGroupRegistry.GetDescription(name);
-                var tools = ToolGroupRegistry.ToolsInGroup(name);
-                var aliases = ToolGroupRegistry.AliasesForGroup(name);
-
-                sb.Append('{');
-                sb.Append("\"name\":"); AppendJsonString(sb, name);
-                sb.Append(",\"enabled\":").Append(enabled ? "true" : "false");
-                sb.Append(",\"requestedEnabled\":").Append(enabled ? "true" : "false");
-                sb.Append(",\"effectiveEnabled\":").Append(effectiveEnabled ? "true" : "false");
-                sb.Append(",\"defaultEnabled\":").Append(defaultEnabled ? "true" : "false");
-                sb.Append(",\"description\":"); AppendJsonStringOrNull(sb, description);
-                sb.Append(",\"aliases\":[");
-                for (var a = 0; a < aliases.Count; a++)
-                {
-                    if (a > 0) sb.Append(',');
-                    AppendJsonString(sb, aliases[a]);
-                }
-                sb.Append(']');
-                sb.Append(",\"toolCount\":").Append(tools.Count);
-                sb.Append(",\"tools\":[");
-                for (var t = 0; t < tools.Count; t++)
-                {
-                    if (t > 0) sb.Append(',');
-                    AppendJsonString(sb, tools[t]);
-                }
-                sb.Append(']');
-                sb.Append('}');
-            }
-            sb.Append(']');
-            return sb.ToString();
-        }
-
-        static void AppendJsonStringOrNull(StringBuilder sb, string? value)
-        {
-            if (value == null) { sb.Append("null"); return; }
-            AppendJsonString(sb, value);
-        }
-
-        static void AppendJsonString(StringBuilder sb, string value)
-        {
-            sb.Append('"');
-            foreach (var c in value)
-            {
-                switch (c)
-                {
-                    case '"': sb.Append("\\\""); break;
-                    case '\\': sb.Append("\\\\"); break;
-                    case '\b': sb.Append("\\b"); break;
-                    case '\f': sb.Append("\\f"); break;
-                    case '\n': sb.Append("\\n"); break;
-                    case '\r': sb.Append("\\r"); break;
-                    case '\t': sb.Append("\\t"); break;
-                    default:
-                        if (c < 0x20)
-                            sb.Append("\\u").Append(((int)c).ToString("x4"));
-                        else
-                            sb.Append(c);
-                        break;
-                }
-            }
-            sb.Append('"');
-        }
-    }
-}
+/*
+ * Design inspired by MCP for Unity (CoplayDev/unity-mcp), Copyright (c) Coplay Inc., MIT License.
+ */
+
+/*
+┌──────────────────────────────────────────────────────────────────┐
+│  Author: Ivan Murzak (https://github.com/IvanMurzak)             │
+│  Repository: GitHub (https://github.com/IvanMurzak/Unity-MCP)    │
+│  Copyright (c) 2025 Ivan Murzak                                  │
+│  Licensed under the Apache License, Version 2.0.                 │
+│  See the LICENSE file in the project root for more information.  │
+└──────────────────────────────────────────────────────────────────┘
+*/
+
+#nullable enable
+using System.Text;
+using com.AtelierAI.Uco.Framework;
+using com.AtelierAI.Uco.Framework.Common;
+using com.AtelierAI.Uco.Framework.Common.Model;
+using com.IvanMurzak.ReflectorNet.Utils;
+using com.AtelierAI.Unity.Copilot.Editor.Utils;
+
+namespace com.AtelierAI.Unity.Copilot.Editor.API
+{
+    using Consts = com.AtelierAI.Uco.Framework.Common.Consts;
+
+    /// <summary>
+    /// Read-only resource that exposes the current tool-group registry
+    /// snapshot at <c>editor://tool-groups</c>. The payload is identical in
+    /// shape to <c>tools-list-groups</c> but delivered through the Uco
+    /// resource channel, which lets clients subscribe / cache it cheaply
+    /// without paying for a tool invocation.
+    /// </summary>
+    [UcoResourceType]
+    public partial class Resource_ToolGroups
+    {
+        public const string ToolGroupsResourceUri = "editor://tool-groups";
+
+        [UcoResource
+        (
+            Name = "Tool Groups",
+            Route = ToolGroupsResourceUri,
+            MimeType = Consts.MimeType.TextJson,
+            ListResources = nameof(ListAll),
+            Description = "Snapshot of every [ToolGroupAttribute] group known to the registry — " +
+                "name, enabled state (soft hint), default-enabled flag, description, and tool ids. " +
+                "Pair with 'tools-set-group-enabled' to flip a group at runtime.",
+            Enabled = true
+        )]
+        public ResponseResourceContent[] Get(string uri)
+        {
+            return MainThread.Instance.Run(() =>
+            {
+                var json = SerializeGroups();
+                return ResponseResourceContent.CreateText(
+                    uri: uri,
+                    mimeType: Consts.MimeType.TextJson,
+                    text: json
+                ).MakeArray();
+            });
+        }
+
+        public ResponseListResource[] ListAll() => new[]
+        {
+            new ResponseListResource(
+                uri: ToolGroupsResourceUri,
+                name: "Tool Groups",
+                enabled: true,
+                mimeType: Consts.MimeType.TextJson)
+        };
+
+        // ---------------------------------------------------------------------
+        // Local minimal JSON serializer.
+        //   We avoid pulling in Newtonsoft / System.Text.Json runtime config
+        //   here because the payload schema is tiny and fully under our control.
+        //   Same approach as Resource_MenuItems / Resource_EditorWindows.
+        // ---------------------------------------------------------------------
+        static string SerializeGroups()
+        {
+            var groups = ToolGroupRegistry.AllGroups();
+            var sb = new StringBuilder(groups.Count * 96 + 16);
+            sb.Append('[');
+            for (var i = 0; i < groups.Count; i++)
+            {
+                if (i > 0) sb.Append(',');
+                var name = groups[i];
+                var enabled = ToolGroupRegistry.IsGroupEnabled(name);
+                var effectiveEnabled = ToolGroupRegistry.IsGroupEffectivelyEnabled(name);
+                var defaultEnabled = ToolGroupRegistry.GetDefaultEnabled(name);
+                var description = ToolGroupRegistry.GetDescription(name);
+                var tools = ToolGroupRegistry.ToolsInGroup(name);
+                var aliases = ToolGroupRegistry.AliasesForGroup(name);
+
+                sb.Append('{');
+                sb.Append("\"name\":"); AppendJsonString(sb, name);
+                sb.Append(",\"enabled\":").Append(enabled ? "true" : "false");
+                sb.Append(",\"requestedEnabled\":").Append(enabled ? "true" : "false");
+                sb.Append(",\"effectiveEnabled\":").Append(effectiveEnabled ? "true" : "false");
+                sb.Append(",\"defaultEnabled\":").Append(defaultEnabled ? "true" : "false");
+                sb.Append(",\"description\":"); AppendJsonStringOrNull(sb, description);
+                sb.Append(",\"aliases\":[");
+                for (var a = 0; a < aliases.Count; a++)
+                {
+                    if (a > 0) sb.Append(',');
+                    AppendJsonString(sb, aliases[a]);
+                }
+                sb.Append(']');
+                sb.Append(",\"toolCount\":").Append(tools.Count);
+                sb.Append(",\"tools\":[");
+                for (var t = 0; t < tools.Count; t++)
+                {
+                    if (t > 0) sb.Append(',');
+                    AppendJsonString(sb, tools[t]);
+                }
+                sb.Append(']');
+                sb.Append('}');
+            }
+            sb.Append(']');
+            return sb.ToString();
+        }
+
+        static void AppendJsonStringOrNull(StringBuilder sb, string? value)
+        {
+            if (value == null) { sb.Append("null"); return; }
+            AppendJsonString(sb, value);
+        }
+
+        static void AppendJsonString(StringBuilder sb, string value)
+        {
+            sb.Append('"');
+            foreach (var c in value)
+            {
+                switch (c)
+                {
+                    case '"': sb.Append("\\\""); break;
+                    case '\\': sb.Append("\\\\"); break;
+                    case '\b': sb.Append("\\b"); break;
+                    case '\f': sb.Append("\\f"); break;
+                    case '\n': sb.Append("\\n"); break;
+                    case '\r': sb.Append("\\r"); break;
+                    case '\t': sb.Append("\\t"); break;
+                    default:
+                        if (c < 0x20)
+                            sb.Append("\\u").Append(((int)c).ToString("x4"));
+                        else
+                            sb.Append(c);
+                        break;
+                }
+            }
+            sb.Append('"');
+        }
+    }
+}

package/vendor/plugin/com.atelierai.unity.copilot/Editor/Scripts/API/SystemTool/Skills.Create.SkillBody.cs

@@ -1,155 +1,155 @@
-/*
-┌──────────────────────────────────────────────────────────────────┐
-│  Author: Ivan Murzak (https://github.com/IvanMurzak)             │
-│  Repository: GitHub (https://github.com/IvanMurzak/Unity-MCP)    │
-│  Copyright (c) 2025 Ivan Murzak                                  │
-│  Licensed under the Apache License, Version 2.0.                 │
-│  See the LICENSE file in the project root for more information.  │
-└──────────────────────────────────────────────────────────────────┘
-*/
-
-namespace com.AtelierAI.Unity.Copilot.Editor.API
-{
-    public partial class Tool_Skills
-    {
-        internal const string SkillsCreateSkillBody = @"## Full sample
-
-```csharp
-#nullable enable
-using System;
-using System.ComponentModel;
-using com.AtelierAI.Uco.Framework;
-using com.IvanMurzak.ReflectorNet.Utils;
-using com.AtelierAI.Unity.Copilot.Editor.Utils;
-using AIGD;
-using UnityEditor;
-using UnityEngine;
-
-namespace com.AtelierAI.Unity.Copilot.Editor.API
-{
-    [UcoToolType]
-    public partial class Tool_Sample
-    {
-        [UcoTool(""sample-get"", Title = ""Sample / Get"")]
-        [Description(""Finds a GameObject and returns its ref data."")]
-        public GameObjectRef Get
-        (
-            [Description(""Name of the GameObject to find."")]
-            string name
-        )
-        {
-            return MainThread.Instance.Run(() =>
-            {
-                var go = GameObject.Find(name)
-                    ?? throw new ArgumentException($""GameObject '{name}' not found."", nameof(name));
-
-                return new GameObjectRef(go);
-            });
-        }
-
-        [UcoTool(""sample-rename"", Title = ""Sample / Rename"")]
-        [Description(""Renames a GameObject."")]
-        public void Rename
-        (
-            [Description(""Current name of the GameObject."")]
-            string name,
-            [Description(""New name to assign."")]
-            string newName
-        )
-        {
-            MainThread.Instance.Run(() =>
-            {
-                var go = GameObject.Find(name)
-                    ?? throw new ArgumentException($""GameObject '{name}' not found."", nameof(name));
-
-                go.name = newName;
-                EditorUtility.SetDirty(go);
-                AssetDatabase.Refresh(ImportAssetOptions.ForceSynchronousImport);
-                EditorUtils.RepaintAllEditorWindows();
-            });
-        }
-    }
-}
-```
-
-## Suggestions
-
-### Refresh UI after visual changes
-If the skill modifies anything visually in the Unity Editor (GameObjects, components, materials, etc.), call these two lines at the end of the tool method to apply changes to the UI immediately:
-```csharp
-AssetDatabase.Refresh(ImportAssetOptions.ForceSynchronousImport);
-EditorUtils.RepaintAllEditorWindows();
-```
-
-### Refresh AssetDatabase after asset or script changes
-If the skill creates, modifies, or deletes any asset file or .cs script on disk outside of Unity API, call this inside a `MainThread.Instance.Run()` block to ensure Unity picks up the changes:
-```csharp
-MainThread.Instance.Run(() =>
-{
-    AssetDatabase.Refresh(ImportAssetOptions.ForceSynchronousImport);
-});
-```
-
-### Use processing mechanic for long-running or domain-reload operations
-Some operations take time to complete and may trigger a Unity domain reload (e.g. writing a .cs script, switching play mode, running tests, adding a package). In these cases the tool must NOT block and wait — instead it must:
-1. Accept a `[RequestID] string? requestId` parameter.
-2. Return `ResponseCallTool.Processing(""..."").SetRequestID(requestId)` immediately.
-3. Schedule the actual work asynchronously via `MainThread.Instance.RunAsync(async () => { await Task.Yield(); ... })`.
-4. When the operation finishes, send the final result by calling:
-```csharp
-_ = UnityCopilotPluginEditor.NotifyToolRequestCompleted(new RequestToolCompletedData
-{
-    RequestId = requestId,
-    Result = ResponseCallTool.Success(""Operation completed."").SetRequestID(requestId)
-});
-```
-If the operation may survive a domain reload (e.g. a .cs file was saved and Unity will recompile), use `ScriptUtils.SchedulePostCompilationNotification(requestId, filePath, operationType)` instead of calling `NotifyToolRequestCompleted` directly — it persists the pending notification to `SessionState` and sends it automatically after the domain reload completes. For package install/removal or other non-compilation domain reloads use `PackageUtils.SchedulePostDomainReloadNotification(requestId, label, action, expectedResult)` the same way.
-
-### Return structured data with a typed response
-Prefer returning a structured data model over a plain string so the AI can parse individual fields. Data models for MCP tools MUST be declared as TOP-LEVEL types in the `AIGD` namespace - never nested inside the tool class. Place each data model in its own `.cs` file (one type per file) and use `ResponseCallValueTool<T>` as the return type. The flat `AIGD` namespace keeps the auto-generated JSON Schema `$defs` keys short and intuitive for AI agents.
-```csharp
-// Tool file (Tool/MyTool.cs) - references the data model from AIGD:
-using AIGD;
-
-namespace com.AtelierAI.Unity.Copilot.Editor.API
-{
-    [UcoToolType]
-    public partial class Tool_Sample
-    {
-        public ResponseCallValueTool<MyResult> MyTool(...)
-        {
-            return ResponseCallValueTool<MyResult>.Success(new MyResult
-            {
-                Name = go.name,
-                InstanceID = go.GetInstanceID()
-            }).SetRequestID(requestId);
-        }
-    }
-}
-
-// Data model (Tool/Data/MyResult.cs) - top-level, in AIGD namespace, NOT nested:
-namespace AIGD
-{
-    public class MyResult
-    {
-        [Description(""Name of the GameObject."")]
-        public string? Name { get; set; }
-
-        [Description(""Unity instance ID of the GameObject."")]
-        public int InstanceID { get; set; }
-    }
-}
-```
-For simpler cases that do not need async/processing, you may return the model directly (without `ResponseCallValueTool<T>`) and Unity-MCP will wrap it automatically. The data model itself MUST still live as a top-level type in the `AIGD` namespace.
-
-### Validate inputs early and throw clearly
-Always validate required parameters at the top of the method before any Unity API calls. Throw `ArgumentException` or `InvalidOperationException` with descriptive messages so the AI knows exactly what went wrong and can self-correct:
-```csharp
-if (string.IsNullOrEmpty(name))
-    throw new ArgumentException(""Name cannot be null or empty."", nameof(name));
-```
-
-### Always use MainThread for Unity API calls
-All Unity API calls (including `GameObject.Find`, `AssetDatabase`, `EditorUtility`, etc.) MUST run on the main thread. Wrap them in `MainThread.Instance.Run(() => { ... })` for synchronous operations, or `MainThread.Instance.RunAsync(async () => { ... })` when you need to await inside.";
-    }
-}
+/*
+┌──────────────────────────────────────────────────────────────────┐
+│  Author: Ivan Murzak (https://github.com/IvanMurzak)             │
+│  Repository: GitHub (https://github.com/IvanMurzak/Unity-MCP)    │
+│  Copyright (c) 2025 Ivan Murzak                                  │
+│  Licensed under the Apache License, Version 2.0.                 │
+│  See the LICENSE file in the project root for more information.  │
+└──────────────────────────────────────────────────────────────────┘
+*/
+
+namespace com.AtelierAI.Unity.Copilot.Editor.API
+{
+    public partial class Tool_Skills
+    {
+        internal const string SkillsCreateSkillBody = @"## Full sample
+
+```csharp
+#nullable enable
+using System;
+using System.ComponentModel;
+using com.AtelierAI.Uco.Framework;
+using com.IvanMurzak.ReflectorNet.Utils;
+using com.AtelierAI.Unity.Copilot.Editor.Utils;
+using AIGD;
+using UnityEditor;
+using UnityEngine;
+
+namespace com.AtelierAI.Unity.Copilot.Editor.API
+{
+    [UcoToolType]
+    public partial class Tool_Sample
+    {
+        [UcoTool(""sample-get"", Title = ""Sample / Get"")]
+        [Description(""Finds a GameObject and returns its ref data."")]
+        public GameObjectRef Get
+        (
+            [Description(""Name of the GameObject to find."")]
+            string name
+        )
+        {
+            return MainThread.Instance.Run(() =>
+            {
+                var go = GameObject.Find(name)
+                    ?? throw new ArgumentException($""GameObject '{name}' not found."", nameof(name));
+
+                return new GameObjectRef(go);
+            });
+        }
+
+        [UcoTool(""sample-rename"", Title = ""Sample / Rename"")]
+        [Description(""Renames a GameObject."")]
+        public void Rename
+        (
+            [Description(""Current name of the GameObject."")]
+            string name,
+            [Description(""New name to assign."")]
+            string newName
+        )
+        {
+            MainThread.Instance.Run(() =>
+            {
+                var go = GameObject.Find(name)
+                    ?? throw new ArgumentException($""GameObject '{name}' not found."", nameof(name));
+
+                go.name = newName;
+                EditorUtility.SetDirty(go);
+                AssetDatabase.Refresh(ImportAssetOptions.ForceSynchronousImport);
+                EditorUtils.RepaintAllEditorWindows();
+            });
+        }
+    }
+}
+```
+
+## Suggestions
+
+### Refresh UI after visual changes
+If the skill modifies anything visually in the Unity Editor (GameObjects, components, materials, etc.), call these two lines at the end of the tool method to apply changes to the UI immediately:
+```csharp
+AssetDatabase.Refresh(ImportAssetOptions.ForceSynchronousImport);
+EditorUtils.RepaintAllEditorWindows();
+```
+
+### Refresh AssetDatabase after asset or script changes
+If the skill creates, modifies, or deletes any asset file or .cs script on disk outside of Unity API, call this inside a `MainThread.Instance.Run()` block to ensure Unity picks up the changes:
+```csharp
+MainThread.Instance.Run(() =>
+{
+    AssetDatabase.Refresh(ImportAssetOptions.ForceSynchronousImport);
+});
+```
+
+### Use processing mechanic for long-running or domain-reload operations
+Some operations take time to complete and may trigger a Unity domain reload (e.g. writing a .cs script, switching play mode, running tests, adding a package). In these cases the tool must NOT block and wait — instead it must:
+1. Accept a `[RequestID] string? requestId` parameter.
+2. Return `ResponseCallTool.Processing(""..."").SetRequestID(requestId)` immediately.
+3. Schedule the actual work asynchronously via `MainThread.Instance.RunAsync(async () => { await Task.Yield(); ... })`.
+4. When the operation finishes, send the final result by calling:
+```csharp
+_ = UnityCopilotPluginEditor.NotifyToolRequestCompleted(new RequestToolCompletedData
+{
+    RequestId = requestId,
+    Result = ResponseCallTool.Success(""Operation completed."").SetRequestID(requestId)
+});
+```
+If the operation may survive a domain reload (e.g. a .cs file was saved and Unity will recompile), use `ScriptUtils.SchedulePostCompilationNotification(requestId, filePath, operationType)` instead of calling `NotifyToolRequestCompleted` directly — it persists the pending notification to `SessionState` and sends it automatically after the domain reload completes. For package install/removal or other non-compilation domain reloads use `PackageUtils.SchedulePostDomainReloadNotification(requestId, label, action, expectedResult)` the same way.
+
+### Return structured data with a typed response
+Prefer returning a structured data model over a plain string so the AI can parse individual fields. Data models for Uco tools MUST be declared as TOP-LEVEL types in the `AIGD` namespace - never nested inside the tool class. Place each data model in its own `.cs` file (one type per file) and use `ResponseCallValueTool<T>` as the return type. The flat `AIGD` namespace keeps the auto-generated JSON Schema `$defs` keys short and intuitive for AI agents.
+```csharp
+// Tool file (Tool/MyTool.cs) - references the data model from AIGD:
+using AIGD;
+
+namespace com.AtelierAI.Unity.Copilot.Editor.API
+{
+    [UcoToolType]
+    public partial class Tool_Sample
+    {
+        public ResponseCallValueTool<MyResult> MyTool(...)
+        {
+            return ResponseCallValueTool<MyResult>.Success(new MyResult
+            {
+                Name = go.name,
+                InstanceID = go.GetInstanceID()
+            }).SetRequestID(requestId);
+        }
+    }
+}
+
+// Data model (Tool/Data/MyResult.cs) - top-level, in AIGD namespace, NOT nested:
+namespace AIGD
+{
+    public class MyResult
+    {
+        [Description(""Name of the GameObject."")]
+        public string? Name { get; set; }
+
+        [Description(""Unity instance ID of the GameObject."")]
+        public int InstanceID { get; set; }
+    }
+}
+```
+For simpler cases that do not need async/processing, you may return the model directly (without `ResponseCallValueTool<T>`) and Unity-Uco will wrap it automatically. The data model itself MUST still live as a top-level type in the `AIGD` namespace.
+
+### Validate inputs early and throw clearly
+Always validate required parameters at the top of the method before any Unity API calls. Throw `ArgumentException` or `InvalidOperationException` with descriptive messages so the AI knows exactly what went wrong and can self-correct:
+```csharp
+if (string.IsNullOrEmpty(name))
+    throw new ArgumentException(""Name cannot be null or empty."", nameof(name));
+```
+
+### Always use MainThread for Unity API calls
+All Unity API calls (including `GameObject.Find`, `AssetDatabase`, `EditorUtility`, etc.) MUST run on the main thread. Wrap them in `MainThread.Instance.Run(() => { ... })` for synchronous operations, or `MainThread.Instance.RunAsync(async () => { ... })` when you need to await inside.";
+    }
+}