Click on "Install 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., "@gmod-mcp debug the Lua error on server start"
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.
A local-first MCP server for AI-assisted Garry's Mod addon development. It plugs into
Claude Code the way claude-in-chrome does: agents discover the MCP tools and iterate on
their own — lint → boot → observe runtime → patch → validate. No web app, no UI.
Two halves:
gmod-mcp — the MCP server, TypeScript/Node, stdio transport.
gmod_mcp_bridge (addon/gmod_mcp_bridge) — a GLua addon exposing server state over a
file transport inside GMod's DATA sandbox. The daemon and srcds share a filesystem, so
no network is involved. This is not a stylistic choice: GMod's HTTP() was measured not to
reach a localhost daemon from a dedicated server.
You talk about the addon in plain language while the model sees the actual game state — "why does this net message never fire?", "fix this error", "show me that menu". The agent lints, boots the server, reads structured Lua errors, patches, reloads and re-validates, in a loop.
Related MCP server: niua-godot-mcp
pnpm install && pnpm build
# Register the server with Claude Code (project scope, committable):
node dist/index.js install
# -> writes <repoRoot>/.mcp.jsonCLI alternative:
claude mcp add gmod-mcp -e GMOD_MCP_REPO=<repoRoot> -- node <abs>/dist/index.js
The daemon finds the repo root by walking up from the cwd looking for tools/lint.sh and
CLAUDE.md, or via GMOD_MCP_REPO, or via .gmod-mcp/config.json.
The bridge addon must be mounted by your dedicated server. Symlink it rather than copying, so
a SteamCMD validate can never overwrite it:
ln -s /path/to/gmod-mcp/addon/gmod_mcp_bridge \
/path/to/srcds/garrysmod/addons/gmod_mcp_bridgeServer realm. The daemon writes srcds/garrysmod/data/gmod_mcp/cmd/<id>.json atomically;
the addon reads it, runs it, writes res/<id>.json and deletes the command. Events (Lua
errors, bridge_up) arrive as evt/<n>.json. The daemon polls res/ and evt/. No port, no
token, no handshake.
One daemon per transport directory, enforced by daemon.lock (PID inside, stale locks
reclaimed). The protocol consumes res/, so a second daemon reading the same directory
deletes results the first one is waiting for: the command really ran, the result really was
written, and the caller still times out. That is what happens the moment a second Claude Code
session is opened on the same repo — measured 2026-07-25, and it cost forty minutes because
the symptom accuses the game. Every bridge tool timed out while srcds was healthy and the
addon mounted; reconnecting the client and restarting the server changed nothing, since the
interfering state lived in a third process. Diagnose it with:
ps -eo pid,etime,args | grep gmod-mcp/dist/index.js # more than one line is the bugA daemon that cannot take the lock keeps its MCP tools but touches nothing: no scanner, no
commands written, and every bridge call refuses with the owner's PID. health reports the
same under bridge.transport. A res/ file matching no in-flight command is now left alone
for a grace period rather than deleted on sight — blind cleanup is what turned coexistence
into an outage — and the count of such files is reported, because on a single-daemon setup it
should be zero.
Client realm. The daemon writes a cl command down the same file channel; the server addon
routes it to the client over a net message; the client runs it and sends the result back, in
chunks reassembled server-side into res/. No HTTP, and the client can be on any machine as
long as it is connected to the server. The target is the first player, or args.player
(SteamID).
Chunks are small and paced one per frame, drained one result at a time, and capped at 48 chunks per result. All three came from the same failure, met twice.
An early version pushed 60 KB chunks in a single frame, which overflowed the client-to-server
reliable channel (send reliable stream overflow) and timed the client out. That failure is
persistent and silent — once the channel is swamped, no net message from that client gets
through, so every client tool times out and the relay looks broken when it has merely been
flooded.
A relayed command the client never answers fails server-side after 20 s, under the
daemon's 30 s round trip, and says so: which tool, how many chunks arrived before the transfer
was discarded, and that srcds itself is fine. Half-received chunks are dropped with it — a
partial reassembly is not a result. read_runtime carries the relay's state (waiting,
oldest_seconds, oldest_tool, partial_transfers), because a stuck channel and an idle one
used to read identically from the daemon.
Per-frame pacing alone was not enough. Measured on a real player: a full-screen capture at quality 80 came to 424 KB and 62 chunks and dropped them from the server, while a full-screen q70 capture (100 KB, 15 chunks) had gone through fine minutes earlier. Two things were wrong. Each result had its own timer, so several in flight summed on the same channel and the pacing stopped meaning anything — a caller retrying a command it believes was lost has two captures in flight, and the second is what tips it over. And nothing bounded a single result. Now one drain serialises every result, and anything over 48 chunks is refused with its size and a suggestion instead of sent. The default half-scale capture is about six chunks.
edit → lint → (boot) → observe → patch → reload → validate → repeat
The daemon shells out to the host project's tools/lint.sh, start-server.sh and
server-log.sh, parsing file:line: and exit codes. It also encodes the traps that cost real
debugging time: the boot boundary inside an accumulating console.log, waiting for
InitPostEntity before reading cvars, the queueing latency of game.ConsoleCommand, and
NUL-safe log reads.
Local (daemon) — health, lint, start_server, stop_server, sync_config,
read_logs, package, patch_file, restore_patch, reload_file, reload_addon,
validate, run_iteration.
Server, reading — batch, read_runtime, read_players, read_entities,
inspect_entity, read_hooks, read_convars, read_net_messages, read_timers,
run_console_command, send_debug, run_test, run_lua (guarded, optional extension).
Server, acting (all guarded) — spawn_entity, world_edit, set_player_state,
force_hook.
Client (via bridge) — read_view, client_input, read_panels, inspect_panel,
capture_screen, read_console, read_client_convars.
health also asks the addon which handlers it registered and reports any the daemon
declares but the game does not have. That gap used to surface only as an "unknown handler"
after a full round trip, or — when a whole include was missing — not at all. It reports the
transport state alongside: whether this daemon owns the directory and who holds it otherwise,
what is in flight, how long since the addon last answered, and how many res/ files matched
nothing of ours. Start every "nothing responds" investigation there.
capture_screen returns a real image content block. Returned as text, a base64 JPEG is
billed to the model token by token and still cannot be looked at, so the "see" half of an
act/see loop silently does nothing while every test passes.
The reading tools diagnose; the acting ones set up what is worth diagnosing. Server-side,
spawn_entity places something, world_edit moves, freezes, heals, arms or removes it,
set_player_state sets money, job, salary or RP name, and force_hook runs a gamemode
hook directly.
Money goes through the r-capitalism ledger when it is loaded. That ledger holds an audited
invariant — sum(balances) == issued - burned — and a raw addMoney would move a balance
without an entry, leaving the drift permanently off zero. A debugging tool must not corrupt
what is being debugged. Amounts are integer cents, as the rest of that server economy is.
force_hook coerces tagged arguments, because JSON cannot carry a game object:
{"__ent": 3}, {"__ply": "STEAM_0:1:2"}, {"__vec": [x,y,z]}, {"__ang": [p,y,r]}.
Client-side, client_input drives the connected GMod client — movement, aim, key holds,
Derma clicks, typing, chat — and read_view reports eye position, aim trace, cursor,
hovered panel and keyboard focus. read_view is the cheap half of an act-then-look loop:
one chunk, no image, and it answers "am I aimed at the door" without a screenshot.
client_input is bounded in Lua rather than guarded behind a confirmation. It drives a
real person's machine, and a prompt clicked two hundred times is not a safety property:
holds expire, durations are seconds and clamped to five, a 30s deadline resets everything,
and gmod_mcp_release in the client console returns control without involving the daemon.
A bridge round trip costs about 0.4s: the addon polls at 0.25s and the daemon scans at
0.15s. Any sequence that acts and then looks pays that per gesture. batch carries up to
32 server steps in one command instead:
{ "steps": [{"tool": "read_runtime"},
{"tool": "read_timers", "args": {"names": ["gmod_mcp_bridge_poll"]}}],
"settleMs": 100 }Measured against a live DarkRP server: three steps in 0.19s, versus roughly 0.75s as three separate calls.
A failing step is data, not a transport error — each step reports its own ok/data/
error, stopOnError marks the rest skipped and records abortedAt, so the caller sees
the whole shape of the batch. settleMs pauses between steps, which is what makes
act-then-look honest: without it a step observes the frame before the previous one landed.
Guarded tools are checked on both sides. batch is a single unguarded definition, so
without the check a run_lua step would bypass the confirmation its own gate demands; the
daemon resolves each step against the registry and the Lua runner repeats the check.
Any argument may instead be {"__step": 1, "get": "index"}, read from an earlier step's
result. Without it, spawning something and then acting on it costs two round trips — the
caller cannot know the EntIndex until the spawn has answered, which is the round trip
batching exists to remove.
Steps share a server tick unless settleMs is set, and some engine effects only land at
end of frame: Entity:Remove() is deferred, so a step reading the entity back still finds
it valid and the agent concludes the removal failed. Set settleMs (100 is usually enough)
whenever a step must observe an earlier one.
Client-realm steps are refused explicitly rather than silently dropped — a batch runs
inside the server addon, and cl tools are relayed over net. So an act-then-look loop on
the client is currently two round trips, not one.
All three realms have been exercised against a live DarkRP server: the server tools on
rp_nycity_day at tick 33, and the client tools against a connected GMod client —
read_panels returning a live VGUI tree and capture_screen returning a complete 1920x1080
JPEG. batch was proven the same way, including its failure paths: a step raising returns
the real Lua error with file:line, the rest come back skipped, and a run_lua step is
refused unconfirmed and executes confirmed.
Guarded tools (run_lua) require confirm: true or membership in toolAllowlist; otherwise
they are refused without executing. A guarded tool used as a batch step needs the batch
itself confirmed, and both the daemon and the Lua runner enforce that independently. Every call, result, patch and executed Lua line is
appended to <repoRoot>/.gmod-mcp/logs/audit.jsonl.
patch_file is locked to the repo root and refuses paths outside it.
No network listener. The server transport is files inside DATA; the MCP layer is stdio. The trust boundary is the local filesystem.
run_lua — arbitrary Lua execution — lives in the optional optional/gmod_mcp_runlua
extension, isolated because glua-audit forbids dynamic execution and the main bridge stays
lint-clean. Development only, never on a production server.
<repoRoot>/.gmod-mcp/config.jsonEvery key is optional (see config.example.json):
{
"repoRoot": ".",
"addons": ["gmod_mcp_bridge"],
"clientWaitMs": 30000,
"toolAllowlist": [],
"plugins": []
}clientWaitMs is how long a client-realm call keeps retrying while the client is absent.
That realm needs a human connected, and humans crash, alt-tab and reconnect; retrying lets an
agent resume when they come back instead of failing the moment they drop. Set it to 0 to fail
fast. Server-realm calls ignore it — srcds does not come and go mid-session, so a failure there
is a real one.
Extend the tool set with ESM modules listed in plugins. Each module exports tools:
// my_plugin.mjs
export const tools = [
{ name: "my_tool", description: "…", realm: "local", inputSchema: {}, handler: () => ({ ok: true }) },
];A failing plugin is reported on stderr without blocking startup.
docs/2026-07-25-autonomie-client-design.md — what
the client side needs before an agent can drive it without a human: name a panel instead of
guessing a pixel, assert text instead of reading a JPEG, and type into a field at all. Each gap
listed there blocked a real session.
pnpm test # vitest
pnpm typecheck
pnpm buildLinting the GLua addon needs the host project's tools/lint.sh (four passes) plus a local
copy of GLua API definitions — see addon/gmod_mcp_bridge/.luarc.example.json.
MIT. See LICENSE.
Runs up to 32 server tools in ONE bridge round trip instead of one per call. A round trip costs about 0.4s, so any act-then-look sequence is dominated by transport unless it is batched. Each step reports its own ok/data/error; a step failing is data, not a transport error. IMPORTANT: with settleMs 0 every step runs in the SAME server tick, and some engine effects only land at the end of a frame -- a removed entity still reads as valid. Set settleMs (100 is usually enough) whenever a step must observe what an earlier one did. Any arg value may be {"__step": 1, "get": "index"} to read a field from an earlier step's result, so spawn-then-act still costs one round trip.
| Name | Required | Description | Default |
|---|---|---|---|
| steps | Yes | ||
| confirm | No | Required if any step is a guarded tool. Applies to every step. | |
| settleMs | No | Pause between steps, in ms. Needed when a step must observe the previous one. | |
| stopOnError | No | Stop at the first failing step and mark the rest skipped. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations have no behavioral hints; description provides rich detail: step independence, error handling, same-tick execution, __step references. No contradictions.
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 sentences, front-loaded purpose, information-dense without fluff. Every sentence adds 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?
Given complexity (batching, chaining, timing) and no output schema, description covers purpose, behavior, parameters, and advanced usage adequately.
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 75%; description adds significant context for settleMs (why needed, typical value) and __step mechanism, and clarifies confirm applies to all steps.
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?
Clearly states the tool runs up to 32 server tools in one round trip, specifying verb and resource. Distinct from siblings by focusing on batching.
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?
Explains when to use to avoid round trip overhead (0.4s) and provides contextual warnings about settleMs and __step chaining. Does not explicitly state when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Captures the client's screen on the next frame and returns it as a viewable image. Every byte travels in 7KB chunks paced by frame, so a full-resolution capture takes seconds and dominates any act-then-look loop: the default half scale at quality 60 is 4-6x cheaper and still legible for a Derma layout. Pass region (from read_panels' screen_x/screen_y) to capture just one panel. A capture that would exceed the client's channel budget is refused with its size rather than sent: a full-screen quality-80 capture measured 424KB and timed the client out of the server. Requires an active GMod client.
| Name | Required | Description | Default |
|---|---|---|---|
| scale | No | Downscale factor applied on the client before encoding. Use 1 to read small text. | |
| region | No | Screen region to capture. Free: render.Capture takes it natively. | |
| quality | No | JPEG quality. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations beyond title, the description fully discloses the tool's behavior: data chunking, time cost, budget limits, failure mode (refusal with size), and requirement for an active GMod client. It is highly 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 concise for the complexity, with information front-loaded and every sentence contributing essential details: purpose, performance, usage tips, requirements. No wasted words.
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 purpose, performance, usage, and failure modes. It does not detail the output format beyond 'viewable image', but that is sufficient given the lack of output schema. Overall it provides complete context for an AI 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?
Schema coverage is 100%, so baseline is 3. The description adds value by recommending parameter values (default scale and quality) and explaining performance implications, and by providing guidance on deriving region from read_panels, enhancing schema documentation.
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 captures the client's screen as an image. It mentions a specific use case (capturing a panel via region from read_panels) but does not explicitly distinguish from sibling tools like read_panels or inspect_entity, which serve different purposes.
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 actionable usage guidance: recommends default half scale and quality 60 for efficiency, suggests using region to capture a single panel, and warns about the channel budget and timeout. However, it does not explicitly state when to use this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Drives the connected GMod client: movement, aim, keys, Derma clicks, typing, chat. Modal -- 'world' drives movement through CreateMove, 'ui' hands input to the panel system, and the two are mutually exclusive; the action switches mode for you. Durations are SECONDS (CreateMove runs at the client's cmdrate, so tick counts are not a duration), clamped to 5s, and everything resets after 30s or on gmod_mcp_release in the client console. To fill a form use set_text (targets a field by name and fires its change notification); type sends real keystrokes and needs a target or an already-focused field. click takes a NAMED target as well as x/y and is self-sufficient -- it moves the cursor, waits for hover to settle, presses and releases, so no move_cursor is needed first. Follow with read_view or read_panel_text to see the effect.
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | click/move_cursor: screen X. Ignored when a named target is given. | |
| y | No | click/move_cursor: screen Y. Ignored when a named target is given. | |
| up | No | move: vertical speed (swimming, ladders). | |
| key | No | press/release: IN_ bit (IN_ATTACK 1, IN_JUMP 2, IN_DUCK 4, IN_FORWARD 8, IN_BACK 16, IN_USE 32, IN_MOVELEFT 512, IN_MOVERIGHT 1024, IN_ATTACK2 2048, IN_RELOAD 8192, IN_SPEED 131072). key_ui: a KEY_ enum instead. | |
| pos | No | look_at: world position to aim at. | |
| yaw | No | look: yaw. | |
| mode | No | mode: which input mode to switch to. | |
| name | No | click/type/set_text: target the panel with this registered vgui name (R_UI_Button, DTextEntry). Not the class -- a kit panel's class is its VGUI base. | |
| side | No | move: strafe speed. | |
| text | No | set_text: the value to put in the field. type: characters to send. say: chat message. | |
| class | No | click/type/set_text: target by VGUI base class (Label, TextEntry, Panel). | |
| delta | No | scroll: wheel delta. | |
| enter | No | set_text: also fire the field's OnEnter, for forms that only validate or submit on Enter. Off by default -- on a chat entry it sends the line. | |
| focus | No | set_text: default true, calls RequestFocus first so the field's own focus logic runs. | |
| index | No | click/type/set_text: which match to act on when several qualify. | |
| pitch | No | look: pitch, clamped to +-89. | |
| action | Yes | ||
| button | No | click: which mouse button. | |
| weapon | No | select_weapon: weapon class the player is carrying. | |
| forward | No | move: forward speed, negative for backward. | |
| contains | No | click/type/set_text: narrow the target to panels whose displayed text contains this (case-insensitive). | |
| duration | No | Seconds to hold a key, a movement or a scripted aim. Clamped to 5. | |
| onScreen | No | click/type/set_text: default true, only panels whose whole ancestry is visible. false reaches hidden ones. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses all relevant behaviors: modal exclusivity, duration in seconds (not ticks), clamping to 5s, reset after 30s or gmod_mcp_release, and detailed click mechanics (cursor movement, hover wait, press/release). No annotations present, so description carries full burden and meets it.
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 structured: general purpose, then modal, then duration/reset, then action-specific details. Every sentence adds value, but it could be slightly more front-loaded or broken into bullet points for quicker scanning. Still, it's efficient 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?
Given 23 parameters, high schema coverage, no output schema, and complex interactions, the description covers all necessary aspects: action modes, parameter dependencies, safety limits, and usage patterns. It leaves no significant gap for an agent to infer.
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 96% with descriptions on almost all parameters. The description adds value beyond schema by explaining duration units, that tick counts are not duration, and relationships between actions (e.g., click does not need move_cursor). However, much of the parameter meaning is already in the schema, so a 3 would be baseline; the extra context justifies a 4.
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 starts with a clear verb+resource statement ('Drives the connected GMod client') and lists all sub-actions (movement, aim, keys, etc.). It distinguishes itself from sibling tools by being the only input tool among read/command/entity tools, so no confusion.
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: modal modes ('world' vs 'ui'), when to use set_text vs type, that click is self-sufficient (no move_cursor needed), and suggests follow-up tools like read_view. Also warns about duration units and resets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GUARDED. Runs hook.Run(name, ...) to exercise a gamemode path without reproducing the situation. JSON cannot carry an Entity, so arguments may be tagged: {"__ent": 3}, {"__ply": "STEAM_0:1:2"}, {"__vec": [x,y,z]}, {"__ang": [p,y,r]}. Requires confirm:true.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Positional arguments, tagged where they are game objects. | |
| name | Yes | Hook name, e.g. PlayerSpawn. | |
| confirm | No | Must be true: this changes the running game and is audited. Otherwise the call is refused. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations lack destructiveHint, but the description explicitly calls it 'GUARDED', requires confirm:true, and states it changes the running game and is audited. It also explains the tagging mechanism for game objects.
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 sentences efficiently cover purpose, JSON limitations, tagging, and requirement. No fluff, front-loaded with key action and guarded status.
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 3 params and no output schema, the description covers purpose, parameter format, confirm requirement, and side effects. Missing potential error behavior, but sufficient for intended 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?
With 100% schema coverage, baseline is 3. The description adds value by explaining that args can be tagged with __ent, __ply, __vec, __ang formats, providing concrete examples beyond the 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 clearly states it runs hook.Run(name, ...) to exercise a gamemode path, which is specific. It distinguishes from siblings like read_hooks (read-only) and run_lua (generic code execution), though not 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 testing without reproducing the situation, and requires confirm:true. However, it does not provide explicit when-to-use or when-not-to-use compared to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gmod-mcp daemon status: version, detected repo root, presence of the tools/ scripts, state directory. Also probes the addon (3s) and reports the transport state -- whether this daemon owns the shared directory (a second Claude Code session starts a second daemon, which breaks every bridge tool), what is in flight, and any server handler the daemon declares but the game has not registered.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no behavioral hints, so the description carries the full burden. It discloses a 3-second probe, the second daemon issue that breaks bridge tools, and details about inflight and unregistered handlers, offering good transparency. However, it does not explicitly state whether it is read-only.
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 sentences front-load the core purpose ('gmod-mcp daemon status') and then provide necessary detail. Could be slightly more concise, but every sentence adds 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?
Given no output schema and a complex sibling set, the description covers the tool's output thoroughly (version, repo, scripts, state, addon probe, transport state, daemon ownership, inflight, handler gaps). Missing error conditions, but overall complete.
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?
No parameters exist, so baseline is 4. The description compensates by describing the output content comprehensively.
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 reports 'gmod-mcp daemon status' and lists specific items (version, detected repo root, presence of tools/scripts, state directory, addon probe, transport state). It distinguishes itself from siblings by focusing on daemon health rather than entity or data queries.
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 checking daemon health but does not explicitly state when to use it versus alternatives like read_runtime, nor does it provide when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Details of one entity by index: class, model, health, owner, key-values.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations lack readOnlyHint or destructiveHint. Description does not disclose what happens if index is out of bounds, whether it's a read-only operation, or any side effects. For a tool with minimal annotation coverage, more behavioral context is needed.
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?
Single sentence, front-loaded with the key action and resource. No redundancy, but could be slightly more structured with bullet points for listed 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?
No output schema, so description should explain return format. It lists fields but doesn't specify structure or types. Missing details on how key-values are represented, or whether all fields are always 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?
Description only mentions 'by index' for the single parameter 'index'. Schema has 0% description coverage, so description should add meaning, but it merely restates the parameter's purpose without additional semantics like range or 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?
Description clearly states it provides details of one entity by index, listing specific fields (class, model, health, owner, key-values). Distinguished from siblings like read_entities which likely list all entities.
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 on when to use this tool versus alternatives such as read_entities. No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds a panel by NAME, class and/or displayed text, and returns its screen rectangle, its text, whether it holds keyboard focus, and the other matches. NAME is the registered vgui name (R_CharCreate, R_UI_Button, echat.textentry) and is what you want: class is the VGUI base the panel derives from, so a kit panel's class reads Label or Panel and searching by class can never find it. Off-screen panels are excluded unless onScreen:false -- a live tree measured 1408 panels of which 5 were on screen.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Registered vgui name, e.g. R_UI_Button. Exact match. | |
| class | No | VGUI base class, e.g. Label, Panel, TextEntry. Exact match. | |
| index | No | Which match to return when several qualify. | |
| contains | No | Substring of the panel's displayed text, case-insensitive -- 'the button that says ÉCROUER'. | |
| onScreen | No | Keep only panels whose whole ancestry is visible. false includes closed menus. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations beyond title, the description carries the full burden. It discloses return values (rectangle, text, focus, other matches) and behavior (excludes off-screen panels unless onScreen:false). It does not explicitly state it is read-only, but the find-and-return nature strongly implies no side effects. The practical statistic adds 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 single dense paragraph that packs all necessary information without redundancy. It is front-loaded with the core action and progressively adds detail. No wasted sentences; every clause 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?
The description covers all parameters and return fields explicitly (rectangle, text, focus, other matches). It lacks an output schema but compensates by naming the return fields. It could mention error behavior when no panel is found, but this is minor. For a simple inspection tool, it is sufficiently complete.
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 100% with good descriptions, but the tool description adds significant value: it explains the vgui name concept with examples, clarifies that class is the base type and often generic (e.g., Label, Panel), and interprets the index and contains parameters. This enriches understanding beyond schema alone.
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 explicitly states it finds a panel by name, class, or displayed text and returns detailed info (rectangle, text, focus, other matches). It clearly distinguishes NAME (registered vgui name) from class (base class), making the purpose unmistakable and differentiating it from sibling tools like read_panels.
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 guidance: 'NAME is what you want' and warns that searching by class is unhelpful. It also explains the onScreen parameter behavior. However, it does not explicitly mention when to use this tool over siblings (e.g., read_panels for listing), though the context is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runs tools/lint.sh on an addon (name or path). Returns structured findings (file, line, rule) and the exit code. Exit 0 means clean.
| Name | Required | Description | Default |
|---|---|---|---|
| addon | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes output but does not state whether the tool is read-only or has side effects, leaving safety profile unclear.
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 sentences packed with necessary information, no fluff. Purpose and output 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?
Despite no output schema, the description sufficiently explains return structure (findings and exit code) and interpretation (exit 0 clean), making the tool complete for a simple linter.
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 'addon' is described as 'name or path', which adds useful context beyond the schema's type constraint, helping the agent understand valid inputs.
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 runs tools/lint.sh on an addon and returns structured findings with exit code. It is specific and distinct from siblings like validate or run_test.
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?
Implied usage for linting addons, but no explicit guidance on when to use this tool over alternatives 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.
Builds an addon's .gma through tools/package-gma.sh, linting first and refusing on failure. Output lands in dist/.
| Name | Required | Description | Default |
|---|---|---|---|
| addon | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal, so description carries full burden. It discloses the build process, lint check, failure behavior, and output destination. Lacks mention of side effects or permissions, but sufficient 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?
Two sentences, concise and front-loaded with the main action followed by key details. No unnecessary words.
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 single-parameter tool with no output schema, the description covers the main action, process, and output location. Could be improved by specifying prerequisites or addon format, but generally complete.
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%, but description adds meaning by linking 'addon' to the entity being built. However, it does not clarify whether 'addon' is a name, path, or ID, leaving some ambiguity.
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?
Description clearly states the verb (builds), resource (addon's .gma), and process (lint first, refuse on failure). It distinguishes from sibling tools like 'lint' and 'validate' by focusing on packaging.
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?
Description implies when to use (to produce a .gma) and that linting is a prerequisite, but does not explicitly state when not to use or provide direct alternatives. The context from siblings aids understanding.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replaces a file's contents (inside the repo) after backing it up. Returns a patch id for restore_patch, plus the unified diff. rationale explains the change.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Path relative to the GMod repo. | |
| content | Yes | The file's complete new contents. | |
| rationale | Yes | Why this change is being made. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (only title), so the description carries the burden. It clearly states behavioral traits: it backs up the file, returns a patch id and diff, and requires a rationale. This adds useful context beyond the structured fields.
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 sentences with no fluff. Every sentence adds essential information: function, side effect (backup), return values, and rationale role. Highly efficient.
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 3 parameters, no output schema, and no nested objects, the description covers purpose, behavioral details, and return format. It lacks explicit error cases or prerequisite info, but is largely complete.
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 100%, baseline 3. The description adds value by noting that 'rationale explains the change' and explaining return values (patch id and diff), which indirectly clarifies parameter purpose.
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 uses the verb 'replaces' and specifies the resource 'file's contents (inside the repo)'. It distinguishes from siblings by mentioning backup and returning a patch id for restore_patch, making the tool's role clear.
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 context by stating the tool backs up the file and returns a patch id for restore_patch, hinting at when to use vs. its sibling. However, it lacks explicit when-to-use or when-not-to-use guidance compared to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Client-side convar values. Without names, returns a common subset.
| Name | Required | Description | Default |
|---|---|---|---|
| names | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description partially discloses behavior by noting that omitting names yields a 'common subset.' However, without readOnlyHint or destructiveHint annotations, it does not confirm safety or side effects, nor cover invalid inputs or error handling.
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 concise sentence. While efficient, it lacks structural elements (e.g., bullet points) that could improve readability. It earns points for brevity but not for organization.
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 output schema and minimal annotations, the description should offer more context. It does not explain return format, error conditions, or behavior for invalid names. The tool is a data-reading operation, so completeness is lacking.
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 0% schema description coverage, the description bears more responsibility. It mentions 'names' only implicitly ('Without names') but fails to explain acceptable values, the effect of different names, or the nature of the 'common subset.' This is insufficient for parameter understanding.
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 it reads 'Client-side convar values' and specifies behavior when names are omitted ('returns a common subset'). This provides a specific verb+resource scope, but it does not explicitly differentiate from the sibling tool read_convars.
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 on when to use this tool versus alternatives like read_convars. The description implies client-side use but lacks explicit context, exclusions, or references to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
CLIENT Lua errors captured since load. GMod does not expose the console buffer itself.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations lack readOnlyHint and destructiveHint, so the description carries the full burden. It states the tool reads captured errors but does not disclose whether reading is destructive (e.g., clears the buffer) or if there are side effects. The mention that 'GMod does not expose the console buffer' adds context but does not clarify behavioral traits like idempotency or performance impact.
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 consists of two concise sentences. The first sentence states the purpose directly ('CLIENT Lua errors captured since load'). The second adds valuable context about a GMod limitation. No extraneous words; every sentence 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?
Given the tool has no parameters and no output schema, the description is minimally adequate. It specifies the input (none needed) and high-level output (captured errors). However, it does not describe the format of the errors, whether the data is truncated, or if reading clears the buffer. For a simple read tool, this is acceptable but leaves some ambiguity.
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 no parameters, so schema coverage is 100%. The description does not need to add parameter semantics. It provides context about what the tool reads (client Lua errors) beyond the empty schema, which is sufficient for a parameterless tool.
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 'CLIENT Lua errors captured since load' and notes a limitation about the console buffer. It specifies the resource (client Lua errors) and the action (read), though it could be more precise about what 'captured since load' entails. It distinguishes from siblings like read_logs by focusing on client-side Lua errors.
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 no guidance on when to use this tool versus alternatives. It does not mention when not to use it or contrast with siblings like read_logs or read_entities. The agent is left without context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Server convar values. Without names, returns a common subset.
| Name | Required | Description | Default |
|---|---|---|---|
| names | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no readOnlyHint or destructiveHint, so the description bears full responsibility. It mentions that without names a 'common subset' is returned, but does not disclose whether this is a read-only operation, potential side effects, or any restrictions. This is minimal 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?
Two sentences, each serving a clear purpose: stating the tool's function and describing parameter behavior. 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?
The tool is simple (one optional param, no output schema), and the description covers basic behavior. However, it lacks information on return format, usage examples, or when to prefer this over the similar 'read_client_convars', leaving some gaps for an AI agent.
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, leaving the parameter 'names' undocumented in schema. The description compensates by explaining its effect: without it, a common subset is returned. This adds meaning beyond the raw schema, though more detail could be given.
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 it reads server convar values and specifies that without the 'names' parameter it returns a common subset. This provides a specific verb and resource, though it does not explicitly differentiate from the sibling tool 'read_client_convars'.
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 reading server convars and suggests that providing names yields specific values, but does not offer explicit guidance on when to use this tool versus alternatives like 'read_client_convars' or other read tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists entities, filterable by class. Returns index, class, model and position.
| Name | Required | Description | Default |
|---|---|---|---|
| class | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read operation by listing return fields, but lacks explicit mention of safety or side effects. Annotations have no readOnlyHint, so the description should state it is read-only; it does not.
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 sentences, front-loaded with purpose. No unnecessary words. Efficiently conveys core functionality.
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?
Returns fields are described, compensating for missing output schema. However, the 'limit' parameter is not explained, and there is no mention of ordering or pagination behavior. Slightly incomplete given the parameter count.
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 the 'class' parameter for filtering, adding value beyond the schema. However, the 'limit' parameter is not described; its constraints are only in the schema (0% schema description coverage).
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 lists entities with optional filtering by class and specifies the return fields (index, class, model, position). This distinguishes it from sibling tools like inspect_entity, which targets a single entity.
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 on when to use this tool versus alternatives like inspect_entity or read_hooks. The verb 'Lists' implies bulk retrieval, but no explicit context or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Registered hooks (hook.GetTable), filterable by event. Returns event -> identifiers.
| Name | Required | Description | Default |
|---|---|---|---|
| event | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions the internal function 'hook.GetTable' and that it returns a mapping, but does not disclose behavioral traits such as read-only nature, required permissions, or side effects. With no annotations beyond title, the description fails to fully inform the agent about safe and expected usage.
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 with two short sentences. It is front-loaded with the main purpose and contains no unnecessary words. Every part contributes 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?
For a simple tool with one optional parameter and no output schema, the description adequately covers the core functionality and return format. However, it could be more robust by mentioning error conditions or data format details to fully complete the 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?
The description indicates the 'event' parameter can be used for filtering, adding meaning beyond the schema (which has no description). However, it does not specify valid values, format, or optionality, leaving gaps. Given 0% schema coverage, this is moderate 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 reads registered hooks and returns a mapping from event to identifiers, indicating a specific verb and resource. However, it does not differentiate from sibling tools like 'read_entities' or 'read_convars', leaving some ambiguity about when to use this specific tool.
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 versus alternatives, when not to use it, or any prerequisites. The description lacks explicit context for selecting this tool among many read-type siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads the server logs. source=game (Lua errors, -condebug) or stdout (the wrapper). sinceBoot:true bounds output to the current boot. errorsOnly:true returns structured runtime findings.
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | game | |
| sinceBoot | No | ||
| errorsOnly | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explains parameter effects (sinceBoot bounds output, errorsOnly returns structured findings) but lacks overall behavior details like output format or pagination. No readOnlyHint annotation, but description implies read 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?
Efficient: one sentence plus three sparse parameter explanations. No filler, all sentences earn their 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?
Covers main purpose and all parameters, but lacks usage context against siblings and prerequisites. Adequate for a simple tool but not fully 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?
Adds full meaning to all 3 parameters: clarifies source enum values, explains boolean flags' effects. Schema documentation coverage was 0%, so description compensates completely.
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?
Clear verb+resource: 'Reads the server logs.' Differentiates from siblings like read_entities, read_hooks, etc., which handle different resources.
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 explicit when-to-use or alternatives mentioned. Does not guide selection between this and similar tools like read_console.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Registered net messages (util.AddNetworkString) and whether a net.Receive exists.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations (no readOnlyHint or destructiveHint), the description carries the full burden. It only states what is returned, lacking details about side effects, performance, or read-only nature. The name suggests safety, but the description does not confirm.
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 sentence without waste. It is concise, though extremely brief, which is acceptable for a simple tool.
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 parameters and no output schema, the description is somewhat complete but lacks details about the output format (e.g., list, dictionary). For a straightforward tool, it is adequate but could be improved.
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 no parameters, and schema coverage is 100%, so the description does not need to add param info. The baseline of 4 is appropriate.
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 returns registered net messages and whether a net.Receive handler exists. It implies a read operation and distinguishes from siblings like read_entities or read_hooks by focusing on net messages.
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 versus alternatives such as read_hooks or read_entities. The agent must infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Derma/VGUI panel tree: class, name, visibility, size, position both parent-relative (x/y) and absolute (screen_x/screen_y), whether mouse input is enabled, and on_screen. Filter on on_screen: visible is the panel's own flag only, so a flat tree is mostly panels belonging to closed menus. Use screen_x/screen_y to aim a click or a capture region -- x/y are relative to the parent and are (0,0) for most nested panels.
| Name | Required | Description | Default |
|---|---|---|---|
| maxDepth | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies this is a read-only operation by describing the returned data, but it does not explicitly state the behavior (e.g., no side effects). Annotations only include title, so the description carries the full burden but omits explicit read-only/destructive hints.
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 long sentence packed with information but could be restructured for better readability. It front-loads the main purpose but then adds details in a somewhat rambling manner.
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 details the returned fields, it ignores the maxDepth parameter, leading to incomplete understanding. No output schema exists, and the description does not clarify the tree structure format (flat vs nested), causing potential confusion.
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, maxDepth, is not mentioned in the description. Schema coverage is 0%, so the description fails to explain its meaning or default behavior, leaving the agent uninformed.
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 returns a Derma/VGUI panel tree with specific fields (class, name, visibility, size, position). It distinguishes itself from sibling tools by detailing the exact attributes and coordinates, making its purpose 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?
Provides guidance on filtering by on_screen and interpreting screen_x/screen_y for clicking or capture regions. It does not explicitly state when not to use this tool, but the context it provides helps the agent decide, e.g., using inspect_panel for a single panel.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dumps what the interface DISPLAYS, as text: name, class, screen rectangle and text content of each panel under a named root. Use this instead of capture_screen to assert a value -- a capture travels in 7KB chunks paced one per frame, and a number read off a compressed JPEG is not an assertion. Text comes from GetText, GetValue, or a .label/.text/.title field (kit buttons paint their label and answer '' to GetText). The list is depth-first with depth relative to the root, so the parent chain is recoverable from the ordering: the DTextEntry that follows the DLabel 'Prénom' is that field. capture_screen remains the tool for anything visual -- z-order, overlap, a missing glyph.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | Panel to dump from, matched as a NAME first then as a class. Omitted, dumps the whole screen. | |
| index | No | Which root when several match. | |
| limit | No | Maximum entries; the rest are counted in `truncated`. | |
| maxDepth | No | Depth below the root. | |
| onScreen | No | Skip panels whose ancestry is hidden. | |
| onlyText | No | Skip panels carrying no text. false dumps the structure too. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses multiple behavioral traits beyond the minimal annotations: explains text sources (GetText, GetValue, .label/.text/.title fields), caveat about kit buttons painting their label and returning empty to GetText, and the depth-first ordering with parent-chain recoverability. Annotations only provide a title, so the description carries full burden and excels.
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 each sentence adds distinct value: purpose, usage guidance, behavioral nuances, ordering explanation. It is well-structured and front-loaded with the main purpose. A slight trim could be possible (e.g., combining the kit button note), but overall it earns its length.
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 6 parameters and no output schema, the description adequately covers the tool's purpose, usage, text sources, and ordering. It lacks an explicit description of the output format (e.g., JSON structure) but compensates by explaining the ordering and what information is dumped. It is sufficient for an agent to use 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 100%, so the baseline is 3. The description does not add extra information about individual parameters beyond what the schema already provides. It provides context about the tool's behavior (e.g., text sources) but no parameter-specific clarifications.
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 uses the verb 'Dumps' with a clear resource: 'what the interface DISPLAYS, as text: name, class, screen rectangle and text content of each panel under a named root.' It clearly distinguishes itself from the sibling tool 'capture_screen' by specifying that this tool is for text assertions while capture_screen is for visual aspects.
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 states when to use this tool: 'Use this instead of capture_screen to assert a value' and explains why capture_screen is not suitable for assertions (7KB chunks, JPEG compression). It also specifies when capture_screen remains appropriate: 'capture_screen remains the tool for anything visual -- z-order, overlap, a missing glyph.' This provides clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists players: name, SteamID, team/job, ping, position, health.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation via the verb 'Lists' and the tool name 'read_', but annotations are minimal (only title). It does not explicitly state that no side effects occur, nor does it specify authentication or rate limits. The behavioral disclosure is adequate but could be more explicit.
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?
A single sentence of ten words, front-loading the action and listing fields efficiently. No superfluous content.
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 parameterless list tool, the description fully specifies what information is returned. With no output schema, the field list compensates completely. The tool's behavior is fully captured given its simplicity.
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 no parameters (schema coverage 100% vacuously). Per the rubric, zero parameters yields a baseline of 4. The description adds no extra param info, which is acceptable as there are none to describe.
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 uses the specific verb 'Lists' and identifies the exact resource 'players', naming the fields included. This clearly distinguishes it from siblings like 'read_entities' (all entities) and 'inspect_entity' (single entity).
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 clearly states the tool retrieves a player list with specified data, but it does not explicitly exclude use cases or mention alternatives. However, the sibling names and purpose clarity provide enough context for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Snapshot of server state: map, gamemode, CurTime, player and entity counts, uptime.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a non-destructive read operation ('snapshot'), but does not explicitly confirm read-only behavior, lack of side effects, or any constraints like rate limits. With no annotations provided, the description carries the full burden and falls short of full 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?
Single sentence that front-loads the purpose ('Snapshot of server state:') and lists key contents. Every word is informative with no 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 zero-parameter tool with no output schema, the description adequately lists the return fields. It is missing specifics on data types or formatting, but is sufficient for an agent to understand what will be retrieved.
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 schema coverage is 100%. The description adds value by clarifying what the output contains (map, gamemode, etc.), which goes 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 clearly states it returns a 'snapshot of server state' and lists specific fields (map, gamemode, CurTime, etc.). It distinguishes from sibling tools like read_entities or read_players by being a general overview rather than a focused query.
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 on when to use this tool versus alternatives. Among many sibling read tools, there is no indication of which one is appropriate for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
State of named timers: exists, time left, repetitions left. GMod cannot enumerate timers, so names is required to get anything back.
| Name | Required | Description | Default |
|---|---|---|---|
| names | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations beyond a title, the description carries full weight. It discloses that the tool is read-only and that it requires named timers. It does not detail error handling or output format, but for a simple read tool this is sufficient.
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 consists of two concise sentences without wasted words. The first states the purpose, the second provides essential usage context.
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 one simple parameter and no output schema, the description covers the key points: what it does, what the parameter does, and a constraint. It could mention the return format, but it is still fairly complete.
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% coverage for parameter descriptions, but the tool description compensates by explaining that the 'names' array is functionally required and why (GMod cannot enumerate timers). This adds critical meaning beyond the 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 clearly states that the tool reads the state of named timers (exists, time left, repetitions left), and it distinguishes itself from sibling tools like read_entities by noting that GMod cannot enumerate timers, so names must be provided.
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 says that the 'names' parameter is required to get any data, implying that without it the tool returns nothing. It provides clear context for when to use the tool, though it does not explicitly mention alternatives 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.
What the client sees and is pointed at: eye position and angles, aim trace (class, index, distance, hit position), health, weapon, cursor position and visibility, the hovered panel, the panel holding keyboard focus, and the current scripted-input mode. This is the cheap half of an act-then-look loop -- one chunk, no image -- and answers 'am I aimed at the door' without a screenshot.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the operation is cheap, returns no image, and lists the data returned. It implies read-only behavior but does not explicitly state lack of side effects. Since annotations are minimal (only title), the description carries the burden and does so well.
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 two sentences, front-loaded with the key outputs, and wastes no words. Every sentence adds value: the first lists returned data, the second provides context and usage guidance.
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 input schema and no output schema, the description provides a reasonably complete picture of what the tool returns. It could be more explicit about the exact return structure, but it sufficiently covers the tool's purpose and behavioral characteristics.
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 parameters, so the description does not need to explain parameters. Baseline for 0 params is 4, and the description adequately sets expectations about what the tool returns.
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 what the tool does: it reads the client's view state including eye position, aim trace, health, weapon, etc. It distinguishes itself from screenshot-based tools by emphasizing 'no image' and positioning itself as the cheap half of an act-then-look loop.
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 the tool (when you need view state quickly and cheaply without an image) and contrasts with a screenshot approach. While it doesn't explicitly name alternatives, the sibling tools list includes 'capture_screen', and the description's context provides clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Touches every .lua file of an addon to trigger autorefresh. Best-effort; structural changes still need a restart.
| Name | Required | Description | Default |
|---|---|---|---|
| addon | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no readOnlyHint or destructiveHint annotations, the description carries the burden. It discloses the action (touching Lua files), the trigger (autorefresh), and the limitation ('Best-effort; structural changes still need a restart'). This provides adequate transparency for a refresh 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 consists of two concise sentences (20 words) with no redundancy. The first sentence front-loads the primary action, and the second provides an important caveat. Every sentence 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?
Given the single required parameter, lack of output schema, and minimal annotations, the description is mostly complete. It explains the tool's behavior and limitations. However, it could be more complete by mentioning the return type (e.g., success/failure) or examples of addon naming.
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 and the description does not elaborate on the 'addon' parameter beyond the tool name. The agent must infer that 'addon' expects a string identifier, but the description adds no format or example, which is insufficient given the schema's minimal documentation.
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 'Touches every .lua file of an addon to trigger autorefresh', specifying the verb (touches), resource (Lua files of an addon), and action (autorefresh). It distinguishes from siblings like 'reload_file' by targeting all files of an addon rather than a single file.
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 code changes without structural impact via 'Best-effort; structural changes still need a restart.' It does not explicitly state when to use or when not to use, nor does it name alternative tools, leaving the agent to infer usage context from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Triggers GMod's Lua autorefresh for a file by bumping its mtime. Best-effort: it covers edits, while new files and autoruns still need a restart.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist beyond title, so the description carries full burden. It mentions 'best-effort' and 'bumping mtime' but does not disclose potential side effects (e.g., file modification, required permissions) or safety profile. The behavioral impact is incompletely described.
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 consists of two concise sentences: the first states the core action, the second clarifies limitations. No redundant words, and critical 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?
Given the tool's simplicity (one param, no output schema), the description covers purpose and constraints but lacks parameter details (e.g., expected format) and does not address error cases. It is adequate but has 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?
With 0% schema description coverage, the description must add meaning to the lone parameter 'file'. It only says 'for a file' without specifying format, path type, or allowed values. This adds minimal value beyond the parameter name itself.
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 ('triggers') and resource ('GMod's Lua autorefresh for a file'), with a specific mechanism ('bumping its mtime'). It also distinguishes from siblings by noting limitations (covers edits, not new files/autoruns), which differentiates it from reload_addon or restart tools.
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 context: 'covers edits, while new files and autoruns still need a restart.' This tells when to use (for edits) and when not (new files/autoruns), but does not name alternative tools directly. Still, it offers clear boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reverts a patch by id, restoring the previous state.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no destructiveHint or readOnlyHint, so the description must convey behavioral traits. It only says 'reverts' and 'restores', which implies mutation but does not disclose whether the operation is destructive, reversible, or has side effects. No output schema exists to clarify return 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 a single sentence with no extraneous words, but it lacks essential details. Conciseness is good, but structural elements like usage context or parameter hints are missing.
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 simplicity (one parameter, no output schema), the description covers the basic action. However, it omits context like what a 'patch' is, whether the operation is reversible, or any constraints on the id. Additional detail would improve 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?
Schema description coverage is 0%, so the description should compensate. It only mentions 'by id' without explaining what the id refers to, what format is expected, or any relationship to other entities. For a single parameter, this is insufficient.
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 'reverts' and the resource 'patch', along with the outcome 'restoring the previous state'. The tool name and description together uniquely identify its purpose relative to 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?
No guidance on when to use this tool versus alternatives like patch_file or other mutation tools. The description does not mention prerequisites, when not to use it, or context for invoking it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runs a server console command (game.ConsoleCommand -- queued, around 0.25s of latency).
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations beyond title, so description carries full burden. It discloses queuing and latency, but omits permissions, side effects, or error behavior. For a command execution tool, more detail is needed.
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?
Single sentence with no fluff. Efficiently conveys key info without 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?
Lacks output schema and annotations. Description covers latency and queuing but doesn't specify return value or error handling. Adequate for a single-param tool, but could be improved.
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 description must add meaning. It identifies the parameter as a server console command and notes it's queued, but doesn't provide format or examples. 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 verb 'Runs' and the resource 'server console command', including technical details like 'game.ConsoleCommand' and latency. It distinguishes from sibling tools like 'run_lua' and 'read_console'.
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 vs alternatives. It mentions queued behavior and latency but lacks when/why guidance. Usage is implied for running console commands.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One full iteration: optional patch -> reload (or a restart note) -> validate. Returns the applied patch and the verdict. This is the core of the edit/observe/fix loop.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | File to patch, together with content. | |
| addon | Yes | ||
| reload | No | Touch files to trigger autorefresh after patching. | |
| content | No | The file's new contents. | |
| rationale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description outlines the sequential steps (patch, reload/restart note, validate) and mentions the return values (applied patch and verdict). However, it lacks detail on what 'restart note' means, the behavior when no patch is provided (does it skip straight to reload?), error states, side effects, or permissions. Since annotations provide no readOnly or destructive hints, the description carries the full burden and falls short of full 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 concise with two sentences. The first sentence defines the tool's workflow precisely, and the second explains its purpose. No superfluous 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?
Given the tool has 5 parameters and no output schema, the description provides a high-level overview but lacks details on parameter roles, error handling, and the exact format of the 'verdict' return value. For a core tool in a loop, more comprehensive documentation would be beneficial.
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 process context ('optional patch' implies file+content are for patching, 'reload' corresponds to the boolean parameter) but does not explain all five parameters (e.g., rationale lacks any description). Schema coverage is 60% (parameters have descriptions in schema), so baseline is 3; the description adds marginal value without fully compensating for undocumented 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's function: 'One full iteration: optional patch -> reload (or a restart note) -> validate. Returns the applied patch and the verdict.' It identifies the specific verb ('run iteration'), resource (an iteration of edit/observe/fix loop), and distinguishes from sibling tools like validate, patch_file, reload_file by combining all steps.
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 as 'the core of the edit/observe/fix loop', suggesting it is intended for iterative development cycles. However, it does not explicitly state when to use this composite tool versus calling individual sibling tools (e.g., patch_file, reload_file, validate) separately, nor does it provide when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GUARDED. Runs arbitrary Lua server-side (RunString) and returns the resulting value. Requires confirm:true. Audited.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | ||
| confirm | No | Must be true: this is a sensitive, audited action. Otherwise the call is refused. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the action is guarded, audited, and requires confirmation, but does not detail potential side effects, error behavior, or return format beyond 'resulting 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?
Two brief sentences with critical info front-loaded ('GUARDED') and no redundant text; every word adds 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?
For a simple tool with 2 params and no output schema, the description covers purpose, guard, and required confirm. It lacks error or return details but is largely sufficient.
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 50% (code lacks description). The description adds that confirm must be true and that code is arbitrary Lua, but does not explain code syntax or limits, leaving the agent to infer 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 description clearly states the tool executes arbitrary Lua code server-side and returns the result, using specific verbs and distinguishing it from sibling tools like run_console_command.
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 notes it is guarded, requires confirm, and is audited, implying sensitive use, but does not explicitly compare to alternatives or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runs a GLua test file server-side and returns {passed, failed, results}. path is relative to lua/, e.g. 'myaddon/tests/x.lua'. The file returns a table { [name] = function(t) end }.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the return format {passed, failed, results} and notes the test file returns a table of functions. No annotations about readOnly or destructive behavior exist, so the description partially covers behavior but omits side effects, safety implications, or any state modifications. Concise but not fully 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?
Two sentences, no filler. The first sentence declares the action and return type; the second provides path format and test structure. Very efficient and 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?
Given a single parameter, no output schema, and simple return description, the description covers the essential aspects. It could mention error behavior or what happens if the file doesn't exist, but overall it's sufficient for an agent to use 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 has one parameter 'path' with 0% description coverage, making it purely a string. The description adds significant meaning: 'relative to lua/', e.g., 'myaddon/tests/x.lua'. This clarifies the expected format and reduces ambiguity. For a single parameter with no schema description, this is effective 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?
Clearly states it runs a GLua test file server-side and returns a specific result structure. The verb 'Runs' and resource 'GLua test file' are specific, and the scope 'server-side' distinguishes from client-side operations. Among siblings like 'run_lua', this tool is distinctly for test files.
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 an example path indicating relative location within lua/, which helps usage. However, it does not explicitly state when to use this tool versus alternatives like 'run_lua', 'validate', or 'lint'. No when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prints a message server-side, useful for marking the log or tracing.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (only title). The description adds that the action is server-side and serves logging purposes, but it does not disclose behavioral details such as whether it is safe, requires permissions, or has side effects beyond printing.
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-structured sentence that conveys the essential information without superfluous words.
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 tool with one parameter and no output schema, the description covers the core function and use case. It lacks information about return value or potential side effects, but the tool's simplicity makes this a minor gap.
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% (no parameter descriptions). The description only says 'prints a message', which adds minimal information beyond the parameter name 'message'. It does not explain format, length limits, or valid 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 clearly states the action ('prints a message server-side') and its utility ('marking the log or tracing'), providing a specific verb and resource. It distinguishes from sibling tools like run_console_command or run_lua by focusing on server-side logging.
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 debugging or tracing ('useful for marking the log or tracing'), but provides no explicit when-to-use or when-not-to-use guidance nor comparisons to alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GUARDED, DarkRP. Sets a player's money, job, salary or RP name. Money is in INTEGER CENTS (1.50$ is 150) and goes through the r-capitalism ledger when it is loaded, so the audited invariant stays intact. Fails with a named error when DarkRP is absent. Requires confirm:true.
| Name | Required | Description | Default |
|---|---|---|---|
| job | No | Job command (e.g. 'police'), job name, or team index. | |
| rpname | No | ||
| salary | No | ||
| target | Yes | ||
| confirm | No | Must be true: this changes the running game and is audited. Otherwise the call is refused. | |
| money_cents | No | Absolute balance in integer cents. The ledger records the delta as an issue or a burn. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is guarded, audited, and requires confirmation. It explains the money is in cents and goes through a ledger. These details add value beyond the sparse annotations (only title). No contradictions with 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 two sentences long with no fluff. The first sentence states the purpose, and the second adds critical details about units, ledger, error handling, and confirmation requirement. Every sentence is valuable.
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 6 parameters and no output schema, the description covers the essential behavioral traits (DarkRP dependency, confirm requirement, money unit). It lacks explicit mention of return values or failure modes beyond 'named error', but overall it provides enough context for an agent to use it safely.
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 50%, and the description adds the crucial clarification that money is in integer cents. However, it does not explain the job parameter or rpname further. The description avoids repeating schema details, but given the moderate coverage, it provides minimal extra guidance.
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 it sets a player's money, job, salary, or RP name. It distinguishes from sibling tools by specifying 'GUARDED, DarkRP' and the scope of state mutation, which sets it apart from read-only and debug tools.
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 notes that it fails with a named error when DarkRP is absent, telling when not to use it. It also emphasizes the need for confirm:true. However, it does not explicitly compare to alternatives or provide conditions for when to use this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GUARDED. Creates and spawns an entity at a position. Returns its EntIndex, which the other world tools take as a target. Requires confirm:true.
| Name | Required | Description | Default |
|---|---|---|---|
| ang | No | Angles [pitch, yaw, roll]. | |
| pos | Yes | World position [x, y, z]. | |
| class | Yes | Entity class, e.g. prop_physics or spawned_money. | |
| model | No | Model path; required by prop_physics. | |
| freeze | No | Disable physics motion once spawned. | |
| confirm | No | Must be true: this changes the running game and is audited. Otherwise the call is refused. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given sparse annotations (only title), the description carries full burden. It notes the tool is 'GUARDED', changes the game, and is audited, indicating destructive behavior. It also mentions the return value. No contradictions with annotations. Some side effects or irreversibility details are absent but overall adequate.
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 very concise—two short sentences with no redundant or irrelevant content. It front-loads the guarded nature and primary action, making it easy 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?
The description covers the main purpose, return value, and a critical constraint. However, given the complexity (6 parameters, no output schema), it lacks details about parameter dependencies (e.g., model required for certain classes) and does not fully place the tool in the broader workflow among siblings.
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 100%, so all parameters are already documented. The description adds no additional semantic value for parameters beyond emphasizing the confirm constraint. Baseline 3 is appropriate.
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 (creates and spawns an entity), the return value (EntIndex), and its use by other world tools. It is specific about the resource and output, though it does not explicitly differentiate from sibling mutation tools like world_edit.
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 includes the key requirement 'confirm:true' and hints that the returned EntIndex is used by other tools. However, it does not provide explicit guidance on when to use this tool versus alternatives like run_lua or set_player_state, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Starts the dedicated server through tools/start-server.sh [map] [gamemode] [tickrate] and records the log's boot boundary. Script defaults: rp_nycity_day/darkrp/33.
| Name | Required | Description | Default |
|---|---|---|---|
| map | No | ||
| gamemode | No | ||
| tickrate | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotation hints, the description carries full burden. It mentions starting a server and recording a log boot boundary but omits critical behavioral traits like whether it stops an existing server, permissions required, or side effects. Minimal 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?
Two efficient sentences without superfluous words. The primary action 'Starts the dedicated server' is front-loaded, and the script path and defaults are presented directly.
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 that starts a server with 3 parameters and no output schema, the description lacks essential context: behavior when server is already running, meaning of 'boot boundary', return value, and any error conditions. Incomplete for robust 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?
Despite 0% schema description coverage, the description provides default values for all three parameters (map, gamemode, tickrate) in order, adding meaning beyond the bare schema. However, it does not explain the purpose or constraints of each parameter 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 'Starts the dedicated server' with specific verb and resource. It further provides the script path and default values, making the purpose unmistakable and distinct from siblings like stop_server.
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 on when to use this tool versus alternatives such as run_console_command or stop_server. No conditions or prerequisites mentioned, leaving the agent without context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stops the dedicated server through tools/stop-server.sh.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description does not disclose behavioral traits such as whether the stop is graceful or forceful, if it affects other tools, or if it requires elevated permissions. The mention of 'through tools/stop-server.sh' is an implementation detail but not a 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 a single concise sentence with no unnecessary words. However, more context could be added without making it verbose.
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 parameters, no output schema, and no annotations, the description is too minimal. It does not explain what happens after stopping, whether the server restarts automatically, or any side effects on other tools or the system.
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, so baseline is 4. The description does not need to add parameter information, and it correctly implies no arguments are needed.
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 (stops) and the resource (dedicated server) with a specific verb and resource. It is distinct from siblings like start_server.
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 versus alternatives. For example, there is no mention that it should be used after start_server or not used during critical operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reapplies server-config/ and (re)creates the symlinks through tools/sync-server-config.sh. check:true compares without writing (--check).
| Name | Required | Description | Default |
|---|---|---|---|
| check | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (only title), so the description must disclose behavior. It mentions destructive actions (reapplying, recreating symlinks) and a dry-run option, but does not detail auth needs 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 a concise two sentences: the first states the main action, the second explains the parameter. No redundant 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?
For a simple tool with one parameter and no output schema, the description covers the essential action and parameter, but lacks context about prerequisites (e.g., server state) and 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?
With 0% schema description coverage, the description adds meaning to the only parameter 'check' by explaining it enables comparison without writing, which is not evident from the schema alone.
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 'reapplies' and 'creates' with the resource 'server-config/' and 'symlinks', making the tool's purpose specific and distinguishable from 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 explains the 'check' parameter's function but does not provide explicit guidance on when to use this tool versus alternatives, leaving usage context largely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verdict for the loop: the addon's lint plus the current boot's runtime errors. ok=true when lint is clean AND no runtime error was seen.
| Name | Required | Description | Default |
|---|---|---|---|
| addon | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses it checks lint and runtime errors to return ok=true/false. No annotations exist, so this is the only behavioral info. It doesn't mention side effects, permissions, or how it accesses data.
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?
Single sentence, concise but terse. Uses unclear terms like 'Verdict for the loop' and 'ok=true' without context. Could be restructured for 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?
No output schema, so description should clarify return format. It only implies a boolean result but doesn't specify if it's a field 'ok' in an object. Missing error conditions or non-ok scenarios.
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?
Input schema has one parameter 'addon' with no description. Description mentions 'the addon's lint', linking parameter to lint check, but doesn't explain format, examples, or how value is used. Schema coverage is 0%, but description adds minimal value.
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?
Description says it's a 'Verdict for the loop' combining lint and runtime errors, which is a specific purpose but vague and jargon-heavy. It doesn't fully clarify what 'validate' computes beyond a boolean condition. Sibling tools like 'lint' and 'read_runtime' suggest aggregation, but no explicit distinction.
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 on when to use this tool vs alternatives like 'lint' or 'read_runtime'. It doesn't specify prerequisites or context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GUARDED. Acts on one entity or player: remove, teleport, set_ang, freeze, unfreeze, set_health, set_armor, give, strip. target is an entity index or a player's SteamID/name. Requires confirm:true.
| Name | Required | Description | Default |
|---|---|---|---|
| ang | No | Angles for set_ang. | |
| pos | No | Destination for teleport. | |
| value | No | Amount for set_health and set_armor. | |
| action | Yes | ||
| target | Yes | ||
| weapon | No | Weapon class for give. | |
| confirm | No | Must be true: this changes the running game and is audited. Otherwise the call is refused. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations providing safety hints, the description discloses that the tool changes the running game (GUARDED, requires confirm:true). It also enumerates destructive actions like remove and teleport. This is strong transparency, though it could explicitly state 'this tool modifies the game state'.
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 sentences, each packed with essential information. No redundant words. Front-loaded with 'GUARDED' to immediately signal safety implications. The structure is exemplary.
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 9 possible actions and no output schema, the description is sufficiently complete: it explains the purpose, target, actions, and safety requirement. It could be enhanced by briefly noting when to use each action, but that is not critical for correct invocation.
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 beyond the schema by explaining that target can be an entity index or a player's SteamID/name. The schema already covers 71% of parameters with descriptions, so the description's value is moderate but useful for understanding the target type and the confirm requirement.
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 acts on one entity or player with specific actions (remove, teleport, etc.). It distinguishes itself from sibling read-only tools like read_entities by its mutating nature. Both the verb 'acts' and the resource 'entity or player' are explicit.
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 lists allowed actions and states target types and confirm requirement, giving clear usage context. It does not explicitly exclude alternatives, but the sibling list implies this is the go-to for modifications. A score of 4 reflects clear context without explicit when-nots.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct aspect of GMod: reading entities vs inspecting vs spawning vs editing; reading panels vs inspecting vs capturing; running commands vs Lua vs tests; file patching vs linting vs validation; etc. There is no ambiguity between tools despite the large set.
The vast majority of tools follow a clear verb_noun pattern (e.g., read_entities, run_console_command, spawn_entity). A few tools like 'batch', 'health', and 'client_input' deviate slightly, but overall the naming is predictable and consistent.
With 38 tools, this is on the higher side of appropriate. While each tool serves a specific purpose in managing a GMod server, the count is above the typical 3-15 range. However, the complexity of the domain justifies the number, so it's borderline heavy rather than excessive.
The tool set covers most major operations: CRUD for entities and players, panel inspection and screen capture, server control, file management, linting, workflow automation (batch, iteration). Minor gaps exist (e.g., no direct tool for installing addons), but the surface is largely complete for development and debugging.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
An MCP server that gives your AI access to the source code and docs of all public github repos
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Generate game-ready 3D models, textures, and audio from natural language, over MCP.
MCP server for AI dialogue using various LLM models via AceDataCloud
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ProjectSocietyStudio/gmod-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
