Script / Read

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description still earns credit by adding behavior beyond them: the read goes through Godot's FileAccess so it works on imported and non-imported res:// paths, and out-of-range slice values are clamped to at-most the whole file rather than erroring.

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 the core purpose in the first sentence, then slice behavior, then the write-back pairing, then the FileAccess caveat — a sensible order. A few stacked parentheticals add density, but no sentence is filler.

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 fully compensates by enumerating the returned fields (res:// path, language, line count, content) and naming the ScriptInfo shape. Combined with slice clamping and path validation notes, an agent has everything needed to call it correctly on the first try.

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 baseline is 3, but the description adds meaning: '1-based' indexing and the clamping policy ('out-of-range values read at-most the whole file') clarify edge behavior that the per-property 'Clamped into range' notes only gesture at. It stops short of 5 because the slice semantics are largely restated from the schema.

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 ('Read a Godot script file') along with the accepted extensions (.cs/.gd), the path namespace (res://), and the return payload (content + path, language, line count). This is clearly distinguishable from the file-lifecycle siblings script-update/script-create, which it explicitly cites as the write-side counterparts.

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 real usage context: read here, then pair with script-update/script-create to write back, and the optional slice for partial reads. It lacks an explicit exclusion (e.g., when to prefer script-validate or rql-query over reading raw content), so it stops just short of full when/when-not routing.

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