Script / Create

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

The description goes well past the annotations: GDScript is syntax-validated and rejected with nothing written, C# is accepted unvalidated, missing parent directories are created, and .cs writes trigger a bounded filesystem reimport before returning. These are exactly the failure-mode and side-effect facts an agent needs and none of them are derivable from readOnlyHint/destructiveHint/idempotentHint.

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?

The creation constraint and the script-update redirect are front-loaded, and each subsequent sentence covers a distinct behavior (validation, C#, parent dirs, settle, return). It is dense and the middle sentences are long, but no sentence is redundant.

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?

For a two-parameter creation tool with no output schema, the description covers failure conditions, validation, side effects, and the next step in the workflow. The only gap is that 'Returns a structured ScriptInfo' does not hint at its fields, which would matter since no output schema exists.

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; the description earns more by explaining that the path's extension ('cs' vs 'gd') changes validation, settle, and follow-up behavior. It does not discuss content encoding or any edge cases of content, but the schema already carries the type and required constraints.

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 states a specific verb and resource ('Create a NEW Godot script file ... with the provided source') and scopes it to res:// paths and two file extensions. It also explicitly distinguishes itself from script-update, so an agent can route between them without inspecting schemas.

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?

It says precisely when not to use it ('Fails if a file already exists at the path — use script-update to overwrite') and points at script-build as the follow-up for C#. It stops short of naming conditions in which script-create should be preferred over other creation paths, but the exclusion and alternative are explicit.

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