An MCP server that lets an agent build, test, and inspect DayZ mods end-to-end: pack and sign mods, boot a test server, get structured verdicts instead of raw logs, drive a live client, query a knowledge index, and manage the model asset pipeline.
Open and inspect projects via two-part profiles, discover the game/tools, and report what is missing.
Build and sign declared mods with lint checks, stale-pbo detection, job-based progress, and optional staging.
Start, stop, and monitor test servers, wait for readiness, check logs, and read or change the stand's verifySignatures policy.
Run client compile checks and get pass/fail verdicts from server or client logs using counters, forbidden strings, warning budgets, and error regexes.
Interact with the live world through a bridge: spawn, delete, teleport, set health/quantity, change time/weather, run mod actions, and inspect nearby entities.
Drive a live game client: start/stop/status, capture screenshots, virtual gamepad movement/camera/buttons, chat, client-side typing, UI menu/widget inspection and clicks.
Build and query a local SQLite knowledge index of game, dependency, and project APIs: find, show, overrides, callers, scope narrowing, and server mod matching.
Run the asset pipeline: export from Blender, binarize models, validate shipped models/textures, convert textures, with verdicts read from artifacts rather than tool exit codes.
Manage bridge lifecycle: build the bridge mod, check heartbeat, clear a stuck command mailbox, and distinguish alive/restarted/frozen/unknown states.
Provides Blender asset export for DayZ modding, using the Blender executable to export models into the mod project.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@dayz-agentic-modding-mcp Build my DayZ mod and run a compile check"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that lets an agent build a DayZ mod, check that the client compiles, run a test server and get a structured verdict instead of a log.
The server does the work itself: it calls FileBank, the signing tool and the diagnostic executable directly. A project does not need its own build script.
The server knows nothing about any particular mod. Everything specific lives in a two-part profile:
dayz-mcp.toml — portable, committed to the mod repository: which mods to pack,
what a healthy boot looks like.
dayz-mcp.local.toml — machine-specific, never committed: where the game, the
tools and the test stand live.
Mixing the halves is rejected on load: that is how a repository stops building on
anyone else's machine. Start from dayz-mcp.example.toml.
A mod is declared once, by name: sources in <root>/Name by default, output
@Name/addons/Name.pbo. build.sources can redirect a mod's source elsewhere
(e.g. "." for a mod whose config.cpp sits at the repository root itself).
dayz-mcp.tomlKey | Meaning |
| what to call this project |
| one entry per mod, by name; source, pbo and |
| where a mod's source really lives, relative to the profile ( |
| what must never be packed. Listing it replaces the default wholesale; the default is |
| pack a filtered copy instead of refusing when something excluded is present — the layout a root-layout mod needs |
| the directory every model path resolves against, relative to this file. It must contain the mod's prefix folder. Required by the model tools and by nothing else — see "The asset pipeline" |
| a PowerShell script run before packing, for projects that generate code first |
| widget classes your own scripts declare (a modded map widget, say), so the layout lint does not refuse them as unknown |
| where the layout generator's tokens file lives, if not the default |
| the line the mod prints when it has finished loading — see below |
|
|
| warning budget; omit the key to disable the check |
| substrings that make a run bad regardless of anything else |
| regexes marking script errors that belong to you, used by the client compile check |
| extra engine noise to ignore, on top of the built-in list |
| launch the client with |
dayz-mcp.local.toml, never committedKey | Meaning |
| the game installation; discovered automatically if absent |
| a dedicated server installation (Steam app 223350) to boot the stand from, instead of the diagnostic executable inside |
| DayZ Tools; discovered automatically if absent |
| the Blender executable, for |
| the prepared test stand. The server boots against it and its logs are read from |
| the server config filename inside the stand (default |
| the port |
| client window size, |
| mod folder names, resolved under the game's own |
| full paths to anything else to load, for mods that do not live in |
| folder names to route to |
server_start finishes when expect.ready_line appears in a log written after
that boot began. It is the one thing the server cannot work out for itself, and
without it two things change: nothing can be waited for, so the boot job starts
the server, confirms it is still alive a moment later and finishes saying so;
and log_verdict has no line to read counters off, so expect.counters never
matches anything. Errors, crashes and the warning budget are still judged. A
profile without a ready line is supported, not broken — project_open says so
in its notes.
Related MCP server: DayZ API MCP Server
Tool | What it does |
| read the profile, discover the game and tools, report what is missing |
| current project, running server, recent jobs |
| pack and sign every declared mod; returns a job id. Refuses a second build of the same project while one is still running |
| start the test server, finish when it is ready. Refuses if the mission the config names is not under |
| pid, whether the process is alive, whether the log is growing (sampled |
| stop the server this session started (optional pid for orphaned servers) |
| read — or deliberately change — the stand's |
| run the diagnostic client and read its logs |
| pass/fail with reasons: counters, forbidden strings, warning budget. |
| last lines, optionally filtered; same two sources |
| status of a long-running job |
| wait for a job to finish |
| retrieve outputs from a completed job |
| pack the bridge mod, whose sources ship with this server ( |
| is the bridge inside the running game still ticking: reports the tick number and whether it advanced over |
| discard the command stuck in the mailbox, naming what it threw away. Refuses while the bridge looks alive unless |
| wait until the bridge inside the game is actually claiming commands. Call it once after the boot job finishes, before the first world command — see "server ready is not bridge ready" below |
| snapshot of the world from the bridge's once-a-second publish: players, position, health, hands. Free with no arguments; with |
| create an item on the ground (with no lifetime, so it cannot vanish mid-check), in the player's hands, in their inventory, or attached to the item they are holding ( |
| move the player to |
| set |
| attach an item the player already has to another of their items. |
| take the attachment out of one slot and put it in the player's |
| move an item the player already has between |
| switch a device on or off wherever it is on the player — worn, in a pocket, in hands — through its energy manager. |
| delete objects of one class nearby. Requires the class; never deletes a real player |
| which objects are nearby, not how many: class, position, distance and health for each. A page, and it says so — the true total comes back beside the list |
| move the world clock. Every field left at -1 keeps its current value, read back from the engine first, because the engine sets a date as five numbers at once |
| move overcast, rain, fog, snowfall or wind. A nudge, not a lock: the engine keeps simulating weather afterwards, and both the tool and the mod say so |
| run a mod's own action through the engine's gate — see below |
| the escape hatch: an arbitrary verb through the same transport, marked non-standard in every answer |
| start the game client and connect it to the stand; returns a job id. Always windowed ( |
| pid, window geometry, whether the window is minimized or in front, the background setting, the player count, and whether a virtual controller is attached |
| stop the client this session started, and unplug the virtual controller |
| capture the client's window to a PNG, with |
| walk the character with the left stick. Analog, and the only tract that moves the character at all. No focus needed |
| turn the camera with the right stick. No focus needed |
| one gamepad button, from a closed table of fourteen names. No focus needed |
| pull an analog trigger — |
| put a line in chat — delivered server-side by the bridge, so no keyboard, no window, no focus |
| type into a client-side input field with real keystrokes. The only tool here that takes the foreground, and it says so in its answer |
| judge the live client by its own |
| what the client's interface is doing: open menu class, cursor, dialog. Free — republished every tick |
| the client's widget tree: path, class, name, visibility, screen rectangle, depth, text and text size (engine pixels, TextWidget family only). A page, and it says so. |
| the same walk, filtered in the client so the whole tree never has to travel — and filtered during the walk, before the 300-node ceiling, so a name is found wherever it is rather than only in the first page. |
| press a widget. |
| what the real mouse is over right now, from the engine's |
| write into an edit box, and read the value back out of the widget |
| show a layout file in the client under a host of the bridge's own size, and list what the engine made of it. |
| remove the preview |
| a layout as the engine draws it, in one folder: a screenshot, every widget's rectangle, and the rectangle checks, with an HTML report over all three. |
| every entry of the project's preview index ( |
| generate every |
| judge the Enforce Script without packing or booting anything. |
| build or refresh a layer of the API index; returns a job id. |
| what each layer holds, how old it is, and whether it still matches what is on disk |
| find a class, method, constant, enum or config class by name |
| one declaration in full: signature, members, inheritance chain, and the source itself — read straight out of an archive if that is where it lives |
| who overrides this class or method |
| who calls this method or builds this class — every call site, with the class and method that made it |
| export a model out of a |
| binarize a mod's models from their MLOD sources, judge what came out, and only then put it in the mod; returns a job id |
| judge the models and textures a mod already ships. Builds nothing, needs no DayZ Tools, answers in milliseconds |
| convert one texture between |
Most of layout_build's JSON vocabulary (frame, panel, vbox, label, button, ...)
reads as what it says. Two are worth a sentence each, because what they emit is not
obvious from the description:
Primitive | Emits |
| a |
| a |
Windows and the ms-gamebar dialog. The first time a virtual controller is
attached, Windows tries to open Xbox Game Bar. On a machine that has it, nothing is
seen; on one that does not — LTSC, Server, or the Xbox packages removed — the shell
cannot resolve the URI and puts up "Get an app to open this ms-gamebar link", once
per attach. Nothing here causes it and nothing here can prevent it: the shell reacts
to the device arriving, and does the same for a physical Xbox pad. So the call that
plugs the pad in says so, with two remedies the machine's owner can apply — turning
off Settings → Gaming → Xbox Game Bar → "Allow your controller to open Xbox Game
Bar" (HKCU\Software\Microsoft\GameBar\UseNexusForGameBarEnabled = 0), or giving
the URI a handler that does nothing.
Signatures, and why the engine's own message sends you the wrong way. Under
verifySignatures = 2 a stand refuses every client with code 118 and "missing
dta\bin.pbo" — a vanilla file name, with no mention of signatures at all. The
cause is usually the keyring: this tool launches the diagnostic executable out of
the CLIENT install, so the engine reads keys beside that executable, while
dayz.bikey — the key that signs the game's own pbos — ships with the separate
DayZServer install. A keys folder that is missing, or holding only a mod's own
key, leaves the server unable to verify anything, vanilla included. client_start
refuses and names which of the three it is; server_start only warns, because a
headless boot with no client is still useful. An unsigned pbo on the client's
-mod line is named the same way — including this server's own bridge, which is
packed unsigned on purpose.
Three limits the engine imposes on the UI tools, none of them worked around:
a plain TextWidget has SetText and no GetText anywhere in enwidgets.c, so a
label's string cannot be read at all — what a mod's interface MEANS stays a question for
the server-side bridge, where the data is real. A script-level click reaches only the open
scripted menu, because Widget has SetHandler and no GetHandler; via="cursor" is
there for everything else. And the client has to load the bridge: one pbo carries both
halves, so a profile listing it under mods.server_only keeps it off the client's -mod
line — that case is refused by name rather than answered with an empty tree.
job_wait is the tool meant to wait, and its timeout is capped at 600
seconds however large a value is passed. Two other tools sleep: server_status
samples the log twice, pulse_seconds apart, capped at 10 seconds — that pause
is how it tells a slow boot from a hung one — and bridge_status samples the
bridge's tick twice, window apart, capped at the same 10 seconds, for the same
reason. Everything else returns immediately; work that takes minutes happens
behind a job id.
bridge_build packs bridge/ from this server's own repository into
@DZMCP_Bridge beside it. It is the server's mod, not yours: one copy serves
every project, nothing is written into your repository except the job record,
and no project's signing key is used — a -serverMod pbo is never handed to a
client to verify, so it is built unsigned and its output folder is kept free
of signatures and keys.
Building it does not load it. That stays your profile's decision, because the
bridge is an extra pbo in the stand and a run without it has to remain possible.
To attach it, add two lines to dayz-mcp.local.toml (the same two
bridge_build's job summary prints):
[mods]
extra = ["<path printed by bridge_build>/@DZMCP_Bridge"]
server_only = ["@DZMCP_Bridge"]server_only is what routes it to -serverMod instead of -mod. Without it
the stand boots perfectly well and bridge_status reports that the bridge never
wrote any state — which is true, and easy to mistake for a broken bridge.
bridge_status also reports the command mailbox. Inside the game only the mod
empties it, by claiming the command; on this side bridge_clear and
server_start's pre-boot clearing do. So a command sent while the stand was
down, or before the bridge was attached, is not discarded and does not expire on
its own — it keeps blocking
every later send, and a stand booted outside these tools would pick it up.
server_start clears both transport files before every boot, so a server
started through this tool never runs a command from a previous session; that is
hygiene, not a substitute for knowing the command is there. The state comes back
as stale_command, and
bridge_clear() is the way out of it. Clearing is a separate tool on purpose:
throwing away a queued command is a decision, not something a status check
should do behind your back. It refuses while the bridge looks alive unless you
pass force=True, and either way it reports the command id it discarded.
bridge_status can tell apartThe tick alone is not enough to judge a bridge, because it restarts at 0 every
boot while the state file survives in the profile directory. Every answer
carries the channel's own verdict in heartbeat, and the four are genuinely
different facts:
|
| meaning |
|
| the tick moved within one session — the only |
|
| a new world came up between the two samples: alive, not frozen, and anything sent to the old session is gone |
|
| the same world seen twice, not moving — a script-side problem, so |
|
| a sample could not be read (or |
Every answer that read a sample also carries session_id — the live world's
id — and a restarted answer carries previous_session_id too, so a caller can
say which world went away.
no_server, stale_command, no_state_file, invalid_state,
unreadable_state and outdated_bridge come before any of that: nothing is
running, a command is wedged, the mod is not loaded, the state document is valid
JSON with a named field wrong (it says which, and checks twice before saying it),
the file never parses at all, or it parses but predates this server's protocol
(rebuild it with bridge_build).
The world tools talk to the bridge over two JSON files in the server's
-profiles directory: a command mailbox (written atomically from this side,
deleted by the mod as its claim) and a state file the mod overwrites once a
second. Enforce Script has no rename, so the mod cannot write atomically —
the reader tolerates torn writes instead, and one failed read is never news.
Four facts, all measured on a live stand, decide how to use them:
Server ready is not bridge ready. The bridge starts claiming commands
tens of seconds after the server reports ready — the spread observed so far
is 18–38 seconds, and it varies boot to boot.
A command sent into that window is not rejected — it is claimed late and
completes after the caller gave up. So: server_start, wait for the boot job,
then world_ready(), then commands. Every world tool also refuses upfront
if the tick is not moving, naming world_ready as the remedy.
Every argument value crosses the wire as a string. The mod's parser is
strict: a JSON number anywhere in args rejects the whole args block. The
tools stringify numbers and booleans themselves and refuse values with no
faithful string form (lists, dicts, None). Positions travel as one string,
"x y z".
A refusal is a result. The mod's own sentence comes back verbatim as the error: "no player is on the server", "the class does not exist", "the action's own Can() said no". Nobody connected is the normal state of a headless stand, and every verb that needs a player says so instead of silently doing nothing.
The session id protects against yesterday's command. Every command carries the session the bridge most recently published; the mod refuses any command addressed to another session (or none) without executing it. A command written while the stand was down can therefore never fire into a freshly booted world. The tools stamp the session automatically — it only matters if you write the mailbox by hand.
Measured on a live stand, three boots. world_time_set(hour=3, minute=7)
moved the clock to 2026-09-20 03:07 and left the date where it was;
world_weather_set("fog", 0.9, seconds=2) took the published fog from 0.085 to
0.900 and held it; world_entities(pos="7500 0 7500", radius=150, limit=5)
listed 5 of 171 objects with truncated: true. Distances came back at 320 m
for a 150 m radius until they were made horizontal, which is what the engine's
own radius test measures.
world_attach, world_detach, world_move and world_power ship in this
bridge rather than in a project's own copy of the dispatcher, and the line is
worth stating: taking an item off a slot, putting one on, carrying one in a
pocket instead of a hand, and throwing an energy manager's switch are the same
calls whatever mod drew the device (FindAttachment,
ServerTakeEntityAsAttachmentEx, ServerTakeEntityToInventory,
ServerDropEntity, GetCompEM().SwitchOn). The rule under world_exec is
about behaviour a mod defines; none of this is.
They exist because a worn device could not be reached at all: world_spawn
attaches a NEW item to whatever is in HANDS, world_set knows health and
quantity, and world_action needs the item in hands too — so on a live stand a
flat battery could not come out, a fresh one could not go in, and nothing could
switch a device on, which left every action whose condition reads IsWorking()
untestable from outside the game. All three name the item the only way a tool
that has never seen it can: "hands", "player" (the character's own worn
slots), or a config class looked up on the player — hands first, then worn
attachments and cargo, recursively, first match by IsKindOf. world_move
covers the other half of the same gap: carry it, do not hold it is where a
test of a worn or pocketed device starts, world_spawn puts an item in one
place and leaves it, and the move between hands, inventory and ground is a drag
inside the inventory screen — a gesture no tool can make.
Each one reads the result back out of the engine rather than reporting the
call's own bool: whether the slot is empty now, whether the item's own
inventory location says it landed in that slot, whether the manager says
switched-on and working. That
is the same rule as ui_text reading its field back, and for the same reason —
SwitchOn() does nothing at all when the device cannot switch on, and says
nothing about it.
An inventory move lands one tick after the frame that asked for it
(measured 2026-09-07): ServerTakeEntityToInventory answered true and the slot
still held the battery in that same frame, and the very next command found the
slot empty and the battery in cargo — so a read-back taken where the call
returns reports a failure for a move that worked. attach, detach and move
defer their own verdict by a tick, the same DeferCompletion(1) ui_load uses
to let a widget reach its first layout pass, and cost about a second more than
the other world verbs for it. attach spends that tick on more than a yes: it
names the slot the item landed in, read off the item's own inventory
location, so a call that named no slot still comes back with the name
world_detach will want.
One tick is not always enough (measured 2026-09-08). A move whose source
is the hands does not go straight into the inventory: HumanInventory turns it
into a HandEventMoveTo and posts it to the hand state machine, which applies
it on the player's next command-handler frame — later than the bridge's next
tick when the player is busy. Attaching the item held in hands to a player slot
answered failed once for a move that had in fact worked. So the three verbs
look again, up to five ticks (still inside the mod's own 30 s hard limit and
well inside this side's 45 s wait), and the answer names the wait it spent:
... after 2 tick(s). A move that never lands is still refused by the mod in
its own words, with the tick count, rather than by a timeout.
A semantic verb like "hand in the sample" lies: in a real mod the same words
mean different things depending on which device is near, the player's faction,
and what is already unlocked. That context is not enumerable, so the bridge
does not try. world_action takes an action's class name, a target and the
held item, and asks the engine to run it through its own gate — the same one a
key press goes through. Applicability is decided by the action's own Can(),
and its refusal is a meaningful test result, not a tool failure. The
distinguishable answers: manager busy, player already acting, player
sprinting, unknown action class, and "the action's own Can() said no".
"Accepted" is not success either — the command stays running until the engine
actually releases the action, and every failure path releases the manager so
the player can still act afterwards.
world_exec is the escape hatchAnything a mod exposes that is not an action — "how many points in the
faction pool" — goes through world_exec(verb, args): an arbitrary verb over
the same transport. Every answer is marked non_standard: this server does
not know the verb, does not validate it, and does not answer for what the mod
does with it. A verb the bridge build does not know comes back listing the
verbs it does. A project that needs its own verb edits its own copy of the
bridge's dispatcher (the comment above KnownVerbs() in
bridge/scripts/5_Mission says exactly where); there is no registration
machinery on purpose — a verb this server typed and validated would be a verb
this server answers for.
The bridge reaches the server. What it cannot do is look at the client's
screen or act through the client — walk a character across ground, open a
menu, fill a field a mod drew. The client_* tools are that, and they use
three different tracts because no one of them can do the other two's work.
Every line below is a measurement against a live client, not a design
intention.
Tract | What it does | Needs the foreground |
the bridge ( | the world, and text into chat | no |
a virtual gamepad, ViGEmBus ( | movement, camera, and some interface | no |
real keystrokes, | text into a field that exists only on the client | yes, and it takes it |
Keyboard emulation does not move the character, and window messages do
nothing at all. SendInput scancodes with the foreground verified: 25 s of
forward, 0 m. PostMessage/SendMessage WM_KEYDOWN into the main window
and its children: 0 m, and no reaction from the menus either. The engine
reads movement from raw input and ignores emulated keys, which is why no
tool here offers a window message.
The virtual gamepad does move it, unfocused, and it is ANALOG — the reason it stays even where a key would do. Measured in one run with a third-party application holding the foreground throughout:
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)Same tract, same character, 2.7× the speed from stick deflection alone. "The character is walking, not running" cannot be expressed with a key, which knows only on and off. In the same run the character walked about 141 m of its own accord, and the mod's own count of objects within 10 m of it went 1 → 0 → 1 as it left the spot and came back — a state change caused by presence, which a teleport cannot produce.
Some of the interface answers the pad, and some does not. Measured, with
the game window behind another application the whole time: back opens and
closes the inventory, start opens the pause menu, b closes it — all at the
default 0.1 s tap, so a tap is long enough for the engine to latch. But a
moved nothing, at 0.1 s or at 0.5 s, and neither did the d-pad inside those
screens: the client did not switch to controller-navigation mode, so there was
no focused element for a confirm to act on. Treat menu dismissal as a
gamepad job and menu confirmation as unproven.
The eyes need no focus either. A capture is a live frame with the window
at the very bottom of the z-order (lit_fraction 0.9997 unfocused, 0.9997
focused in the same session). The one state that defeats them is a
minimized window, whose client area collapses to 0×0 — refused with a
reason rather than saved as a valid-looking empty picture.
All of that background behaviour rests on one client setting, pauseMode
(GAME → UPDATE IN BACKGROUND). At the value measured here the client keeps
drawing and simulating while unfocused, which is why the frame is live and the
stick still moves the character. At "no graphics" both would stop silently —
a frozen frame looks exactly like a live one. So client_start and
client_status READ that setting and warn; they never write it, because it
belongs to whoever owns the machine.
Two more profile settings ride along on the same launch line.
client.file_patching adds -filePatching (the stand's server config needs
allowFilePatching = 1 or the client is refused at connect), and
machine.window — or a per-call window= override — adds -x/-y.
client_type is the only tool that takes the screen, and it is honest
about it: the answer carries foreground_taken and a sentence saying the
person at the machine could not type into their own window while it ran. It
verifies the foreground with GetForegroundWindow after asking for it, because
SetForegroundWindow returns success having done nothing when Windows refuses
— and typing blind sends the keystrokes into whatever window the person is
actually using. When the foreground cannot be had, nothing is typed and the
refusal names the process holding it.
ViGEm is emulation of a real device and this is a test stand. The driver is signed and installs without a reboot, and the gamepad is a new device rather than a filter over the machine's own keyboard and mouse — a filter driver was tried here once and cost the machine's owner all keyboard and mouse input until it was unwound by hand. None of that is a promise about anticheat on a live server, and nothing in this phase makes one.
An agent writing a mod keeps asking the game the same questions: is there such
an API, what is it called, where is it declared, who overrides it. Answering
them meant unpacking scripts.pbo and sweeping the text — and every session
paid again. knowledge_* turns that work into a question.
It is a plain SQLite file in the project's own .dayz-mcp/, built by this
server out of the game, the mods a project declares and the project's own
sources. No embeddings, no external service, no key.
Layer | Source | Goes stale when |
| the game: | the game updates |
| the archives of the mods the profile declares, read without unpacking them | a dependency is updated, or the declared set changes |
| the mod's own sources, read where they lie | every edit |
One index built in one go would be wrong within a minute of being right: the
game moves a few times a year, a dependency a few times a month, and the
project between one agent turn and the next. So each layer is built, aged and
measured on its own, and every build is incremental — unchanged sources are
skipped by size and modification time, and only=[path] skips even the walk
that discovers them.
Staleness is measured, not guessed: a layer records the size and modification time of every source it read, and that is compared against the files as they are now.
Every answer names the layers it used and how old each one is. An answer with no results names every layer it searched — "not found" is worth exactly as much as the layers behind it are current.
The project layer's freshness is measured on every search, whether or not it contributed. That is the dangerous case: an agent adds a class, asks about it, and a layer built a minute ago says "not found" — a confident statement about code that exists.
A search over a layer that was never built is refused, and the refusal names the call that builds it. "Not found" and "not looked" are different facts, and only one of them is safe to act on.
Narrowing carries the same trap one level down, so an empty narrowed answer
reports where the name does exist: asking 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".
Config classes live under kind='config', not kind='class'. Counted in this
machine's own index of the game: 88 102 config classes against 43 595 script
declarations of every kind put together, so mixed into one kind they bury every
script answer. Separated, "does the game have an item class called X" is a
question you can ask exactly.
The index answers what exists: class, method, signature, where declared, who
overrides. It does not answer what is right — that modded class X extends X compiles and silently fails to apply, that _co costs the alpha channel,
that binarize takes directories rather than files. None of that is derivable
from the sources; it was learned the hard way and lives in the modding skill and
in the mod itself. The index does not try to replace either, and it does not try
to understand what a field means or why a class is there.
The decision was made by measurement, not caution: every lookup that shaped this server's earlier phases was a lookup by name. And an embedding index would break the rule the rest of this server keeps — install it and it works, with no external service and no key. The predecessor project this one deliberately did not build on documents its knowledge layer as local and free while its code imports a paid embedding client, fails without a key and carries hard-coded prices. Its two search tools also hang forever, because the client behind them was created without a timeout; hence the ceiling every search here runs under. If exact search turns out not to be enough, semantic search is a separate phase with one condition: the model ships inside the delivery.
On this machine — the game with 2810 script files, 35 installed mods, one real project of 41 sources — through the tools, not their internals:
Build | Result | Time |
| 2927 sources, 131 697 declarations (41 gave nothing) | 70.2 s |
| 8 archives, 10 925 declarations | 0.9 s |
| 523 archives, 204 768 declarations, 3 archives unreadable and named | 139–147 s |
| 41 sources, 1196 declarations | 0.12 s |
The index on disk: 74.7 MB for a real project's three layers; 110 MB for the 523 dependency archives on their own. Those archives are 92 GB, and none of them is unpacked.
Call sites are what the index pays for. The game's own scripts hold 43 579 declarations and 113 703 call sites, and recording the second set roughly doubles the index: measured on the game layer alone, 23.8 MB and 3.7 s to build without them, 49.6 MB and 4.5 s with. That is the price of being able to answer "who calls this", and it is stated here rather than discovered later on a full disk.
Answer | Time |
| 4.2 ms end to end, of which 3.0 ms is the project walk |
| 3.2 ms of query |
| 4.2 ms |
| 0.38 ms of query |
| 277 ms of text checks, 7 ms of index checks |
| 6.8 ms |
| 41 ms (110 ms on the first call after a build) |
Incrementality, on the real project: a full rebuild 136 ms; one edited file
found by the walk 8.8 ms (15×); the same file named through only= 5.8 ms
(23×). On a 2810-file tree the walk dominates and only= is worth far more
— but on a project of this size, 15× is what an ordinary rebuild actually buys.
The ceiling bites for real: a query measured at 77 ms, run under a 19.3 ms ceiling, was stopped at 19.9 ms, and the connection went on answering.
Getting a model from Blender into a mod is ten steps, and until this phase all of them were run by hand. The value is not in launching the tools. It is that every tool in this chain is structurally unable to report failure, and each of those silences had already cost days.
Measured on the real binaries, not assumed:
What happened | What the tool returned |
| 0, an empty output directory, not one line of text |
| 0, an ODOL of 46,190 bytes where a correct build is 58,644 |
|
|
the Blender exporter with its own default arguments |
|
So the rule this whole namespace is built on: the verdict is read off the artifact, never off the tool's report. The exit code is recorded and believed in neither direction.
binarize has no project-root option at all — the full switch list was
enumerated against the real binary. The root is the working directory of the
process. The same command, the same input, a different directory, and out comes
a valid ODOL with plausible texture paths that the engine renders untextured,
with a success code and no complaint. The exporting Blender add-on has the same
root in a preference of its own, remembered from whatever project was open
last: on the machine this was developed on it pointed at a directory from an
unrelated session, and against a wrong root the add-on does not fail either —
it strips the drive letter, keeps the rest, and writes paths that look like
paths.
build.project_root is that directory, stated once in the portable half of the
profile. The server sets it as the binarizer's working directory and pushes it
into the add-on for the duration of the run, so what the add-on has stored
decides nothing (it is reported, so you can go and fix it). That is what makes
a wrong root impossible rather than detectable, and it is why the key is
required before anything model-shaped will run at all.
The refusals it produces happen before a process exists — measured at 0.0003 s — and a refused build leaves the model the mod already ships byte for byte untouched.
asset_check runs them without building anything and without DayZ Tools,
because a fresh clone must be able to ask whether what it is shipping is
healthy. Four refuse: a built model is there and is an ODOL (C1), no reference
escapes the mod (C3), a material was actually inlined (C4), and nothing already
binarized is offered back to binarize (C10). 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, a structural fingerprint that no longer
matches what the last build deployed. Every finding says what to do.
C4 is the one worth knowing about. When binarize resolves an rvmat it copies
that material's own stage textures into the model — fresnel,
#(argb,8,8,3), env_land_co.paa, _nohq, _smdi — strings no MLOD
contains. Six artifacts out of six were separated correctly by that one test,
and it found a broken model on this machine that nobody knew about.
asset_export is the only tool here that needs Blender, and everything
downstream works on a .p3d from anywhere — a hand export, a partner's file, a
model committed years ago. A machine with no Blender builds and ships a mod
perfectly well; the refusal says so rather than presenting it as a broken
installation. It does need the exporting add-on to be enabled in the Blender it
finds, and it never writes Blender's user preferences back (verified: the
preferences file was byte-identical after every run).
Export and build are two calls rather than one, because each half has its own verdict and a build refused by one and allowed by the other is not a decision.
Neither half of this pipeline is reproducible, and the design says so instead of pretending:
The export. Seven exports of one unchanged source file — three from one session, three from another, and one made by hand in the GUI months earlier — gave seven different SHA-256s at a constant 334,032 bytes. The difference is the order of one internal block.
binarize. Four runs on one unchanged input gave three different results:
the size moved by 5 bytes and two 8-byte fragments leaked out of compressed
regions.
So a model is never cached or compared by content hash. What is compared is a structural fingerprint — the file's kind, its LOD count and its set of names. Across all seven of those exports that fingerprint was one value.
One small model, on this machine, through the tools:
Step | Result | Time |
| MLOD, 334,032 B, 5 LODs, clean | 2.1 s (about 8 s on a cold start) |
| ODOL v55, 58,646 B, 4 LODs, all five C4 markers | 43.8 s (75.6–78.7 s measured on four earlier runs) |
| 1 model and 10 texture pairs judged | milliseconds |
| one PNG to DXT1, 50,764 B | 0.52 s |
a refusal on a wrong root | before any process is started | 0.0003 s |
Both logs are almost entirely boilerplate, and what is muted is counted rather
than dropped: Blender's 169 lines came down to 4, and binarize's 91 to
6 — one of those six being the model's only genuine complaint.
Chained end to end, the export and the build reproduced a model that had been made by hand months earlier: same kind, same 4 LODs, the same 50 strings, and a size one byte apart.
Whether the model looks right, is scaled right, is wound right, has a collision. Nothing outside the game answers that. C1–C12 shorten the road to it; they do not replace it.
Stale-pbo detection is mtime-based, not content-based. mod_build
refuses a freshly built pbo that is older than its sources -- the usual
cause is a running server still holding the old file open, so packing
silently produced nothing. But git checkout changes a file's modification
time without changing its content, so a perfectly good pbo built right
after switching branches can trip this check too. If mod_build reports
"stale pbo" immediately after a branch switch, this is the likely reason,
not a real packing failure -- rebuild and it will pass. A mature tool in
this space moved to a content hash for exactly this reason; that is future
work here, not done in this phase (see packer.py, pack_one).
A mod source folder is packed whole. mod_build refuses to pack a mod
whose source directory contains anything matching build.exclude (the
seven-pattern default is listed above) rather than silently shipping it
inside the published pbo. It refuses regardless of build.exclude when the
source contains this server's own artifacts -- the signing keys, either half
of the profile, the job store, the mod's previous build -- because packing
those publishes the private signing key, and no project should have to
configure that away. By default it does not stage a filtered copy first: a
copy is always newer than the sources, which would permanently disable the
stale-pbo check above if that check measured the copy. build.stage = true
opts into copying anyway -- safe only because the stale-pbo comparison always
measures the original source tree, never the copy. This is the layout a mod
whose source is the repository root needs (it always contains at least
.git).
A verdict judges the whole log, not just your mod's lines. log_verdict
reads the log of the stand it is pointed at, so a stand shared with other
mods counts their warnings against your expect.max_warnings budget and
their errors as reasons. Two projects sharing one machine.stand_root will
see each other's baseline. Either give each project its own stand, or set the
budget knowing what else is loaded. A project-scoped filter, symmetric with
expect.error_regex, is the obvious refinement and is not implemented.
expect.noise cannot rescue a line that already counts as an error.
Classification is ordered forbid → crash → error → noise → warning, so a
line containing ERROR or FATAL (or one of your forbid strings) is
decided before noise is consulted. That order is deliberate -- noise matching
first would let an innocuous substring swallow a fatal line -- but it means
noise can only suppress warnings and ordinary lines, never demote an
error-level one.
client_verdict is an errors-and-crashes verdict, not a readiness one.
[expect] describes the server's log: its ready line and counters are
printed by a mod's server-side init, and max_warnings is a budget counted
over that same log. A client .RPT contains none of it, so those three keys
are deliberately not applied here and the answer lists them in
not_applied. forbid, error_regex and noise are about the text of a
log line and still apply. There is no client-side ready line to declare;
whether the client got in is answered by the player count client_start
waits on, not by its log.
The client tools join a stand this session did not start; client_chat
cannot. client_start will happily connect to whatever is already on the
port, and says whose it is. But chat is delivered server-side, through the
same channel as the world_* tools, and that channel acts only on a server
this session started — so on a borrowed stand everything except client_chat
works. The refusal names the pids holding the port rather than suggesting a
server_start that would refuse them.
Chat is not reachable from the gamepad, and confirming a menu is not
either. The game binds its chat line to Enter and nothing else, and there
is no on-screen keyboard, so text is either a bridge message (client_chat,
free) or real keystrokes (client_type, costs the foreground).
client_type("", submit=True) sends Enter alone, which is how the chat line
is opened — and, on the evidence above, the only confirm the tool set has.
Every knowledge search pays a walk of the project tree. That walk is how the project layer's staleness is measured on every answer, which is the one property the index exists for. It costs 3.0 ms on a real 41-source mod (whose tree holds about 1800 entries) and 21 ms on a tree of 2810 files. Caching it for a second or two would remove the cost and restore exactly the window of silence the design refuses; if it ever becomes too expensive, that trade has to be made deliberately, not by accident.
A build always goes through a job, and the job costs more than a small
build does. Turnaround measured at 70–95 ms against a 6 ms project rebuild:
job_wait polls at 100 ms. The single shape is deliberate — a caller must
not have to know which build blocks — and nothing forces you to wait, because
the next search measures the layer itself.
The dependency layer is measured against the profile as it is now. Add a
mod to mods.required and its archives arrive as added; remove one and its
archives read as missing. That is the requirement (the declared set is part
of what the layer is built from) but it looks like the index went stale when
what actually changed was the profile.
core always includes the game's configs, and that is most of its cost.
70 s with them against about 4 s for the scripts alone. There is no switch:
without the configs "is there an item class called X" cannot be answered, and
a second axis would make the staleness measurement ambiguous — the walk would
not know whether to expect the Addons archives.
knowledge_show answers nearest-layer-first. For a class a dependency
reopens with modded class, the mod's declaration comes before the game's.
That is the right order and a surprising one; pass layer='core' for the
game's own.
Conditional compilation is indexed, not resolved. 4.9% of the game's
script lines sit inside #ifdef, including about a hundred class
declarations. This server drives server, client and diagnostic builds, so
there is no single correct set of defines: everything is indexed and the
guard is recorded on the declaration. A name can therefore be reported that a
particular build excludes — the alternative, filtering by one guess at the
defines, would deny the existence of methods that are in the running build.
C12's fingerprint carries the file's size, and binarize's size is not
stable. Rebuilding a model that nobody edited produced an artifact one byte
larger than the shipped one, with the same kind, the same LOD count and the
same fifty strings — and a different digest, because the size is part of it.
So C12 can warn about a rebuild that changed nothing. It warns rather than
refuses for exactly this reason, and the parts it is built from are reported
beside it so the comparison can be made by hand. Splitting the digest into a
stable half and a size is the obvious refinement and is not done.
A partial export warns; it does not refuse. With the exporter's own default arguments a model came out carrying 2 of its 5 LODs and passing every other check. This server does not pass those arguments, so it should not happen — but an object marked as a LOD and not linked into the scene counts on one side of the comparison and not the other, which is a legitimate reason for the counts to differ, so a refusal would have false positives. Read E3.
The containment rule cannot see every wrong root. It refuses a root that does not hold the mod's prefix folder, which is the measured failure. A root that does hold a folder of that name — a repository whose own mod directory is spelled like the prefix, for instance — passes it, and what catches that case is C10 or C3/C4 one layer down. Measured: pointed at such a root, the build refused, deployed nothing and left the shipped artifact untouched, but the refusal came from the job rather than from the call.
asset_export needs the exporting add-on enabled in Blender, and cannot
install it. Blender is launched with the machine owner's real preferences,
because starting it with --factory-startup takes the add-on away entirely.
Their other add-ons are kept off the search path for the run (two of the ones
installed here reach the network as they start and are blamed for crashes),
which Blender reports as "Add-on not loaded" in the log — that line is this
server's own doing, not a fault.
A binarised config has no body to show. knowledge_show(body=True) reads
a declaration back out of the file or archive it was indexed from, but a
config.bin holds the binary form while the index holds what CfgConvert
made of it. The answer says so instead of returning nothing.
python -m pip install -e ".[dev]"
python -m pytestThat is the hermetic suite: everything runs against fixtures, on any machine, in about eighty seconds.
A second half of the suite runs the readers and the checks against REAL
artifacts — a binarized model that works in game, one built from the wrong
directory, a texture whose alpha survived conversion and one whose did not, an
unpacked scripts.pbo, a folder of installed mods. Those artifacts are not in
this repository and never will be: they are gigabytes, and most of them belong
to somebody's mod rather than to this server. The tests find them through
environment variables named after the PROPERTY under test, never after the mod
they came from, and skip when a variable is unset.
Set them once per machine: copy tests/samples.local.example.toml to
tests/samples.local.toml (git-ignored) and fill in your own paths. That file
is read by tests/conftest.py before any test module is imported — which is
when the skips are decided — and never overrides a variable the environment
already carries, so a one-off DAYZ_MCP_SAMPLE_ODOL=... pytest still wins.
The cheap half then runs by default. The expensive half — anything that
launches DayZ Tools or Blender, or indexes a whole corpus — carries the
corpus marker and stays out of the default run, because it takes minutes
rather than seconds:
python -m pytest -m corpusThe one sample a normal machine does not already have is the vanilla layout
corpus, because the game ships it packed. Unpack it once with this server's
own formula, then point DAYZ_GUI_LAYOUTS at the result:
python -c "import subprocess; from pathlib import Path; from dayz_mcp.packer import bankrev_cmd; from dayz_mcp.paths import BANKREV_REL, find_tools; subprocess.run(bankrev_cmd(Path(find_tools()) / BANKREV_REL, Path(r'<game>/dta/gui.pbo'), Path(r'<corpus>')))"<corpus>/gui/gui/layouts is then the directory to name. If you regenerate
data/layout-vocab.json at all, regenerate it from the same unpack, so the
vocabulary and the parse test are talking about one build of the game.
python -m pip install -e ".[dev]"Register in your MCP client:
{ "mcpServers": { "dayz": { "command": "dayz-mcp" } } }GPL-3.0-or-later. See 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
