Eval Lua in the running game

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

With no annotations, the description carries the full burden. It discloses timeout behavior, the multiplayer desync side effect, and the debugger context. It doesn't specify return serialization or error behavior, but the critical operational caveats are covered.

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

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

Three sentences, each purposeful: the core action, the usage pattern, and the behavioral caveats. Front-loads the main purpose and avoids redundancy; 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?

For an eval tool with no output schema, it explains how to obtain values and flags side effects. It doesn't detail error handling or result formatting, but given the tool's open-ended nature, the essential usage and risks are covered. Slightly more on timeout_ms would push it to 5.

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

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

The description effectively explains that chunk should contain Lua code and demonstrates the 'return' pattern, which maps to the schema's example. It touches on timeout indirectly via the 'can time out' note, but timeout_ms itself is not explicitly described. Since schema coverage is only 50%, this partial compensation is acceptable but not complete.

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: executing a Lua chunk in the game's VM via the debugger and returning the result. It gives a concrete pattern ('return <expr>') and distinguishes from sibling tools that search or read files, making the intent unambiguous.

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

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

It instructs to use 'return <expr>' for output, warns that the VM only responds during Lua execution (timeout in menu/paused), and flags multiplayer desync—implicitly saying when not to use it. However, it does not explicitly contrast with alternatives like search_lua_api, so a small gap remains.

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