batch_scene_operations

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

Annotations provide destructiveHint: true, but description adds significant behavioral context: runs in one Godot process (~3s startup avoided), shares in-memory cache, saves once at end. Also details abortOnError and output format. No contradiction 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?

Two sentences, no wasted words. Front-loaded with purpose and key benefit. Structure is clear and 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?

Despite no explicit output schema shown, the description explains return format (results[] in input order, tagged). Given tool complexity (batching multiple ops), it covers performance benefit, process flow, and error handling sufficiently.

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 covers all parameters with descriptions (100% coverage). The description adds context: each operation item picks its sub-operation and supplies its own params, and output is results array in input order. This adds value beyond schema, justifying a score above baseline 3.

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 batches multiple scene operations (add_node, load_sprite, save) to avoid overhead, and distinguishes it from chaining individual calls. The verb 'use this instead of' directly contrasts with sibling 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?

Explicitly instructs when to use: 'Use this instead of chaining add_node / load_sprite / save_scene calls when you have multiple mutations on the same or related scenes'. Also explains abortOnError behavior and default (false continues), providing clear guidance.

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