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

Annotations only declare destructive/not-idempotent; the description adds the operational traits that matter: all-or-nothing validation before any write, editor undo (Ctrl+Z), scene edits left unsaved vs. .tres files auto-saved, receipt contents ($ref, member, old, new), omitted unchanged assignments being counted, and the 200/1000 target cap. It even documents non-obvious limits (nodes inside scene instances can take property overrides but can't be removed or reparented) and tool-specific caveats like LightmapGI having no scriptable bake.

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 critical rules are correctly front-loaded before the example list, but the text is very large, with ~30 example lines plus trailing prose blocks on Editor state, Baking, Bulk create, and Object literals that sprawl rather than being grouped. Much of the example material overlaps the RQL guide it explicitly points to in rql-query's description, so a meaningful share of the length is duplicative rather than earning its place.

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 compensates by describing the receipt shape, per-row $ref/result columns, truncation at 50 rows with a counted remainder, and failure modes. For a high-complexity mutation tool spanning nodes, resources, project settings, and editor state, an agent has everything needed to call it correctly and interpret what comes back.

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, but the description adds real meaning beyond the schema: dry_run returns the receipt without writes and omits unchanged assignments with a count, max_targets defaults to 200 and can be raised to the match count (max 1000) for an intended bulk change that stays one undo step, and query must terminate in set or call. The extras are behavioral rather than syntax-level, which keeps it short of a 5.

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: "Change the live Godot editor with an RQL query whose last stage is set or call." It also implicitly separates itself from the sibling read tool by naming rql-query for listing and gameLog reads, so an agent can distinguish mutate from query without opening either 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 explicit when-to guidance and exclusions: read-only members fail with readonly-member rather than being approximated, destructive cleanup over query matches requires a two-turn confirm flow via rql-query, and dry_run=true previews first. It also instructs reporting name-to-object mappings and warns against doing more than the requested change.

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

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

Annotations already establish the read-only, idempotent, non-destructive profile, but the description adds substantial behavior: compact row output format, truncation of long results, refinement via where/first/count, warning-and-suggestion behavior for unknown members, and call-limit receipts.

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 description is organized into labeled sections and examples, but it is extremely long and reads like a full language reference rather than a tool description. The linked RQL documentation is mentioned but much of its content is duplicated inline, making the definition excessively verbose.

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 complex DSL-based query tool with no output schema, the description is exceptionally complete: it covers return format, truncation, error behavior, source types, operators, and many worked examples. An agent has enough information to construct and interpret queries correctly.

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% and the only parameter is the query string, but the description goes far beyond the schema by documenting sources, stages, expression syntax, paths, meta fields, type-specific members, and language rules. This is necessary semantic detail for constructing a valid query.

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 opening sentence states a specific verb and resource: 'Run a read-only RQL query against the live Godot editor and return compact rows.' It also distinguishes the tool from its sibling by noting 'Changes need rql-mutate.'

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 explicitly advises 'One precise query beats many exploratory calls,' routes mutations to rql-mutate, and points to rql-schema(type) for member discovery. This gives clear when-to-use and when-to-use-something-else guidance.

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

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

Annotations already establish readOnlyHint/idempotent/closed-world, and the description goes beyond them by describing what content comes back per mode, including node class counts and the 'ro = read-only' member flag plus the props["name"] convention. It does not discuss output size, truncation, or cost of introspecting a large scene, which would be a fuller disclosure.

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 paragraph is dense and front-loaded, leading with the acronym and its reference link before the mode breakdown, and every clause maps to a distinct behavior. The parenthetical reference URL and a couple of nested asides make it slightly heavier than necessary, but there is no 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?

With only one optional parameter and no output schema, the description carries the burden of explaining return content, and it does so for each mode including the shape of member listings (name type; ro markers; props["name"]). Nothing essential for correct invocation is missing.

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 would be 3, but the description substantially enriches the single `type` parameter by explaining the three semantic branches (omitted, extension name, type name) and giving concrete example values. That is meaning the schema alone does not convey.

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 precisely what the tool returns and enumerates three distinct modes keyed by the optional `type` argument: no type gives sources/functions/extensions/scene node classes plus Node members, an extension name gives that extension's guide, and a type name gives members, methods, and Godot properties. This is far more specific than the title 'RQL / Schema' and distinguishes it from siblings like rql-query and rql-mutate.

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 gives explicit usage guidance in 'Use it before querying an unfamiliar class,' which tells the agent to call this as a discovery step ahead of querying. It does not name a concrete alternative (e.g. rql-query) or state when not to use it, so it falls short of the top score.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds real behavioral value: rendering happens in a temporary off-screen SubViewport so the editor's live selection/camera is untouched, output edges are capped for transportability, and a --headless launch yields a structured error rather than a blank PNG. That headless failure mode is exactly the hidden behavior an agent needs before calling.

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 lead sentences are front-loaded and dense with useful information. The trailing 'Argument types — give these arguments as RQL values' block is generic shared boilerplate that partly duplicates the schema, adding bulk without adding tool-specific meaning.

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 3-parameter read tool with no output schema, the description covers the return type (PNG), the rendering isolation, the size limiting, and the headless error case. The remaining gap is that the dimension cap is referenced but never quantified, and sibling disambiguation is absent.

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 schema baseline is a 3. The description goes beyond it by spelling out the accepted NodeRef forms (ref("Node3D#12"), godot.find("Name"), instance id, or a path below the scene root) and by stating that unneeded keys may be omitted. It does not clarify the actual dimension cap value for width/height.

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: capture a screenshot from a specific Camera3D (or Camera2D) in the edited scene and return a PNG. The nodeRef requirement and off-screen SubViewport rendering are concrete. It stops short of naming the siblings screenshot-viewport / screenshot-isolated, which are the obvious alternatives an agent must choose between, so differentiation is only implicit.

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?

Usage is implied by the framing (render a specific camera's world without disturbing the editor), but there is no explicit when-to-use/when-not statement and no routing to screenshot-viewport or screenshot-isolated. The agent must infer the choice from names alone.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds substantive behavior: rendering uses a temporary off-screen copy so the edited scene is never mutated, output is capped for transportability, and missing GPU support surfaces as a structured error rather than a blank PNG. Those are exactly the traits an agent cannot derive from the annotation flags.

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 core sentence is front-loaded and dense with useful facts, and the GPU caveat is correctly placed at the end. The trailing 'Argument types — give these arguments as RQL values' block is boilerplate that duplicates framework-wide conventions rather than this tool's specifics.

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 9-parameter tool with no output schema, the description still covers the return value (square resolution x resolution PNG, capped), the non-mutation guarantee, and the failure mode. Nothing an agent needs to decide whether to call it or to interpret the result is missing.

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 above that by explaining that nodeRef accepts ref() from a query, godot.find(), an instance id, or a scene-relative path, and that backgroundColor only applies when background is SolidColor. It stays silent on padding, fieldOfView, and the clip planes, leaving those entirely to 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 ('Render a target Node3D in ISOLATION') plus scope constraints ('only the target is visible, in its own world') and the output form (PNG). The isolation scope is what separates it from screenshot-camera and screenshot-viewport without the agent needing to open either 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 clear conditions of use — pick a node, pick a view, pick a background — and an explicit environment prerequisite (needs a real GPU; '--headless' fails). It never names screenshot-camera or screenshot-viewport, so the choice between the three screenshot tools remains an inference from the word 'isolation' rather than an explicit routing rule.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the description is free to add genuinely new behavior: the PNG return format, the longest-edge downscaling with aspect preserved, and the headless/--headless failure mode surfacing as a structured error instead of a blank PNG. That last point is exactly the kind of non-obvious operational constraint annotations cannot express.

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?

Three tight sentences: purpose first, then mode selection, then output scaling and the headless caveat. Every sentence contributes distinct information with no repetition of the title or 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?

For a single-optional-param read tool with no output schema, the description still covers what is returned (PNG), how it is sized, and how failure manifests. Nothing an agent needs in order to call it correctly and interpret the result is missing.

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 mode enum, default and case-insensitivity are already documented in the schema. The description restates them faithfully but adds no syntax or edge-case detail beyond it; baseline 3 is appropriate when the schema carries the parameter burden.

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 ('Capture') and resource ('Godot editor's main viewport'), and clarifies it is the 3D or 2D editing surface as opposed to the camera or isolated views implied by the sibling tools. An agent can distinguish this from screenshot-camera and screenshot-isolated without opening any 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 clear selection guidance between '3d' (default) and '2d', and states the precondition that the editor must have a live GPU render. It does not explicitly route the agent to the sibling screenshot tools when the camera or an isolated view is wanted, which is the one remaining gap.

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

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

Goes well beyond the annotations: it discloses the underlying mechanism (script resource loaded and set via Node.SetScript), the side effect that the scene is marked unsaved, the follow-up call needed to persist, and the destructive clear-on-empty behavior that explains destructiveHint=true. It also describes the return payload (structured ScriptInfo on attach, an identity record with 'detached' status on clear), which matters since there is no output schema.

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: the core action, argument contract, and side effects come before the RQL value-format digression, and every sentence carries information. The only waste is the NodeRef definition appearing twice (in the 'Argument types' block and again as the trailing 'NodeRef — a node:' line).

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, the description supplies the return shape for both attach and detach, and for a two-parameter mutation it covers side effects, persistence, and argument forms. Nothing an agent needs in order to call it correctly and interpret the result is missing.

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, but the description adds real meaning: the accepted forms of nodeRef (ref("Node3D#12") from a query, godot.find("Name"), raw instance id, or scene-root-relative path) with a stated preference order. It also reinforces the extension constraint on scriptPath and the detach sentinel. The redundant restatement of NodeRef at the end of the description slightly dilutes the added value.

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+resource ('Attach a script ... to a Node') and bounds the scope to 'the currently edited Godot scene'. It further disambiguates from siblings by explaining the tool also performs DETACH when scriptPath is empty, and grounds the concept with 'the Godot analog of adding a MonoBehaviour to a GameObject'. An agent can distinguish this from script-create/script-update/script-delete without opening any 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 clear operating context: attach in the currently edited scene, scriptPath must point to an existing res:// file, and persisting requires a separate rql-mutate 'editor | call SaveScene()'. It also defines the detach path and its precondition. It stops short of explicitly saying 'use script-create first if the file does not exist' or naming script-update as the alternative for changing script contents, so alternatives are only implied.

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

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

Adds substantial behavior beyond the annotations: the build runs in the background, a successful build triggers an assembly reload and plugin reconnect, results (warnings or errors) arrive asynchronously after the reload via requestId, and concurrent calls are rejected with a retryable error. It does not address why destructiveHint=true (what on disk may be overwritten) or expected duration, so it is not fully exhaustive.

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 core action and its purpose are front-loaded in the first sentence, and the async/retry details follow in logical order. The second sentence is long and densely packed (reload, reconnect, requestId delivery), costing some readability but no wasted content.

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, the description correctly explains the return path (compiler warnings/errors delivered after the reload via requestId) and the async/retry contract, which is what an agent needs to call it safely. It omits build scope details (whole solution vs project) and expected build duration, so it is strong but not fully complete.

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?

Zero input parameters, so the baseline is 4 and there is little for the description to clarify. It mentions a 'requestId' that does not exist in the schema, which is mildly confusing but does not affect invocation since no arguments are accepted.

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+resource (build the project's C# via dotnet build, Debug configuration) and ties the effect directly to sibling tools script-create/script-update by explaining what the build makes loadable ([GlobalClass] types, changed node scripts). An agent can distinguish this from script-validate or script-execute without opening a 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 clear when-to-use guidance: call after writing/updating scripts so they load in the editor. It also explains the failure mode to expect (calls during the pending reload are refused with a retryable error, retry in a few seconds). It does not compare against alternatives such as script-validate, so it stops short of explicit when-not-to-use routing.

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

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.

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

Annotations already flag destructive/non-readOnly, but the description goes well beyond them: failure when no file exists, identity captured before deletion, the '.uid' sidecar removal, a filesystem rescan, and a bounded settle for '.cs'. It also discloses a non-obvious side effect — a loaded copy is detached so an open scene embeds it on its next save — which no annotation conveys.

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-loads the action and resource in the first sentence, then layers failure mode, mechanics, and the breakage warning in a logical order. It is dense but every clause carries operational information; only the 'BOUNDED-settles' phrasing is slightly opaque jargon.

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, the description does state what comes back ('structured ScriptInfo' with path and language captured pre-deletion). It omits the concrete shape of that return object and any error payload detail, but for a one-parameter destructive tool the operational picture is essentially complete.

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% and the single parameter already documents the res:// path format and '.cs'/'.gd' extension requirement. The description adds only the implied must-exist constraint, so the baseline 3 applies with little extra meaning contributed.

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 ('Delete a Godot script file') plus the scope ('from the res:// filesystem') and accepted file types ('.cs' or '.gd'). It is unmistakable against siblings like script-update or script-read, which mutate or inspect rather than remove.

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 an explicit precondition before use: 'verify with script-read first' because nodes/resources referencing the deleted script will break. That names a sibling and the condition selecting it. It does not, however, contrast against other mutation siblings (script-update, script-create) or state when deletion is inappropriate beyond the breakage warning.

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

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

Annotations only say destructive/open-world/non-idempotent; the description goes far beyond by disclosing exactly what is guarded (endless loops against a time budget, runaway recursion), that the process survives failures, and precisely which spawned concurrency (Thread, Task.Run, ThreadPool) is cleaned up versus which is not (timers, async void after first await, blocked waits). It also states the failure mode ('fails with Timeout') and that leftover threads produce a warning, which is unusually honest behavioral disclosure for an execution tool.

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?

It is front-loaded with the core purpose and modes, and nearly every sentence carries operational information (timeouts, thread cleanup, RQL encoding). The second paragraph is a dense wall of text with an unfinished sentence ('(a node, string, int, float, bool)'), and the timeout default is restated from the schema, so it is not fully tight.

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 an 8-parameter, no-output-schema execution tool this covers the essentials: what is returned (result plus Console/GD.Print output), both compilation modes, parameter passing syntax, resource limits, and concurrency cleanup caveats. An agent has enough to invoke it correctly and to anticipate failure modes without further documentation.

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, but the description adds meaning the schema does not: the RQL value grammar ({key: value}, [a, b], "text", ref("Node3D#12"), godot.find("Name")) and the rule that each named value is passed as a parameter of that value's type. That materially helps an agent construct 'parameters' correctly. Minor deduction because the argument-types explanation trails off with an incomplete parenthetical and repeats the timeout default already in 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?

The first clause gives a precise verb and resource: 'Compiles and runs C# in the Godot editor', then distinguishes its two operating modes (snippet with implicit usings vs. a declared class with a static method). It is immediately clear what the tool does and how it differs in effect from a build/validate tool, though no sibling (script-build, script-validate, rql-query) is named explicitly to route the agent.

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 gives real in-tool selection guidance: snippet vs. full class, when to set className/methodName, how isMethodBody overrides mode detection, and 'leave out keys you do not need' for parameters. It also explains when to raise 'timeout'. What it lacks is any statement of when to choose this over siblings like script-build or rql-query, so it stops short of explicit alternatives.

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

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.

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

Goes well beyond the annotations: it discloses that GDScript is syntax-validated and rejected without touching the existing file, C# is written as-is with no in-editor compile, that a bounded reimport/settle occurs for .cs, and that compile errors surface post-write. Failure behavior and side effects are described in concrete terms consistent with destructiveHint=true.

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-loads the operation and scoping, then layers validation and follow-up behavior; nearly every clause carries information. It is dense and somewhat parenthetical ('BOUNDED-settles', capitalized emphasis), which costs a little readability but not correctness.

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 2-parameter mutation with no output schema, it covers failure modes, validation, and follow-up steps thoroughly. The one gap is the return value: it only says "Returns a structured ScriptInfo" without any indication of what that structure contains, and there is no output schema to fall back on.

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 100%, so both parameters are already documented (full-content replacement, res:// path ending in .cs or .gd). The description mostly restates those constraints rather than adding new syntax or format guidance, so the baseline 3 applies.

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?

"Overwrite an EXISTING Godot script file ... under res:// with the provided source" gives a specific verb, resource, and scope, plus the accepted extensions. It explicitly names the sibling tools script-create, script-read, and script-build, so an agent can distinguish the intended tool without opening 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?

States the preconditions (a file must already exist at the path), tells what to do otherwise (use 'script-create'), recommends inspecting first with 'script-read', and names the follow-up tool 'script-build' for C# types. Explicit when/when-not plus alternatives.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds substantial behavior: full-scan file capping with a 'truncated' flag that invalidates a whole-project all-clear, version-dependent fidelity (Precise vs Coarse diagnostics on Godot <4.5), warning severity that does not flip 'ok', and res://addons/ skipping. These are exactly the caveats an agent could otherwise misread as success signals.

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 verb and result shape, then cleanly sectioned into Inputs and Result. It is long and occasionally editorial ('Closes the gap where the agent gets NO feedback', the GOOD-word caps), but nearly every clause carries operational information.

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?

There is no output schema, and the description compensates by enumerating the result fields (ok, diagnostics shape, counts, truncated, fidelity) and their semantics. Version-gated behavior, warning handling, and the C# gap are all covered — nothing an agent needs to interpret a clean or truncated result is missing.

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% and its own description already explains omit-to-scan-all, so the baseline is 3. The description adds real context beyond the schema: the omission path is bounded by FullScanFileCap, and that cap interacts with the 'truncated' result flag, which the schema does not mention.

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 ('Validate GDScript .gd files') plus the exact return shape (structured parse/compile diagnostics). It explicitly excludes C# ('.cs') files, which separates it from the sibling script-build, and the framing as the 'is the project error-free?' query distinguishes it from script-execute and script-read.

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 explicit when-to-use ('on-demand is the project error-free check') and when-not-to (C# files, which surface through the project build). It also names a complementary path — pairing with rql-query on the 'console' source — so the agent knows how to cover what this tool misses.

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