Which integrations are available for this server?

Provides tools to control the Unity Editor through a C# bridge, including bridge selection/binding, play-mode and scene operations, compilation checks, console logs, screenshots and evidence collection, assertions, UI/input simulation, camera/world observation, Lua evaluation, and script reload workflows.

How do I use UnityMCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@UnityMCP enter play mode and show me any console errors" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

UnityMCP

by LANLightning

Overview Schema Source Related Servers Discussions Admin

Python

Local

UnityMCP：让 AI 通过 MCP 控制 Unity Editor

UnityMCP 由 Python MCP 服务和 Unity Editor C# Bridge 包组成。AI 根据工具定义选择操作，Python 校验参数并发出桥接命令，Unity 在编辑器主线程执行，再把状态、日志、截图或断言结果交还给 AI。

**公开脱敏适配模板：**文档、示例和源码中的 PROJECT_* / <PROJECT_*> 均为通用代称，不对应任何真实项目。高级功能的项目接口必须由使用者在自己的私有环境中接入；公开版不包含真实绑定关系。本地实际运行版本与公开模板分离。

**兼容性先读：**编辑器连接、场景、播放模式、日志、截图等能力使用 Unity API；UI、Lua、登录、实体、相机和特效等高级能力包含 项目 UI / Lua 运行时适配接口，不是任意 Unity 项目安装后都能使用。反射消除了编译时依赖，但没有消除运行时依赖。

当前源码状态

项目	当前值 / 说明
Python 包	`unity-mcp-py`，元数据版本 `0.10.0`
Unity UPM 包	`com.local.unitymcp-bridge`，元数据版本 `0.8.0`
桥接协议	`1.10.0`，以桥包内 `protocol.schema.json` 为准
默认工具数	41，由实际 FastMCP 注册列表核实
可选工具	`profile_performance`，开启后共 42 个
Python	3.11+；此次测试环境为 Windows / Python 3.14.3
MCP Python SDK	`mcp>=1.0.0,<2`；使用 v1 FastMCP API，不能直接升级到 v2
Unity	包声明最低 2022.3；具体项目仍需 EditMode 与实机验证
版本性质	公开脱敏模板；项目绑定需自行适配，不能直接覆盖私有运行版本

此次整理保留当前多实例绑定、认证、恢复功能，并整合此前性能分支的两个改动：握手响应超时设为 5 秒；重复截图默认省略相同帧的图像数据。没有把旧分支整个覆盖到新工作区。

**不要直接使用旧 dist/ 中同名压缩包。**修改 Python 或 C# 后必须重新构建两端；协议相同也不意味着旧包已包含最新实现。具体测试与发布记录见 PUBLICATION_REPORT.md。

Related MCP server: Agent Bridge for Unity

目录导航

快速安装

1. 安装 Python 服务

下载仓库源码后进入根目录，创建专用虚拟环境，不建议把开发依赖装入全局 Python：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

macOS/Linux 使用 .venv/bin/python。Unix 用户必须先完成下文的认证目录权限配置，再启动 Bridge。

2. 安装 Unity Bridge

在 Unity Package Manager 中选择 Add package from disk...，打开本仓库的：

unity-bridge/com.local.unitymcp-bridge/package.json

或先执行 python scripts/pack_unity_bridge.py，再用 Add package from tarball... 导入新生成的 tgz。桥包依赖 Newtonsoft JSON、Editor Coroutines、Input System；版本以 package.json 为准。

需要打开真实 Unity 项目并等待脚本编译完成。ensure_ready 不会替你启动 Unity。

3. 配置 MCP 客户端

<MCP_ROOT> 表示本工具源码根目录，<PROJECT_ROOT> 表示使用者自己的 Unity 工程，<UNITY_EDITOR_PATH> 表示编辑器可执行文件。占位符必须替换后才能执行。

以下是通用 MCP stdio JSON 配置示意，路径替换为本机实际路径。不同客户端的配置文件位置不同。

{
  "mcpServers": {
    "unity-mcp-py": {
      "command": "<MCP_ROOT>/.venv/Scripts/python.exe",
      "args": ["-m", "unity_mcp_py.server"],
      "env": {
        "UNITY_MCP_PROJECT_PATH": "<PROJECT_ROOT>",
        "UNITY_MCP_BRIDGE_HOST": "127.0.0.1",
        "UNITY_MCP_BRIDGE_PORT": "17873",
        "UNITY_MCP_CLIENT_ID": "mygame-editor-agent"
      }
    }
  }
}

Codex 的等价项目配置采用 TOML：

[mcp_servers.unity-mcp-py]
command = '<MCP_ROOT>/.venv/Scripts/python.exe'
args = ['-m', 'unity_mcp_py.server']

[mcp_servers.unity-mcp-py.env]
UNITY_MCP_PROJECT_PATH = '<PROJECT_ROOT>'
UNITY_MCP_BRIDGE_HOST = '127.0.0.1'
UNITY_MCP_BRIDGE_PORT = '17873'
UNITY_MCP_CLIENT_ID = 'mygame-editor-agent'

一个稳定且独立的 UNITY_MCP_CLIENT_ID 对应一个逻辑客户端；多个客户端不要复用相同身份。未配置时会回退到会话变量或 PID，PID 改变后不能保证自动恢复原绑定。启动后先让 AI 调 select_bridge(scan=true)、核对项目，再绑定目标，而不是盲目接管第一个端口。

4. 多 Unity 实例与端口

Bridge 优先监听本机 127.0.0.1:17873。
未显式指定端口且端口占用时，Unity listener 可回退至 17874..17883。
Python 默认扫描覆盖 17873..17882；17883 需要明确指定，不要把扫描范围与回退范围混为一谈。
优先使用 bind_bridge 持久绑定；只想切换当前连接时使用 select_bridge。
使用 expected_bridge_id 核对身份，不仅核对端口；不应自动设置 force_takeover=true 抢占其他工作会话。
Python 当前只接受字面量 loopback IP，不接受 DNS 主机名或公网地址；旧文档中的远程开关不适用。

AI 控制的完整链路

用户自然语言
  ↓
外部模型 + MCP 客户端（选择工具、生成结构化参数）
  ↓ MCP / stdio
Python FastMCP：参数 schema → telemetry → 可选 JSONL recorder
  ↓ tools/*.py → bridge_call / BridgeSession
线程转发 + 异步锁串行化 + 身份握手 / HMAC
  ↓ TCP，换行分隔的自定义 JSON request/response
UnityMCPServer：接收请求 → 主线程队列
  ↓ EditorApplication.update
UnityMCPCommands.Dispatch：命令处理器 / 跨帧协程
  ↓
Unity Editor API、反射调用、项目 Lua VM
  ↓
结构化结果 / 日志 / PNG / 断言 → 模型决定下一步

**Bridge 中没有大模型，也不会自己理解自然语言。**控制来自模型选择的工具调用，执行来自可审查的 Python/C# 实现。MCP 协议与 Unity TCP 桥接协议是两层不同协议；不要把后者称为完整 MCP JSON-RPC 服务。

实现入口：

src/unity_mcp_py/server.py：工具注册、服务端指导语、记录/遥测中间件。
src/unity_mcp_py/tools/：每个工具的参数处理及业务编排。
src/unity_mcp_py/bridge/session.py：连接、串行调用、切换及取消清理。
src/unity_mcp_py/_vendor/bridge_client.py：连接认证、握手、请求 ID、响应匹配、通知缓冲及超时。
unity-bridge/com.local.unitymcp-bridge/Editor/UnityMCPServer.cs：本机 TCP listener、认证和主线程调度。
同目录 UnityMCPCommands.cs：命令分派及编辑器/Lua 操作。
同目录 UnityMCPUIInspector.cs、UnityMCPWorldObserver.cs：项目 UI 和世界状态适配。

Unity 主线程每帧使用有限请求数量/时间预算；长时间等待通过协程跨帧完成。Python 异步并不代表 Unity 可以在任意后台线程安全执行 API。

重要工具如何实现

以下 Python 入口均为 src/unity_mcp_py/tools/<工具名>.py。表中的命令由 UnityMCPCommands.cs 分派，除非标注为 Python 本地操作。参数完整 schema 以客户端 tools/list 为准；客户端显示的 mcp__...__ 前缀不是服务器原始工具名。

A. 连接、身份与恢复（4 个）

工具	AI 如何控制 / 实现	使用边界
`ensure_ready`	`BridgeSession.connect()` 完成认证和 Handshake，调用 `GetPlayState`；可选进入 PlayMode	`engine_binary_path` 当前不启动程序；项目路径参数不等于严格的目标身份验证。重复连接返回的握手信息可能是缓存状态。
`select_bridge`	管理通道查询各端口状态，不占用业务槽；准备候选连接，握手成功后切换活动 session	指定端口、预期 bridge ID；失败不能误把另一项目当成目标。
`bind_bridge`	在选择逻辑之外持久化 client→bridge 绑定；文件锁、revision/CAS、失败补偿控制并发	`auto` 遇多实例返回候选，需选择；`restore` 依赖稳定客户端身份；`unbind` 解除当前绑定。
`bridge_admin`	`run_bridge_admin` 分派 `pair/status/owners/diagnose/clear/repair`；使用带认证的控制协议	`clear` 区分 binding/accepted/listener；破坏性动作核对实例与连接代次，不杀进程。不是公网远程管理工具。

B. 编辑器、场景与编译（8 个）

工具	AI 如何控制 / 实现	使用边界
`enter_playmode`	写操作调用 `EnterPlaymode`，设置编辑器播放状态	不证明游戏初始化、资源加载或登录完成，需继续观察。
`exit_playmode`	调用 `ExitPlaymode` 返回编辑模式	会停止运行态，应先保存需要的证据。
`open_scene`	Python 校验场景路径，发送 `OpenScene`，C# 使用 `EditorSceneManager`	MCP 参数是 `scene_path`；不能假设桥接协议额外模式均被 MCP 暴露。操作会改变当前场景。
`query_scene`	`GetSceneState` 枚举场景根对象/组件概要，并附带播放状态、日志位置	不是完整深度对象图，也不是游戏业务实体列表。
`run_method`	`RunEditMethod` 查找已加载程序集的类型，通过反射调用 public static 方法，收集返回值和日志	不是 C# 编译器；有危险类型/命名限制，可用 Unity 进程环境变量 `UNITY_MCP_RUN_METHOD_ALLOW` 收窄类型前缀，但不是沙箱。
`assert_no_compile_errors`	查询编译状态，发现编译错误时阻止当前检查通过	编译通过不等于运行逻辑正确。
`get_console_logs`	`TailEditorLog` 读取内存日志窗口，Python 按游标、级别、正则和数量过滤	日志缓冲有上限；不能证明未保留的历史没有错误。
`clear_console`	查询最新日志位置并推进 Python recorder 的虚拟日志游标，返回 previous_cursor/new_cursor	不删除 Unity Console 日志，不产生写操作 token；它是逻辑游标重置，不是编辑器清屏。

C. 截图、证据和断言（5 个）

`capture_screenshot`

查询验证会话；根据 session.code_dirty 决定是否需要人工批准截图。
调用 Unity CaptureScreenshot，等待帧处理后取得 PNG。
Python 输出 full（Base64 图像）、metadata（摘要/大小）、file_ref（本地 PNG 路径）。
默认 skip_if_unchanged=true：仅当 full 模式与该 Python 进程上次实际交付的 full 帧相同时才省略图片，返回 unchanged。metadata/file_ref 不更新该交付记录；file_ref 每次返回有效文件路径。已交付并不保证客户端真的展示或模型已经查看；最终验收应设 skip_if_unchanged=false 并实际查看图片。
file_ref 需要客户端另行读取本地图片；后续截图会清理之前跟踪的缓存文件，需留档时自行复制。

代码重载会置 dirty 标记，下一次截图可等待用户点击“继续”。这不是始终无人干预的截图服务。遇到 screenshot_available=false 或空图片不能当作已完成视觉验证。图片摘要当前按 Base64 文本计算，不能直接当作 PNG 文件原始字节哈希。

`observe_evidence`

顺序取得日志增量、场景根对象、播放状态和可选截图，再消费指定 write_op_token。默认不截图，默认精简日志和场景字段；verbose=true 可保留更完整信息。该工具提供证据，不替模型理解画面。可选截图失败可能表现为缺少图像，因此必须检查实际输出。

`verify_assertions`

Python 服务端执行显式断言并返回 passed/failures/results，避免模型逐条猜测：

expect_no_errors：保留的日志窗口中无错误。
log_matches：匹配或排除某正则。
play_state：播放状态符合预期。
node_exists/node_visible：匹配指定 UI 节点。
lua_expr：执行表达式并比较字符串化结果，必须注明 goal。

只证明所写断言，不证明画面正确。lua_expr 走真实 Lua 执行，并非强制只读沙箱。有效完成的断言检查会重新补充 Lua runway；断言失败时应看原因，而不是自动宣称验证成功。

`list_pending_writes`

读取 Python WriteOpGuard 中尚未消费的操作标记，帮助 AI 找出缺失的观察步骤。标记是进程内状态，不随重启永久保存。

`escalate_via_click`

同一目标验证反复失败时，执行调用方提供的 undo_lua，再用指定 UI 入口 simulate_click，可选重新执行断言。用于避免“内部函数把面板打开了，但绕过业务数据初始化”的假成功。undo 不是自动生成的事务回滚；点击也仍然是项目模拟接口。

D. Lua、热重载与开发登录（4 个）

工具	实现路径	前提和风险
`lua_eval`	`LuaEval` → `DefaultLuaDoString()` → 反射获得 `<PROJECT_LUA_VM>` → xLua `DoString()`	需要项目 VM 与 PlayMode；script 长度受限、goal 必填。runway 要求定期观察现实，但不是权限隔离；客户端超时不能保证终止 Unity 主线程死循环。
`lua_reload_module`	校验模块列表后调用 `<PROJECT_RELOAD_MODULE>`	不是所有 Lua 框架通用重载；检查 payload 中的 `ok` 与 traceback。传输成功不代表脚本成功；成功路径标记代码变更。
`csharp_reload_scripts`	`CsharpReloadScripts` → `CompilationPipeline.RequestScriptCompilation`；force 路径处理播放模式切换	域重载可能影响连接和运行状态，不承诺任意状态无损热替换。之后重新检查编译并观察。
`auto_login`	向 `<PROJECT_LOGIN_SERVICE>` 提交测试登录参数，轮询登录 token 是否存在	项目特定开发登录入口，不是通用账号密码表单。绕过 SDK/UI 的部分逻辑；被服务器接受不代表角色创建或进场完成。仅对授权测试环境使用。

auto_login 的默认参数来自 UNITY_MCP_LOGIN_USERNAME、UNITY_MCP_LOGIN_SERVER_ID、UNITY_MCP_LOGIN_SCENE_ID。不要把真实账号写进仓库。Lua runway 的配置为 UNITY_MCP_LUA_RUNWAY、UNITY_MCP_LUA_SOFT_LIMIT、UNITY_MCP_LUA_RUNAWAY_MAX；这是工作流约束，不是恶意脚本隔离。

E. UI、本地化与输入（6 个）

工具	AI 调用后真实执行	不代表什么
`list_ui_nodes`	`UnityMCPUIInspector.ListNodes()` 遍历项目 UI layer 下的 PROJECT_UI 节点，提取 instanceId、panelUid、name/path、文字、textId、可见性、交互属性和屏幕矩形	不是通用 UGUI/UI Toolkit 检查器；节点数量上限会截断结果。
`resolve_localization`	根据 ID 和语言反射调用项目 `PROJECT_LOCALIZATION_LOOKUP(int, PROJECT_LANGUAGE)`	不是自动翻译，也不会替你生成缺失的词条。
`open_panel`	`PROJECT_RUNTIME.global.ui:open(uid, info)` 后用跨帧轮询检查是否打开/可见	内部开面板不一定走真实用户入口，不能证明业务数据链正确；info 仅支持平面基本类型。
`simulate_click`	用 panel UID + refKey/path 找 PROJECT_UI 节点；raycast 模式调 `PROJECT_CLICK_WITH_HIT_TEST(false)`，force 模式调 `PROJECT_CLICK_DIRECT(false)`	不是操作系统鼠标注入；force 绕过命中检查。必须检查 `clicked/nodeFound`，不是看见 token 就算点中。
`simulate_key`	`PROJECT_RUNTIME.global.PROJECT_INPUT_SERVICE:PROJECT_TRIGGER_ACTION` 依次触发 Performed 和 Canceled	不是物理键盘/手柄输入；可能绕过焦点等输入 gate，仅覆盖真实 InputActionAsset，虚拟热键可能不触发。
`set_input_text`	找到输入节点，设置 text、激活输入框，再调用 PROJECT_COMMIT_TEXT	不是逐键输入，不验证 IME、每键事件或硬件输入路径。

路径基准不同：list_ui_nodes.path 相对于 UI layer root，包含 panel root 名称；simulate_click / set_input_text.path 相对于指定 panel root。调用前需转换路径，不能原样照抄。ref_key 来自项目 PROJECT_NODE_REFERENCE 配置，不能用节点 name 或 instanceId 代替。

这些工具适合让 AI 复现应用层交互路径。涉及硬件手柄、输入法、焦点或系统级鼠标行为时，需要用户或真正设备级 E2E 测试补充。

F. 世界状态、相机与特效（7 个）

工具	实现	AI 应如何解读
`observe_camera`	`UnityMCPWorldObserver` 查询项目 camera manager，合并反射字段，可计算目标投影	观察项目相机状态，不是任意 Camera 的全量管理工具。
`list_entities`	构造 Lua 查询 `PROJECT_RUNTIME.global.PROJECT_ENTITY_SERVICE`，过滤 actor/class/template 并裁剪数量	返回逻辑实体目录，不等于 Hierarchy GameObject 列表。
`observe_entity`	按 entity/actor/template 定位，采集位置、HP、生命/战斗/动画等状态	读取已有实体，不负责生成或修改它。
`list_effects`	反射项目 effect manager 列出特效生成器/实例	是当前时刻快照，瞬态特效可能已结束。
`observe_effect`	Lua 查询实例状态/时长，结合子 ParticleSystem 粒子计数	未看到不等于从未播放，应必要时改用时间窗口。
`observe_window`	跨帧重复计算 Lua 表达式，返回采样值、everTrue、首次/末次命中等	可捕捉短暂状态，但采样有间隔；语法限制不是完全纯函数或安全证明。
`operate_camera`	白名单 action 映射 `PROJECT_RUNTIME.game.camera` 方法，比较 before/after	`applied` 依赖无错误且可观测变化；`settle_ms` 当前保留但未实现延迟等待，不承诺动画已稳定。

G. 人机协作（3 个）

start_verification_session：在 Unity 显示验证提示，监听人类接管输入，配置暂停/中止和截图 gate。提示窗不进入 Game View 截图。显式启动默认 gate 与截图工具按 dirty 自动调整是两条不同路径。
end_verification_session：结束指定 session，清理验证状态。应传对应 session ID，避免误结束后来者。
human_collab_gate：第一次保存截图/日志基线，返回待用户操作状态与 opaque ID；第二次接收真实用户的 Done/Skipped/Failed，再比较证据。基线约一小时过期。AI 不能自行伪造用户已完成的结论。

H. 录制和回放（4 个）

record_start 开启工具调用 JSONL 记录；record_stop 停止并返回摘要；list_sessions 列出已有记录；replay 从注册表查找同名工具重新调用，并比较结果。

录制不是视频。回放不是只读浏览。replay 默认 dry_run=false，可能再次进入播放、点击、改场景或执行代码；先设 dry_run=true 检查计划，再选择 skip_tools 和 stop_on_error。录制参数/结果没有完整敏感字段脱敏，不能直接公开。

I. 可选性能工具（1 个，默认关闭）

在 Python MCP 进程启动前设置 UNITY_MCP_ENABLE_PROFILER=1，重新启动后注册 profile_performance：

ProfilerCapabilities 确认可用性；不可分析时返回原因，不编造指标。
按 scenarios、cpu/memory/both、sample_frames 构造矩阵。
Unity 用 ProfilerRecorder / 相关采样命令跨帧收集指标，可临时改变质量、目标帧率和分辨率，结束时尝试恢复。
第一次成功采样建立 Python 内存 baseline，后续按场景 label 比较并报告回归。
baseline 可跨 Bridge 断线保留，但不跨 Python 进程重启；reset=true 清空。

它不是自动性能修复器，也不自动证明根因；强退等情况不保证配置恢复。不要拿不同项目或不同工作负载的数据作无条件比较。

验证闭环与调用示例

写操作标记的真实含义

_write_op_helper.write_op() 先取日志游标，执行命令，成功返回后登记 write_op_token、requires_observation 和 line_number_before。AI 再把 token 传给 observe_evidence 关联后续观察。

**这不是强制安全事务。**未消费 token 不会统一拦截所有后续操作，payload 里的业务结果也可能失败。服务端 SERVER_INSTRUCTIONS 的最终截图规则是模型行为指导，不是不可绕过的“完成证明”。

示例流程（工具调用示意，不是 Python 导入调用）

select_bridge(scan=true)
bind_bridge(port=17873, expected_bridge_id="从扫描结果取得的真实 ID")
ensure_ready(project_path="<PROJECT_ROOT>")
assert_no_compile_errors()
enter_playmode()
observe_evidence(consume_tokens=["上一调用返回的 token"])

# 仅在对应项目 UI 适配存在时：
list_ui_nodes(panel_uid=实际面板编号)
simulate_click(panel_uid=实际面板编号, ref_key="真实节点引用", mode="raycast")
observe_evidence(consume_tokens=["点击返回的 token"])
verify_assertions(assertions=[{"type":"expect_no_errors"}])
capture_screenshot(mode="full", skip_if_unchanged=false)

工具接受 JSON 类型参数，示例中的中文占位值需换成运行时查到的数据。多屏流程逐步取证；最后实际查看图像。普通没有高级适配的 Unity 项目可先验证编辑器工具，不应直接复制项目 Lua 示例。

项目适配边界

公开文档只使用下列接口角色代称，不列出真实项目代码：

Lua VM：<PROJECT_LUA_VM>，表示项目的 Lua 执行入口。
UI：<PROJECT_UI_SYSTEM>，表示节点枚举、定位、点击和输入适配接口。
本地化：<PROJECT_LOCALIZATION_SERVICE>，表示按词条 ID 和语言查询文本的接口。
运行时观察：<PROJECT_CAMERA_SERVICE>、<PROJECT_ENTITY_SERVICE>、<PROJECT_EFFECT_SERVICE>。
重载：<PROJECT_RELOAD_MODULE>，表示项目自己实现的模块重载能力。
登录：<PROJECT_LOGIN_SERVICE>，表示授权测试环境的登录适配接口。

源码里使用合法示例标识符（不带尖括号）；它们仍然是占位契约，不是任何真实项目的类名或调用链。通用 Unity/MCP API、协议字段和 MCP 工具名保持原名。迁移时应修改 UnityMCPCommands 中 Lua 获取/调用入口、UnityMCPUIInspector 和 UnityMCPWorldObserver 的适配，再为目标项目添加 EditMode/PlayMode 测试。MCP 工具的 schema、错误语义和协议字段应保持同步。未适配时如实返回不可用，而不是返回空结果伪装成功。

安全与数据边界

仅供可信本机开发环境。只监听 loopback 不意味着同一 OS 用户下的恶意进程不可访问。
当前认证采用 nonce-bound HMAC，核对 bridge/client/instance/generation；不是 TLS，也不是远程托管服务设计。
lua_eval、run_method、业务重放拥有实际执行/修改能力。白名单、runway、token 不能替代 OS 隔离与备份。
账号、认证文件、绑定文件、真实环境变量、截图、JSONL、Console 日志都可能含私人数据；不要提交到版本库或直接发给无关模型服务。
变更工具可能触发游戏后端请求。使用专门测试账号和环境，避免生产交易、付费资源或不可逆业务操作。
请求超时不等于 Unity 中的操作已经撤销；先查状态再决定是否重试。

macOS/Linux 必须完成的权限缓解

当前 C# Bridge 自动创建认证文件时尚未自动收紧 Unix 权限。在默认 umask/可遍历 home 下存在其他本机用户读取 token 的条件性风险。以下是部署要求，不是声称代码已经修复。

关闭 Unity/MCP，确认目录/文件属于当前用户、无额外 ACL 授权且不是共享/同步目录，然后执行：

umask 077
test ! -L "$HOME/.unity-mcp" || exit 1
mkdir -p "$HOME/.unity-mcp"
chmod 700 "$HOME/.unity-mcp"
if test -e "$HOME/.unity-mcp/auth-token"; then
  test ! -L "$HOME/.unity-mcp/auth-token" || exit 1
  chmod 600 "$HOME/.unity-mcp/auth-token"
fi

保持目录 0700，并在首次创建后确认 token 为 0600。仅改 umask 不能修复旧文件，也不能保证 Unity Hub 启动的进程继承设置。已泄露的 token 需由用户另行安排轮换；此操作不会打印或覆盖现有 token。Windows 应确保用户配置目录 ACL 私有。

开发测试和打包

python -m pip install -e ".[dev]"
python -m pip install pytest-cov pip-audit
python -m pytest -q --cov=unity_mcp_py --cov-report=term-missing
python -m pip_audit
python scripts/build_release.py

构建脚本默认先运行测试，再构建 Python wheel、Unity tgz 与部署 bundle。输出写入 dist/，不提交旧二进制。不要在测试失败时用 --skip-tests 对外声称已验证。

测试分层：Python 单元/MockBridge 集成测试；桥包 Tests.EditMode；真实 Unity 项目的手工/自动 PlayMode 验证。Python 测试通过不等于 C# 已在所有 Unity/OS 组合编译，更不等于项目 UI/登录流程已实测。本次没有执行真实游戏交互。

常见故障

现象	检查方法
找不到 bridge	Unity 是否打开、包是否导入成功、编译是否干净、实际监听端口、禁用标记
端口忙 / 多实例	`select_bridge(scan=true)` 和 `bridge_admin(action="status", port=...)`，核对 ID 后再绑定
握手超时	新实现握手响应 5 秒超时；Unity 主线程编译/阻塞时稍后重试，不直接抢占或杀进程
协议不一致	同步更新 Python 与 Unity 包；检查 schema 版本，不只看 wheel/tgz 文件名
Lua/UI 类型找不到	项目尚未接入 UI / Lua 占位契约，不能靠换端口解决
点击无效	检查 nodeFound/blocked/ clicked 等实际字段、路径和遮挡；force 与真实用户操作并不等价
截图等待	代码 dirty 后可能需要用户点击继续；不要擅自代替人工确认
截图没有像素	检查 mode、unchanged、screenshot_available；最终视觉验证强制 full 且不跳过
绑定重启丢失	设置稳定独立 client ID，核对绑定存储和预期 bridge ID

许可证

本仓库附 MIT LICENSE。该许可证不自动授予第三方游戏项目、素材、SDK 或内部业务接口的使用权；迁移适配前应确认相关授权。

Available Tools

41 tools

assert_no_compile_errorsD

Name	Required	Description	Default
No parameters

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

auto_loginD

Name	Required	Description	Default
`scene_id`	No
`username`	No
`server_id`	No
`timeout_s`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

bind_bridgeA

将 Unity bridge 绑定到当前 MCP 会话。

这个工具会记住当前会话的绑定关系，重启 MCP server 后可以自动恢复。适合需要长期固定连接到特定 Unity 实例的场景。

Args: port: 要绑定的端口号。如果不指定，显示当前绑定状态。 auto: 设为 True 时自动检测并绑定。如果只有一个实例则自动绑定，如果有多个实例则返回列表让用户选择。 unbind: 设为 True 时解除当前会话的绑定。 restore: 设为 True 时从持久化文件恢复之前的绑定。

Returns: 操作结果，包含绑定状态、会话 ID、端口信息等。

Examples: # 自动检测并绑定（如果只有一个实例） bind_bridge(auto=True)

# 绑定到指定端口
bind_bridge(port=17874)

# 查看当前绑定状态
bind_bridge()

# 解除绑定
bind_bridge(unbind=True)

# 恢复之前的绑定
bind_bridge(restore=True)

Name	Required	Description	Default
`auto`	No
`port`	No
`unbind`	No
`restore`	No
`wait_seconds`	No
`force_takeover`	No
`expected_bridge_id`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations present, the description carries the full burden and largely does so: it discloses session-scoped memory, persistence/restore behavior, multi-instance auto-detection semantics, and unbind as a distinct mode. It stops short of stating failure modes, whether binding evicts another session, or what the returned status contains in any detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and persistence guarantee are front-loaded, and the Args section is compact. The Examples block is somewhat redundant with the Args prose but does usefully disambiguate the mutually exclusive modes, so it earns most of its space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Correctly omits return-value details because an output schema exists, and covers the primary mode-switching parameters plus the persistence contract. The remaining gaps (three undocumented booleans) are real but narrow relative to a tool whose whole surface is 'bind, inspect, or unbind'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 7 parameters, so the description must compensate. It clearly explains four of them (port, auto, unbind, restore), but wait_seconds, force_takeover, and expected_bridge_id are never mentioned, and force_takeover in particular is a consequential behavioral knob left undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first line states a specific verb and resource: binding a Unity bridge to the current MCP session, with the added scope that the binding is persisted across server restarts. It does not, however, distinguish itself from close siblings like select_bridge or bridge_admin, which an agent must still infer from their names alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear context for when the tool is the right choice ('适合需要长期固定连接到特定 Unity 实例的场景'), and the per-argument notes explain the auto-detect tradeoff when multiple instances exist. It never names an alternative tool or an explicit when-not-to-use condition, so routing against select_bridge/bridge_admin remains guesswork.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

bridge_adminB

Pair, inspect, diagnose, clear, or safely repair a Unity bridge.

Actions: pair, status, owners, diagnose, clear, repair. Clear also requires side=binding|accepted|listener. Destructive operations retain bridge/client/generation identity checks and never kill a process.

Name	Required	Default
`host`	No	127.0.0.1
`port`	No
`side`	No
`force`	No
`action`	Yes
`bridge_id`	No
`client_id`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it does surrender useful safety context: destructive operations keep bridge/client/generation identity checks and 'never kill a process.' However, it never says what clear actually removes, whether repair mutates state or requires force, or what any action returns — leaving the mutation profile of six actions largely opaque.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Compact and front-loaded: the verb list comes first, followed by the action enumeration and then the constraint on clear. No filler sentences, though the compression is part of why several parameters go unexplained.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value explanation is fairly excused, but for a multiplexed six-action tool with seven parameters at 0% coverage and no annotations, the description is under-specified. It never explains what each action does or which parameters each action needs, so an agent must guess before invoking.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 7 parameters, so the description must compensate and mostly does not. It documents only the side enum requirement for clear; host, port, force, bridge_id, and client_id remain undefined in both schema and prose, including which actions consume which identity parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb set and a clear resource: 'Pair, inspect, diagnose, clear, or safely repair a Unity bridge,' and then enumerates the six action values. An agent can see the surface area at a glance, though it does not distinguish this from siblings like select_bridge or bind_bridge.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The action list implies when each mode applies, and the 'Clear also requires side=binding|accepted|listener' line is a real constraint. But there is no explicit guidance on when to choose this tool over the sibling bridge tools (select_bridge, bind_bridge, ensure_ready), nor any when-not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

capture_screenshotA

capture_screenshot tool. Read-only. No token.

PERF 2026-05-25: mode parameter controls payload shape.

full (default, unchanged behavior): base64 PNG in response.
metadata: sha256 + sizeBytes only — saves the ~2MB base64 from the LLM context. Caller can re-request with full if needed.
file_ref: persist PNG to UNITY_MCP_SCREENSHOT_DIR keyed by sha256 and return the file path. For local agents that need the bytes without paying for them in token context.

Wall-clock cost is dominated by Unity-side CaptureScreenshot (~300ms, two-tick delay + PNG encode); mode does not change that. The win is on the LLM payload side.

FINAL-VERIFICATION ROLE: the final verification of any user-facing change MUST include a screenshot from this tool showing the expected result — read-state probes (lua_eval / logs / assertions) do not by themselves prove the change works. If the change spans multiple screens, capture one per meaningful step. When unsure the game is on the relevant screen, ask the user before capturing.

Name	Required	Default
`mode`	No	full
`width`	No
`height`	No
`supersize`	No
`skip_if_unchanged`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full load and does well: it declares read-only, no token requirement, ~300ms Unity-side cost dominated by CaptureScreenshot, that mode does not change cost, that file_ref persists to UNITY_MCP_SCREENSHOT_DIR, and that the ~2MB base64 payload is the real cost driver. It stops short of saying whether the capture alters game state or camera framing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The mode breakdown is front-loaded and earns its place, but the 'PERF 2026-05-25' dated changelog paragraph and the cost/token narrative repeat themselves and are noise for an agent deciding how to call the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return shapes need not be spelled out, and the verification-role and mode guidance cover the decision-critical parts. However, for a 5-parameter tool with zero schema coverage and no annotations, leaving four parameters undocumented makes the definition incomplete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must define every parameter. It explains mode thoroughly (three values including the default), which is genuinely additive since the schema has no enum, but width, height, supersize, and skip_if_unchanged are never mentioned anywhere, leaving four of five parameters semantically undefined.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The tool name plus the mode table make clear this captures a PNG screenshot and controls how the image is returned. It does not, however, distinguish itself from the sibling observe_camera or from read-state probes beyond asserting the screenshot is required for final verification, so the boundary with observe_camera is left implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use: final verification of any user-facing change MUST include a screenshot from this tool, one capture per meaningful screen. It also gives mode-selection guidance (re-request with full if metadata was enough, file_ref for local agents) and an explicit escalation path ('ask the user before capturing' when unsure of the screen).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

clear_consoleD

Name	Required	Description	Default
No parameters

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

csharp_reload_scriptsD

Name	Required	Description	Default
`force`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

end_verification_sessionD

Name	Required	Description	Default
`session_id`	Yes

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ensure_readyD

Name	Required	Description	Default
`project_path`	No
`engine_binary_path`	No
`auto_enter_playmode`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

enter_playmodeD

Name	Required	Description	Default
No parameters

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

escalate_via_clickA

escalate_via_click tool. Write op. Command-line fallback to real input.

When lua_eval command-line operations (e.g. PROJECT_RUNTIME.global.ui:open(uid)) don't carry real data — surfaced by repeated verify_assertions failures under the same goal (verdict.escalation.should_escalate) — the agent should NOT keep forcing the lua path. This tool atomically:

Restores the lua op by running the caller-supplied undo_lua (the inverse operation, e.g. PROJECT_RUNTIME.global.ui:close(uid)).
Re-enters through REAL simulated input by clicking the true entry-point button (delegates to simulate_click).
On a landed click, clears the escalation gate for goal and soft-grounds the lua runway (entering the real environment is a reality-touching act).

If the undo fails, the click is NOT attempted (never stack a click on an un-restored dirty state) and the gate is left intact. If the click misses, the gate is left intact so the agent can retry with a different locator / mode.

PlayMode-only (lua VM + simulate both require Play Mode).

USE WHEN: verify_assertions returned escalation.should_escalate=true — your lua command-line operations are not reaching the real environment. Pass undo_lua to restore your prior lua op and the real entry button's panel_uid + ref_key/path; this tool restores then clicks for real, so the next screenshot/assertion faces the true environment.

DO NOT ask the user before the real click. The fallback (undo -> real click -> reverify) is deterministic and runs entirely inside this tool. Pass assertions (same shape as verify_assertions) describing the real-environment success state; after a landed click the tool re-verifies and returns needs_user:

needs_user=false -> the real path worked (or click missed -> retry locator); proceed WITHOUT asking the user.
needs_user=true -> the click landed but the real environment STILL doesn't match the goal — THIS is the only time you ask the user.

Omitting assertions keeps the legacy behavior (no reverify; you decide).

Name	Required	Default
`goal`	Yes
`mode`	No	raycast
`path`	No
`ref_key`	No
`undo_lua`	Yes
`panel_uid`	Yes
`assertions`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full load and does so: it discloses atomicity, the PlayMode-only constraint, failure semantics (undo fails means no click and the gate stays intact; a missed click leaves the gate intact for retry), the delegation to simulate_click, and the needs_user return contract. This is exactly the behavioral context an agent needs before invoking a destructive-adjacent write.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The numbered three-step atomic sequence and the needs_user bullet list are well structured and front-load the trigger, but the opening line 'escalate_via_click tool. Write op.' is redundant filler and the overall text is longer than strictly necessary. Most sentences still earn their place, so the density is acceptable rather than wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, yet the description still explains the needs_user outcome explicitly, which is the one return value an agent must act on. Combined with the PlayMode restriction, failure paths, and the undo→click→reverify pipeline, there is nothing material missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate; it explains undo_lua as the caller-supplied inverse operation with an example, panel_uid and ref_key/path as the real entry-point locator, assertions as matching verify_assertions' shape, and goal as the key that gates escalation. It doesn't explain mode's default 'raycast' or the accepted values, leaving one param under-documented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb+resource framing — a command-line fallback that atomically undoes a lua op, re-enters through real simulated input, and re-verifies. It explicitly names where it delegates (simulate_click) and what it replaces (lua_eval command-line ops), so an agent can tell it apart from simulate_click or lua_eval without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is an explicit USE WHEN tied to a concrete trigger (verify_assertions returning escalation.should_escalate=true), a DO NOT instruction about not asking the user first, and a precise condition for when the user should be involved (needs_user=true). Alternatives and the escalation path are named outright.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

exit_playmodeD

Name	Required	Description	Default
No parameters

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_console_logsD

Name	Required	Description	Default
`level`	No
`limit`	No
`pattern`	No
`since_seq`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

human_collab_gateD

Name	Required	Description	Default
`wu_id`	No
`fail_levels`	No
`user_choice`	No
`human_instruction`	Yes

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_effectsD

Name	Required	Description	Default
No parameters

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_entitiesD

Name	Required	Description	Default
`summary`	No
`actor_type`	No
`class_name`	No
`template_id`	No
`max_entities`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_pending_writesD

Name	Required	Description	Default
No parameters

Output Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_sessionsD

Name	Required	Description	Default
`limit`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_ui_nodesD

Name	Required	Description	Default
`layers`	No
`max_nodes`	No
`panel_uid`	No
`include_all`	No
`path_prefix`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lua_evalD

Name	Required	Description	Default
`goal`	Yes
`script`	Yes
`chunk_name`	No
`allow_unbounded`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lua_reload_moduleD

Name	Required	Description	Default
`modules`	Yes
`imp_files`	No
`del_key_models`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

observe_cameraD

Name	Required	Description	Default
`target_pos`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

observe_effectD

Name	Required	Description	Default
`effect_id`	Yes
`generator_id`	Yes

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

observe_entityD

Name	Required	Description	Default
`actor_id`	No
`entity_id`	No
`template_id`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

observe_evidenceD

Name	Required	Description	Default
`verbose`	No
`log_levels`	No
`max_log_lines`	No
`consume_tokens`	No
`screenshot_width`	No
`since_line_number`	No
`include_screenshot`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

observe_windowD

Name	Required	Description	Default
`lua_expr`	Yes
`duration_ms`	No
`interval_ms`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

open_panelD

Name	Required	Description	Default
`uid`	Yes
`info`	No
`verify`	No
`timeout_ms`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

open_sceneD

Name	Required	Description	Default
`scene_path`	Yes

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

operate_cameraD

Name	Required	Description	Default
`flag`	No
`value`	No
`action`	Yes
`actor_id`	No
`settle_ms`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_sceneD

Name	Required	Description	Default
`scene`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

record_startD

Name	Required	Description	Default
`note`	No
`session_id`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

record_stopD

Name	Required	Description	Default
No parameters

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

replayD

Name	Required	Description	Default
`dry_run`	No
`session_id`	Yes
`skip_tools`	No
`stop_on_error`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolve_localizationD

Name	Required	Description	Default
`ids`	Yes
`language`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_methodD

Name	Required	Description	Default
`args`	No
`type_name`	Yes
`method_name`	Yes

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

select_bridgeB

选择和绑定到特定的 Unity bridge 实例。

当有多个 Unity 编辑器实例运行时使用此工具。每个实例应该配置不同的端口。

Args: port: 要连接的 Unity bridge 端口号。如果不指定，显示当前连接状态。 scan: 设为 True 时扫描并列出所有可用的 bridge 实例（端口 17873-17882）。

Returns: 操作结果，包含连接状态或扫描到的实例列表。

Examples: # 扫描所有可用的 bridge 实例 select_bridge(scan=True)

# 查看当前连接状态
select_bridge()

# 连接到端口 17874 的 Unity 实例
select_bridge(port=17874)

Name	Required	Description	Default
`port`	No
`scan`	No
`client_id`	No
`wait_seconds`	No
`force_takeover`	No
`expected_bridge_id`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

B3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it covers only the benign paths: default shows current status, scan enumerates ports 17873-17882. It is silent on the behaviorally significant parameters it actually accepts — 'force_takeover' (implies seizing a binding from another client), 'wait_seconds' (implies blocking), and 'expected_bridge_id' (implies a safety check) — all undisclosed, so an agent cannot judge side effects or disruption.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then Args/Returns/Examples — a readable structure. But the three examples only restate the already-documented port/scan behavior and consume space that should have gone to the four undocumented parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the Returns section is not strictly needed, yet the four unexplained parameters remain the real gap. For a connection-management tool with no annotations and 0% schema coverage, the description is not complete enough for an agent to call it safely, particularly around force_takeover.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it documents only 'port' and 'scan' out of 6 parameters. The semantics of client_id, wait_seconds, force_takeover, and expected_bridge_id are entirely absent from both schema and description, leaving half the surface unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: selecting and binding to a particular Unity bridge instance, which is distinct from most siblings in the Unity-editor toolset. However it never distinguishes itself from the sibling 'bind_bridge', and the overlap between 'select' and 'bind' leaves ambiguity about which tool owns which operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly gives the triggering condition: use when multiple Unity editor instances are running. The three examples demonstrate scan, status-check, and direct-connect cases, which is concrete when-to-use guidance. It stops short of when-not-to-use or naming a preferred alternative over the sibling bind_bridge.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_input_textA

set_input_text tool. Write op. Sets an PROJECT_UI input field's text and commits it.

Resolves the input node (panel uid + refKey OR path), sets its settable .text, calls ActivateInputField(), then fires the field's PROJECT_COMMIT_TEXT callback (if any) so the panel reacts as if the user typed and committed. Does NOT synthesize per-key device events (unreliable for TMP/UGUI input fields under the new Input System).

PlayMode-only.

FINAL-VERIFICATION ROLE: when the user's repro steps involve typing into a field, set it here during final verification, then capture_screenshot to evidence the result.

Name	Required	Description	Default
`path`	No
`text`	Yes
`ref_key`	No
`panel_uid`	Yes

Output Schema

Name	Required	Description
No output parameters

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and does it well: it discloses node resolution (panel uid + refKey OR path), that it calls ActivateInputField(), fires the PROJECT_COMMIT_TEXT callback, and that it does NOT synthesize per-key device events because that is unreliable under the new Input System. It omits failure behavior when the node is missing and whether text replaces or appends.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads 'Write op' and the core action, then layers resolution and behavior in short paragraphs. The FINAL-VERIFICATION block is useful but slightly verbose relative to the rest.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and the PlayMode-only constraint plus resolution scheme are stated. What remains thin is error behavior for unresolved nodes, minor for a UI helper.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% across 4 parameters, so the description must compensate. It clarifies the key relationship that the node is resolved by panel uid + refKey OR path, which the flat schema cannot express, but it never explains path/ref_key formats or text semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Sets an PROJECT_UI input field's text and commits it') and qualifies it as a write op. It also distinguishes itself from the per-key event path, so an agent can tell it apart from sibling simulate_key.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear conditions: PlayMode-only, and use it during final verification when repro steps involve typing, followed by capture_screenshot. It excludes the per-key alternative implicitly but never names simulate_key explicitly, so no full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

simulate_clickA

simulate_click tool. Write op. Clicks a UI node via PROJECT_UI's own simulate API.

Main path (no real input device, no screen coordinate): resolves the node by panel uid + refKey (panel PROJECT_NODE_REFERENCE key) OR path (transform path under the panel root), then calls:

mode='raycast' (default): PROJECT_CLICKABLE:PROJECT_CLICK_WITH_HIT_TEST(false) — raycasts at the node's screen point and only fires if it's the topmost/visible hit; returns whether it actually clicked (self-validating occlusion check).
mode='force': PROJECT_CLICKABLE:PROJECT_CLICK_DIRECT(false) — fires the handler with no hit-test (use when the node is known-good but raycast fails, e.g. off-screen).

PlayMode-only. Device-pixel clicking (screenXY via InputSystem.QueueStateEvent) is deferred to a later phase.

FINAL-VERIFICATION ROLE: when the user described repro steps, drive the same clicks here during final verification instead of calling internal handlers that bypass the input path; then capture_screenshot to evidence the result.

Name	Required	Default
`mode`	No	raycast
`path`	No
`ref_key`	No
`panel_uid`	Yes

Output Schema

Name	Required	Description
No output parameters

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden and does so well. It discloses that this is a write operation, PlayMode-only, that raycast mode performs an occlusion/hit-test and self-validates whether a click occurred, and that force mode bypasses hit-testing; it also notes device-pixel clicking is deferred.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the operation and main path, then organized by mode and final-verification role. It is dense rather than padded, though some placeholder-style wording and long clauses make it slightly heavier than necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity, lack of annotations, and presence of an output schema, the description provides enough operational context to call the tool correctly. It does not fully clarify whether ref_key or path must be supplied alongside panel_uid, but the core execution model and constraints are covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate, and it explains ref_key as the panel PROJECT_NODE_REFERENCE key, path as a transform path under the panel root, and mode as raycast vs force with behavior differences. The required panel_uid parameter is used but not explicitly defined, which keeps this below a perfect score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it clicks a UI node through PROJECT_UI's own simulate API. It also distinguishes the two execution paths, raycast and force, so an agent can tell exactly what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage conditions: raycast is default, force is for known-good nodes where raycast fails such as off-screen nodes, and it should be used during final verification instead of internal handlers. It does not explicitly compare against nearby siblings like simulate_key or escalate_via_click, leaving some alternative-selection guidance implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

simulate_keyA

simulate_key tool. Write op. Triggers an input ACTION by its action path.

Calls PROJECT_RUNTIME.global.PROJECT_INPUT_SERVICE:PROJECT_TRIGGER_ACTION(actionPath, 'Performed') then 'Canceled' — this routes through the game's InnerHandleInputInfo funnel exactly like real input, but bypasses the focus / inputEnabled gate, so it works even when the Editor Game view isn't focused. Use for "press the key bound to feature X" (e.g. "Hud/OpenMap", "Player/Jump").

IMPORTANT — only REAL InputActionAsset actions can be triggered this way. Virtual PROJECT_HOTKEY_SYSTEM bindings (isVirtual=true, driven by PROJECT_HOTKEY_CALLBACK — most panel hotkeys like "Common/ClosePanelCommon") are NOT in playerInput.actions, so this returns triggered=false with a note. For those, use simulate_click on the bound button, or lua_eval the panel method.

Device-level raw keystrokes (InputSystem.QueueStateEvent on Keyboard) are deferred to a later phase. PlayMode-only.

FINAL-VERIFICATION ROLE: when the user gave repro steps involving key/gamepad presses, replay them here during final verification, then capture_screenshot to evidence the outcome. (Reaches only real InputActionAsset actions — for virtual PROJECT_HOTKEY_SYSTEM hotkeys use simulate_click on the bound button.)

Name	Required	Description	Default
`action_path`	Yes

Output Schema

Name	Required	Description
No output parameters

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does: it declares this is a write op, discloses that it bypasses the focus/inputEnabled gate so it works when the Game view isn't focused, notes that virtual hotkey bindings silently return triggered=false with a note rather than firing, and flags PlayMode-only and deferred raw keystroke support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The critical facts are front-loaded and the structure is logical, but the virtual-hotkey caveat is repeated three times (main body, the IMPORTANT paragraph, and again in FINAL-VERIFICATION ROLE). The final paragraph is largely redundant with earlier content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a mutation-style tool with no annotations and a single opaque parameter, the description covers the mechanism, preconditions, failure mode (triggered=false for virtual actions), and how it fits a verification workflow with capture_screenshot. An output schema exists, so return-value detail is unnecessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single action_path parameter has 0% schema description coverage, so the description must compensate. It does partially: it explains that the path refers to a real InputActionAsset action and gives two example path strings ('Hud/OpenMap', 'Player/Jump'), but never spells out the path format or where valid paths can be discovered.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'Triggers an input ACTION by its action path', and explains the mechanism (PROJECT_TRIGGER_ACTION with 'Performed' then 'Canceled' through InnerHandleInputInfo). It is clearly distinguished from sibling simulate_click, lua_eval, and set_input_text by naming the exact action kinds it handles.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use ('press the key bound to feature X', with concrete paths like 'Hud/OpenMap', 'Player/Jump') and explicit when-not-to-use with named alternatives: virtual PROJECT_HOTKEY_SYSTEM bindings require simulate_click on the bound button or lua_eval of the panel method. It also states the PlayMode-only precondition.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_verification_sessionD

Name	Required	Description	Default
`note`	No
`abort_on_high`	No
`gate_screenshots`	No
`pause_silence_ms`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

verify_assertionsD

Name	Required	Description	Default
`goal`	No
`assertions`	Yes

Output Schema

Name	Required	Description
No output parameters

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

41 tool updatesv0.10.0Oct 26, 2026
- First observedassert_no_compile_errors
- First observedauto_login
- First observedbind_bridge
- First observedbridge_admin
- First observedcapture_screenshot
- First observedclear_console
- First observedcsharp_reload_scripts
- First observedend_verification_session
- First observedensure_ready
- First observedenter_playmode
- First observedescalate_via_click
- First observedexit_playmode
- First observedget_console_logs
- First observedhuman_collab_gate
- First observedlist_effects
- First observedlist_entities
- First observedlist_pending_writes
- First observedlist_sessions
- First observedlist_ui_nodes
- First observedlua_eval
- First observedlua_reload_module
- First observedobserve_camera
- First observedobserve_effect
- First observedobserve_entity
- First observedobserve_evidence
- First observedobserve_window
- First observedopen_panel
- First observedopen_scene
- First observedoperate_camera
- First observedquery_scene
- First observedrecord_start
- First observedrecord_stop
- First observedreplay
- First observedresolve_localization
- First observedrun_method
- First observedselect_bridge
- First observedset_input_text
- First observedsimulate_click
- First observedsimulate_key
- First observedstart_verification_session
- First observedverify_assertions

Deploy Server

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

D1.9/5.0

Scored 2026-10-26 05:35 across 41 tools

Disambiguation2/5

The tool set has several fuzzy boundaries: select_bridge, bind_bridge, and bridge_admin all manage bridge connection/binding state; observe_evidence, verify_assertions, capture_screenshot, and the observe_* tools overlap in evidence gathering; and escalate_via_click wraps simulate_click. Many tools also have empty descriptions, which makes distinguishing intended use harder for an agent.

Naming Consistency4/5

Tool names are consistently snake_case, which is a strong baseline. There are minor deviations in verb style and noun-only names (e.g. human_collab_gate, bridge_admin) alongside verb-led names, but the pattern remains readable.

Tool Count2/5

With 41 tools, the server is well above the typical well-scoped range and includes many niche operations for camera/entity/effect/window observation, recording/replay, verification, and bridge management. These could likely be consolidated into fewer, clearer tools without losing capability.

Completeness4/5

The surface covers a broad Unity automation lifecycle: scene/playmode control, UI inspection and input simulation, screenshots, console logs, Lua/C# execution, assertions, recording/replay, and bridge management. Direct CRUD-style operations for game objects/assets are limited, but lua_eval and run_method provide escape hatches for many missing operations.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Related MCP Connectors

ChiR24-unreal_mcp_serverOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Developer Tools App Automation Software Architecture
2975
https://server.smithery.ai/@ChiR24/unreal_mcp_server/mcp
mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
https://mcp.niftypm.com/mcp
FlowraOAuth
io.github.flowradev
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Agent Orchestration Autonomous Agents
11
https://mcp.flowra.dev/mcp
Unified.to MCP Server B
to.unified.docs
Unified MCP Server is a remote MCP connector for AI agents and vertical AI products that provides access to 22,000+ authorized SaaS tools across 400+ integrations and 24 categories directly inside LLMs (Claude, GPT, Gemini, Cohere). Tools operate only on explicitly authorized customer connections, enabling agents to safely read and write against live third-party systems.
App Automation Agent Orchestration Developer Tools
312
https://mcp-api.unified.to/mcp

Related MCP Servers

MCP For Unity
Developer Tools App Automation Code Execution
yunuscan
F
license
Not graded
quality
D
maintenance
Enables AI clients to interact with and control the Unity Editor through a Python MCP server bridge, allowing natural language-based Unity project manipulation.
Updated a year ago (2025-12-10 22:02 UTC)
-
Agent Bridge for Unity
Developer Tools Autonomous Agents
sebastiankurvers-dev
A
license
Not graded
quality
C
maintenance
Enables AI agents to control the Unity Editor through MCP, allowing scene building, runtime scripting, visual QA, and more.
Updated 8 months ago (2026-03-09 11:31 UTC)
5
Apache 2.0
upilot
Developer Tools Testing & QA Tools App Automation
codingriver
A
license
Not graded
quality
A
maintenance
Unity Editor automation bridge for AI agents and MCP clients, enabling inspection, control, and diagnostics of the Editor.
Updated 9 days ago (2026-10-17 13:02 UTC)
MIT
UnityMCP
Developer Tools Code Execution
isuzu-shiranui
A
license
Not graded
quality
A
maintenance
Enables AI agents to drive the Unity Editor directly over HTTP, including scene and asset editing, diagnostics, play mode control, code execution, input simulation, and builds, with no separate MCP server process.
Updated 18 days ago (2026-10-08 15:28 UTC)
336
MIT