Редактирование сцены

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false. On top of that the description discloses the default dry-run behavior, that changes apply in memory first, that a backup is auto-created in .mcp-backups, and that edits are transactional — real context beyond the 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?

Dense but front-loaded: transactional statement and dry-run workflow come first, then the operation catalog, then value-format rules. Every sentence carries load-bearing information; only minor tightening would be possible.

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 notes the dry-run result lands in the log rather than a return payload. For a destructive batch-mutation tool it covers transactionality, backup, and value syntax adequately, though it does not explain failure/rollback semantics when one op in the batch is invalid.

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 80% and documents path/save/backup, but the ops array is left untyped (additionalProperties: {}). The description compensates heavily by enumerating all 14 operation types and the op fields (parent, type, name, props, script, groups, index, path, to, signal, method, binds) plus value encoding formats for vectors, colors, and resource refs.

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?

Names a specific verb and resource ('Транзакционное изменение .tscn пачкой операций') and scopes it as batched, transactional editing, which separates it from sibling godot_scene (read) and godot_scene_backups. An agent knows exactly what the tool mutates without opening the 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 a concrete workflow: default save=false is a dry run, inspect the logged result, then re-run with save=true. This tells the agent when the safe path applies and how to escalate to a real write, though it does not explicitly compare against other scene-editing siblings.

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