Скрипты GDScript

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

All four documented modes are pure inspection operations, yet the annotations declare readOnlyHint=false and destructiveHint=true. The description describes no write capability, no data being modified or destroyed, and no mode that would justify a destructive classification, so the agent receives directly conflicting signals about safety.

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 dense sentence front-loaded with the general purpose, then a compact mode-by-mode clause list. Every clause carries information; it is slightly run-on but has no filler or restatement of the tool name.

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?

With no output schema and 38% schema coverage on 8 parameters, the description does the important work of describing what each mode returns. It still leaves gaps: paging/limit behaviour, the default mode, the conditional path requirement, and the unresolved safety conflict with the annotations.

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 only 38% across 8 parameters, so the description must compensate and it partially does: it explains each mode's semantics and hints at line-range usage for mode=read (from_line/to_line) and symbol/dirs usage for references. It says nothing about limit, include_definition, or the fact that path is required for all modes except references.

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 names the resource (GDScript scripts) and enumerates all four modes with the concrete payload each returns (metadata, symbol structure, raw text, call-site references), so an agent understands exactly what the tool does. It is weaker only on sibling differentiation — it never distinguishes itself from godot_script_check or godot_class, which an agent could reasonably confuse with the symbols/references modes.

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 mode-to-need mapping (info for metadata, symbols for structure, read for text, references for call sites) gives implicit guidance on which mode to pick, which is genuinely useful. However there is no explicit 'use this when / not when', no mention of the default mode, and no routing to alternatives such as godot_script_check for validation.

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