runtime_eval

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

Annotations only supply the boolean safety flags; the description adds real behavioral context: side effects ('Calls run for real and may change the game'), the name-resolution scope (base node members, autoloads, engine singletons, class_name globals), and the failure mode (engine error text). There is mild tension with destructiveHint=false given that calls can mutate game state, but mutating is not the same as destructive/reversible-deletion, so this is a caution rather than a contradiction.

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?

Front-loaded with purpose, then language constraints, then name resolution, then side effects, then return value. Dense and mostly waste-free; 'while it runs' is mildly redundant with 'in a running game' but it reinforces the no-breakpoint point.

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 exists, and the description compensates by stating the return contract ('the value, or the engine's error text'). Combined with the expression-language limits, name-resolution scope, and side-effect warning, an agent has everything needed to invoke this 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 the baseline is 3, and the description exceeds it by explaining what the 'expression' parameter actually accepts (Godot Expression operators/calls/constructors, no statements or assignment) and what namespace the 'node' parameter resolves against. It does not address the session_id parameter, but the schema already documents that.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Evaluate an expression in a running game') and immediately differentiates itself from the debugger-based sibling with 'no breakpoint needed', which is the key distinction against debug_evaluate and debug_pause/continue. An agent can pick this over debug_evaluate without opening a schema.

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

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

Gives clear selection context ('while it runs - no breakpoint needed') and constrains the input to Godot's Expression subset ('no statements or assignment'). It does not explicitly name debug_evaluate as the alternative for breakpoint-based evaluation, so it stops short of explicit when-not/alternatives guidance.

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