一个 MCP 服务器，让代理能够构建 DayZ 模组、检查客户端能否编译、运行测试服务器，并获取结构化结论而不是日志。
服务器自己完成这些工作：它直接调用 FileBank、签名工具和诊断可执行文件。项目不需要自己的构建脚本。
服务器对任何特定模组一无所知。所有具体内容都存在于两部分配置文件中：
dayz-mcp.toml — 可移植，提交到模组仓库：要打包哪些模组，健康启动是什么样的。
dayz-mcp.local.toml — 特定于机器，绝不提交：游戏、工具和测试台在哪里。
加载时如果混合了两部分，会被拒绝：这就是仓库不会在别人机器上构建的原因。从 dayz-mcp.example.toml 开始。
模组按名称声明一次：默认源在 <root>/Name，输出为 @Name/addons/Name.pbo。build.sources 可以将模组的源重定向到其他地方（例如，对于 config.cpp 位于仓库根目录本身的模组，使用 "."）。
dayz-mcp.toml键 | 含义 |
| 这个项目叫什么 |
| 每个模组一个条目，按名称；源、pbo 和 |
| 模组源实际所在位置，相对于配置文件（ |
| 绝不能打包的内容。列出它会完全替换默认值；默认值是 |
| 当存在被排除的内容时，打包一个过滤后的副本，而不是拒绝——这是根目录布局模组所需的布局 |
| 所有模型路径解析所依据的目录，相对于此文件。它必须包含模组的前缀文件夹。仅模型工具需要，其他都不需要——参见“资源管线” |
| 打包前运行的 PowerShell 脚本，用于先生成代码的项目 |
| 模组完成加载时打印的行——见下文 |
| 该行携带的 |
| 警告预算；省略该键以禁用检查 |
| 无论其他情况如何，只要出现这些子串就使运行失败 |
| 标记属于你的脚本错误的正则表达式，用于客户端编译检查 |
| 除了内置列表之外，要忽略的额外引擎噪音 |
dayz-mcp.local.toml，绝不提交键 | 含义 |
| 游戏安装；如果缺失则自动发现 |
| DayZ 工具；如果缺失则自动发现 |
| Blender 可执行文件，仅用于 |
| 准备好的测试台。服务器针对它启动，其日志从 |
| 测试台内的服务器配置文件名称（默认 |
|
|
| 模组文件夹名称，在游戏自己的 |
| 要加载的其他任何内容的完整路径，用于不在 |
| 要路由到 |
server_start 在启动开始后写入的日志中出现 expect.ready_line 时完成。这是服务器无法自行推断的唯一一件事，没有它，两件事会改变：无法等待任何内容，因此启动作业会启动服务器，确认它片刻后仍然存活，然后完成并说明这一点；并且 log_verdict 没有行可读取计数器，因此 expect.counters 永远不会匹配。错误、崩溃和警告预算仍然会被判断。没有就绪行的配置文件是受支持的，而不是损坏的——project_open 会在其注释中说明这一点。
Related MCP server: DayZ API MCP Server
工具 | 功能 |
| 读取配置文件，发现游戏和工具，报告缺失项 |
| 当前项目、运行中的服务器、最近的作业 |
| 打包并签名所有声明的模组；返回作业 ID。同一项目已有构建在运行时拒绝第二次构建 |
| 启动测试服务器，就绪后完成。如果配置指定的任务不在 |
| pid、进程是否存活、日志是否在增长（间隔 |
| 停止本会话启动的服务器（孤儿服务器的可选 pid） |
| 读取 — 或有意更改 — 测试台的 |
| 运行诊断客户端并读取其日志 |
| 通过/失败及原因：计数器、禁止字符串、警告预算。 |
| 最后几行，可选过滤；同上述两个来源 |
| 长时间运行作业的状态 |
| 等待作业完成 |
| 从已完成的作业中检索输出 |
| 打包桥接模组，其源码随此服务器（ |
| 运行中的游戏内的桥接是否仍在跳动：报告跳动编号以及是否在 |
| 丢弃卡在邮箱中的命令，并说明丢弃了什么。除非 |
| 等待游戏内的桥接实际认领命令。在启动作业完成后、第一个世界命令之前调用一次 — 见下文"服务器就绪不等于桥接就绪" |
| 来自桥接每秒一次发布的世界的快照：玩家、位置、生命值、双手。无参数时免费；带 |
| 在地面（无生命周期，因此不会在检查中途消失）、玩家手中或玩家背包中创建物品 |
| 将玩家移动到 |
| 设置 |
| 删除附近某一类的对象。需要类名；绝不删除真实玩家 |
| 附近哪些对象，而非多少：每个对象的类、位置、距离和生命值。一页，并且会说明 — 真实总数随列表一起返回 |
| 移动世界时钟。每个保持 -1 的字段保留其当前值，先从引擎读回，因为引擎将日期一次设置为五个数字 |
| 移动阴天、雨、雾、雪或风。轻推而非锁定：引擎之后会继续模拟天气，工具和模组都会说明这一点 |
| 通过引擎的门运行模组自己的动作 — 见下文 |
| 逃生舱口：通过同一传输通道的任意动词，在每个回答中标记为非标准 |
| 启动游戏客户端并将其连接到测试台；返回作业 ID。始终窗口化。当桥接报告 |
| client_status() | pid、窗口几何信息、窗口是否最小化或在前台、背景设置、玩家数量，以及是否连接了虚拟控制器 |
| client_stop() | 停止本会话启动的客户端，并拔出虚拟控制器 |
| client_shot(path) | 将客户端窗口捕获为 PNG，附带 lit_fraction —— 用于区分真实帧与全黑帧的数字。无需焦点 |
| client_move(x, y, seconds) | 用左摇杆移动角色。模拟量，也是唯一能移动角色的通道。无需焦点 |
| client_look(x, y, seconds) | 用右摇杆转动镜头。无需焦点 |
| client_press(button, seconds) | 按下一个手柄按键，来自十四个名称的封闭表。无需焦点 |
| client_chat(text, color) | 在聊天中发送一行——由桥接器在服务端投递，因此无需键盘、无需窗口、无需焦点 |
| client_type(text, submit) | 用真实按键输入到客户端侧输入框。这是此处唯一需要抢占前台的工具，其返回值中也会说明这一点 |
| client_verdict(since) | 根据客户端自身的 .RPT 判断其状态——一个错误与崩溃判定；见下文 |
| ui_menu() | 客户端界面当前在做什么：打开的菜单类、光标、对话框。免费——每 tick 重新发布 |
| ui_tree(root, depth, limit) | 客户端的控件树：路径、类、名称、可见性、屏幕矩形、深度和文本。是一页数据，返回值中也会说明 |
| ui_find(name, class_name, text, root) | 同样的遍历，但在客户端内过滤，因此整棵树无需传输 |
| ui_click(path, expect_name, expect_class, via) | 按下一个控件。via="script" 通过已打开菜单的处理器执行，无需焦点；via="cursor" 将真实鼠标放到其矩形上 |
| ui_text(path, text, expect_name) | 写入编辑框，并从控件中读回该值 |
| mod_lint(mod, strict) | 在不打包或不启动任何东西的情况下检查 Enforce Script。mod_build 会先运行它，并在其拒绝的内容上拒绝 |
| knowledge_build(layer, full, only) | 构建或刷新 API 索引的某一层；返回一个任务 id。only=[path] 只重新读取你指定的文件 |
| knowledge_status() | 每一层包含什么、有多旧，以及是否仍与磁盘上的内容匹配 |
| knowledge_find(name, kind, owner, layer, prefix, limit) | 按名称查找类、方法、常量、枚举或配置类 |
| knowledge_show(name, ..., body) | 完整展示一个声明：签名、成员、继承链，以及源码本身——如果它存在于归档中，则直接从归档中读取 |
| knowledge_overrides(name, owner, layer) | 谁覆写了此类或方法 |
| knowledge_callers(name, kind, owner, layer) | 谁调用此方法或构建此类——每个调用点，连同发起调用的类和方法 |
| asset_export(blend, mod, source, name) | 从 .blend 中导出模型到 build.project_root，无头模式；返回一个任务 id。可选的第一步——见下文 |
| asset_build(mod, source, deploy) | 将 mod 的模型从其 MLOD 源二进制化，检查产出，然后才放入 mod；返回一个任务 id |
| asset_check(mod, model) | 检查 mod 已随附的模型和纹理。不构建任何东西，不需要 DayZ Tools，毫秒级响应 |
| asset_convert(source, output) | 在 .png 和 .paa 之间转换一个纹理，并检查结果 |
签名，以及为什么引擎自身的消息会把你引向错误方向。 在 verifySignatures = 2 下，stand 会以代码 118 和 "缺少 dta.pbo" 拒绝每个客户端——这是一个原版文件名，完全未提及签名。原因通常是密钥环：此工具从 CLIENT 安装目录启动诊断可执行文件，因此引擎读取的是该可执行文件旁边的 keys，而 dayz.bikey——即签署游戏自身 pbo 的密钥——随独立的 DayZServer 安装一起提供。keys 文件夹缺失，或只包含 mod 自身的密钥，会导致服务器无法验证任何内容，包括原版文件。client_start 会拒绝并指出是三种情况中的哪一种；server_start 只发出警告，因为无客户端的无头启动仍然有用。客户端 -mod 行上的未签名 pbo 也会以同样方式被点名——包括本服务器自身的桥接器，它是有意以未签名方式打包的。
引擎对 UI 工具施加的三个限制，均未绕过： 普通 TextWidget 在 enwidgets.c 中有 SetText 而没有 GetText，因此标签的字符串完全无法读取——mod 界面的含义只能留给服务端桥接器来回答，那里的数据才是真实的。脚本级点击只能到达已打开的脚本化菜单，因为 Widget 有 SetHandler 而没有 GetHandler；via="cursor" 用于其他一切情况。此外，客户端必须加载桥接器：一个 pbo 同时携带两半，因此配置文件将其列在 mods.server_only 下会使其远离客户端的 -mod 行——这种情况会按名称被拒绝，而不是返回空树。
job_wait 是用于等待的工具，其 timeout 上限为 600 秒，无论传入多大的值。另外两个工具会休眠：server_status 采样日志两次，间隔 pulse_seconds，上限 10 秒——这个停顿就是它区分慢启动与挂起的方式——bridge_status 采样桥接器的 tick 两次，间隔 window，上限同为 10 秒，原因相同。其他所有工具立即返回；需要数分钟的工作在任务 id 背后进行。
bridge_build 将 bridge/ 从本服务器自身的仓库打包到其旁边的 @DZMCP_Bridge 中。它是服务器的 mod，不是你的：一份副本服务于所有项目，除了任务记录外不会向你的仓库写入任何内容，也不使用任何项目的签名密钥——-serverMod pbo 永远不会交给客户端去验证，因此它以未签名方式构建，其输出文件夹保持无签名和密钥。
构建它并不会加载它。这仍然是你配置文件的决定，因为桥接器是 stand 中的一个额外 pbo，没有它的运行必须仍然可行。要附加它，请在 dayz-mcp.local.toml 中添加两行（bridge_build 的任务摘要也会打印同样的两行）：
[mods]
extra = ["<path printed by bridge_build>/@DZMCP_Bridge"]
server_only = ["@DZMCP_Bridge"]server_only 是将其路由到 -serverMod 而非 -mod 的原因。没有它，stand 也能正常启动，而 bridge_status 会报告桥接器从未写入任何状态——这是事实，但容易被误认为是桥接器损坏。
bridge_status 还会报告命令邮箱。在游戏内部只有 mod 通过认领命令来清空它；在这一侧，bridge_clear 和 server_start 的启动前清理会清空它。因此，在 stand 关闭时或桥接器附加之前发送的命令不会被丢弃，也不会自行过期——它会持续阻塞后续的每次发送，而通过这些工具之外启动的 stand 会拾取它。server_start 在每次启动前都会清空两个传输文件，因此通过此工具启动的服务器永远不会运行来自先前会话的命令；这是卫生习惯，而非了解命令存在的替代品。该状态以 stale_command 返回，而 bridge_clear() 是摆脱它的方法。清空是有意作为独立工具的：丢弃排队的命令是一个决定，而不是状态检查应该在背后替你做的事情。当桥接器看起来还活着时它会拒绝，除非你传入 force=True，无论哪种方式它都会报告它丢弃的命令 id。
bridge_status 能区分什么仅凭 tick 不足以判断桥接器，因为它每次启动都会从 0 重新开始，而状态文件在配置文件目录中持续存在。每个答案都在 heartbeat 中携带通道自身的判定，而这四种是真正不同的事实：
|
| 含义 |
|
| tick 在同一会话内移动——唯一 |
|
| 两次采样之间出现了新世界：存活，未冻结，且发送给旧会话的任何内容都已消失 |
|
| 同一世界被看到两次且未移动——脚本侧问题，因此 |
|
| 无法读取采样（或 |
每个读取过采样的答案还携带 session_id——当前存活世界的 id——而 restarted 答案还携带 previous_session_id，因此调用方可以说出哪个世界消失了。
no_server、stale_command、no_state_file、invalid_state、unreadable_state 和 outdated_bridge 都先于上述任何情况出现：没有东西在运行、命令被卡住、mod 未加载、状态文档是合法 JSON 但某个命名字段错误（它会指出是哪个字段，并在断言之前检查两次）、文件完全无法解析，或者它能解析但早于本服务器的协议（用 bridge_build 重建它）。
世界工具通过服务器 -profiles 目录中的两个 JSON 文件与桥接器通信：一个命令邮箱（从这一侧原子写入，由 mod 作为认领删除）和一个 mod 每秒覆写一次的状态文件。Enforce Script 没有重命名操作，因此 mod 无法原子写入——读取器改为容忍撕裂写入，一次失败的读取永远不算新闻。在活 stand 上测量的四个事实决定了如何使用它们：
服务器就绪不等于桥接器就绪。 桥接器在服务器报告就绪之后数十秒才开始认领命令——目前观察到的散布范围是 18–38 秒，且每次启动都不同。在该窗口内发送的命令不会被拒绝——它会被延迟认领，并在调用方放弃之后才完成。因此：server_start，等待启动任务，然后 world_ready()，再发命令。如果 tick 未移动，每个世界工具也会预先拒绝，并点名 world_ready 作为补救措施。
每个参数值都以字符串形式过线。 mod 的解析器很严格：args 中任何位置的 JSON 数字都会拒绝整个 args 块。工具自行将数字和布尔值字符串化，并拒绝没有忠实字符串形式的值（列表、字典、None）。位置以单个字符串 "x y z" 传输。
拒绝就是结果。 mod 自身的句子会逐字作为错误返回："服务器上没有玩家"、"该类不存在"、"动作自身的 Can() 拒绝了"。无人连接是无头 stand 的正常状态，每个需要玩家的动词都会明确说明，而不是静默地什么都不做。
会话 id 防止昨天的命令。 每个命令都携带桥接器最近发布的会话；mod 拒绝任何发往其他会话（或无会话）的命令而不执行它。因此，在 stand 关闭时写入的命令永远不会射入新启动的世界。工具会自动盖上会话戳——只有当你手写邮箱时才需要关心。
像“上交样本”这样的语义动词具有欺骗性：在真实的模组中，同样的词语会根据附近是哪个设备、玩家的阵营以及已经解锁了什么而表示不同的含义。这种上下文无法枚举，因此桥接层不做这种尝试。world_action 接受一个动作的类名、一个目标和手持物品，并请求引擎通过它自己的门控来运行——与按键所经过的同一个门控。适用性由动作自身的 Can() 决定，其拒绝是一个有意义的测试结果，而不是工具故障。可区分的答案有：管理器忙、玩家已在行动中、玩家在冲刺、未知的动作类，以及“动作自身的 Can() 拒绝了”。“已接受”也不等于成功——命令会一直运行，直到引擎真正释放该动作，而每一条失败路径都会释放管理器，使玩家之后仍能行动。
world_exec 是逃生舱模组暴露的任何不是动作的东西——“阵营池里有多少点数”——都通过 world_exec(verb, args) 处理：在同一个传输通道上执行任意动词。每个答案都标记为 non_standard：此服务器不知道这个动词，不验证它，也不为模组用它做了什么而负责。桥接层构建时不知道的动词，会返回它所知道的动词列表。需要自己动词的项目，编辑它自己的副本中的桥接层分发器（bridge/scripts/5_Mission 中 KnownVerbs() 上方的注释精确指出了位置）；故意不设注册机制——一个由本服务器输入并验证的动词，就是一个由本服务器负责的动词。
桥接层到达服务器。它做不到的是查看客户端的屏幕或通过客户端行动——让角色走过地面、打开菜单、填写模组绘制的字段。client_* 工具就是干这个的，它们使用三条不同的通道，因为没有哪一条能完成另外两条的工作。下面每一行都是对照真实客户端的测量结果，而不是设计意图。
通道 | 它做什么 | 需要前台 |
桥接层（ | 世界，以及向聊天发送文本 | 否 |
虚拟手柄，ViGEmBus（ | 移动、镜头，以及部分界面 | 否 |
真实按键， | 向仅存在于客户端上的字段输入文本 | 是，而且会占用它 |
键盘模拟不会移动角色，窗口消息则完全无效。 已验证前台的 SendInput 扫描码：向前 25 秒，0 米。向主窗口及其子窗口发送 PostMessage/SendMessage WM_KEYDOWN：0 米，菜单也没有任何反应。引擎从原始输入读取移动，忽略模拟按键，这就是为什么这里没有任何工具提供窗口消息。
虚拟手柄确实能移动它，无需聚焦，而且是模拟量——这就是即使按键也能做到时仍保留它的原因。 在一次运行中测量，第三方应用全程持有前台：
stick fully forward, 10.0 s -> 38.40 m (3.84 m/s)
stick at 0.3 forward, 8.0 s -> 11.34 m (1.42 m/s)同一条通道，同一个角色，仅靠摇杆偏转就达到 2.7 倍速度。“角色在走而不是在跑”无法用按键表达，因为按键只知道开和关。在同一次运行中，角色自行走了约 141 米，模组自身统计的 10 米内物体数量从 1 → 0 → 1，因为它离开该位置又回来——这是由在场状态引起的状态变化，传送无法产生这种变化。
部分界面响应手柄，部分不响应。 实测，游戏窗口全程位于另一个应用后面：back 打开和关闭物品栏，start 打开暂停菜单，b 关闭它——全部在默认的 0.1 秒点按下完成，所以一次点按足以让引擎锁定。但 a 什么都没移动，无论是 0.1 秒还是 0.5 秒，方向键在这些界面内也一样：客户端没有切换到控制器导航模式，所以没有聚焦元素可供确认键作用于其上。将菜单关闭视为手柄的工作，将菜单确认视为未经证实。
眼睛也不需要聚焦。 捕获是实时帧，窗口位于 z 序最底部（同一会话中未聚焦时 lit_fraction 为 0.9997，聚焦时也为 0.9997）。唯一能击败它们的状态是最小化的窗口，其客户区塌缩为 0×0——会附上原因被拒绝，而不是保存为一张看起来有效的空白图片。
所有这些后台行为都取决于一个客户端设置，pauseMode（GAME → UPDATE IN BACKGROUND）。在此处测量的值下，客户端在未聚焦时仍持续绘制和模拟，这就是帧是实时的、摇杆仍能移动角色的原因。在“无图形”模式下，两者都会静默停止——冻结的帧看起来和实时帧一模一样。因此 client_start 和 client_status 会读取该设置并发出警告；它们从不写入它，因为它属于机器的所有者。
client_type 是唯一会占用屏幕的工具，而且它对此很诚实：答案带有 foreground_taken 和一句话，说明坐在机器前的人在它运行期间无法在自己的窗口里输入。它在请求前台后用 GetForegroundWindow 验证前台，因为当 Windows 拒绝时，SetForegroundWindow 会返回成功但实际上什么都没做——而盲打会把按键发送到那个人实际正在使用的任何窗口。当无法获得前台时，什么都不会输入，拒绝信息会指出持有它的进程。
ViGEm 是对真实设备的模拟，而这是一个测试台。 驱动已签名，无需重启即可安装，手柄是一个新的设备，而不是对机器自身键盘和鼠标的过滤——这里曾尝试过一次过滤驱动，结果让机器所有者失去了所有键盘和鼠标输入，直到手动解除。这些都不是对真实服务器上反作弊的承诺，本阶段也不会做出任何承诺。
编写模组的智能体不断向游戏提出同样的问题：是否有这样的 API，它叫什么，在哪里声明，谁覆盖了它。回答这些问题意味着解包 scripts.pbo 并扫描文本——而每次会话都要重新付出代价。knowledge_* 把这项工作变成了一个问题。
它是项目自己的 .dayz-mcp/ 目录中的一个普通 SQLite 文件，由本服务器从游戏、项目声明的模组以及项目自身的源码构建。没有嵌入、没有外部服务、没有密钥。
层 | 来源 | 何时过期 |
| 游戏：API 用 | 游戏更新 |
| 配置文件声明的模组的存档，不解包直接读取 | 依赖更新，或声明的集合改变 |
| 模组自身的源码，在其所在位置读取 | 每次编辑 |
一次性构建的索引会在正确后一分钟内就出错：游戏一年动几次，依赖一个月动几次，而项目在智能体的一次回合和下一次之间就会变。因此每一层都独立构建、老化、测量，每次构建都是增量的——未变化的源码按大小和修改时间跳过，only=[path] 连发现它们的遍历都跳过。
陈旧度是测量出来的，不是猜出来的：一层记录它读取的每个源码的大小和修改时间，然后与文件当前的状态进行比较。
每个答案都指明它使用了哪些层以及每层有多旧。没有结果的答案指明它搜索过的每一层——“未找到”的价值恰好等于其背后各层的时效性。
项目层的时效性在每次搜索时都会测量，无论它是否贡献了结果。那是危险的情况：智能体添加了一个类，询问它，而一分钟前构建的层说“未找到”——这是对已存在代码的一个自信陈述。
对从未构建过的层的搜索会被拒绝，拒绝信息会指明构建它的调用。“未找到”和“未查找”是不同的事实，其中只有一个可以安全地据此行动。
收窄范围在下一层带有同样的陷阱，因此空的收窄答案会报告该名称确实存在的位置：对游戏仅在配置中声明的名称询问 kind='class'，会得到一个真实的“否”，读起来像是“游戏没有这样的类”。
配置类位于 kind='config' 下，而不是 kind='class' 下。在本机器自己的游戏索引中统计：88 102 个配置类，对比 43 595 个各种脚本声明加在一起。如果混入同一个种类，它们会淹没所有脚本答案。分开后，“游戏是否有名为 X 的物品类”就是一个可以精确提出的问题。
索引回答存在什么：类、方法、签名、在哪里声明、谁覆盖。它不回答什么是对的——modded class X extends X 能编译但静默地不生效，_co 会消耗 alpha 通道，binarize 接受目录而不是文件。这些都不是能从源码推导出来的；它们是靠惨痛教训学到的，存在于模组编写技能和模组本身中。索引不试图取代这两者，也不试图理解字段的含义或类存在的原因。
这个决定是通过测量而非谨慎做出的：塑造本服务器早期阶段的每一次查找都是按名称的查找。而嵌入索引会打破本服务器其余部分遵守的规则——安装即可用，没有外部服务、没有密钥。本项目刻意不基于其构建的前身项目，将其知识层描述为本地且免费，而其代码却导入付费的嵌入客户端，没有密钥就失败，并带有硬编码的价格。它的两个搜索工具还会永远挂起，因为背后的客户端创建时没有超时；因此这里的每次搜索都在一个上限下运行。如果精确搜索被证明不够用，语义搜索是单独的一个阶段，有一个条件：模型随交付物一起内置。
在这台机器上——游戏有 2810 个脚本文件、35 个已安装模组、一个 41 个源文件的真实项目——通过工具而非其内部机制测量：
构建 | 结果 | 时间 |
| 2927 个源文件，131 697 个声明（41 个无产出） | 70.2 秒 |
| 8 个存档，10 925 个声明 | 0.9 秒 |
| 523 个存档，204 768 个声明，3 个存档不可读且已点名 | 139–147 秒 |
| 41 个源文件，1196 个声明 | 0.12 秒 |
磁盘上的索引：真实项目三层的 74.7 MB；仅 523 个依赖存档就 110 MB。这些存档共 92 GB，没有一个被解包。
调用点（call site）才是索引真正花钱的地方。 游戏自身的脚本包含 43 579 个声明和 113 703 个调用点，记录第二组数据大约使索引体积翻倍：仅就游戏层本身测量，不记录调用点时构建需要 23.8 MB 和 3.7 秒，记录后则需要 49.6 MB 和 4.5 秒。这就是能够回答"谁调用了这个"所付出的代价，在这里明确写出来，而不是等到磁盘满了之后才发现。
答案 | 时间 |
| 端到端 4.2 ms，其中 3.0 ms 是项目遍历 |
| 查询 3.2 ms |
| 4.2 ms |
| 查询 0.38 ms |
| 文本检查 277 ms，索引检查 7 ms |
在实机上测量，三次启动：world_time_set(hour=3, minute=7) 将时钟拨到 2026-09-20 03:07 并保持日期不变；world_weather_set("fog", 0.9, seconds=2) 将已发布的雾浓度从 0.085 提升到 0.900 并保持；world_entities(pos="7500 0 7500", radius=150, limit=5) 列出了 171 个对象中的 5 个，并带有 truncated: true。距离在改为水平测量之前，150 m 半径返回的是 320 m——而水平测量正是引擎自身半径测试所采用的方式。
| 6.8 ms |
| 41 ms（构建后首次调用为 110 ms） |
在真实项目上的增量性能：完整重建 136 ms；遍历发现一个被编辑的文件 8.8 ms（15×）；同一个文件通过 only= 指定 5.8 ms（23×）。在 2810 个文件的树上，遍历占主导地位，only= 的价值远不止于此——但在这种规模的项目上，15× 才是普通重建实际能获得的提升。
上限确实会生效：一个测得 77 ms 的查询，在 19.3 ms 的上限下运行，在 19.9 ms 时被停止，连接继续正常应答。
把模型从 Blender 弄进一个 mod 需要十个步骤，而在这个阶段之前，所有这些步骤都是手工完成的。价值不在于启动这些工具，而在于这条链中的每个工具在结构上都无法报告失败，而每一次这种沉默都已经付出了数天的代价。
在真实二进制上测量，而非假设：
发生了什么 | 工具返回了什么 |
| 0，一个空的输出目录，没有任何一行文本 |
| 0，一个 46,190 字节的 ODOL，而正确构建应为 58,644 |
|
|
Blender 导出器使用其自身的默认参数 |
|
因此，整个命名空间所依据的规则是：结论从产物本身读取，绝不从工具的报告读取。 退出码会被记录，但两个方向都不予采信。
binarize 根本没有项目根目录选项——完整的开关列表是针对真实二进制逐一枚举出来的。根目录就是进程的工作目录。同样的命令、同样的输入、不同的目录，输出的是一个有效的 ODOL，带有看似合理的纹理路径，但引擎渲染出来却没有纹理，而且返回成功码、毫无怨言。导出的 Blender 插件在自己的偏好设置里也有同样的根目录，记住的是上次打开的项目：在开发这台机器时，它指向的是某个无关会话的目录，而面对错误的根目录，插件同样不会失败——它会去掉盘符，保留其余部分，写出看起来像路径的路径。
build.project_root 就是那个目录，在配置文件的便携半部分声明一次。服务器将其设置为二进制化器的工作目录，并在运行期间推送给插件，因此插件存储的内容不决定任何事（它会被报告出来，这样你可以去修复）。这就是让错误根目录不可能发生而非"可检测"的原因，也是为什么在运行任何与模型相关的东西之前，这个键是必需的。
它产生的拒绝发生在进程存在之前——测得 0.0003 秒——而被拒绝的构建会让 mod 已经随附的模型逐字节保持原样不动。
asset_check 在不构建任何东西、也不需要 DayZ Tools 的情况下运行这些检查，因为一个全新的克隆必须能够询问它所发布的内容是否健康。四项会拒绝：构建的模型存在且是 ODOL（C1）、没有引用逃出 mod（C3）、材料确实被内联了（C4）、没有把已经二进制化的东西再交回给 binarize（C10）。其余的是警告：悬空引用、指向另一个 mod 的 rvmat、因 DXT1 而丢失的透明度（C7）、从未到达产物的动画、不是产物构建所依据的那个 model.cfg、与上次构建部署的结构指纹不再匹配。每条发现都会说明该怎么做。
C4 是最值得了解的。当 binarize 解析 rvmat 时，它会将该材料自身的阶段纹理复制到模型中——fresnel、#(argb,8,8,3)、env_land_co.paa、_nohq、_smdi——这些字符串是任何 MLOD 都不包含的。六个产物中有六个被这一项测试正确区分开来，而且它在这台机器上发现了一个没人知道的损坏模型。
asset_export 是这里唯一需要 Blender 的工具，而下游的一切都适用于来自任何地方的 .p3d——手工导出、合作伙伴的文件、多年前提交的模型。一台没有 Blender 的机器也能完美地构建和发布 mod；拒绝会明确说明这一点，而不是把它呈现为安装损坏。它确实需要在其找到的 Blender 中启用导出插件，而且它从不写回 Blender 的用户偏好设置（已验证：每次运行后偏好设置文件都逐字节相同）。
导出和构建是两个调用而非一个，因为每一半都有自己的结论，而一个被一方拒绝、被另一方允许的构建不是一个决定。
这条管线的两半都不可复现，设计上明确说明了这一点，而不是假装可以：
导出。 对一个未更改的源文件进行七次导出——三次来自同一会话，三次来自另一会话，一次是几个月前在 GUI 中手工完成的——在恒定的 334,032 字节下给出了七个不同的 SHA-256。差异在于一个内部块的顺序。
binarize。 对一个未更改的输入运行四次，得到三个不同的结果：大小移动了 5 字节，两个 8 字节片段从压缩区域泄漏出来。
因此，模型永远不会按内容哈希缓存或比较。被比较的是结构指纹——文件的种类、LOD 数量及其名称集合。在那七次导出中，这个指纹始终是同一个值。
一个小模型，在这台机器上，经过这些工具：
步骤 | 结果 | 时间 |
| MLOD，334,032 B，5 个 LOD，干净 | 2.1 秒（冷启动约 8 秒） |
| ODOL v55，58,646 B，4 个 LOD，全部五个 C4 标记 | 43.8 秒（此前四次运行测得 75.6–78.7 秒） |
| 1 个模型和 10 对纹理被判定 | 毫秒级 |
| 一个 PNG 转 DXT1，50,764 B | 0.52 秒 |
错误根目录上的拒绝 | 在任何进程启动之前 | 0.0003 秒 |
两份日志几乎全是套话，被静默的内容是被计数而非丢弃：Blender 的 169 行缩减为 4 行，binarize 的 91 行缩减为 6 行——其中一行是模型唯一真正的抱怨。
端到端串联起来，导出和构建复现了一个几个月前手工制作的模型：同样的种类、同样的 4 个 LOD、同样的 50 个字符串，大小只差一个字节。
模型看起来是否正确、缩放是否正确、绕序是否正确、是否有碰撞。游戏之外没有任何东西能回答这些。C1–C12 缩短了通往答案的路；它们不能替代答案。
过时 pbo 检测基于修改时间，而非内容。 mod_build 会拒绝打包比其源文件更新的 pbo——通常原因是服务器仍在运行并持有旧文件，导致打包静默地没有产生任何结果。但 git checkout 会改变文件的修改时间而不改变内容，因此在切换分支后立即构建的 pbo 即使完全正常也可能触发此检查。如果 mod_build 在切换分支后立即报告"过时 pbo"，很可能就是这个原因，而不是真正的打包失败——重新构建即可通过。该领域的成熟工具正是因为这个原因改用了内容哈希；这是未来的工作，本阶段未完成（参见 packer.py、pack_one）。
模组源文件夹是整体打包的。 如果模组的源目录包含任何匹配 build.exclude 的内容（默认的七模式列表见上文），mod_build 会拒绝打包，而不是将其静默地包含在发布的 pbo 中。当源目录包含该服务器自身的产物时——签名密钥、配置文件的任一半、任务存储、模组之前的构建——无论 build.exclude 如何设置，它都会拒绝，因为打包这些内容会发布私有的签名密钥，任何项目都不应该需要配置来排除这些。默认情况下，它不会先暂存过滤后的副本：副本总是比源文件新，如果检查的是副本，这将永久禁用上述的过时 pbo 检查。build.stage = true 选择无论如何都进行复制——之所以安全，仅仅是因为过时 pbo 比较总是测量原始源树，而不是副本。这是源目录为仓库根目录的模组所需的布局（它总是至少包含 .git）。
判定会检查整个日志，而不仅仅是模组的行。 log_verdict 读取其指向的服务器实例的日志，因此与其他模组共享的服务器实例会将其警告计入你的 expect.max_warnings 预算，并将其错误视为原因。两个项目共享一个 machine.stand_root 会看到彼此的基线。要么给每个项目分配自己的服务器实例，要么在知道还加载了什么的情况下设置预算。与 expect.error_regex 对称的项目级过滤器是明显的改进方向，但尚未实现。
expect.noise 无法挽救已经算作错误的行。 分类顺序为 forbid → 崩溃 → 错误 → noise → 警告，因此包含 ERROR 或 FATAL（或你的 forbid 字符串之一）的行在咨询 noise 之前就已经被决定了。这个顺序是刻意的——如果 noise 先匹配，一个无害的子串可能会吞掉致命行——但这意味着 noise 只能抑制警告和普通行，而不能降级错误级别的行。
client_verdict 是错误和崩溃判定，而非就绪判定。 [expect] 描述的是服务器的日志：其就绪行和计数器由模组的服务器端初始化打印，max_warnings 是在同一日志上计算的预算。客户端 .RPT 不包含这些内容，因此这三个键在此处刻意不适用，答案在 not_applied 中列出。forbid、error_regex 和 noise 与日志行的文本相关，仍然适用。没有客户端就绪行可声明；客户端是否进入由 client_start 等待的玩家数量来回答，而不是其日志。
客户端工具加入的是本会话未启动的服务器实例；client_chat 不能。 client_start 会愉快地连接到端口上已有的任何内容，并说明其归属。但聊天是通过与 world_* 工具相同的通道在服务器端传递的，而该通道仅作用于本会话启动的服务器——因此，在借用的服务器实例上，除 client_chat 之外的所有功能都可用。拒绝时会指出占用端口的进程 ID，而不是建议一个会拒绝它们的 server_start。
聊天无法从游戏手柄访问，确认菜单也不行。 游戏将聊天行绑定到回车键，没有其他方式，也没有屏幕键盘，因此文本要么是桥接消息（client_chat，免费），要么是真实的按键（client_type，需要前台）。client_type("", submit=True) 单独发送回车键，这就是打开聊天行的方式——根据上述证据，这也是该工具集唯一的确认方式。
每次知识搜索都会遍历项目树。 每次回答时，项目层的过期检测都是通过这种遍历来衡量的，这是索引存在的唯一目的。在一个真实的 41 源文件模组（其树约有 1800 个条目）上，这需要 3.0 毫秒；在 2810 个文件的树上需要 21 毫秒。将其缓存一两秒将消除成本，并恢复设计所拒绝的静默窗口；如果它变得过于昂贵，这个权衡必须是有意做出的，而不是偶然的。
构建总是通过任务进行，而任务的开销大于小型构建本身。 实测周转时间为 70-95 毫秒，而项目重建仅需 6 毫秒：job_wait 以 100 毫秒轮询。单一形态是刻意的——调用者不必知道哪些构建块——而且没有什么强制你等待，因为下一次搜索会自己测量该层。
依赖层是针对当前状态的配置文件进行测量的。 向 mods.required 添加模组，其存档会以 added 形式出现；移除模组，其存档会显示为 missing。这是符合预期的（声明的集合是构建该层的一部分），但这看起来像是索引过期了，而实际改变的是配置文件。
core 始终包含游戏的配置文件，这是其大部分成本所在。 包含配置文件需要 70 秒，而仅脚本需要约 4 秒。没有开关：没有配置文件，"是否存在名为 X 的物品类"就无法回答，而第二个轴会使过期检测变得模糊——遍历将不知道是否期望 Addons 存档。
knowledge_show 优先显示最近的层。 对于依赖项使用 modded class 重新打开的类，模组的声明在游戏的声明之前。这是正确的顺序，但也是令人惊讶的；传递 layer='core' 以获取游戏自身的声明。
条件编译被索引，但不被解析。 游戏中 4.9% 的脚本行位于 #ifdef 内，包括大约一百个类声明。该服务器驱动服务器、客户端和诊断构建，因此不存在单一正确的宏定义集：所有内容都被索引，守卫记录在声明上。因此，可能会报告特定构建排除的名称——另一种选择是根据对宏定义的猜测进行过滤，这会否认正在运行的构建中存在的方法。
C12 的指纹包含文件大小，而 binarize 的大小不稳定。 重新构建一个没有人编辑过的模型，生成的产物比发布的版本大一个字节，具有相同的类型、相同的 LOD 数量和相同的五十个字符串——但摘要不同，因为大小是其中的一部分。因此，C12 可能会对没有改变任何内容的重新构建发出警告。正是因为这个原因，它只是警告而不是拒绝，并且其构建部分会显示在旁边，以便手动进行比较。将摘要拆分为稳定部分和大小是明显的改进方向，但尚未完成。
部分导出会警告，但不会拒绝。 使用导出器自身的默认参数，模型导出了 5 个 LOD 中的 2 个，并通过了所有其他检查。该服务器不传递这些参数，因此不应该发生这种情况——但标记为 LOD 且未链接到场景中的对象只计算在比较的一侧，这是数量差异的合理原因，因此拒绝会产生误报。请阅读 E3。
包含规则无法发现所有错误的根目录。 它拒绝不包含模组前缀文件夹的根目录，这是已测量的失败。一个确实包含该名称文件夹的根目录——例如，其自身模组目录拼写与前缀相同的仓库——会通过检查，而捕获这种情况的是下一层的 C10 或 C3/C4。已测量：指向这样的根目录时，构建拒绝，不部署任何内容，并保持已发布的产物不变，但拒绝来自任务而不是调用。
asset_export 需要在 Blender 中启用导出插件，并且无法自行安装。 Blender 以机器所有者的真实首选项启动，因为使用 --factory-startup 启动会完全移除插件。他们的其他插件在运行时被排除在搜索路径之外（此处安装的两个插件在启动时访问网络并被归咎于崩溃），Blender 在日志中报告为"插件未加载"——该行是此服务器自身的行为，不是故障。
二进制的配置文件没有可显示的正文。 knowledge_show(body=True) 从索引时所在的文件或存档中读回声明，但 config.bin 保存的是二进制形式，而索引保存的是 CfgConvert 处理后的结果。答案会说明这一点，而不是返回空值。
python -m pip install -e ".[dev]"
python -m pytest在您的 MCP 客户端中注册：
{ "mcpServers": { "dayz": { "command": "dayz-mcp" } } }GPL-3.0-or-later。参见 NOTICE.md。
Build a mod's models from their MLOD sources and put them in the mod.
Returns a job_id immediately: ONE small model measured 75.6 to 78.7
seconds across four runs, so this can never be a blocking call. Wait for it
with job_wait(job_id, timeout=...) -- give it minutes, not seconds -- and
read the numbers in the job's summary and its asset-build.json artifact.
What it does, in order: run binarize with its working directory set to
the project root declared as build.project_root, judge the ARTIFACT that
came out (never the tool's exit code -- three separate broken outcomes were
measured exiting 0, one of them leaving a zero-length file), and only then
copy the models into the mod. A refused build deploys nothing and leaves
the artifact the mod already ships exactly as it was.
mod names one of build.mods; with a single declared mod it can be
omitted. source is the model directory relative to the mod's own folder
under the root (e.g. "data/models"); left out, the only directory holding
.p3d files is used and two candidates are a refusal rather than a guess.
deploy=False builds and judges without writing into the mod.
The source is the MLOD export and the ODOL is the build's output (decision
D3). Handed an ODOL, binarize dies with 0xC0000005 and leaves a
zero-length file behind, so that is refused before the process starts.
Model.cfg is never copied for you: it is what the artifact was built from, and a mismatch between the copy under the root and the copy in the mod is reported by C11 with what to do about it. Rebuilds are not byte-stable and are not expected to be -- what a rebuild is compared against is structural.
| Name | Required | Description | Default |
|---|---|---|---|
| mod | No | ||
| deploy | No | ||
| source | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is highly transparent: it explains the internal steps (running binarize, checking artifact, copying models), side effects (deploy or not), failure modes (refusal for invalid source or ambiguous candidates), and non-deterministic rebuilds. It also notes the return behavior (job_id) and that Model.cfg is not copied. With no annotations, it fully carries the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose and repetitive, with duplicated statements about the process (e.g., 'Build...and put them' vs. 'copy the models into the mod') and an anecdotal timing example that adds length without essential value. While well-paragraphed, it is not concise; it could be streamlined by removing redundancies.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main context: parameters, return behavior, refusal conditions, artifact handling, and structural comparison. It references job_wait for polling and mentions the artifact but does not describe the output schema or exact job_id format. Given no output schema is provided, it is reasonably complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are explained with meaningful detail beyond the schema: mod ('names one of build.mods...'), deploy ('deploy=False builds and judges without writing'), and source ('model directory relative to the mod's own folder...'). It covers defaults, exclusions, and edge cases (e.g., two candidates cause refusal). Schema coverage is 0%, so the description compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Build a mod's models from their MLOD sources and put them in the mod.' It specifies the resource (mod models) and the source (MLOD sources), distinguishing it from siblings like asset_export or asset_convert. The verb 'build' is specific and the scope is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description details the behavior and conditions for use (e.g., default source selection, refusal cases), but it does not explicitly state when to use this tool over alternatives like asset_export or mod_build. The guidance is implicit through detailed process explanation, but lacks a clear 'use this when...' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Judge the models and textures a mod already ships. Builds nothing.
Needs no DayZ Tools and no build: every check reads a file that is already on the disk, because the tools that produce these files are structurally unable to report failure. Answers in milliseconds.
Twelve checks (C1-C12). Four of them refuse, and this call fails when one
does: a built model is there and is an ODOL, no reference escapes the mod,
a material was actually inlined, and nothing already binarized is offered
back to binarize. The rest warn -- dangling references, an rvmat pointing
into another mod, a transparency lost to DXT1 (C7), an animation that never
reached the artifact, a model.cfg that is not the one the artifact was
built from, and a structural fingerprint that no longer matches what the
last build deployed. Every finding says what to DO about it.
model narrows it to one file, relative to the mod's directory. Files the
packer will drop (build.exclude) are not judged: a refusal about a file
that never enters the pbo is a refusal about nothing.
A texture is judged against the PNG it came from -- beside it or at the
same place under build.project_root -- because a legitimately opaque
texture and one whose transparency was destroyed are identical in the
output alone.
| Name | Required | Description | Default |
|---|---|---|---|
| mod | No | ||
| model | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers exceptionally. It discloses failure modes ('four of them refuse, and this call fails when one does'), specific warnings (C7, animation to artifact, fingerprint mismatches), edge cases ('build.exclude' files not judged), and the PNG comparison logic. Nothing about this tool's behavior is hidden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The main purpose is front-loaded and every sentence earns its place for a tool of this complexity. The twelve-check enumeration, however, is delivered as a dense paragraph where a more scannable list format would improve parseability. The description is rich but could be condensed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and substantial complexity, the description is remarkably complete: purpose, performance, side effects, failure modes, edge cases, and parameter hints are all addressed. The output schema covers return values. The lone gap is the 'mod' parameter semantics and explicit sibling differentiation, keeping it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 0%, the description had to compensate, and it does meaningfully for 'model' — 'narrows it to one file, relative to the mod's directory' — adding real semantic value. However, the 'mod' parameter is never explicitly described, either in the schema or the tool description, leaving the agent to infer its purpose from context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence 'Judge the models and textures a mod already ships' pairs a specific verb with a clear resource, and 'Builds nothing' cleanly separates it from build/convert siblings. The enumeration of twelve distinct checks (C1-C12) with concrete examples (DXT1 transparency, ODOL references, rvmat pointers) leaves zero ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear when this is appropriate: when validating an existing mod's files without building, needing no DayZ Tools, and expecting millisecond responses. However, no sibling alternatives are explicitly named (e.g., mod_lint for code-level linting), so the exclusion logic is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert one texture between .png and .paa, and judge the result.
Which compression ImageToPAA writes is decided by the SOURCE FILE'S NAME,
and nothing says so at the time: a name ending in _co produces DXT1,
which keeps ONE BIT of alpha. A source measured 6 distinct alpha levels
going in and 2 coming out. So this measures the source's alpha before
converting, warns before the loss and again after it (C7), and says what to
do -- rename the source to end in _ca, because the output itself cannot
be repaired once the levels are gone.
source is absolute, or relative to the repository, or relative to
build.project_root. output defaults to the same name with the other
extension, beside the source; a relative output also lands beside it.
The verdict is read off the file that was written, never off the exit code.
| Name | Required | Description | Default |
|---|---|---|---|
| output | No | ||
| source | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does this thoroughly. It discloses that compression is decided by source filename, that alpha loss may occur, that warnings are issued before and after conversion, that output cannot be repaired, and that verdicts are read from the written file rather than the exit code.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than typical but every paragraph carries essential operational detail: conversion behavior, compression quirk, path rules, and verdict source. It is front-loaded with the core action and remains coherent, though the alpha-loss narrative could be tightened slightly without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a conversion tool with subtle behavior. It covers path resolution, defaults, output placement, compression selection, alpha-loss limitation, and result interpretation. Even though an output schema exists, the description adds necessary behavioral context beyond structured fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters—and it does. It defines source path resolution relative to absolute, repository, or build.project_root, and explains output defaults and placement behavior. This gives an agent everything needed to pass meaningful values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: converting one texture between .png and .paa and judging the result. It clearly distinguishes this from the sibling tools by focusing on a single texture conversion plus quality verdict, making it easy for an agent to recognize when this tool is relevant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when this tool is applicable—when converting textures between PNG and PAA formats and needing alpha-loss awareness. It does not explicitly name alternatives or exclusions, but the scenario is specific enough that an agent can infer appropriate use without confusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a model out of a .blend into the project's model root.
Returns a job_id; wait for it with job_wait(job_id, timeout=...). One
five-LOD model measured 2.1 s warm and about 8 s cold, but the ceiling is
minutes, because how long an export takes is a property of the model.
This is the pipeline's OPTIONAL first step. It produces the MLOD; the
binarized model that the game loads is what asset_build makes from it,
and that is a separate call on purpose -- each half has its own verdict,
and a mod whose .p3d came from somewhere else skips this entirely.
The project root declared as build.project_root is pushed into the
exporting add-on for the duration of the run, so what the add-on has stored
decides nothing. That matters: an add-on preference is remembered from
whatever was open last, and against the wrong root every texture path comes
out with the drive letter stripped and the rest kept -- valid-looking,
resolving to nothing, reported as a success.
The verdict is read off the file: it must be an MLOD, this run must be what
wrote it, all of the source's LODs must have reached it, and none of its
references may leave the mod. Measured on a real model: with the exporter's
own default arguments, 2 LODs of 5 came out as a valid MLOD with correct
paths, FINISHED, exit 0, and no mention of it in 169 lines of log.
blend is absolute, or relative to the repository, or relative to
build.project_root. source is the directory the model should land in,
relative to the mod's own folder under that root (e.g. "data/models"); with
exactly one such directory already holding models it can be omitted.
name is the file to write, defaulting to the source file's own name with
a .p3d extension.
Nothing else is touched: an export that produces nothing leaves the model that is already there exactly as it was, and Blender's user preferences are never written back.
| Name | Required | Description | Default |
|---|---|---|---|
| mod | No | ||
| name | No | ||
| blend | Yes | ||
| source | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, and it goes above and beyond: it reveals the async contract (returns job_id, wait with `job_wait`, seconds-to-minutes latency), a subtle corruption failure mode (wrong root strips drive letters, looks valid, resolves to nothing, reports success), the exact verdict logic (must be an MLOD, this run must have written it, no outgoing references), and guarantees that nothing else is touched and Blender preferences are never written back. That is unusually deep transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long (six paragraphs) but nearly every sentence carries decision-relevant facts: purpose, timing, failure mode, verdict criteria, side-effect guarantees, parameter semantics. It is front-loaded with the core behavior and only slightly verbose in the measured-example details (the 2-of-5 LODs / 169-line log anecdote), which explains a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex asynchronous pipeline tool with a known silent failure mode and zero annotations, the definition covers everything an agent needs to invoke it correctly: parameters and defaults, the job-waiting protocol, timing bounds, verdict conditions, and non-destructive guarantees. Since an output schema exists, the description need not enumerate return fields, and it still mentions the `job_id` return.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the weight. It compensates well for three parameters: `blend` gets three path-resolution modes, `source` gets its meaning and the single-directory omission rule, and `name` gets its default (source file name with `.p3d` extension). The `mod` parameter, however, is never explicitly explained; an agent must infer it from the 'mod's own folder' phrase.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific verb and resource: Export a model out of a `.blend` into the project's model root. It also explicitly differentiates itself from the sibling `asset_build` by explaining the export produces the MLOD while the binarized game model is a separate call, so an agent can distinguish it from the other 50+ build assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states positioning explicitly: 'This is the pipeline's OPTIONAL first step' and names the natural next step (`asset_build`) as 'a separate call on purpose.' It also gives a concrete exclusion rule for when to skip the tools: a mod whose `.p3d` came from somewhere else. An agent can decide when to call this tool versus its pipeline neighbor without further inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pack the bridge mod from this repository's own sources.
The bridge is the server's own mod, not the project's: one copy serves every project, and it is built UNSIGNED -- no project's signing key is used, and the output folder is kept free of signatures and keys.
Building it does not load it. Attaching it stays a profile decision (the job summary prints the two lines to add), because the bridge is an extra pbo in the stand and a run without it has to remain possible.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses key behaviors: the build is unsigned (no signing key used), the output folder is kept free of signatures/keys, and building does not load the mod. It also explains the rationale for not auto-attaching it. This is good behavioral disclosure for a build tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded. The first sentence states the core purpose, followed by concise paragraphs explaining the bridge's nature, the unsigned build, and the non-loading behavior. Every sentence adds value, and the structure is clear and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema details are provided (though output schema exists), the description covers the essential context: what the bridge is, how it's built, and what happens after building. It could mention the output location or how to check the result, but the description is fairly complete for a zero-parameter build tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100% (vacuously, since there are no properties). The description doesn't need to explain parameters, but it does explain the build context and output behavior, which is useful. With no parameters, the baseline is 4, and the description adds relevant context about the build process.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Pack the bridge mod from this repository's own sources.' It specifies the verb (pack/build), the resource (the bridge mod), and the source (this repository's own sources). It also distinguishes the bridge from the project's own mod, which helps differentiate it from sibling tools like mod_build.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool: to build the bridge mod, which is the server's own mod shared across projects. It clarifies that building does not load it, and attaching it remains a profile decision. However, it doesn't explicitly name alternative tools or state when NOT to use it, though the context implies it's for the bridge specifically.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discard whatever command is sitting in the mailbox.
The remedy for bridge_status's stale_command. Inside the game, claiming
a command IS deleting the file, so a command sent while the stand was down,
or before the bridge was wired into -serverMod, is never claimed and never
expires on its own: it blocks every later send until something removes it.
Two things on this side do -- this tool, and server_start, which clears the
transport before every boot. A stand booted outside these tools would run
the command instead.
Its own tool, and never a side effect of asking for status: throwing away a
queued command is a decision, and bridge_status reporting the wedge must
not be the thing that silently resolves it.
Refuses when anything suggests the bridge is alive, because a running mod
could claim that command at any moment and destroying live in-flight work
is worse than leaving the wedge. FIRST on the plain fact that a server this
session started is running -- whatever its bridge is or is not publishing,
which matters most for a mod that has not started writing state yet -- and
that refusal costs no probe at all. Otherwise the channel probes for
probe_window
seconds and refuses on a tick that moved, on a world that restarted, AND on
a readable first sample followed by an unreadable second one -- that last
is proof something was alive moments ago, which a downed stand never
produces. force=True overrides all of it, and what it overrode is
reported either way.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | ||
| probe_window | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and handles it exceptionally. It discloses the deletion semantics (claiming IS deleting the file), the safety refusal logic (won't act if the bridge may be alive), the probing preconditions, and that force=True overrides everything. It also contrasts its behavior with server_start and explains what would happen outside these tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is substantial but every sentence earns its place. It front-loads the core purpose in the first line, then builds context in tight, meaningful paragraphs without fluff. The structure flows from purpose → context → safety behavior → parameters, and no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the complexity — a 2-param tool with an output schema, no annotations, and embedded 'own name references' in the description — the description explains what the tool does, why the problem exists, when to use it, what safety checks apply, and what force does. The only tiny gap is that probe_window units aren't specified, but the output schema presumably covers return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 does. It explains force=True ('overrides all of it') and probe_window ('probes for probe_window seconds'), which adds real meaning beyond the bare schema fields. The only minor gap is not specifying units or boundary behavior for probe_window, but the essential semantics are there.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description immediately states 'Discard whatever command is sitting in the mailbox' — a specific verb, resource, and action. It clearly distinguishes itself from related tools like bridge_status and server_start by explaining the wedge problem and naming the sibling that also clears it. The purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use it ('the remedy for bridge_status's stale_command') and when not to ('Refuses when anything suggests the bridge is alive'), and names the alternative (server_start) that also clears the transport. It states that throwing away a queued command is a decision, never a side effect of status checks — strong guidance on usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Is the bridge inside the running game still ticking?
Blocks for up to window seconds (default 2, clamped to STATUS_WINDOW_MAX)
because that is what it costs to see a tick MOVE. window=0 returns at
once and then usually cannot tell -- it reports "unknown", never "frozen".
A stand with no state file at all now costs the FULL window too (measured: 2.07s at the default, 10.05s at the cap), because the reader retries to the deadline rather than giving up on the first miss. If the question is only "is the bridge publishing anything yet" -- the usual one while wiring it up -- pass window=0 and get the same answer in a tenth of a second; a window buys movement, and nothing else.
The answers, told apart in this order:
no_server nothing is running, so there is nothing to ask. Checked
FIRST and on the process, not on the file: the state
file outlives the server that wrote it, and reading a
leftover snapshot as a live bridge is precisely the lie
this ordering prevents.
stale_command the same, but with a command still sitting in the
mailbox. Its own answer because the remedy is its own:
the command does not expire, it blocks every send, and
a stand booted OUTSIDE these tools would pick it up.
(server_start clears the transport before every boot,
so a server started through these tools will not.)
no_state_file / the server is up but nothing readable came back. Four
outdated_bridge / fixes, so four answers: the mod is not loaded; the mod
invalid_state / predates this server's protocol (no session_id at all);
unreadable_state the document is valid JSON but a named field is wrong
(the answer says which field, what was expected and
what was seen, and it is checked twice a publish
interval apart so a mangled write is never reported as
a schema bug); or it does not parse at all.
alive / restarted a comparison was made. alive means the tick moved;
/ frozen / restarted means a new world came up mid-sample (also
unknown alive, and NOT frozen); frozen means the same world
was seen twice without moving; unknown means no
comparison could be made. Only the first two return ok.
| Name | Required | Description | Default |
|---|---|---|---|
| window | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels: it explains blocking behavior, the cost of window=0, the no-state-file penalty, and the order of answer checks, including why no_server is checked on process not file to avoid stale snapshots. It discloses the multiple return values and their meanings, which is rare and high-value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but densely informative, with a clear front-loaded opening question, then structured sections for answers. Every sentence adds value, though it could tighten some phrasing. The length is justified by the complexity of the tool's semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, one optional parameter, and high-quality schema/output schema coverage, the description is complete: it explains all return states, the reason for ordering, and the cost trade-offs. An agent has everything needed to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter `window` has 0% schema description coverageible> but the description thoroughly explains its semantics: default, clamping, unit (seconds), and the behavioral impact of different values (window=0 returns immediately and reports unknown vs larger windows detect movement). This is far more than the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks if the bridge is 'still ticking' in the running game, with a specific verb and resource. It distinguishes itself from siblings like server_status and bridge_build by focusing on the bridge's live tick status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises when to use window=0 for quick 'is it publishing' checks vs a larger window for movement detection Menu>implied usage is not present; it gives concrete guidance on block timing and trade-offs, and warns about the cost of no state file. It also implicitly differentiates from siblings like server_status (server-level) and bridge_build (build action).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put a line in the connected player's chat. FOCUS IS NOT NEEDED.
Said plainly because the general rule about typing does not apply here. Chat is a SERVER-SIDE MESSAGE: the engine hands the mod a call that delivers text to a player, so the bridge sends it as data -- no keyboard, no window, no foreground, and nothing taken away from whoever is at the machine. It is also more trustworthy than real typing, because the command carries an id and comes back with the mod's own confirmation instead of "typed it and hoped".
This is NOT the tool for a mod's own input field -- a PDA, a terminal, a
form. Those exist only on the client and are filled by client_type, which
does need the foreground.
The line goes to EVERY connected player, and the answer says how many got it: the engine's call names one recipient, so a verb that quietly took the first player would put the line on one screen and leave it missing from the one the caller was watching.
color is one of colorStatusChannel (the default), colorAction,
colorFriendly or colorImportant. Anything else is refused BY THE MOD rather
than passed on, because the client turns a colour class it does not know
into plain white and says nothing about it. Long lines are refused too,
rather than cut somewhere the caller cannot see.
What success promises is that the engine accepted the call for each named recipient -- not that the line was visible. A client drops whole chat channels according to the player's own profile options, so an accepted line that nobody can see is a client setting, not a fault in the bridge.
Requires the bridge to be loaded and ticking, like every other world command, and requires the stand to be running a bridge build that knows the verb; if it is not, the mod says so and the hint says what to do.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| color | No | ||
| timeout | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it excels: it discloses that focus is unnecessary, messages are server-side, go to all connected players, color values are validated by the mod with refusal for invalid ones, long lines are refused, success means engine acceptance rather than visibility, and client profile options may drop channels. This is exceptionally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose but structured into clarifying paragraphs that each add meaningful detail: purpose, distinction from typing, recipient semantics, color validation, success meaning, and prerequisites. Every section earns its place given the tool's nuance, though it could be tightened without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and schema descriptions, the description covers all critical aspects: prerequisites, behavior (all players), validation (color, length), semantics of success, and response meaning (count of recipients). The only notable omissions are the exact behavior of timeout and the precise response format, both of which are partially implied but not fully specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 'text' as the chat line and 'color' with explicit allowed values and validation/refusal behavior. However, 'timeout' is never mentioned—neither its purpose nor behavior. While this is a common parameter, it is completely undocumented in both schema and description, so compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Put a line in the connected player's chat.' It explicitly distinguishes itself from typing (server-side) and from client_type, which is for mod's own input fields. This leaves no ambiguity about 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states when to use the tool (to send a line to all connected players) and when NOT to use it (for client-only input fields like PDA/terminal, pointing to client_type). It also includes prerequisites (bridge loaded and ticking, bridge build knows the verb) and explains focus is not needed, covering both context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compile the CLIENT half of the scripts and judge the result. Returns a job id.
A server boot never compiles anything behind the client-only guard, so a
broken menu, a broken widget or a broken client-side action passes every
server check and then breaks in front of a player. This runs the diagnostic
client for wait_seconds, stops it, and judges what it wrote -- and the
verdict does not accept a clean log on its own: the game's own "Module:
Mission" line has to appear, otherwise "no errors" only means "not that far
yet" and the job says so.
The client runs against a THROWAWAY -profiles directory inside this job's artifacts, so it never reads or writes the test stand. It also joins nothing: this is a compile pass, not a session. For the live client that connects to the stand -- and for looking at it, acting through it, and judging its .RPT -- the tools are client_start and its siblings, and log_verdict(source="client") reads THIS job's log while client_verdict reads the live client's.
extra_mods appends to the -mod list for this run only, for checking that
a mod still compiles alongside another one.
| Name | Required | Description | Default |
|---|---|---|---|
| extra_mods | No | ||
| wait_seconds | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior. It details that the tool runs a diagnostic client for wait_seconds, stops it, and judges its output, requiring the specific 'Module: Mission' line to accept the log. It also notes the use of a throwaway profiles directory, that it does not read/write the test stand, and that it joins no session. This is comprehensive behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense and structured logically, starting with the core function, then nuance, then exclusions, then parameters. While slightly long, every sentence contributes value. It could be tightened, but it remains efficient and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with this complexity—compile logic, judgment criteria, exclusions, parameters—the description covers all necessary aspects: what it compiles, how it judges, what it doesn't do, alternatives, and parameter behavior. It even states the return type ('Returns a job id'). Nothing essential for an agent to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description explains both parameters: 'runs the diagnostic client for wait_seconds' and 'extra_mods appends to the -mod list for this run only.' This fully compensates for the lack of schema documentation, adding meaning beyond the raw property definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb-resource pair: 'Compile the CLIENT half of the scripts and judge the result.' It explicitly distinguishes itself from live-client tools by stating 'this is a compile pass, not a session' and names alternatives like client_start. This leaves no ambiguity about what the tool does relative to its siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives. It explains that for the live client, one should use client_start and siblings, and it clarifies that log_verdict(source='client') reads this job's log while client_verdict reads the live client's. It also warns that a server boot never compiles the client-only guard, implying this tool is needed for client-side validation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn the camera with the right stick. NO FOCUS NEEDED.
Same units and the same guarantees as client_move: x positive right,
y positive up, clamped to [-1, 1], released on every exit path.
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| seconds | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes on the behavioral disclosure burden and does a good job: it defines coordinate orientation, clamps inputs to [-1, 1], and promises that inputs are released on every exit path. It does not explain the effect of seconds or error behavior, but the stated guarantees are concrete and useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded, and every sentence provides distinct information: the action, the precondition, the coordinate/unit conventions, and the exit guarantee. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-number tool with an output schema, the description covers most of what an agent needs: target behavior, coordinate frame, clamping, and release behavior. The only substantial omission is the role of 'seconds', which prevents full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions and 0% coverage, so the description must compensate. It explains x and y conventions and their ranges, but says nothing about the required 'seconds' parameter, leaving a meaningful gap in how to invoke the tool with the correct semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Turn the camera') with the input mechanism ('right stick') and a clear precondition ('NO FOCUS NEEDED'). It also distinguishes the tool from sibling client_move by clarifying that this is a camera-look operation, not a movement operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives helpful context ('NO FOCUS NEEDED') and references client_move for units, but it never explicitly states when to choose client_look over client_move or another input tool. The reader must infer that this tool is for camera control rather than character movement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Walk the character with the left stick. NO FOCUS NEEDED.
x is positive to the right, y positive forward, both in [-1, 1] and
clamped (and reported as clamped) beyond that. client_move(0, 1, 6) is the
measured 24 m walk. The stick is back at rest when this returns, on every
path including a failure -- a stick left engaged is a character running
forever with nobody watching.
This is the only tract that moves the character at all: keyboard emulation was measured at 0 m over 25 s with the foreground verified. It is also the only one that is ANALOG, so "walking rather than sprinting" is testable here and nowhere else.
The first call attaches a virtual controller to this machine, which the
game can see -- DayZ switches its on-screen hints to controller mode -- and
the answer says so. client_stop unplugs it.
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| seconds | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly. It discloses axis directions, coordinate ranges, clamping behavior, a concrete calibration example (client_move(0,1,6) = 24m walk), stick-rest-on-return semantics including failure paths, and the side effect of attaching a virtual controller visible to the game. This is exemplary behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then packs essential behavioral details, units, side effects, and failure safety into a compact text. Every sentence adds substantive information; none are filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a movement tool with no annotations and an output schema present, the description covers everything an agent needs: effect, coordinate semantics, calibration, device state on return, failure behavior, and integration with client_stop. No critical operational context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 all three parameters. It does: x positive to the right, y positive forward, both clamped to [-1,1], and the example implies seconds is a duration. All parameters are meaningfully explained beyond their bare names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Walk the character with the left stick') and resource (character), and explicitly distinguishes itself as the only tract that moves the character and the only analog movement option among many siblings. Clear verb, resource, and differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: this is the only tool that moves the character at all, and the only analog one, so 'walking rather than sprinting' is testable here and nowhere else. It also mentions `client_stop` as the companion to unplug the virtual controller, giving clear context on related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Press one gamepad button. NO FOCUS NEEDED -- this drives the INTERFACE too.
Measured with a third-party application holding the foreground the whole
time: right_shoulder moved between options tabs, back opened and closed
the inventory, b left the menu. So menus and inventory are reachable
without ever taking the screen from the person at the machine, and that is
why this module offers no window messages and no mouse: window messages
were measured to do nothing at all.
What a pad cannot do is type -- DayZ has no on-screen keyboard. Text in
chat goes through client_chat (server-side, no focus); text in a mod's own
input field goes through client_type (real input, foreground).
Buttons: a b x y back start left_shoulder right_shoulder left_thumb right_thumb dpad_up dpad_down dpad_left dpad_right.
| Name | Required | Description | Default |
|---|---|---|---|
| button | Yes | ||
| seconds | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the tool works without focus and drives the UI, and it explicitly states it cannot type. It also notes that no mouse or window messages are used, making the behavior transparent. However, some details like the mention of a third-party application are not essential and slightly obscure the transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is unnecessarily verbose and repetitive. Phrases like 'Measured with a third-party application holding the foreground the whole time' and 'window messages were measured to do nothing at all' add little value and are redundant. The structure could be much more concise and focused.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides good context about the tool's capabilities and limitations (no typing, works without focus, lists buttons). However, it does not mention the output or return value, even though an output schema exists. This leaves a gap in understanding what the tool returns, but given the simplicity of the tool, it is a minor omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description enumerates all valid button names (a, b, x, y, back, start, left_shoulder, right_shoulder, dpad_up, dpad_down, dpad_left, dpad_right), which is crucial for the `button` parameter. It does not explain the `seconds` parameter explicitly, but the default (0.1) and context imply it is press duration. Overall, parameter meaning is well-addressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Press one gamepad button.' It also specifies the resource (gamepad) and distinguishes it from other input tools by noting it works without focus. The verb 'Press' is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool versus alternatives: it mentions that text input should go through `client_chat` and `client_type`, and clarifies that this tool is for button presses without focus. This provides clear guidance on usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture the client's window to a PNG. NO FOCUS NEEDED.
Measured rather than assumed: the frame is live with the client at the very bottom of the z-order and live when it is in front. The one state it cannot survive is MINIMIZED -- the client area collapses to 0x0 and there is nothing to copy -- and that is refused with a hint saying to restore the window, not reported as an empty picture.
lit_fraction in the answer is the honest half: a black capture is exactly
the failure that otherwise reports success, so the fraction of non-black
pixels comes back with every shot. A dark frame is never failed -- night is
dark -- but a caller reading 0.0 knows the eyes were shut.
With no path the file lands in this project's own .dayz-mcp/shots.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so impressively. It discloses that the capture is 'measured rather than assumed,' explains the minimized state refusal instead of an empty result, and reveals a critical failure mode: what appears to be a successful capture can be a black image, so 'lit_fraction' is returned to disambiguate. This goes far beyond the schema and gives an agent real insight into what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-structured, starting with the core action in the first sentence and then adding behavioral nuances in tight paragraphs. Some phrases, such as 'the honest half' or 'dark frame is never dark' arguably are stylistic, but they still convey important expectations without unnecessary bulk. More precise language could trim a few words, hence not a full 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter schema and available output schema, the description provides complete coverage of the client's screen semantics. It addresses the main failure mode (minimized), the edge case of black frames, the meaning of 'lit_fraction', and the default output location. An agent has enough detail to call the tool correctly and interpret its results without further documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes the sole 'path' parameter only by type and default, with 0% description coverage inside the schema. The description compensates by explaining what happens when path is omitted: 'the file lands in this project's own .dayz-mcp/shots.' This adds meaning beyond the schema, though it does not fully specify the semantics of an explicitly provided path (e.g., whether it is a directory, full filename, or expected extension).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Capture the client's window to a PNG.' This clearly distinguishes client_shot from sibling tools like client_press, client_chat, or client_move, none of which involve visual capture. The bold 'NO FOCUS NEEDED' additionally clarifies the operational constraint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides meaningful usage context: it explicitly states the tool works with the client both at the bottom of the z-order and in front, and warns that the only unusable state is MINIMIZED, where 'the client area collapses to 0x0 and there is nothing to copy.' This gives clear when-to-use and when-not-to-use guidance, though it does not compare against alternative sibling tools because none exist for this purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start the game client and connect it to the test stand. Returns a job id.
Three things worth knowing before calling, all of them observable:
IT LAUNCHES WINDOWED, always. A fullscreen D3D window does not yield the foreground -- an attempt to cover one simply hung -- so a fullscreen client can be neither typed into nor left behind while the owner works. The window size itself is the client profile's business (DayZ.cfg), not this server's.
IT REFUSES WHEN THERE IS NO STAND TO JOIN. The client connects, it does not listen, so there is no port of its own to pre-flight; what there must be is something already on the stand's port. Without that the client sits at the server browser forever and every later tool answers about a client that never joined anything.
IT READS pauseMode AND WARNS. That setting (GAME -> UPDATE IN BACKGROUND,
stored in the client's own profile) is why the screenshot is a live frame
and why the gamepad moves the character while another window has the
foreground. At another value both stop working with nothing said anywhere,
so the value is reported on every start and a warning is attached when it is
not the one measured here. It is never rewritten: it belongs to the person
who owns this machine and is changed from inside the game.
READINESS IS THE PLAYER COUNT IN THE BRIDGE STATE, NOT A TIMER. Connecting
took about 50 s when it was measured and it varies; a timer would call a
still-loading client ready and a never-connecting client a success. The job
finishes when the bridge publishes players >= 1, and if that never
happens the failure says which of the two things went wrong -- the bridge
was never readable (the signal was unavailable) or it was readable and
nobody joined (the client itself did not get in).
extra_args appends launch arguments after the fixed ones, an explicit
one-run opt-in. Arguments this tool computes (-connect, -port, -mod,
-profiles, -window, -nolauncher) are refused rather than allowed to
displace its own.
| Name | Required | Description | Default |
|---|---|---|---|
| timeout | No | ||
| extra_args | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels. It discloses that the client launches windowed (with a rationale), refuses connection without a stand, reads and warns about pauseMode, defines readiness by player count rather than a timer, and explains failure reporting. It also reveals the extra_args opt-in behavior and refusal of computed arguments. This is exceptional transparency beyond basic annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Though lengthy, every sentence adds essential context. The structure uses clear headings ('IT LAUNCHES WINDOWED...', 'READINESS IS...') to front-load critical knowledge. No redundant filler; each paragraph addresses a distinct aspect of behavior. Despite its length, it is efficient and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers prerequisites, return value (job id), failure modes, behavioral quirks, and parameter restrictions. It even explains how to interpret readiness. The output schema is present, so return format is assumed. This is a model of completeness for a complex tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. It thoroughly explains extra_args, including its append-only nature and protected arguments. However, timeout is left entirely undocumented in both schema and description; an agent must infer its role (likely a wait limit). This is a notable gap for a parameter that controls the tool's blocking behavior. Overall, partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific statement: 'Start the game client and connect it to the test stand. Returns a job id.' This identifies the verb, resource, and outcome. It distinguishes the tool from siblings like client_status and client_stop by its unique launch role. No ambiguity about what it does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive contextual guidance on when to call it: it requires a stand to join, explains the readiness condition (player count, not timer), and warns about windowed mode. It implies the appropriate timing and prerequisites. However, it does not explicitly state when NOT to use it or name alternative tools, though the conditions make that clear. Slight gap in explicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything about the client that decides whether the other tools can work.
Four questions in one answer, because each of them has silently broken a run before: is the process alive; is its window in a state the eyes can capture (a MINIMIZED window cannot be captured at all -- its client area is 0x0); is UPDATE IN BACKGROUND still at the value that keeps the frame live and the gamepad effective while unfocused; and has the client actually joined the stand (the player count the bridge publishes).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description hints at underlying logic (process liveness, window state, update flag, joined state) but does so in a metaphorical and unclear manner. It fails to disclose the return value, side effects, or how the four checks are combined, leaving the behavior ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a long, meandering paragraph with unnecessary poetic language and filler (e.g., 'silently broken a run before'). It lacks a clear front-loaded summary and is not concise or well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool appears to be a status check, but the description does not explain what the tool returns (e.g., a boolean, a string, a verdict). It also does not cover error handling, when it might fail, or how the results relate to the mentioned checks. Given the minimal schema and output description, this is highly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so there is nothing to describe. The description does not add any meaningful clarification about implicit inputs or configuration, but this is not a significant gap given the empty parameter list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description vaguely states 'everything about the client that decides whether the other tools can work' but does not clearly specify the tool's function, resource, or output. The 'four questions' are cryptic and not directly tied to a concrete action or result.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool compared to sibling status-check tools like 'client_verdict' or 'server_status'. The description does not mention any conditions or scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop the client this session started, and unplug the virtual controller.
The pad goes with it deliberately. Nothing else in this tool set closes it, and a controller left attached is visible inside any game running on this machine -- DayZ switches its on-screen hints to controller mode as soon as one appears. Stopping the client is the end of the input session, so it is where the device is given back.
Takes no pid on purpose: the client runs the same executable as the server, so a pid argument could not be checked against the image the way server_stop's is, and "stop this pid" would become a general process killer.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and succeeds. It discloses the side effects: stopping the client, unplugging the virtual controller, and intentionally discarding the pad. It also explains the consequence of leaving a controller attached, including a concrete example with DayZ switching on-screen hints to controller mode.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately detailed and well-structured, front-loading the core action before explaining side effects and the deliberate absence of a pid parameter. Every sentence earns its place, including the DayZ example, which concretely justifies why the controller must be unplugged.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has no parameters and an output schema exists, the description need not explain return values. It fully covers what the tool does, when to use it, why it has no parameters, and the behavioral consequences of not using it. Nothing necessary for an agent to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and the schema is empty, which gives a baseline of 4. The description goes further by explaining why there is no pid parameter: the client and server share the same executable, so a pid argument could not be safely validated and would turn the tool into a generic process killer. This adds meaningful rationale beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: 'Stop the client this session started' and 'unplug the virtual controller.' It also explicitly distinguishes itself from server_stop by explaining that client_stop takes no pid because the client shares an executable with the server, preventing it from becoming a general process killer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly defines when to use the tool: 'Stopping the client is the end of the input session, so it is where the device is given back.' It also states that 'Nothing else in this tool set closes it,' ruling out alternatives, and explains why the pid-based approach of server_stop does not apply.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Type into a CLIENT-SIDE INPUT FIELD -- a mod's PDA, terminal or form. REQUIRES THE ACTIVE WINDOW, and takes it.
This is not chat. Chat is a server-side message and client_chat delivers
it with no focus at all; use that unless the point of the test IS the
typing. What this tool is for is the case the bridge cannot reach: a field
that exists only on the client, which can only be filled the way a person
fills it -- the input line opening, the characters landing in the field,
the keyboard layout behaving.
So it brings the client window to the front and VERIFIES that it got there before sending a single keystroke. If Windows refuses -- which it does to a background process -- nothing is typed and the refusal says so, rather than keystrokes going into whatever window the person at the machine is using. That accident happened here once and is why the verification is not optional.
A successful call reports that the foreground was taken, because that is a side effect on a human, not an implementation detail.
The text is typed as US-layout scancodes, because the client starts on another layout and a virtual-key code would produce different characters. Anything with no scancode is refused by name BEFORE the screen is taken -- an underscore that arrived as a hyphen once failed a run as if the mod were at fault.
submit presses Enter afterwards, so filling a field and confirming it does
not need a second tool that takes the foreground all over again. With
submit=True and EMPTY text it sends Enter and nothing else, which is the
only way anything in this tool set can confirm or open something. Measured
on a live client: the game binds its chat line to Enter alone, and the
virtual gamepad's A button -- the obvious candidate for a confirm -- moved
nothing in the pause menu at 0.1 s or 0.5 s, while B (back) dismissed it at
the default. So dismissing is a gamepad job and confirming is this one.
Empty text WITHOUT submit is still refused: it would take the foreground to
do nothing at all.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| submit | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that the tool takes the foreground, verifies it obtained focus before typing, refuses keystrokes if Windows denies focus, uses US-layout scancodes, rejects characters without scancodes by name before taking the screen, and exactly what submit/empty-text combinations do. It even explains the historical accident that made verification non-optional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but every sentence adds essential behavioral or safety information for a tool that can steal focus from a human user. The core purpose is front-loaded, and the length is justified by the tool's risk profile and the need to prevent the exact failure mode described.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there are no annotations, the description fully covers prerequisites (active window), side effects (foreground taken), safety checks, keyboard layout concerns, refusal behavior, submit semantics, and empty-text edge cases. An output schema exists, so the description need not explain return values. An agent has enough context to invoke the tool correctly and avoid the documented accident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain both parameters. It specifies that text is typed as US-layout scancodes and that unscancodeable characters are refused by name. It also details submit ('presses Enter afterwards'), including the special case of submit=True with empty text sending only Enter, and the refusal of empty text without submit. This goes far beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb and resource: 'Type into a CLIENT-SIDE INPUT FIELD -- a mod's PDA, terminal or form.' It clearly distinguishes itself from client_chat by explaining that chat is server-side and delivered without focus, while this tool exists for client-only fields that must be typed into like a person would.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when not to use it: 'This is not chat. Chat is a server-side message and client_chat delivers it with no focus at all; use that unless the point of the test IS the typing.' It also explains the submit behavior to avoid needing a second foreground-taking tool, giving clear context for when submit is useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Judge the running (or last) client by its own .RPT.
The .RPT and not a script log, and that is a finding rather than a preference: in the Steam DIAG build the script log receivers are compiled out, so -logToFile / -logToScript / -logToRpt inject nothing and no script_*.log is produced for a client at all. Whatever the mod printed to the RPT is here; whatever it wrote only to the script log does not exist, and this says so instead of returning a clean verdict over an empty file.
Not to be confused with log_verdict(source="client"), which judges the
throwaway profile a client_compile_check job produced. This one judges
the LIVE client -- the one client_start launched, against the stand.
since ties the verdict to a run (pass the value client_start returned):
a report last modified before it belongs to an earlier client and is
refused as a reason rather than silently judged.
| Name | Required | Description | Default |
|---|---|---|---|
| since | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors, such as ignoring script logs because they may not exist in certain builds, and that old reports (before 'since') are refused rather than silently judged. It does not mention any side effects or detailed file-handling logic, but the core decision-making is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is excessively verbose and repetitive, circling around the script log vs. RPT distinction multiple times. A more concise structure would improve readability without losing key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose and parameter semantics, but it does not describe the output/verdict format or possible values. Given the output schema is not shown, the user is left guessing what the tool actually returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema provides no description for 'since', the tool text thoroughly explains its meaning and how to use it (pass the timestamp from client_start). This compensates for the schema gap, though the explanation could be more concise.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool judges the running or last client based on its .RPT file, and it differentiates itself from log_verdict for compile checks. However, it gets bogged down in caveats about script logs, making the primary purpose slightly less immediate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly contrasts with log_verdict(source='client') and explains when to use this tool (for the live client) versus the alternative. It also gives concrete guidance on the 'since' parameter by instructing to pass the value returned from client_start, making the intended usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
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.
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.
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.
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.
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.
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.
Wait for a job to finish, or until timeout seconds pass.
timeout is clamped to at most MAX_WAIT_SECONDS (600s) regardless of what
is requested.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| timeout | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite having no annotations, it discloses the key behavioral trait: it blocks and that the timeout will be clamped to at most 600s. It does not mention behavior for missing or failed jobs, but the core blocking-and-timeout contract is well communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences deliver the complete contract: wait until finished, or wait until timeout, and timeout is capped. There is no redundant information and the most important semantics are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for an agent to invoke the tool correctly, especially because an output schema is present. It could still state what happens if the job ID is invalid or whether job failure is treated as a terminal state, but these are not severe gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description partially compensates by specifying timeout in seconds and explaining the 600s cap. job_id is not detailed in words, but its purpose is clear from the tool name and the natural reading of the sentence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action, wait, and its resource, a job, with a well-specified termination condition: job completion or timeout. This distinguishes it from sibling tools like job_status and job_artifacts, which check or use jobs without blocking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The wait and timeout behavior implies that this is for callers that need to block until a job reaches a terminal state. However, the description never explicitly says when to prefer this tool over job_status or other non-blocking status checks, leaving that routing decision mostly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build or refresh a knowledge layer. Returns a job_id immediately.
Layers, and how often each one needs this:
project the mod's own sources, read where they lie. Goes stale on every edit -- rebuild it whenever you want to ask about code you just wrote. Measured: 0.11 s for 41 files. deps the archives of the mods this project declares as dependencies, read without unpacking them. Stale when a dependency is updated or the declared set changes. Measured: 150 s for 36 mods. core the game itself: scripts.pbo for the API, Addons/*.pbo for the item classes. Stale when the game updates. Measured: 3.9 s for the scripts alone, 69 s with the configs. all (the default) every layer that applies to this project. Layers that cannot be built here -- no game installed, no dependencies declared -- are named with the reason instead of failing the call.
Nothing here blocks: wait with job_wait(job_id, timeout=...) and read the
per-layer numbers in the job's summary and its knowledge-build.json
artifact.
only=[path, ...] is the fast route for the project layer when you already
know what changed. It re-reads exactly those files and skips the directory
walk entirely -- and it therefore does NOT notice a file created or deleted
anywhere else. A named path that no longer exists is dropped from the
index, so a delete you name is handled; one you do not name is not. Without
only, every build is incremental anyway: unchanged sources are skipped by
size and modification time, and full=True forces the whole layer to be
re-read.
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | ||
| only | No | ||
| layer | No | all |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It discloses async behavior (returns job_id immediately), the non-blocking nature (wait with job_wait), the meaning of layers, and the nuanced semantics of 'only' (does NOT notice unlisted changes). Very thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Long but well-structured with layer breakdowns and examples. Every sentence contributes value (measurements, staleness triggers). Slightly verbose but justifiable given the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a multi-layer async tool. It covers all parameters, behavior, output (job_id, artifact), and integration with job_wait. The existing output schema (though not provided) handles return specifics, so the description adds the necessary behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain every parameter. It does: layer is explained with each possible value, 'only' gets a detailed semantics explanation (including edge cases like deleted paths), and 'full' is explicitly described as forcing a whole-layer re-read. Nothing is left to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource ('Build or refresh a knowledge layer') and distinguishes from siblings like knowledge_find (querying) and knowledge_status (status). The description explicitly enumerates the layer types and their staleness conditions, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context on when each layer is stale (e.g., 'rebuild it whenever you want to ask about code you just wrote') and explains the 'only' fast route for project layer. It doesn't explicitly name alternatives to not use, but the guidance is strong enough to route the agent correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who CALLS this -- every place a method is invoked or a class is built.
A different question from knowledge_overrides, and one no search over
declarations can answer: an override is a declaration, a call is not.
This is the question asked before changing a signature, before removing
something, and when working out how a piece of the game is actually used.
kind narrows to call or new. owner narrows to calls made from one
class. Each hit names the class and method it was made from, the file and
line, and the layer -- with that layer's age, like every other answer
here.
What it does NOT see, so that an empty answer is not read as proof: a call
reached through a variable whose type the index does not track is recorded
under the method's own name, not the variable's, and new array<string>()
has no identifier before its parenthesis to record at all.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| name | Yes | ||
| layer | No | ||
| limit | No | ||
| owner | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description openly states what the tool returns ('Each hit names the class and method it was made from, the file and line, and the layer') and explicitly discloses blind spots: 'What it does NOT see... a call reached through a variable whose type the index does not track...' This is thorough transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose and repetitive, using parallel poetic structures that restate the same ideas across three paragraphs (e.g., 'before changing a signature, before removing something' mirrors 'before changing a signature, before removing something'). It could be significantly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides enough context to understand the tool's core behavior, output, and use cases. It lacks details on parameters like `layer` and `limit`, but the overall context is sufficient for typical usage, especially with an output schema present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains `kind` ('narrows to call or new') and `owner` ('narrows to calls made from one class'), but does not explain `name`, `layer`, or `limit`. Since schema coverage is 0% and only 2 of 5 parameters are clarified, the description only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Who CALLS this -- every place a method is invoked or a class is built.' It explicitly distinguishes this from knowledge_overrides, making the resource and verb unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides usage context: 'A different question from knowledge_overrides' and advises using it 'before changing a signature, before removing something, and when working out how a piece of the game is actually used.' It also highlights limitations, guiding appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find declarations by name: classes, methods, constants, enums, configs.
Matching is case-insensitive and exact unless prefix=True. Answers come
nearest-layer-first -- the project's own declaration before its
dependencies', and those before the game's.
kind separates two namespaces that share a name space:
'class' a class declared in Enforce Script 'method' a function, with its owning class and full signature 'constant' / 'enum' what flags like ECE_* are found through 'config' a class declared in a config.cpp or a binarised config.bin -- this is how you ask "does the game have an item class called X". Kept apart because the game alone holds 88 102 of them against 43 595 script declarations, and mixed together they bury every script answer.
Every answer names the layers it used and how old each one is -- and an answer with no results names every layer it searched, because "not found" is worth exactly as much as the layers behind it are current. The project layer's staleness is measured on every call, so an answer taken from an index built before your last edit says so instead of describing code that no longer exists. A search that finds nothing while a layer that could have held it was never built is refused, not answered: "not found" and "not looked" are different facts.
Narrowing has the same trap one level down, so an empty narrowed answer
checks whether the name exists outside the narrowing and says where in
elsewhere -- asking for kind='class' about a name the game declares
only in a config gets a true "no" that reads as "the game has no such
class".
Every search runs under a hard time ceiling and a result limit; neither can be removed.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| name | Yes | ||
| layer | No | ||
| limit | No | ||
| owner | No | ||
| prefix | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It details case-insensitive matching, prefix behavior, layer ordering (nearest-first), staleness measurement on every call, the distinction between 'not found' and 'not looked', narrowing with `elsewhere` fallback, and hard time/result limits. This is exceptionally thorough and leaves no major behavioral surprises.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence contributes meaning. It leads with purpose, then dives into matching semantics, kind distinctions, output behavior, and edge cases in a logical order. It could be tightened (e.g., the config explanation is lengthy), but for a tool with this complexity, the density is appropriate and nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, 0% schema coverage, no annotations), the description covers most critical aspects: matching rules, kind semantics, layer ordering, staleness, empty-result behavior, and limits. It also describes output contents. However, it fails to mention the `owner` parameter entirely and does not fully specify acceptable values for `layer`, leaving those aspects incomplete for an agent to use the tool correctly in all cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. It explains `kind` in depth (with rationale for separation), `prefix` explicitly, and touches on `layer` via the layering concept and `limit` via the hard ceiling. However, the `owner` parameter is entirely unmentioned, and `layer` is not clearly defined as a parameter (e.g., what values it accepts). The description adds substantial meaning for some parameters but misses others, leaving gaps for an agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Find declarations by name' and enumerates the kinds (classes, methods, constants, enums, configs). This clearly distinguishes it from sibling tools like knowledge_show, knowledge_callers, and knowledge_scope, which have different scopes. The purpose is unambiguous and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use different `kind` values, including a concrete example ('does the game have an item class called X'). It explains the layer ordering and prefix behavior, and warns about situations where a search is refused due to missing index layers. However, it does not explicitly state when NOT to use this tool or name alternative tools as fallbacks, leaving some room for inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who overrides this class or this method -- the question a text sweep answers worst.
For a method: every declaration of it marked override, and every one
declared inside a modded class, which routinely replaces a method without
writing override at all. The original declaration is not an answer.
For a class: everyone who extends it, and every modded class that reopens
it.
Both readings are answered at once, because a caller asking "who overrides X" usually does not yet know which X it is. The answer names the layer each hit came from and how old that layer is; a search over a layer that was never built is refused rather than answered emptily.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| layer | No | ||
| limit | No | ||
| owner | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly. It discloses that the original declaration is not an answer, that both method and class readings are returned together, that results name the layer and layer age, and that searches over unbuilt layers are refused rather than returning empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every paragraph adds meaningful behavioral detail. The opening sentence front-loads the core purpose, and the subsequent paragraphs clarify method/class semantics and output behavior. It is somewhat verbose but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core semantics well, including method versus class handling, layer behavior, and refusal on unbuilt layers. However, with no annotations and 0% schema coverage, the unexplained 'limit' and 'owner' parameters leave gaps that an agent would need to resolve before calling the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. It adds meaning to 'name' by explaining it can refer to a class or method, and it implies the 'layer' parameter through the discussion of built versus unbuilt layers. However, 'limit' and 'owner' are never explained, and no explicit parameter mapping is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool answers 'who overrides this class or this method' and distinguishes between method and class semantics. It is specific about the resource and behavior, but it does not explicitly differentiate from sibling tools like knowledge_callers or knowledge_scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: when a caller needs to know overrides for a method or class, and it explains that both readings are answered at once. It does not mention alternatives or exclusions, but the intended use case is well conveyed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Declare, inspect or clear the active mod set.
With no arguments it reports the set in force and every mod folder the dependency layer holds, so a caller can see what there is to choose from.
mods=[...] narrows every knowledge answer to those mod folders. The game
and the project's own code always answer -- the game is the substrate a
DayZ mod is written against, and the project layer is the code being
written, so narrowing either would report "no such class" about code you
are looking at.
Nothing is hidden by the narrowing. A search whose answer lies in a mod outside the set does not come back empty: it comes back naming the mod that holds it, and it comes back as a refusal, so it cannot be read as "no such thing". That is the whole point of the feature -- an invisible narrowing is the same silent lie as an answer from a stale layer.
source is free text saying where the set came from ("the server at
clear=True returns the index to answering from every mod it holds. An
empty mods=[] is refused rather than read as "narrow to nothing": those
are different requests and only one of them is ever meant.
The set is stored beside the index and survives a restart. It is NOT
changed by server_mods, which only proposes one.
| Name | Required | Description | Default |
|---|---|---|---|
| mods | No | ||
| note | No | ||
| clear | No | ||
| source | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the set persists across restarts, that clear resets it, that server_mods does not modify it, and that empty mods array is refused. It also explains that narrowing affects knowledge answers. This is comprehensive, though the repetitive and metaphorical wording ('silent lie') may confuse rather than clarify.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is excessively verbose and repetitive. Similar concepts ('narrow', 'silent lie', 'narrowing') are restated multiple times with poetic metaphors. While it has a logical flow (declaration, per-parameter explanations, persistence note), the length and redundancy severely hurt readability and quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers essential behavioral aspects: how the tool behaves with no arguments, with mods, clear, source, persistence across restarts, and its relationship to server_mods. It also mentions edge cases (empty mods list). Since an output schema exists, return values need not be explained. Overall, it is complete despite being over-embellished.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions, so the tool description must compensate. It explains mods (narrows answers, empty array refused), clear (resets to all mods), and source (free text label). Note is not mentioned, but the other three parameters are well described, adding significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear statement of purpose: 'Declare, inspect or clear the active mod set.' This distinguishes it from siblings like knowledge_find or server_mods, though the subsequent verbose metaphors could obscure the core functionality for some agents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains behavior under different arguments (no args, mods, clear, source) and contrasts with server_mods, but does not explicitly say 'use this when you need to scope knowledge queries' or provide direct comparison with alternative tools like knowledge_find or world_* tools. Guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything the index holds about one declaration.
Where knowledge_find lists matches, this expands them: the full
signature, the file and line, what the declaration inherits from all the
way up, and -- for a class -- what is declared inside it.
body=True reads the declaration back out of the source it was indexed
from, up to max_lines lines, including out of an archive that was never
unpacked. A binarised config has no readable source to return and says so
rather than returning nothing.
Matches come nearest-layer-first, so a class a dependency reopens with
modded class is shown before the game's own declaration of it: pass
layer='core' to ask the game specifically.
Like every answer here, it names the layer each declaration came from and how old that layer is -- and when it finds nothing, every layer it looked in.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | ||
| kind | No | ||
| name | Yes | ||
| layer | No | ||
| limit | No | ||
| owner | No | ||
| max_lines | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It details behavior such as reading source from the index, handling archives and binarised configs, returning layer information, and reporting which layers were searched when nothing is found. It does not mention side effects but covers key edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose with multiple paragraphs, each adding useful context but resulting in a dense block of text. The structure is clear but not concise; it could be trimmed to essential information without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It explains the tool's behavior well and references an output schema separately. However, it does not clarify the meaning of parameters like limit and owner, nor does it specify behavior when multiple declarations match the given name. This leaves some gaps for a tool with 7 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain parameters. It explicitly covers body, max_lines, and layer, but omits limit, owner, kind, and name. While name is self-explanatory, the others are left undefined, leaving gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool shows everything the index holds about one declaration, distinguishing it from knowledge_find which lists matches. It specifies the verbose/resource combo: retrieving full details of a single declaration from a knowledge index.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly contrasts with knowledge_find: 'where knowledge_find lists matches, this expands them,' indicating to use this tool when full details of a specific declaration are needed. It also provides a concrete usage hint with layer='core' to target the game's own declaration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What each knowledge layer holds, how old it is, and whether it still matches what is on disk.
Staleness is a measurement, never a guess: each layer records the size and modification time of every source it read, and this compares them against the files as they are now. A layer reports what changed, what appeared and what is gone -- so "the project was edited" is a different fact from "the game was updated", which is the whole reason there are three layers.
Two counts that must not be confused, and both are here: sources is
everything the build walked, and empty_sources is how many of those gave
no declarations at all -- an archive that could not be read, or a file that
genuinely declares nothing. Which of the two is in last_build: skipped
is what the LAST build could not read, and outstanding is every source
the layer still holds nothing from, including ones an earlier build found.
The second exists because the first is correctly empty after an incremental
build that re-read nothing, which left empty_sources standing with no
explanation at all.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It fully discloses the measurement mechanism (comparing size and modification time against disk), the semantics of 'sources' vs 'empty_sources', and the subtle distinction between 'skipped' and 'outstanding', including why 'outstanding' exists after incremental builds. This goes far beyond typical transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than strictly necessary, but it is structured logically—first the overall purpose, then the staleness measurement, then the detailed explanation of the two counts. The front-loaded purpose is clear, and every sentence adds substantive information, though it could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the staleness semantics and the presence of an output schema, the description is entirely complete. It covers what each layer holds, how staleness is computed, and the meaning of both counts, including edge cases like incremental builds. No necessary information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameters, so the baseline is 4. The description adds valuable meaning to the return values by explaining the meaning of the counts and their relationship, which compensates for the lack of an output schema in the given context (though an output schema exists per signals). No params are left undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('holds', 'how old', 'matches') for the knowledge layers, and explains the core concept of staleness as a measurement. It clearly distinguishes the purpose from other knowledge tools (e.g., searching or showing) by focusing on status and integrity, though it does not name a sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for inspecting layer status and staleness, but it does not explicitly contrast with alternatives like knowledge_find or knowledge_show, nor does it state conditions for when to prefer this tool. The context is clear but exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | ||
| source | No | server | |
| pattern | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
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.
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.
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.
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.
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.
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.
Judge the newest log for source.
since ties the verdict to a specific run (typically the value server_start
returned): a log last modified before since cannot belong to the run being
judged -- it is a leftover from an earlier boot (possibly one still holding the
file open on Windows) -- so it is refused as a reason, not silently judged.
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | ||
| source | No | server |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does disclose a non-obvious trait: logs modified before `since` are 'refused as a reason, not silently judged,' including a Windows file-lock nuance. It does not mention side effects or permissions, but the refusal behavior is genuinely informative beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, stating purpose in the first sentence and then concentrating all nuance into one focused paragraph about `since`. Every sentence earns its place and there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core behavior and the subtle `since` behavior are covered well, and an output schema exists so return-format details are not required. Still, `source` is under-specified and there is no cross-tool guidance, leaving the description slightly incomplete for self-contained agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds real meaning to `since` by tying it to a run and explaining the cutoff behavior, which compensates for 0% schema coverage. However, `source` is only echoed as a placeholder and never given semantic meaning or expected values, so the description only partially compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Judge the newest log for `source`.' It is clear that this tool evaluates a log, but it does not differentiate itself from siblings such as log_tail or client_verdict, and the exact meaning of 'judge' 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful workflow context for `since`, noting it is 'typically the value `server_start` returned,' and explains the consequence of a too-old log. However, it never explicitly says when to call this tool instead of alternatives like log_tail or client_verdict; usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pack this project's mods. Returns a job_id.
Runs mod_lint first and refuses on what it refuses. That check costs
milliseconds and the boot it replaces costs a minute -- and two of the
defects it names would not appear in that boot's log at all, because a
modded class that modifies nothing loads and reports success.
skip_lint=True packs anyway. It exists because a refusal that cannot be
overridden is a refusal that gets worked around by not using the tool.
| Name | Required | Description | Default |
|---|---|---|---|
| skip_lint | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although annotations are absent, the description goes beyond a simple call to action. It discloses that it runs mod_lint first, that failure to lint blocks the build, that running lint is cheap, and that skipping lint can mask real defects (the example of a modded class that loads and reports success). This is rich behavioral context that an agent needs to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is slightly verbose with the runtime-cost rationale, but the first sentence is sharp and the extra lines about skip_lint earn their place by explaining a non-obvious parameter. It is well-structured with the main purpose first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single boolean parameter and an output schema, the description covers what the tool does, what it returns, when to skip lint, and the safety/correctness rationale. It's complete for an agent to decide when to call it and what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a boolean with a default and title, but 0% description coverage means the description must explain it. It does: skip_lint is introduced and its purpose/rationale are clearly described. Could add a touch more about consequences (e.g., potential build failure), but the current explanation is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('Pack this project's mods') and states the return value ('Returns a job_id'). It clearly distinguishes this from sibling tools by describing the lint-first behavior, which no other tool describes. The purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use skip_lint and why: skip_lint packs anyway, and the rationale ('a refusal that cannot be overridden is a refusal that gets worked around') provides clear guidance on when to override. It also implies normal usage (use without skip_lint) and the alternative of fixing lint errors first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a mod's Enforce Script without packing or booting anything.
mod limits the check to one of the project's mods; empty checks them
all. strict makes warnings count as failure too -- off by default,
because a warning is something to read, not something to stop for.
Refusals: a class that extends itself (modded class X extends X loads
and applies nothing), an exception statement (try/catch/finally are
not Enforce), and a modded class whose target nothing declares.
Warnings: a statement continued onto the next line with a leading +,
which Enforce drops silently.
The modded class check needs the knowledge index, and says so when the
index cannot answer: an unbuilt layer makes it warn rather than accuse,
because "no such class" and "I have not read the game yet" are different
answers and only one of them is the mod's fault.
| Name | Required | Description | Default |
|---|---|---|---|
| mod | No | ||
| strict | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility and excels: it discloses non-destructive behavior (no packing/booting), defines refusal and warning categories, and details the knowledge-index dependency and its fallback to warning rather than accusing. This is comprehensive behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a bit long but each sentence adds value: core purpose, parameter semantics, refusal conditions, warning conditions, and a behavioral caveat. It is well-structured with bullets-ish paragraphs and front-loads the primary function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all critical aspects: what the tool does, parameter effects, edge cases (self-extension, exceptions, unresolved modded class), and the dependency on the knowledge index. Since an output schema exists, not explaining return format is acceptable, making this complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage, but the description fully explains both parameters: mod (restrict to one mod or default to all) and strict (treat warnings as failures, default off). It adds meaning that the schema alone lacks, fully compensating for the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks a mod's Enforce Script without packing or booting, distinguishing it from build operations. It specifies the scope (one mod or all) and the strict flag, making the purpose concrete and distinct from siblings like mod_build or client_compile_check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains parameter behavior (mod empty = all, strict defaults to false) and the conditions for refusals vs warnings. It doesn't explicitly name alternatives or say when to prefer this over building, but the 'without packing or booting' phrasing implies it's for quick validation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
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.
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.
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.
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.
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.
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.
Ask a running server which mods it runs, and PROPOSE an active set.
address is "host" or "host:port"; query_port overrides an embedded one.
It must be the QUERY port, not the game port. The game port never
answers a Source query -- measured on six live servers, silent on all six,
while the query port answered on all six. The two are not related by a
fixed offset (252 distinct offsets in a live sample): a server browser
shows it, and for a local stand it is steamQueryPort in the server config.
The answer is three buckets, matched by Workshop id and never by name:
matched the server runs it and it is installed here on_server_not_installed the server runs it and this machine has not installed_not_on_server installed here, the server does not run it
Nothing is applied. proposed_scope and apply are a suggestion and
the exact call that would take it; running that call is a separate,
deliberate act. A query that silently rescoped the index would make a
mismatch an invisible action rather than something the caller read.
Three things this cannot see, and it says so in notes rather than letting
the answer read as complete: server-only mods (reasoned, not tested), the
BUILD of a mod behind an id, and mods downloaded but not linked into the
modpack.
| Name | Required | Description | Default |
|---|---|---|---|
| address | No | ||
| timeout | No | ||
| query_port | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden and does so exceptionally well. It explicitly states 'Nothing is applied,' explains matching is by Workshop id and never by name, and discloses three categories of things the tool cannot see. This goes far beyond a typical description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and uses bold labels, bullets, and clear separations. The empirical detail about six live servers and 252 distinct offsets is useful but somewhat heavy; it earns its place for port guidance but makes the description denser than strictly necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the key contextual needs: non-mutating behavior, port semantics, result buckets, and known limitations. It does not clarify whether address is effectively required despite having zero required parameters, nor what timeout means precisely. The output schema reduces the need to explain return values in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It adds real meaning for address ('host' or 'host:port') and for query_port (overrides embedded port and must be the QUERY port). The timeout parameter is left without explicit units or behavior, which prevents a higher score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific, actionable statement: 'Ask a running server which mods it runs, and PROPOSE an active set.' It clearly identifies the resource (a running server's mods) and the unique contribution (proposing an active set), distinguishing it from siblings like server_status or mod_build.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives strong operational guidance: use the QUERY port, not the game port, and explains with evidence why the game port will fail. It also clarifies how results are bucketed and that nothing is applied. However, it does not explicitly name alternative tools or state when to prefer them, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read -- or deliberately change -- the stand's signature policy.
With no argument this only reports. With value it writes verifySignatures
into the config the profile names as this stand's, and reads it back.
WHY THIS IS ITS OWN TOOL. verifySignatures = 2 makes a stand refuse every
client with code 118 and "missing dtain.pbo" -- a vanilla file name that
says nothing about signatures, and that has already cost one session a long
hunt through byte-identical files. On a local stand the honest fix is
usually to turn the check off rather than to sign a throwaway bridge mod,
and doing that by hand in somebody's config is worse than doing it here,
where the previous value is reported, the file is read back, and nothing
else in it is touched.
WHAT KEEPS IT SAFE. It edits exactly one file: machine.stand_root /
machine.config, the stand this project already boots, and it refuses a
path that resolves outside that root. It refuses while a server is running
against that config, because a change the running server will never read is
a success message about nothing. And it says which way the setting moved:
0 is off, and the answer says so in words rather than leaving a number.
| Name | Required | Description | Default |
|---|---|---|---|
| value | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full weight. It discloses the read vs. write behavior, the safety check about editing exactly one file within the root, refusal while a server is running, and the output semantics ('says which way in words'). This is exemplary for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Text is clear and well-organized with headers, but slightly verbose. Some redundancy (e.g., 'has already cost one session a long hunt') adds color but could be trimmed. Still, every paragraph earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers purpose, behavior, safety constraints, failure modes, and output semantics. Even with an output schema, the description's narrative provides richer context. It's complete for an agent to decide when and how to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has one nullable integer parameter with a default of null meaning no argument; description explains that `value` writes and no argument reads. It doesn't constrain valid integers beyond 0/1/2 implied, but that's fine. Schema coverage is 0% so description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads or writes the `verifySignatures` setting in a server config, and explicitly positions it as a distinct tool with rationale. It distinguishes itself from siblings like server_start/stop by focusing on policy editing rather than lifecycle management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use it (no argument = read; with value = write), and provides a strong 'WHY THIS IS ITS OWN TOOL' section explaining the failure mode and why using this tool is preferred over manual edits. It doesn't explicitly name an alternative, but the rationale implies it's the right tool for signature-check toggling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start the test server and wait for it to be ready. Returns a job id.
Two things worth knowing before calling, both observable:
It CLEARS THE BRIDGE TRANSPORT first -- the command mailbox and the state
file in the -profiles directory are removed before the server is spawned, so
no world ever starts against a command or a state document left by an
earlier one. Script logs are deliberately left alone; see
clear_bridge_transport for why the two are treated differently. A file that
could not be removed is reported in bridge_transport_left and on the job,
and never fails the boot.
It REFUSES if the game port is already held, naming the pids holding it. A stand is shared -- one machine, one port, one profile directory -- and booting into a held port produces a server that dies during world load with nothing in its own log to say why. If the holder is a server this session started, the hint says to stop it with server_stop. If it is anyone else's, the refusal identifies it (pid and -mod= tail) and offers stopping it as the caller's own act -- the owner authorised stopping a neighbouring stand that blocks a live run -- but this tool never auto-stops a process it did not start.
extra_args appends launch arguments after the fixed ones -- an explicit
one-run opt-in, the same pattern as attaching the bridge, not profile
surgery. A list of strings, never one string to re-split. Arguments the
tool itself owns (-config, -profiles, -port, -mod, -serverMod) are refused:
the profile is where those are decided. The extras are recorded in the boot
job's summary, so a later reader can see the boot was non-standard. The
known use is the engine's action log (-doScriptLogs=1 -logToFile=1),
which writes to scriptExt.log -- a file log_verdict never reads, so these
flags cannot poison a verdict.
Readiness has two independent signals, and the summary always names which
one answered. expect.ready_line appearing in a log written by THIS run
says the MOD finished loading. The game port being bound by the pid we
spawned says the ENGINE is up and listening -- which needs neither a mod nor
a declared line, and is the readiness verdict for a project that declares
none (measured on a real stand: bound 16.9s after spawn). With a ready line
declared it remains the verdict, since a bound port cannot say a mod loaded;
the port is then what tells "the boot failed" apart from "the server is
listening and it is the mod's line that never appeared".
| Name | Required | Description | Default |
|---|---|---|---|
| timeout | No | ||
| extra_args | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It reveals that the tool CLEARS THE BRIDGE TRANSPORT before spawning, reports but never fails on left-behind files, never auto-stops a process it did not start, refuses certain reserved arguments, and resolves readiness from two independent signals while reporting which one answered. This is precisely the hidden behavior an agent needs to predict the side effects of a server boot.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but it is structured and dense: bolded signal words ('CLEARS THE BRIDGE TRANSPORT first', 'REFUSES if the game port is already held') front-load the critical warnings, and each paragraph earns its content. Minor asides like the measured 'bound 16.9s after spawn' provide a useful real-world anchor but could be trimmed if brevity were a priority.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A complex tool with no annotations and only 0% schema description coverage — the description compensates well: cleanup semantics, port-conflict refusal, extra argument rules, log-record behavior, and the dual-signal readiness logic are all covered. The only meaningful gap is the timeout parameter's role and what its expiry implies, which is left entirely to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The extra_args parameter is exceptionally well described: it must be a list of strings, is appended after fixed arguments, is an explicit one-run opt-in, refuses the tool's own flags, and is recorded in the boot job's summary. However, the timeout parameter (default 420) is never mentioned at all, and schema description coverage is 0%, so the description must compensate — the omission is not covered anywhere.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence is explicit and compact: 'Start the test server and wait for it to be ready. Returns a job id.' It names the specific verb, the resource, the behavior, and the return contract in one breath. It also clearly distinguishes this tool from its siblings like server_status, server_stop, and world_ready — this is the lifecycle-start action, not an observer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides real decision points: it 'REFUSES if the game port is already held,' names the pids holding it, and explicitly routes the caller to server_stop when the holder is a server this session started. It also gives the when-not-to-invent pattern for extra_args ('never one string to re-split') and explains that profile surgery belongs elsewhere, not here. It stops short of listing alternatives for every scenario, but the guidance given is concrete and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A quick health read: is the process alive, and is its log actually growing.
A hung boot and a slow one both look "alive, no ready line yet" from the
outside -- this project has hit a genuine post-compile server hang before --
so this samples the newest log's size twice, pulse_seconds apart, and also
reports how long it has been since the log last changed at all.
| Name | Required | Description | Default |
|---|---|---|---|
| pulse_seconds | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It does well by revealing that the tool samples the newest log's size twice pulse_seconds apart and reports recency of the last log change, adding meaningful behavior beyond a simple 'is it alive' check. It doesn't claim any side effects, and 'health read' implies a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with a clear summary in the first sentence. The following sentences add useful rationale and behavioral detail about why two samples are taken. The brief historical note about a post-compile hang is slightly extra, but it supports the tool's purpose without bloating the definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple one-parameter read-only tool, and an output schema exists, so the description doesn't need to explain return values. The description covers the tool's purpose, input parameter, and core behavior, leaving no critical gaps for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain pulse_seconds. It does so by stating the tool samples the log's size twice 'pulse_seconds apart,' which defines the parameter as the sampling interval. However, it doesn't elaborate on units, acceptable ranges, or the effect of choosing a larger or smaller value beyond the obvious.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a health read: checking if the server process is alive and if its log is actually growing. This distinguishes it from sibling status tools like project_status, bridge_status, and client_status, though it doesn't explicitly name an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: as a quick health read, especially when a hung boot and a slow boot look similar from the outside. However, it does not explicitly state when not to use it or which sibling tool to prefer in other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a server this session is responsible for.
With no pid, stops the session's own currently tracked server (the
original behaviour). With pid, stops that specific process instead --
but only if this session started it at some point, or it was reported as
orphaned_server_pid by project_open after a project switch (see
session.known_pid). Any other pid is refused: this is the only way an
orphaned server can be reached at all, and it must not become a general
process killer.
Either way, the pid is checked against the recorded image name before it
is handed to stop() (which calls taskkill): a recycled Windows pid can
belong to an unrelated process by the time this runs, and killing that
process instead would be a worse outcome than the stale bookkeeping this
guards against.
| Name | Required | Description | Default |
|---|---|---|---|
| pid | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the safety check against the recorded image name before invoking stop(), and explains the rationale (recycled Windows pids could target unrelated processes). It also mentions that stop() calls taskkill, providing concrete behavioral transparency beyond the simple 'stop' action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Though the description is a few paragraphs, every sentence contributes critical information: main action, two modes, eligibility rules, orphaned access, and safety rationale. It is front-loaded with the primary action and uses structured paragraphs for edge cases, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no annotations and a minimal schema, the description is exceptionally complete. It covers what the tool does, when to use it vs. not, the exact conditions for pid acceptance, the safety mechanism, and the underlying implementation (taskkill). An agent has all necessary context to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a pid integer with default 0 and no description, so schema coverage is 0%. The description compensates fully by explaining the semantics of pid: absence stops the session's own server, presence stops a specific pid only if it meets eligibility criteria (started by session or orphaned), and any other pid is refused. This adds deep meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb + resource combination: 'Stop a server this session is responsible for.' It distinguishes two modes (own tracked server vs. specific pid) and explicitly differentiates from siblings like server_start and server_status by defining scope ('this session is responsible for').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides precise when-to-use guidance: no pid stops the session's own server, while a pid stops that specific process only if it was started by the session or reported as orphaned_server_pid. It explicitly refuses any other pid, and states that this is the only way to reach an orphaned server, preventing misuse as a general process killer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Press a widget, by path, having checked it is still the one meant.
expect_name and expect_class are how a path stops being a loaded gun. A
tree walked a minute ago is not the tree in front of the mouse now, and
pressing "whatever is at 0.3.1 today" is how an automated run presses the
wrong button and reports success. Both are optional -- sometimes the caller
genuinely means "whatever is there" -- but then that is the caller's own
decision, taken in the open.
TWO TRACTS, and the answer always says which one was used:
via="script" delivers the click to the open menu's own handler. Works
with the client in the background, no focus taken. Reaches ONLY the open
scripted menu: Widget has no GetHandler, so a HUD widget's own handler
is not reachable from script at all.
via="cursor" puts the real mouse on the widget's rectangle and clicks.
Reaches anything the player could click -- and TAKES THE FOREGROUND, like
client_type, because a real click goes wherever the real cursor is.
A handler that returns false is reported as what it is: the click was delivered and the menu did not act on it. That is a fact about the mod, not a failure of this tool, and the answer says so rather than inventing a verdict.
| Name | Required | Description | Default |
|---|---|---|---|
| via | No | script | |
| path | Yes | ||
| root | No | menu | |
| button | No | ||
| timeout | No | ||
| expect_name | No | ||
| expect_class | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure, and it excels. It reveals that the tool checks the widget identity via expect_name/expect_class, that script delivery reaches only the open scripted menu (HUD widgets are unreachable), that cursor delivery steals foreground, and that a handler returning false is reported as a fact about the mod rather than a failure. These are significant behavioral traits beyond the schema, and they are clearly articulated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence adds value. It fronts the core purpose and the safety rationale, then clearly distinguishes the two via tracts with examples, and finally explains the handler-false behavior. The formatting with headers and code formatting aids scanning. No filler or unnecessary repetition – it is appropriately concise for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 7 parameters and no schema descriptions, the description covers behavior thoroughly but omits parameter semantics for root, button, and timeout. The output schema exists, so return format is not a burden, and the description does mention that the answer indicates which tract was used and how handler-false is reported. Still, the missing parameter details leave the tool incompletely specified, especially for an agent that must supply or adjust these defaults.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameter descriptions, so the description must compensate. It explains the purpose of path (the widget path), via (delivery mechanism), expect_name and expect_class (identity checks). However, it does not explain root (default 'menu'), button (default 0), or timeout (default 45). With 7 parameters and 0% schema coverage, partial coverage leaves a meaningful gap for agents trying to call the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise statement of what the tool does: 'Press a widget, by path, having checked it is still the one meant.' This names the specific verb, resource, and a key safety verification. It clearly distinguishes itself from generic click tools (like client_press) by focusing on path-based UI interaction with expectation checks. The two via modes (script vs cursor) further clarify its scope, making it unambiguous versus siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the two via modes: 'via="script"' for open scripted menus (works in background, no focus) and 'via="cursor"' for anything the player could click (takes foreground). It also explains the expectation checks as a way to avoid pressing the wrong widget. However, it does not directly mention alternative tools like client_press or when to prefer this over them, leaving the broader selection context implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find widgets by name, class or text, without fetching the whole tree.
name and class_name match exactly; text matches as a substring,
because a label's exact string is the one thing a caller rarely knows in
advance. At least one of the three is required -- with none of them this
would be ui_tree, and answering it as such would hide which question was
actually asked.
Filtering happens in the client, not here: sending the whole tree back so it could be filtered locally is exactly what the page limit exists to avoid.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| root | No | menu | |
| text | No | ||
| depth | No | ||
| limit | No | ||
| timeout | No | ||
| class_name | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure and does so effectively. It explains matching semantics (exact for name/class_name, substring for text), the requirement that at least one criterion be supplied, and that filtering occurs client-side, not here. This goes beyond the input schema and gives the agent realistic expectations about performance and result scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary purpose and is efficiently written across three short paragraphs. The first sentence delivers the core action, and subsequent paragraphs add necessary context without fluff. The only slight waste is the longer explanation of why substring matching is used, but it justifies a non-obvious decision, so it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters and an output schema, the description covers the key behavioral aspects and the main alternative, but leaves several parameters undefined. The output schema presumably documents the return structure, so that gap is mitigated. Still, an agent may not know how `root`, `depth`, `limit`, and `timeout` affect results without deeper inspection. Given the complexity, the description is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. It explains the meaning of `name`, `class_name`, and `text`—the three search parameters—including exact vs. substring matching and the implicit requirement that at least one be provided. However, it does not describe `root`, `depth`, `limit`, or `timeout`, leaving those to be inferred from their names. Given that 4 of 7 parameters are undocumented in both schema and description, this is only partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence 'Find widgets by name, class or text, without fetching the whole tree' states a specific verb, resource, and explicit scoping constraint. It also explicitly contrasts itself with ui_tree, making it clear which sibling it is not, so an agent can distinguish it without consulting other schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names ui_tree as the alternative when no search criteria are provided ('with none of them this would be ui_tree'), giving a clear when-not-to-use condition. It also clarifies that filtering is client-side, implying this is the right tool when you want filtered results rather than the full tree. It doesn't discuss all siblings, but the primary alternative is well addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write into an edit box, and read it back.
Only a field the player could type into may be written. A plain
TextWidget has SetText too, but writing a mod's label from outside would
change what the player sees without changing anything the mod believes -- a
lie drawn on the screen -- so it is refused rather than quietly allowed.
The value is read back out of the widget before the answer is returned:
SetText is native and returns nothing, so "it was set" would otherwise be
this tool's own claim about itself.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| root | No | menu | |
| text | Yes | ||
| timeout | No | ||
| expect_name | No | ||
| expect_class | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and it does so well: it discloses refusal behavior for non-editable widgets and verifies writes by reading the value back before answering. It doesn't cover failure/timeout behavior or focus side effects, but it explains the important semantic guarantees of the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The summary action is front-loaded, and both follow-up paragraphs earn their place by explaining a refusal guard and why the read-back is necessary. There is no filler, and the rationale is tightly tied to correct usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has six parameters and zero schema description coverage, and the description only covers the write/read behavior. It omits how `root`, `timeout`, `expect_name`, and `expect_class` shape the lookup or verification, leaving an agent with significant unknowns for correct invocation despite the output schema covering returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description only weakly illuminates the parameters: 'text' is implied as the value written and read back, and 'path' as the target widget. 'root', 'timeout', 'expect_name', and 'expect_class' are not explained at all, so an agent cannot infer their meaning from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific action and resource ('Write into an edit box, and read it back'), and the later constraint makes clear it targets only player-editable fields. It doesn't explicitly name a sibling tool as an alternative, so it stops short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit when-to-use ('Only a field the player could type into may be written') and an explicit when-not-to-use (writing a mod's label would create a lie on screen and is refused). It also points at the alternative naive approach (TextWidget.SetText) and explains why it is not acceptable, so an agent has clear selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The client's widget tree: what is on screen, as the engine holds it.
root is "menu" (the open scripted menu, the default) or "screen" (the
whole workspace). Each node comes back with its path, class, name,
visibility, screen rectangle, depth and -- where the engine allows it to be
read -- its text.
The answer is A PAGE: total is how many nodes the walk visited and count
is how many it listed, and truncated says when they differ. A shorter list
that did not say so would read as the whole interface.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | menu | |
| depth | No | ||
| limit | No | ||
| timeout | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It usefully explains the paging/trailing semantics and node fields, but it does not state whether this tool is read-only, whether any side effects occur, whether a timeout is needed for deep trees, or how large a response may be. Some behavior is revealed, but important safety/performance characteristics are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, well-structured, and front-loaded: the core purpose appears first, followed by the root choices, then the node fields, and finally the important trunction/paging semantics. No sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema gives the fine-grained response shape, so the description does not need to re-list fields. It is missing enough parameter semantics that a caller does not know how `limit` and `depth` control the page, and side effects are unaddressed. The completeness is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schemas provide no descriptions for any of the 4 parameters (0% coverage), so the tool description must compensate. It explains `root` values (`menu`/`screen`) but remains silent on `depth`, `limit`, and `timeout`. Without these semantics, an agent does not know how batching or scan depth affect results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool as a getter for the client's widget tree and specifies the distinction between `root: menu` and `root: screen`. It conveys the specific resource (UI widget tree), though it does not explicitly name sibling tools to differentiate itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys what the tool is for, and root options imply when to pass `menu` vs `screen`, but it never states when to prefer `ui_tree` over siblings like `ui_find`, `ui_text`, or `ui_menu`. Usage context is implicitly inferred, not explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a mod's own action through the engine's gate, on the server.
action_class is the action's script class name. There is deliberately no
verb dictionary: the same word means different things in a mod depending on
context, so applicability is decided by the ACTION'S OWN Can() -- and its
refusal is a meaningful test result, not a tool failure. The distinguishable
refusals, classified in the mod before the engine is touched: the manager is
busy; the player is already acting; the player is sprinting; the action
class is unknown; and "the action's own Can() said no" -- the last one being
the answer this tool exists to produce.
target_class names the config class of the object to aim at (resolved to
the first match near the player); many actions take no target and it can be
omitted. subject optionally names a Man-derived entity class to act AS
instead of the connected player -- a diagnostic escape hatch, because a
spawned survivor owns an action manager while not being counted as a
player.
"Accepted" is not success: the engine can drop an accepted action one frame
later without clearing it. The mod therefore holds the command running
until the manager actually releases the action, and any failure path
releases it too -- otherwise that player could never act again for the rest
of the session. Expect an answer only after the action has genuinely ended;
a stuck action fails by the mod's own 20s watchdog, with the release noted
in the detail.
| Name | Required | Description | Default |
|---|---|---|---|
| pos | No | ||
| radius | No | ||
| subject | No | ||
| timeout | No | ||
| action_class | Yes | ||
| target_class | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels: it reveals that 'Accepted' is not success, the engine may drop an action, the mod holds the command until release, failure paths release too, and there is a 20s watchdog. This gives an agent a precise mental model of the asynchronous behavior and failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place, covering purpose, parameter semantics, behavioral nuances, and failure handling in a logical, front-loaded structure. There is no fluff or repetition; the density is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and missing parameter explanations, the description is highly informative for the core semantics but incomplete for three parameters. The output schema exists, so return values needn't be described, but the undocumented pos/radius/timeout leave a gap in complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. It explains action_class, target_class, and subject in detail, but provides no meaning for pos, radius, or timeout. These three parameters are entirely undocumented, leaving an agent guessing about their purpose and format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb-resource pair: 'Run a mod's own action through the engine's gate, on the server.' It distinguishes itself from siblings like world_spawn or world_exec by focusing exclusively on invoking mod-defined actions, leaving no ambiguity about 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it explains how applicability is determined by the action's own Can() method, that no verb dictionary exists, and when target_class and subject may be omitted. It doesn't explicitly name alternative tools or state when NOT to use this tool, but the context makes it obvious this is the only bridge for mod actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete every object of class_name within radius of pos (or of the
player, when pos is omitted).
The class is required: the mod will not delete everything nearby regardless of class, and the radius is clamped on its side. Players are never deleted, whatever the class filter says.
| Name | Required | Description | Default |
|---|---|---|---|
| pos | No | ||
| radius | No | ||
| timeout | No | ||
| class_name | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that the class is required, radius is clamped, and players are never deleted—critical safety information for a destructive operation. It doesn't mention timeout behavior or what happens to the objects (e.g., permanent deletion), but the core destructive nature and safety guardrails are well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core action, then adds critical constraints in a second sentence. Every sentence earns its place—no fluff, no repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (destructive, multi-parameter) and the lack of annotations, the description covers the essential usage and safety aspects. It doesn't explain the 'timeout' parameter or the output schema, but the output schema exists and the description covers the most critical behavioral aspects. A small gap remains on timeout semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. It explains the meaning of 'pos' (defaults to player position when omitted) and 'radius' (clamped), and clarifies that 'class_name' is required. It doesn't explain 'timeout', but the description adds significant value beyond the bare schema for the other three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes objects of a specific class within a radius, with a clear verb ('Delete'), resource ('every object of class_name'), and scope ('within radius of pos or player'). It distinguishes itself from siblings like world_set or world_action by specifying a destructive, class-filtered deletion operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use it (to delete objects of a class) and provides important exclusions: the class is required, radius is clamped, and players are never deleted. It doesn't explicitly name alternative tools for non-destructive world manipulation, but the context is clear enough for an agent to infer when this is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WHICH objects are nearby, not how many.
world_state(class_name=...) counts; this one names them, with each
object's class, position, distance and health. An empty class_name lists
everything found rather than nothing.
The list is a page: the mod caps it at 200 entries and reports the true
total separately, so total larger than count means there is more out
there -- never a shorter list quietly standing in for the world.
distance is HORIZONTAL, because the engine's own radius test ignores
height: at the centre of Chernarus the terrain is 300 m up, so a
straight-line distance from a position written as "7500 0 7500" reads 320 m
for objects the engine returned inside a 150 m radius. A number that
contradicts the filter that produced it is worse than no number.
Players are not in it. The mod's own gather step skips them, which is what
keeps a delete of everything nearby from reaching the person standing in
it, and this tool shares that step deliberately rather than growing a
second notion of what is in the world.
| Name | Required | Description | Default |
|---|---|---|---|
| pos | No | ||
| limit | No | ||
| radius | No | ||
| timeout | No | ||
| class_name | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations, the description carries the full disclosure burden and excels: it reveals the 200-entry cap with a separately reported true total, explains that distance is HORIZONTAL because the engine's radius test ignores height (with a concrete Chernarus example that proves why a straight-line reading would be misleading), and discloses that players are deliberately excluded, including the safety rationale. This anticipates exactly the behavioral traps an agent would stumble into.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four dense paragraphs, each earning its place: purpose/contrast, pagination, distance semantics, player exclusion. The core message is front-loaded in the opening line. The Chernarus example is lengthy but necessary to make the horizontal-distance warning concrete and credible; nothing feels padded or repetitive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and 0% schema coverage, this is a complex tool to document, and the description covers every major trap: what it returns vs world_state, empty-class_name semantics, pagination interpretation, horizontal distance, and player exclusion. An output schema exists, so return-value explanation is rightly omitted. Minor omissions are timeout semantics and an explicit pos format specification, though both are partially inferable from the example.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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, and it does substantially: the empty-class_name meaning ('lists everything found rather than nothing') is critical and non-obvious, the pagination note directly explains the limit parameter's cap behavior, and the radius/distance discussion clarifies how the radius filter is actually applied. The only gap is timeout, which receives no added meaning, and pos format is conveyed only by example ('7500 0 7500').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description leads with a precise contrast: 'WHICH objects are nearby, not how many,' then names the sibling it is not ('world_state counts; this one names them'). It states the exact resource, the verb (name/list nearby objects), and the returned fields (class, position, distance, health). An agent can distinguish it from world_state 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly names the alternative tool and the selection condition: 'world_state(class_name=...) counts; this one names them.' It also gives concrete usage guidance for edge behavior (empty class_name lists everything rather than nothing) and for interpreting pagination (total > count means more results exist). The player-exclusion note additionally frames when this tool is safe to pair with bulk deletes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an arbitrary verb through the bridge -- the debugging escape hatch, not a testing path.
This server does not know the verb, does not validate its arguments beyond
stringifying them, and does not answer for what the mod does with it; every
answer is marked non_standard to say so. Anything a mod's behaviour can
express as an ACTION should go through world_action instead, where the
mod's own Can() gives the refusal meaning.
A verb this bridge build does not know comes back as a failure listing the
verbs it does -- that is the mod answering, not this tool guessing. A
project that needs its own verb adds it to ITS OWN copy of the bridge's
dispatcher (IsKnownVerb, the routing, and a handler); this server ships
no registration machinery on purpose, because a verb the server typed and
validated would be a verb the server answers for.
The verb must be lowercase ASCII (letters, digits, underscore, up to 41 chars): the mod recovers a command's id by a raw string search when a parse fails, and the id embeds the verb -- characters outside that set can make a failure impossible to correlate, which is the silence this product exists to remove.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| verb | Yes | ||
| timeout | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description extensively discloses behavioral traits: the server does not know the verb, does not validate arguments beyond stringifying them, marks all responses as 'non_standard', and returns a failure listing known verbs for unknown ones. It also details the verb format constraints (lowercase ASCII, up to 41 chars). This fully covers the tool's behavior given no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely verbose and repetitive. The same contrast with world_action is stated multiple times, and the language is overly poetic ('silence this product exists to remove'). It could be condensed into a few clear sentences without loss of meaning. The structure is not efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's generic nature (arbitrary verb bridge), the description covers all necessary context: purpose, constraints, failure modes, and relationship to world_action. It is complete enough for an agent to decide when to use it and what to expect. However, the verbose style makes it less accessible, though not incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning to the 'verb' parameter (format and constraints) and 'args' (stringified without validation). It does not explain the 'timeout' parameter, but that is a common parameter with a default value. Overall, it enriches understanding of the schema beyond its bare types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Send an arbitrary verb through the bridge' and positions it as a 'debugging escape hatch'. It distinguishes itself from world_action, which is for normal actions. The core function is unambiguous despite the flowery language.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs when to use this tool versus alternatives: 'Anything a mod's behaviour can express as an ACTION should go through `world_action` instead'. It also notes it's for debugging and that unknown verbs return a failure listing valid verbs. This gives clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wait until the bridge inside the game is actually ticking.
Call this once after server_start's boot job finishes and before the first
world command. The bridge publishes its first state during mission init but
does not start reading commands until tens of seconds AFTER the server
reports ready -- 18-38 s in the boots measured so far. A command sent in that
window
is claimed eventually and completes normally, long after the caller gave up.
Blocks, with a ceiling, because there is nothing else to do with the answer: the alternative is handing back "not yet" and having the caller poll, which is the same wait with more round trips.
| Name | Required | Description | Default |
|---|---|---|---|
| timeout | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses that the tool blocks, has a ceiling, why waiting is necessary, the measured delay window, and the failure mode of sending commands during that window. This is far richer than a generic 'waits until ready' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Longer than average, but every paragraph earns its place: the operational instruction is front-loaded, followed by timing evidence and a rationale for blocking. There is no filler or repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers when, why, and blocking behavior, and an output schema exists so return values need not be explained. The only gap is the timeout parameter's units and expiry behavior, which is a small completeness hole for a tool whose only knob is that parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one optional timeout parameter with 0% description coverage, so the description must document it. It only indirectly references a 'ceiling' and never names the parameter, states its units, or explains what happens when it expires. The agent can infer seconds from context but not explicitly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a concrete action—'Wait until the bridge inside the game is actually ticking'—and clearly identifies the resource and readiness condition. It also gives explicit sequencing relative to server_start and world commands, distinguishing it from siblings without merely restating the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states exactly when to call: after server_start's boot job finishes and before the first world command. It explains why this matters (the 18-38 s gap) and even contrasts with a polling alternative, so an agent knows when this tool is the intended choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set health or quantity.
target is "player" or "hands"; left empty it defaults per what -- health
on the player, quantity on the held item -- because a single default for
both would make one of the two combinations a trap (a player has no
quantity, and empty hands have no health).
| Name | Required | Description | Default |
|---|---|---|---|
| what | Yes | ||
| value | Yes | ||
| target | No | ||
| timeout | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It does an excellent job explaining the defaulting logic and why the defaults exist ('a single default for both would make one of the two combinations a trap'). However, it doesn't address the purpose of the required timeout parameter or what happens when this tool is called (side effects, return values).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences total: the first states the action, the second details the target/variable combination, and the third justifies the design decision. Every sentence contributes value, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter, this is mostly complete. The tool's purpose is clear, and the explanation of the trap is valuable for an agent. However, the purpose of a timeout parameter on an apparently instantaneous operation remains a gap, as does what the agent can expect in return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
This dimension is where description value matters most with 0% schema coverage. The description adds significant meaning to target ('player' or 'hands') and what (health or quantity), which is necessary. However, timeout is entirely unexplained, and it's unclear if value is absolute or relative. The description partially compensates for the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource: 'Set health or quantity.' The description clearly indicates this is a setter tool without ambiguity about what it operates on, and the mention of 'player' and 'held item' provides context. However, it doesn't differentiate itself from more specific sibling tools like world_time_set or world_weather_set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains a nuanced defaulting behavior for the target parameter but provides no guidance on when to choose this tool over alternatives. There's no mention of what makes this tool preferable or 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.
Create an item: on the ground, in the player's hands, or in their inventory.
where is "ground" (default), "hands" or "inventory". A ground spawn takes
pos as "x y z" and falls back to the player's own position when it is
omitted; with neither a position nor a player, the mod says so in words
rather than doing nothing.
Ground spawns are created with ECE_PLACE_ON_SURFACE and ECE_NOLIFETIME. Without the second flag the item lives by the lifetime in its own config and the central economy is free to remove it partway through a check -- which turns "my test item vanished" into a hunt through the mod under test. The flag is the mod's, not this tool's; it is named here because it is the reason a spawned item can be trusted to still be there a minute later.
| Name | Required | Description | Default |
|---|---|---|---|
| pos | No | ||
| where | No | ground | |
| timeout | No | ||
| quantity | No | ||
| class_name | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It discloses critical behavioral traits: ground spawns are created with ECE_PLACE_ON_SURFACE and ECE_NOLIFETIME, explaining why an item persists and why the flag matters. It also describes the fallback when neither position nor player is given (the mod says so in words) and the consequence of omitting the lifetime flag. This is substantial transparency for a mutation tool, though it does not cover every hypothetical side effect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-ordered paragraph: purpose first, then parameter details, then flag rationale. It is dense but each sentence contributes value; no filler. The front-loading makes the primary function immediately clear. It is slightly long but justified by the technical context needed for correct use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main placement and flag behavior, which is crucial for correct invocation. However, it omits the semantics of `timeout` and `quantity`, both of which could significantly affect results. An output schema exists, so return values may be documented there, but the parameter omissions leave gaps. Given the 5-parameter complexity and 0% schema coverage, the description needs to explain all parameters; it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description must clarify parameters. It fully explains `where` (enumerating options and default) and `pos` (format and fallback), adding real meaning. However, it does not address `class_name` (the required parameter), `timeout`, or `quantity`, which remain opaque despite their presence in the schema. The description partially compensates but leaves key parameters unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb–resource pair, 'Create an item,' and specifies three distinct placement contexts (ground, hands, inventory). This is specific enough to distinguish it from sibling world_* tools like world_set or world_exec, which target different actions (state changes, commands). No ambiguity remains about 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context for the `where` parameter (ground, hands, inventory) and the behavior of `pos` (including fallback), which helps an agent decide placement. However, it never frames this tool against alternatives or states exclusions, e.g., 'use world_exec for commands instead.' The guidance is implicit rather than explicit, but the parameter-level detail does inform usage choices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What the world looks like right now.
With NO class_name this costs nothing and waits for nothing: the mod republishes the player's position, health and what is in their hands every tick, so the answer is already on disk. That is deliberate -- a snapshot a caller has to pay a full command round trip for (a second to be claimed, two more of terminal dwell) would make the cheapest question the most expensive one.
With a class_name it also sends a query command to count objects of that
class within radius, because a count needs arguments only a command
carries. The count comes back in world.query_count as well as in the
detail, so it stays readable on later snapshots too -- which is how "is the
item I spawned a minute ago still there?" gets answered.
| Name | Required | Description | Default |
|---|---|---|---|
| pos | No | ||
| radius | No | ||
| timeout | No | ||
| class_name | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the burden. It explains that without class_name it reads cached player state (republished every tick) and with class_name it sends a query command and returns a count. This covers some behavior but does not explicitly state whether the command has side effects or if the tool is read-only. The phrasing 'the answer is already on disk' implies a cached read, but side effects are not fully disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose and unnecessarily poetic, repeating a rhythmic pattern that obscures core information. It could convey the same functionality in a fraction of the words. The structure is not concise, making it harder to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description explains the two operational modes (with/without class_name) and the caching rationale, it lacks details on return structure (output schema is not shown), error conditions, required parameters (all are optional but their defaults are unclear), and how the tool integrates with the broader workflow. The description is incomplete for a developer to use it confidently without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no parameter descriptions, and the description only partially hints at parameters: pos, radius, timeout, and class_name are mentioned, but their precise meanings and defaults are not fully explained. For example, radius is referenced in the context of the class_name query, but pos and timeout are not clarified. Schema coverage is 0%, so the description must compensate, but it does not sufficiently define each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool returns the current world state (player position, health, items) and optionally a count of objects by class. However, the wording is cryptic and poetic, making the exact purpose less straightforward than it could be. It does differentiate from siblings like world_entities by focusing on player state and optional query counts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives (e.g., world_entities, world_spawn). It explains the caching behavior and query mechanism but provides no guidance on selection criteria or situational usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move the player to pos, given as "x y z".
The same format world_state reports positions in, so a position read out
of a snapshot can be handed straight back. With nobody connected the mod
refuses by name -- an absent player is a distinct, stated reason, never a
silent no-op.
| Name | Required | Description | Default |
|---|---|---|---|
| pos | Yes | ||
| timeout | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It explicitly states that when no player is connected, the mod refuses by name, and that this is a stated reason rather than a silent no-op. This is valuable transparency, though it does not cover other side effects or success behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences that immediately convey the core purpose and format. It front-loads the essential information and adds a practical cross-reference to world_state without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, and the description covers the key parameter and a notable edge case. However, it fails to mention the 'timeout' parameter, which is part of the input schema and could affect invocation. Since an output schema exists, return values are covered, but the missing parameter documentation makes it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. It thoroughly explains the 'pos' parameter and its format, but completely omits the 'timeout' parameter, leaving its purpose and constraints undocumented. This is a significant gap given the schema provides no help.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Move' and the resource 'player', and specifies the parameter format. It is unambiguous in what the tool does, but it does not explicitly differentiate from sibling tools such as world_spawn or world_set, relying instead on the generic phrasing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the position format matches world_state, implying it should be used when a position from that tool is available. However, it does not state when to avoid this tool or recommend an alternative, so the usage guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move the world clock.
Every field left at -1 keeps the value the world already has, read back from the engine before the change. That matters because the engine sets a date as five numbers at once: a tool that filled in the missing ones would move the date every time somebody set the hour.
Ranges are the engine's own documented ones -- month 1-12, day 1-31, hour 0-23, minute 0-59 -- and are checked in the mod, before a native call that would otherwise be handed a value it does not define behaviour for.
The answer carries the world's clock as it stands after the change, from the mod's own snapshot rather than from what was asked for.
| Name | Required | Description | Default |
|---|---|---|---|
| day | No | ||
| hour | No | ||
| year | No | ||
| month | No | ||
| minute | No | ||
| timeout | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly explains the sentinel behavior (-1 means keep existing value), the engine-defined ranges for each field, and that the response reflects the post-change state. This is valuable and goes beyond what the schema alone provides, though it could be more explicit about potential errors or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise but repeats the -1 semantics and range information in a slightly redundant manner across three paragraphs. It could be tightened, but it is not excessively verbose and the structure (purpose, semantics, return) is logical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations, the description covers the key aspects: partial update behavior, value ranges, and response content. Since an output schema exists, the return format need not be detailed, but the description still mentions the post-change snapshot. It lacks edge-case details but is sufficient for most usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the parameters by stating that -1 (the default) means 'keep existing value' and by giving explicit ranges for day, month, hour, and minute. This goes beyond the raw schema, which only shows defaults. It does not explain the 'timeout' parameter, but the core time fields are well clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Move' or set) and resource ('world clock'), making it clear the tool adjusts the world time. It differentiates from read-only siblings like world_state and broader tools like world_set, though it does not explicitly name them. The phrase 'Move the world clock' is slightly unconventional but unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool over alternatives. It focuses on behavioral semantics (partial updates, ranges) but never states 'use this for setting time' or contrasts with world_set or world_weather_set. Agents must infer applicability from the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move one weather phenomenon towards a value.
what is "overcast", "rain", "fog", "snowfall" or "wind". The first four
take a value between 0 and 1; wind takes a speed in metres per second.
seconds is how long the change takes (0 is immediate) and duration is
how long the value is held before the engine's own simulation may move it
again.
THIS IS A NUDGE, NOT A LOCK. The engine keeps simulating weather, so a value set here drifts afterwards -- said here and in the mod's own answer, because the alternative is a caller who sets rain, looks up two minutes later and concludes the tool did nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| what | Yes | ||
| value | Yes | ||
| seconds | No | ||
| timeout | No | ||
| duration | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | No | |
| hint | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explains that the engine continues simulating weather, so set values drift—a key non-obvious behavior. It also clarifies the meaning of seconds (change time) and duration (hold time). However, it doesn't mention potential error conditions, permission requirements, or side effects beyond drift. The main quirk is well documented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but every sentence adds value: it defines the phenomena, value ranges, the meaning of seconds and duration, and the nudge behavior. It front-loads the purpose and then adds necessary detail. It's not overly verbose; the drift warning is repeated for emphasis, which is somewhat redundant but acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, multiple weather types, timing semantics), the description covers most essential aspects. It explains the operational behavior and the main parameters. The output schema exists, so return value details aren't needed. The missing timeout explanation is a gap, and it doesn't mention prerequisites (e.g., world must be loaded), but overall it's fairly complete for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. It explains 'what' (the five phenomena), 'value' (range per phenomenon), 'seconds' (transition time), and 'duration' (hold time). However, 'timeout' is completely unexplained, leaving one of five parameters semantically undocumented. Since the description covers most but not all parameters, it's a partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool moves a weather phenomenon toward a value, listing the specific weather types and their value ranges. It distinguishes itself implicitly from other world_* tools by focusing on weather, but doesn't explicitly name alternatives or contrast with them. The purpose is specific and understandable, but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a critical usage warning: this is a nudge, not a lock, and values drift afterward. This is valuable context for when to use the tool (expect drift) but it does not state when to use this tool over alternatives like world_time_set or world_set. There's no explicit 'when-not' guidance or comparison to siblings, so it's a clear but implicit usage note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0asset_buildasset_checkasset_convertasset_exportbridge_buildbridge_clearbridge_statusclient_chatclient_compile_checkclient_lookclient_moveclient_pressclient_shotclient_startclient_statusclient_stopclient_typeclient_verdictjob_artifactsjob_statusjob_waitknowledge_buildknowledge_callersknowledge_findknowledge_overridesknowledge_scopeknowledge_showknowledge_statuslog_taillog_verdictmod_buildmod_lintproject_openproject_statusserver_modsserver_signaturesserver_startserver_statusserver_stopui_clickui_findui_menuui_textui_treeworld_actionworld_deleteworld_entitiesworld_execworld_readyworld_setworld_spawnworld_stateworld_teleportworld_time_setworld_weather_setScored across 55 tools
Every tool targets a distinct capability, and the descriptions actively pre-empt confusion between near-neighbors: client_verdict vs log_verdict, world_state vs world_entities, client_chat vs client_type, world_action vs world_exec, and knowledge_find vs knowledge_show are all explicitly differentiated. Even the largest families (11 world tools, 11 client tools, 7 knowledge tools) have no functional overlap.
All 55 tools follow a predictable snake_case domain_prefix_suffix pattern (knowledge_*, world_*, client_*, ui_*, asset_*, server_*, bridge_*, job_*, log_*, mod_*, project_*), so the domain of any tool is identifiable at a glance. Minor deviations: compound suffixes like world_time_set, world_weather_set, and client_compile_check, plus a mix of verb suffixes for actions and noun suffixes for read-only queries (status, state, tree, menu).
55 tools is more than double the 25-tool threshold the rubric treats as too many, and an agent must navigate families of 11 world tools, 11 client tools, and 7 knowledge tools in a single selection space. The scope is genuinely broad and every tool earns its place, but the surface could be consolidated by 30-40% (parameterized client input, merged environment setters, combined job operations) without losing capability.
The toolchain covers the full modding pipeline end-to-end: knowledge indexing, lint/build, the complete asset pipeline (export, binarize, check, convert), server lifecycle, bridge management, world manipulation, client automation, and UI interaction, with observability at every stage via jobs, logs, and verdicts. Minor gaps remain: full player inventory cannot be read (only hands), UI testing lacks wait-for-widget and scroll operations, and bridge attachment stays a manual profile edit.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
An MCP server that gives your AI access to the source code and docs of all public github repos
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
