エージェントがDayZ MODをビルドし、クライアントがコンパイルされることを確認し、 テストサーバーを起動して、構造化された判定結果をログの代わりに得られるようにするMCPサーバーです。
サーバーは処理を自ら行います。FileBank、署名ツール、診断実行ファイルを 直接呼び出します。プロジェクト側でビルドスクリプトを持つ必要はありません。
サーバーは特定のMODについては何も知りません。具体的な内容はすべて 2つの部分からなるプロファイルに記述されます：
dayz-mcp.toml — 移植可能で、MODリポジトリにコミットされます：どのMODをパックするか、
正常なブートとはどのようなものか。
dayz-mcp.local.toml — マシン固有で、コミットされません：ゲーム、ツール、テストスタンドが
どこにあるか。
2つの部分を混在させることは読み込み時に拒否されます。これにより、リポジトリが
他の誰かのマシン上でビルドされ続けることはありません。dayz-mcp.example.tomlから始めてください。
MODは名前で一度だけ宣言されます：ソースはデフォルトで<root>/Nameにあり、出力は
@Name/addons/Name.pboです。build.sourcesでMODのソースを別の場所に
リダイレクトできます（例：config.cppがリポジトリルート直下にあるMODの場合は"."）。
dayz-mcp.tomlキー | 意味 |
| このプロジェクトの呼び名 |
| MODごとに1エントリ。名前、ソース、PBO、 |
| MODのソースが実際にある場所。プロファイルからの相対パス（ |
| 絶対にパックしてはならないもの。これを指定するとデフォルトの除外リストが置き換えられます。デフォルトは |
| 除外されたものが存在する場合に拒否する代わりに、フィルタリングしたコピーをパックする — ルートレイアウトのMODに必要なレイアウト |
| すべてのモデルパスが解決される基準ディレクトリ。このファイルからの相対パス。MODのプレフィックスフォルダを含んでいなければなりません。モデルツールにのみ必要で、他のツールには不要です — 「アセットパイプライン」を参照 |
| パック前に実行されるPowerShellスクリプト。コードを先に生成するプロジェクト向け |
| MODが読み込みを完了したときに出力する行 — 下記参照 |
| その行に含まれる |
| 警告の許容上限。このキーを省略するとチェックは無効になります |
| 実行を失敗させる部分文字列。これ以外は問いません |
| あなたのMODに属するスクリプトエラーを示す正規表現。クライアントのコンパイルチェックで使用されます |
| 組み込みリストに加えて無視するエンジンのノイズ出力 |
dayz-mcp.local.tomlキー | 意味 |
| ゲームのインストール先。省略時は自動検出されます |
| DayZ Tools。省略時は自動検出されます |
| Blenderの実行ファイル。 |
| 準備済みのテストスタンド。サーバーはここから起動し、ログは |
| スタンド内のサーバー設定ファイル名（デフォルトは |
|
|
| MODフォルダ名。ゲーム自身の |
|
|
|
|
server_startは、expect.ready_lineが、そのブート中に書き込まれたログに
現れたときに完了します。これはサーバー自身では判断できない唯一の事項であり、
これがない場合、2つのことが変わります：何も待機できないため、ブートジョブは
サーバーを起動し、少し後にまだ生きていることを確認して、完了を報告します。
また、log_verdictにはカウンターを読み取る行がないため、expect.countersは
決して一致しません。エラー、警告上限、クラッシュは依然として判定されます。
レディラインのないプロファイルもサポートされています — 壊れているわけではありません。project_openが
そのメモに記載しています。
Related MCP server: DayZ API MCP Server
ツール | 機能 |
| プロファイルを読み、ゲームとツールを検出し、不足しているものを報告する |
| 現在のプロジェクト、実行中のサーバー、最近のジョブ |
| 宣言されたすべてのmodをパックして署名し、ジョブIDを返す。同じプロジェクトのビルドが実行中の間は、2回目のビルドを拒否する |
| テストサーバーを起動し、準備ができたら完了する。設定が指定するミッションが |
| pid、プロセスが生存しているかどうか、ログが増加しているかどうか（ |
| このセッションが起動したサーバーを停止する（孤児サーバーにはオプションの pid） |
| スタンドの |
| 診断用クライアントを実行し、そのログを読む |
| 理由付きの合格/不合格：カウンタ、禁止文字列、警告予算。 |
| 最後の行を返す。オプションでフィルタリング。ソースは同じ2つ |
| 長時間実行ジョブのステータス |
| ジョブが完了するまで待つ |
| 完了したジョブから出力を取得する |
| ブリッジmodをパックする。そのソースはあなたのプロジェクトではなく、このサーバーに同梱されている（ |
| 実行中のゲーム内のブリッジがまだ動作しているかを確認する。ティック番号と、 |
| メールボックスに詰まったコマンドを破棄し、何を捨てたかを示す。ブリッジが生存しているように見える間は |
| ゲーム内のブリッジが実際にコマンドを受け付けるまで待つ。起動ジョブの完了後、最初のワールドコマンドの前に1回呼び出すこと — 下記の「サーバーレディはブリッジレディではない」を参照 |
| ブリッジが毎秒公開するワールドのスナップショット：プレイヤー、位置、体力、手に持っているもの。引数なしならコストなし。 |
| 地面（ライフタイムなしなので、チェック中に消えることはない）、プレイヤーの手の中、またはインベントリ内にアイテムを生成する |
| プレイヤーを |
|
|
| 近くにある1つのクラスのオブジェクトを削除する。クラスの指定が必要。実際のプレイヤーを削除することは決してない |
| 近くにどのオブジェクトがあるか。数ではなく、それぞれのクラス、位置、距離、体力を返す。1ページ分の結果で、その旨も示される。実際の合計はリストとともに返る |
| ワールドの時計を進める。-1 のままにしたすべてのフィールドは現在の値を保持する。エンジンは日付を5つの数値として一度に設定するため、現在の値はまずエンジンから読み戻される |
| 曇り、雨、霧、降雪、または風を変化させる。ロックではなく微調整：その後もエンジンは天候をシミュレートし続け、その旨はツールとMODの両方が明示する |
| エンジンのゲートを介してMOD独自のアクションを実行する — 後述参照 |
| 逃げ道：同じトランスポートを介して任意のverbを実行する。すべての応答で非標準とマークされる |
| ゲームクライアントを起動してスタンドに接続し、ジョブIDを返す。常にウィンドウモード。ブリッジが |
| client_status() | クライアントのPID、ウィンドウが最小化されているか最前面にあるか、背景設定、仮想コントローラが接続されているかどうか |
| client_stop() | このセッションが起動したクライアントを停止し、仮想コントローラを取り外す |
| client_shot(path) | クライアントのウィンドウをPNGにキャプチャする。lit_fraction は実際のフレームと全面黒のフレームを区別する数値。フォーカスは不要 |
| client_move(x, y, seconds) | 左スティックでキャラクターを歩かせる。アナログ操作であり、キャラクターを動かせる唯一のツール。フォーカスは不要 |
| client_turn(x, y, seconds) | 右スティックでカメラを回転させる。フォーカス不要 |
| client_press(button, seconds) | 14個の名前からなる固定リストからゲームパッドのボタンを1つ押す。フォーカス不要 |
| client_chat(text, color) | チャットに1行送る — ブリッジがサーバー側で配信するため、キーボードもウィンドウもフォーカスも不要 |
| client_type(text, submit) | 実際のキー入力でクライアント側の入力フィールドに文字を打ち込む。ここで唯一フォアグラウンドを必要とするツールで、その旨が応答に記載される |
| client_verdict(since) | ライブのクライアントを、それ自身の .RPT によって判定する — エラーとクラッシュの判定。後述 |
| ui_menu() | クライアントのUIの状態（開いているメニュークラス、カーソル、ダイアログ）を返す。無料 — 毎ティック再公開される |
| ui_tree(root, depth, limit) | クライアントのウィジェットツリー: パス、クラス、可視性、画面の矩形、深さ、テキスト。1ページ分であり、その旨が明記される |
| ui_find(name, class_name, text, root) | 同じ走査をクライアント側でフィルタするため、ツリー全体を転送する必要がない |
| ui_click(path, expect_name, expect_class, via) | ウィジェットを押す。via="script" はフォーカスなしで開いているメニューのハンドラを通る。via="cursor" は実際のマウスをその矩形に置く |
| ui_text(path, text, expect) | 編集ボックスに書き込み、その値をウィジェットから読み戻す |
| mod_lint(mod, strict) | パックや起動をせずに Enforce Script を判定する。mod_build はそれを最初に実行し、拒否した場合は拒否する |
| mod_build(mod, source, deploy) | モッドのスクリプトを検証し、パックしてから配置する。Job id を返す。検証は mod_lint を呼び出し、それが拒否した内容を拒否する |
| mod_status(mod) | モッドのビルド状態の概要: どのソースが読み込まれ、どの出力が配置されているか、さらに検証結果 |
| server_start() | ブート、進行状況、レポート、利用可能なプラットフォームとセッションの一覧を返す |
| server_stop() | ブート済みのサーバを停止し、プロファイルディレクトリをロックする |
| server_console(command) | サーバコンソールと同じコマンドを発行し、その応答を返す |
| server_message(text, announce) | ゲーム内メッセージをブロードキャストする（rcon/say 形式） |
| world_ready() | サーバープロセス、ログ、ブリッジがそれぞれの準備完了状態にあることを確認する |
| world_tick() | ワールドが進行中であることを確認する（ライブスタンドのティック変位、約2秒） |
| log_verdict(range, offset, level, match) | 最近のサーバーログを確認し、クラッシュ、スタック、および関連メッセージの判定を返す。オプションで指定したコンテキスト行数を含む |
| log_msg(needle, since, limit) | サーバーログからメッセージを検索する。オプションの after でブリッジが停止した箇所から再開できる |
| server_tasks() | 実行中のバックグラウンドタスクを一覧表示する。どのサーバーにも同じ key がある |
| server_wait(signal, timeout, raise) | セマフォを待つ。timeout=0 で無限待機し、raise=false なら、呼び出し側の処理を中断する代わりに "timeout" を返す |
| server_notify(name) | セマフォを設定または解除する |
| mod_pack(mod, options) | リポジトリ内の mod を Arma 3 pbo にパックする |
| mod_lint(mod, strict) | パックやブートをせずに mod を検査する。厳密モードは警告をエラーとして扱う |
| mod_diagnose(mod) | サーバー起動時に mod がクラッシュを起こす理由を検査する。ログの検索と差分比較を実施する |
| mod_apply(mod) | 設定を再生成し、mod をパックして、サーバーを再起動する |
| mod_repo(mod) | mods/ 配下のファイルのみを対象に、mod のリポジトリ内ファイルを一覧表示する |
| mod_settings(mod) | サーバーの -config ファイルから mod の設定値（class、value、type）を読み取る |
| mod_set(mod, key, value, type) | -config ファイル内の設定値を変更する。復元は type=auto で行う |
| bridge_build() | リポジトリ内の bridge/ を @DZMCP_Bridge にパックする。リポジトリと keys/ フォルダの外には何も書き込まれない |
| bridge_status() | ブリッジの状態を判定する。応答にはtick番号と前回サンプルからの経過セッションが常に含まれる |
| bridge_clear(force) | ブリッジのコマンドキューをクリアする。ブリッジがアクティブな間は force=false では拒否される |
| bridge_wait(signal, timeout) | ブリッジがコミット状態を報告するまで待機する。デフォルトは timeout=30 で、poll 間隔は約0.2秒。ブリッジがダウンしている場合は即座に失敗する |
| log_ship(path, lines) | サーバーまたはクライアントのログから直近の行を抽出する。パスが空の場合は自動検出される |
| log_verdict(mod) | 利用可能なすべてのログソースをクロスチェックし、ブート失敗の診断結果を返す |
| log_crash(mod) | Windows イベントログとプロファイルディレクトリ内の .mdmp ファイルを検索する |
| pbo_list(path) | Arma 3 PBO 形式のアーカイブを一覧表示する |
| pbo_extract(path, files) | PBO からファイルのサブセットを抽出する。パスは常に / セパレータで、mod-relative かつ / で始まる形式 |
| debug_mcp_whitelist(mod) | admin.add の現在の値を返す。これは「MCP ブリッジが誰を信頼するか」のサーバー側の真実である |
| debug_mcp_grant(mod) | admin.add を一時的に設定する。MCP管理下の mod にのみ作用し、ブリッジが再起動時に再適用する |
[mods]
extra = ["<path printed by bridge_build>/@DZMCP_Bridge"]
server_only = ["@DZMCP_Bridge"]「サンプルを手渡す」のような意味論的な動詞は嘘をつく。実際のMODでは、同じ言葉が、近くにあるデバイス、プレイヤーの派閥、すでにアンロックされているものによって異なる意味を持つ。その文脈は列挙不可能なので、ブリッジはそれを試みない。world_action はアクションのクラス名、ターゲット、保持中のアイテムを受け取り、エンジンにそれ自身のゲート——キー押下が通るのと同じゲート——を通して実行するよう依頼する。適用可能性はアクション自身の Can() が決定し、その拒否はツールの失敗ではなく、意味のあるテスト結果である。区別可能な応答は次のとおり: マネージャーがビジー、プレイヤーがすでに行動中、プレイヤーがスプリント中、未知のアクションクラス、そして「アクション自身の Can() がノーと言った」。 「受理」も成功ではない——エンジンが実際にアクションを解放するまでコマンドは実行中のままであり、すべての失敗経路はマネージャーを解放するため、プレイヤーはその後も行動できる。
world_exec は逃げ口であるMODが公開するものでアクションではないもの——「派閥プールに何ポイントあるか」——は world_exec(verb, args) を通る: 同じトランスポート上の任意の動詞である。すべての応答は non_standard とマークされる: このサーバーはその動詞を知らず、検証もせず、MODがそれで何をするかについても答えない。ブリッジのビルドが知らない動詞は、それが知っている動詞のリストを返す。独自の動詞を必要とするプロジェクトは、ブリッジのディスパッチャーの自身のコピーを編集する(bridge/scripts/5_Mission の KnownVerbs() の上のコメントが正確な場所を示している)。意図的に登録機構はない——このサーバーがタイプし検証した動詞は、このサーバーが責任を持つ動詞になるからだ。
ブリッジはサーバーに到達する。しかしクライアントの画面を見たり、クライアントを通じて行動したり——キャラクターを地面の上を歩かせたり、メニューを開いたり、MODが描いたフィールドを埋めたり——することはできない。client_* ツールはそれを担い、3つの異なる経路を使用する。なぜなら、どれ1つとして他の2つの仕事をこなせないからだ。以下の各行は、設計意図ではなく、生きたクライアントに対する測定値である。
経路 | 機能 | フォアグラウンドが必要 |
ブリッジ ( | ワールド、およびチャットへのテキスト | いいえ |
仮想ゲームパッド、ViGEmBus ( | 移動、カメラ、および一部のインターフェース | いいえ |
実際のキーストローク、 | クライアントにのみ存在するフィールドへのテキスト | はい、そしてそれを奪う |
キーボードエミュレーションはキャラクターを動かさず、ウィンドウメッセージはまったく何もしない。 フォアグラウンドを確認した状態での SendInput スキャンコード: 前方へ25秒、0 m。メインウィンドウとその子への PostMessage/SendMessage WM_KEYDOWN: 0 m、メニューからの反応もない。エンジンは生の入力から移動を読み取り、エミュレートされたキーを無視する。これが、ここでどのツールもウィンドウメッセージを提供しない理由である。
仮想ゲームパッドは、フォーカスなしでそれを動かし、しかもアナログである——キーで足りる場合でもそれが残る理由。 サードパーティ製アプリケーションがフォアグラウンドを終始保持した状態での1回の実行で測定:
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 m歩き、MOD自身の10 m以内のオブジェクト数は、その場を離れて戻ってくるにつれて 1 → 0 → 1 と変化した——これは存在によって引き起こされた状態変化であり、テレポートでは生み出せない。
インターフェースの一部はパッドに応答し、一部は応答しない。 ゲームウィンドウが終始別のアプリケーションの背後にある状態で測定: back はインベントリを開閉し、start はポーズメニューを開き、b はそれを閉じる——すべてデフォルトの0.1秒タップで、つまりタップはエンジンがラッチするのに十分な長さである。しかし a は0.1秒でも0.5秒でも何も動かさず、それらの画面内でのdパッドも同様だった: クライアントはコントローラーナビゲーションモードに切り替わらなかったため、確定ボタンが作用するフォーカスされた要素がなかった。メニューの閉じるはゲームパッドの仕事として扱い、メニューの確定は未証明として扱え。
目もフォーカスを必要としない。 キャプチャは、ウィンドウがzオーダーの最下部にある状態でのライブフレームである(同じセッションで、フォーカスなし lit_fraction 0.9997、フォーカスあり 0.9997)。それらを無効にする唯一の状態は最小化されたウィンドウであり、そのクライアント領域は0×0に潰れる——有効に見える空の画像として保存されるのではなく、理由付きで拒否される。
そのバックグラウンド動作のすべては、1つのクライアント設定 pauseMode (GAME → UPDATE IN BACKGROUND) に依存している。 ここで測定された値では、クライアントはフォーカスがない間も描画とシミュレーションを続ける。これが、フレームがライブであり、スティックが依然としてキャラクターを動かす理由である。「グラフィックスなし」では、両方とも静かに停止する——凍結したフレームはライブのフレームとまったく同じに見える。したがって client_start と client_status はその設定を読み取り、警告する。決して書き込まない。なぜなら、それはマシンを所有する人のものだからだ。
client_type は画面を奪う唯一のツールであり、それについて正直である: 応答には foreground_taken と、実行中はそのマシンの前にいる人が自分のウィンドウに入力できなかったという一文が含まれる。SetForegroundWindow はWindowsが拒否したときに何もせずに成功を返すため——そして盲目的なタイピングは、その人が実際に使用しているウィンドウにキーストロークを送ってしまうため——要求後に GetForegroundWindow でフォアグラウンドを検証する。フォアグラウンドを取得できない場合、何もタイプされず、拒否はそれを保持しているプロセスを名指しする。
ViGEm は実デバイスのエミュレーションであり、これはテストスタンドである。 ドライバーは署名済みで再起動なしでインストールされ、ゲームパッドはマシン自身のキーボードとマウスに対するフィルターではなく新しいデバイスである——フィルタードライバーはかつてここで試され、手で巻き戻されるまでマシンの所有者のすべてのキーボードとマウス入力を奪った。そのどれも、ライブサーバー上のアンチチートについての約束ではなく、このフェーズでは何も約束しない。
MODを書くエージェントは、ゲームに同じ質問を繰り返し尋ねる: そのようなAPIはあるか、何と呼ばれるか、どこで宣言されるか、誰がそれをオーバーライドするか。それらに答えることは、scripts.pbo を展開してテキストをくまなく調べることを意味し——そして毎セッションで再びコストを払った。knowledge_* はその作業を質問に変える。
これは、プロジェクト自身の .dayz-mcp/ にあるプレーンなSQLiteファイルであり、このサーバーがゲーム、プロジェクトが宣言するMOD、プロジェクト自身のソースから構築する。埋め込みなし、外部サービスなし、キーなし。
層 | ソース | 陳腐化するタイミング |
| ゲーム: API用の | ゲームが更新されたとき |
| プロファイルが宣言するMODのアーカイブ、展開せずに読み取られる | 依存関係が更新されたとき、または宣言されたセットが変更されたとき |
| MOD自身のソース、置かれている場所で読み取られる | 編集のたび |
1回で構築された1つのインデックスは、正しくなってから1分以内に間違ったものになるだろう: ゲームは年に数回動き、依存関係は月に数回動き、プロジェクトはエージェントの1ターンと次のターンの間に動く。したがって、各層は独自に構築、熟成、測定され、すべてのビルドは増分である——変更されていないソースはサイズと変更時刻でスキップされ、only=[path] はそれらを発見するウォーク自体もスキップする。
陳腐化は推測ではなく測定される: 層は、読み取ったすべてのソースのサイズと変更時刻を記録し、それが現在のファイルと比較される。
すべての応答は、使用した層と各層の古さを名指しする。結果がない応答は、検索したすべての層を名指しする——「見つからない」は、その背後にある層が最新であるのとまったく同じだけの価値がある。
プロジェクト層の鮮度は、寄与したかどうかに関係なく、すべての検索で測定される。それが危険なケースである: エージェントがクラスを追加し、それについて尋ね、1分前に構築された層が「見つからない」と言う——存在するコードについての自信に満ちた発言。
構築されたことのない層に対する検索は拒否され、拒否はそれを構築する呼び出しを名指しする。「見つからない」と「調べていない」は異なる事実であり、そのうちの1つだけが行動しても安全である。
絞り込みは同じ罠を1レベル下に運ぶため、空の絞り込み応答は、名前が実際に存在する場所を報告する: ゲームがconfigでのみ宣言する名前について kind='class' と尋ねると、「ゲームにはそのようなクラスがない」と読める真の「ノー」が得られる。
Configクラスは kind='config' の下にあり、kind='class' ではない。このマシン自身のゲームのインデックスで数えた: あらゆる種類のスクリプト宣言43 595件に対して88 102のconfigクラス。したがって、1つの種類に混ぜると、すべてのスクリプト応答を埋没させる。分離すれば、「ゲームにXというアイテムクラスがあるか」は正確に尋ねられる質問になる。
インデックスは何が存在するかに答える: クラス、メソッド、シグネチャ、宣言場所、誰がオーバーライドするか。何が正しいかには答えない——modded class X extends X がコンパイルされて静かに適用に失敗すること、_co がアルファチャンネルを犠牲にすること、binarize がファイルではなくディレクトリを受け取ること。そのどれもソースから導出可能ではなく、苦労して学ばれ、MOD作成スキルとMOD自体に生きている。インデックスはどちらかを置き換えようとはせず、フィールドが何を意味するか、クラスがなぜそこにあるかを理解しようともしない。
その決定は慎重さではなく測定によってなされた: このサーバーの初期フェーズを形作ったすべてのルックアップは名前によるルックアップだった。そして埋め込みインデックスは、このサーバーの残りが守る規則を破るだろう——インストールすれば動作し、外部サービスもキーもない。このプロジェクトが意図的に基盤としなかった前身プロジェクトは、その知識層をローカルで無料と文書化している一方で、そのコードは有料の埋め込みクライアントをインポートし、キーなしでは失敗し、ハードコードされた価格を運ぶ。その2つの検索ツールも、背後にあるクライアントがタイムアウトなしで作成されたため、永遠にハングする。したがって、ここでのすべての検索が実行される上限がある。正確な検索で不十分であることが判明した場合、セマンティック検索は1つの条件付きの別フェーズである: モデルが配信物の内部に同梱されること。
このマシン上で——2810のスクリプトファイル、35のインストール済みMOD、41ソースの1つの実際のプロジェクトを持つゲーム——内部ではなくツールを通して:
ビルド | 結果 | 時間 |
| 2927ソース、131 697宣言(41は何も生み出さなかった) | 70.2秒 |
| 8アーカイブ、10 925宣言 | 0.9秒 |
| 523アーカイブ、204 768宣言、3アーカイブは読み取り不能で名前が挙げられた | 139–147秒 |
| 41ソース、1196宣言 | 0.12秒 |
ディスク上のインデックス: 実際のプロジェクトの3層で74.7 MB。523の依存関係アーカイブだけでは110 MB。それらのアーカイブは92 GBであり、どれも展開されていない。
コールサイトこそがインデックスの代償である。 ゲーム自身のスクリプトには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 |
76ファイルのmodに対する | テキスト検査277 ms、インデックス検査7 ms |
実機スタンドで3回起動して測定: 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。走査で見つかった編集済みファイル1件8.8 ms（15倍）。同じファイルをonly=で指定した場合5.8 ms（23倍）。2810ファイルのツリーでは走査が支配的でonly=の価値ははるかに大きい——しかしこの規模のプロジェクトでは、通常のリビルドが実際に得られるのは15倍である。
天井は現実に効く: 77 msと測定されたクエリを19.3 msの天井の下で実行すると19.9 msで停止され、接続は応答し続けた。
Blenderからモデルをmodに取り込むのは10ステップで、このフェーズまではすべて手作業で実行されていた。価値はツールを起動することではない。このチェーン内のすべてのツールが構造的に失敗を報告できないことであり、その沈黙のひとつひとつがすでに数日を費やしていた。
実バイナリで測定したものであり、推測ではない:
何が起きたか | ツールが返したもの |
| 0、空の出力ディレクトリ、テキスト1行もなし |
読み込みに失敗したマテリアルを持つ | 0、正しいビルドが58,644バイトのところ、46,190バイトのODOL |
すでにバイナライズ済みのモデルを |
|
独自のデフォルト引数を持つBlenderエクスポーター |
|
したがって、この名前空間全体が基づくルールは次のとおり: 判定はアーティファクトから読み取るのであり、ツールの報告からではない。 終了コードは記録されるが、どちらの方向でも信じられない。
binarizeにはプロジェクトルートオプションがまったく存在しない——完全なスイッチ一覧は実バイナリに対して列挙された。ルートはプロセスの作業ディレクトリである。同じコマンド、同じ入力、異なるディレクトリ、そして出力されるのは、もっともらしいテクスチャパスを持つ有効なODOLであり、エンジンはそれをテクスチャなしでレンダリングする。成功コード付きで、何の不満もなく。エクスポート用のBlenderアドオンも、独自のプリファレンスに同じルートを持ち、最後に開いていたプロジェクトから記憶されている。この開発マシンでは、無関係なセッションのディレクトリを指しており、間違ったルートに対してもアドオンは失敗しない——ドライブ文字を削除し、残りを保持し、パスのように見えるパスを書き出す。
build.project_root はそのディレクトリであり、プロファイルのポータブルな半分に一度だけ記述される。サーバーはそれをバイナライザーの作業ディレクトリとして設定し、実行中はアドオンにプッシュする。したがって、アドオンが保存しているものは何も決定しない（報告されるので、修正しに行ける）。これこそが、間違ったルートを「検出可能」ではなく不可能にするものであり、モデル関連の何かが実行される前にこのキーが必須である理由である。
それが生み出す拒否は、プロセスが存在する前に発生する——0.0003秒と測定——そして拒否されたビルドは、modがすでに配布しているモデルをバイト単位で無傷のまま残す。
asset_check は何もビルドせず、DayZ Toolsもなしでそれらを実行する。なぜなら、新しいクローンが自分が配布しているものが健全かどうかを問い合わせられる必要があるからだ。4つは拒否する: ビルド済みモデルが存在し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が含まない文字列だ。6つのアーティファクトのうち6つがこの1つのテストで正しく分離され、このマシンで誰も知らなかった壊れたモデルを発見した。
asset_export はここでBlenderを必要とする唯一のツールであり、下流のすべてはどこからの.p3dでも動作する——手動エクスポート、パートナーのファイル、何年も前にコミットされたモデル。Blenderのないマシンでもmodを完全にビルドして配布できる。拒否はそれを壊れたインストールとして提示するのではなく、そのように言う。見つけたBlenderでエクスポート用アドオンが有効になっている必要があり、Blenderのユーザープリファレンスを書き戻すことは決してない（検証済み: プリファレンスファイルは毎回の実行後にバイト単位で同一だった）。
エクスポートとビルドは1つの呼び出しではなく2つである。なぜなら、それぞれの半分に独自の判定があり、一方が拒否し他方が許可するビルドは決定ではないからだ。
このパイプラインのどちらの半分も再現可能ではなく、設計はそれを装うのではなく明言する:
エクスポート。 1つの変更されていないソースファイルの7回のエクスポート——1つのセッションから3回、別のセッションから3回、そして数ヶ月前にGUIで手動で行った1回——は、一定の334,032バイトで7つの異なるSHA-256を与えた。違いは1つの内部ブロックの順序である。
binarize。 1つの変更されていない入力に対する4回の実行は3つの異なる結果を与えた: サイズは5バイト動き、2つの8バイト断片が圧縮領域から漏れ出した。
したがって、モデルはコンテンツハッシュでキャッシュまたは比較されることは決してない。比較されるのは構造フィンガープリント——ファイルの種類、LOD数、名前の集合——である。それらの7つのエクスポートすべてにわたって、そのフィンガープリントは1つの値だった。
このマシンで、ツールを通した1つの小さなモデル:
ステップ | 結果 | 時間 |
| MLOD、334,032 B、5 LOD、クリーン | 2.1秒（コールドスタートでは約8秒） |
| ODOL v55、58,646 B、4 LOD、C4マーカー5つすべて | 43.8秒（以前の4回の実行では75.6〜78.7秒と測定） |
| 1モデルと10テクスチャペアを判定 | ミリ秒 |
| PNG 1枚をDXT1へ、50,764 B | 0.52秒 |
間違ったルートでの拒否 | プロセスが開始される前 | 0.0003秒 |
両方のログはほぼすべて定型文であり、ミュートされたものは破棄されるのではなく数えられる: Blenderの169行は4に、binarizeの91行は6に——その6つのうち1つはモデルの唯一の正当な不満である。
エンドツーエンドで連結すると、エクスポートとビルドは数ヶ月前に手作業で作られたモデルを再現した: 同じ種類、同じ4つのLOD、同じ50の文字列、そしてサイズは1バイト違い。
モデルが正しく見えるか、正しくスケーリングされているか、正しく巻かれているか、コリジョンがあるか。ゲームの外では何もそれに答えない。C1〜C12はそこへの道を短くする。それらは道を置き換えない。
stale-pbo の検出はコンテンツベースではなく mtime ベースです。 mod_build
は、ソースより古い新しくビルドされた pbo を拒否します。通常の原因は、古いファイルを開いたまま保持しているサーバーが実行中であることで、パッキングは黙って何も生成しません。しかし git checkout はファイルの内容を変えずに変更時刻を変えるため、ブランチを切り替えた直後にビルドされた完全に正常な pbo もこのチェックに引っかかることがあります。ブランチ切り替え直後に mod_build が「stale pbo」を報告した場合、これは実際のパッキング失敗ではなく、この可能性が高いです。再ビルドすれば通ります。この分野の成熟したツールは、まさにこの理由でコンテンツハッシュに移行しました。これはここでの将来の作業であり、このフェーズでは行われていません (packer.py、pack_one を参照)。
mod ソースフォルダーは全体がパッキングされます。 mod_build は、ソースディレクトリに build.exclude に一致するもの（7 パターンのデフォルトは上記に記載）が含まれている mod を、公開された pbo 内に黙って出荷するのではなく、パッキングを拒否します。ソースにこのサーバー自身の成果物（署名キー、プロファイルのどちらか半分、ジョブストア、mod の以前のビルド）が含まれている場合、build.exclude に関係なく拒否します。なぜなら、それらをパッキングすると秘密の署名キーが公開されることになり、どのプロジェクトもそれを設定で除外する必要があるべきではないからです。デフォルトでは、最初にフィルタリングされたコピーをステージングしません。コピーは常にソースより新しいため、もしそのチェックがコピーを測定していたら、上記の stale-pbo チェックを恒久的に無効化することになります。build.stage = true は、とにかくコピーすることを選択します。stale-pbo の比較が常に元のソースツリーを測定し、コピーを決して測定しない場合にのみ安全です。これは、ソースがリポジトリのルートである mod が必要とするレイアウトです（常に少なくとも .git が含まれます）。
判定は、あなたの mod の行だけでなく、ログ全体を判断します。 log_verdict は、それが指すスタンドのログを読み取るため、他の mod と共有されるスタンドは、その警告をあなたの expect.max_warnings の予算に数え、そのエラーを理由として数えます。1 つの machine.stand_root を共有する 2 つのプロジェクトは、お互いのベースラインを見ることになります。各プロジェクトに独自のスタンドを与えるか、他に何がロードされているかを知った上で予算を設定してください。expect.error_regex と対称的なプロジェクトスコープのフィルターが明らかな改良であり、実装されていません。
expect.noise は、すでにエラーとして数えられている行を救うことはできません。 分類は forbid → クラッシュ → エラー → ノイズ → 警告の順序であり、ERROR または FATAL（または forbid 文字列の 1 つ）を含む行は、ノイズが参照される前に決定されます。その順序は意図的です。ノイズが最初に一致すると、無害な部分文字列が致命的な行を飲み込む可能性があります。しかし、それは noise が警告と通常の行のみを抑制でき、エラーレベルの行を決して降格できないことを意味します。
client_verdict は、準備完了の判定ではなく、エラーとクラッシュの判定です。 [expect] は サーバー のログを記述します。その準備完了行とカウンターは mod のサーバーサイドの init によって出力され、max_warnings は同じログに対して数えられる予算です。クライアントの .RPT にはそのどれも含まれていないため、これら 3 つのキーはここでは意図的に適用されず、回答はそれらを not_applied にリストします。forbid、error_regex、noise はログ行のテキストに関するものであり、引き続き適用されます。クライアント側の準備完了行を宣言するものはありません。クライアントが入ったかどうかは、client_start が待つプレイヤー数によって回答され、そのログによってではありません。
クライアントツールは、このセッションが開始しなかったスタンドに参加します。client_chat はできません。 client_start は、ポート上にすでにあるものに喜んで接続し、それが誰のものかを示します。しかし、チャットはサーバーサイドで配信され、world_* ツールと同じチャネルを通じて行われ、そのチャネルはこのセッションが開始したサーバーにのみ作用します。したがって、借用したスタンドでは、client_chat を除くすべてが機能します。拒否は、それらを拒否する server_start を提案するのではなく、ポートを保持している pid を指名します。
チャットはゲームパッドからは到達できず、メニューの確認もできません。 ゲームはチャット行を Enter にのみバインドし、他には何もバインドせず、オンスクリーンキーボードもないため、テキストはブリッジメッセージ（client_chat、無料）または実際のキーストローク（client_type、フォアグラウンドを消費）のいずれかです。client_type("", submit=True) は Enter のみを送信します。これがチャット行を開く方法であり、上記の証拠によれば、ツールセットが持つ唯一の確認方法です。
すべての知識検索は、プロジェクトツリーのウォークを支払います。 そのウォークは、プロジェクトレイヤーの陳腐化がすべての回答で測定される方法であり、インデックスが存在する唯一のプロパティです。実際の 41 ソースの mod（ツリーには約 1800 エントリが含まれます）では 3.0 ms、2810 ファイルのツリーでは 21 ms かかります。1、2 秒キャッシュするとコストが削除され、デザインが拒否するまさにその沈黙のウィンドウが復元されます。それが高価になりすぎた場合、そのトレードオフは意図的に行う必要があり、偶然ではありません。
ビルドは常にジョブを経由し、ジョブは小さなビルドよりもコストがかかります。 6 ms のプロジェクト再ビルドに対して 70〜95 ms のターンアラウンドが測定されました。job_wait は 100 ms でポーリングします。単一の形状は意図的です。呼び出し元はどのビルドがブロックするかを知る必要はありません。次の検索がレイヤー自体を測定するため、待つことを強制するものはありません。
依存関係レイヤーは、現在のプロファイルに対して測定されます。 mods.required に mod を追加すると、そのアーカイブは added として到着します。削除すると、そのアーカイブは missing として読み取られます。それが要件です（宣言されたセットはレイヤーが構築されるものの一部です）。しかし、実際に変更されたのはプロファイルであるのに、インデックスが古くなったように見えます。
core には常にゲームの設定が含まれ、それがコストの大部分です。 設定ありで 70 秒、スクリプトのみで約 4 秒です。スイッチはありません。設定なしでは「X というアイテムクラスはあるか」に答えることができず、2 番目の軸があると陳腐化の測定が曖昧になります。ウォークは Addons アーカイブを期待するかどうかを知らないからです。
knowledge_show は最も近いレイヤーから最初に答えます。 依存関係が modded class で再オープンするクラスの場合、mod の宣言がゲームの宣言より先に来ます。それは正しい順序であり、驚くべき順序です。ゲーム自身のものには layer='core' を渡してください。
条件付きコンパイルはインデックス化され、解決されません。 ゲームのスクリプト行の 4.9% が #ifdef 内にあり、約 100 のクラス宣言が含まれます。このサーバーはサーバー、クライアント、診断ビルドを駆動するため、単一の正しい定義セットはありません。すべてがインデックス化され、ガードは宣言に記録されます。したがって、特定のビルドが除外する名前が報告される可能性があります。代替案である定義の 1 つの推測でフィルタリングすると、実行中のビルドにあるメソッドの存在を否定することになります。
C12 のフィンガープリントはファイルのサイズを保持し、binarize のサイズは安定していません。 誰も編集していないモデルを再ビルドすると、出荷されたものより 1 バイト大きいアーティファクトが生成され、同じ種類、同じ LOD 数、同じ 50 の文字列、そしてサイズが一部であるため異なるダイジェストが生成されました。したがって、C12 は何も変更していない再ビルドについて警告できます。まさにこの理由で、拒否ではなく警告し、それが構築される部分がその隣に報告されるため、手動で比較できます。ダイジェストを安定した半分とサイズに分割することが明らかな改良であり、行われていません。
部分的なエクスポートは警告します。拒否はしません。 エクスポーター自身のデフォルト引数では、モデルは 5 つの LOD のうち 2 つを運び、他のすべてのチェックに合格して出てきました。このサーバーはそれらの引数を渡さないため、これは起こるべきではありません。しかし、LOD としてマークされ、シーンにリンクされていないオブジェクトは、比較の一方の側で数えられ、もう一方では数えられません。これはカウントが異なる正当な理由であり、拒否は誤検出を持つことになります。E3 を読んでください。
包含ルールは、すべての間違ったルートを見ることはできません。 それは、mod のプレフィックスフォルダーを保持しないルートを拒否します。これは測定された失敗です。その名前のフォルダーを保持するルート（たとえば、独自の mod ディレクトリがプレフィックスのように綴られているリポジトリ）はそれを通過し、そのケースを捕まえるのは C10 または 1 層下の C3/C4 です。測定済み：そのようなルートを指すと、ビルドは拒否され、何もデプロイせず、出荷されたアーティファクトは変更されませんでしたが、拒否は呼び出しではなくジョブから来ました。
asset_export は、Blender でエクスポートアドオンを有効にする必要があり、インストールできません。 Blender はマシン所有者の実際の設定で起動されます。--factory-startup で起動するとアドオンが完全に取り除かれるためです。彼らの他のアドオンは、実行の検索パスから除外されます（ここにインストールされている 2 つは起動時にネットワークに到達し、クラッシュの原因とされています）。Blender はログに「Add-on not loaded」と報告します。その行はこのサーバー自身の仕業であり、障害ではありません。
バイナリ化された設定には、表示する本体がありません。 knowledge_show(body=True) は、インデックス化されたファイルまたはアーカイブから宣言を読み戻しますが、config.bin はバイナリ形式を保持し、インデックスは CfgConvert がそれから作ったものを保持します。答えは、何も返す代わりにその旨を述べます。
python -m pip install -e ".[dev]"
python -m pytestMCP クライアントに登録します：
{ "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
