Godotwright

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

Beyond the annotations, it discloses offline behavior, per-query-type return shapes, that member lookup resolves through inheritance, that unknown names return an error with close matches, and that Godot 3 names are mapped to their Godot 4 equivalents. It also honestly discloses the side effect — a lookup is written to a local learning file unless GODOTWRIGHT_LEARN=0 — which reconciles the 'changes no project files' claim with readOnlyHint=false.

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 lookup target and the sibling routing are front-loaded, and the paragraph moves logically from input forms to output shapes to error behavior to side effects. It is dense but every sentence carries information; the learning-file clause is the one piece that could be relegated to a shorter parenthetical.

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 fully covers return values for each query type, error behavior, and the only meaningful side effect. Nothing an agent needs in order to call this 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; the description goes slightly beyond by explaining what the two `detail` levels actually contain ('brief gives the signature and the first paragraph; full gives the whole entry'), clarifying the enum's practical effect. It adds modest value but does not elaborate on formatting or escaping of the `query` string, which the schema examples already cover.

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 — 'Exact lookup in the official Godot 4.7 class reference, offline' — and enumerates the accepted query forms (Class, Class.member, Class.Enum.VALUE, @annotation, global function). It explicitly contrasts with the sibling godot_api_search, so an agent can distinguish the two 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 an explicit when-to-use rule ('Use it before calling any engine API you are not sure about') and routes the agent to the alternative when the exact name is unknown ('use godot_api_search first'). Both the trigger and the fallback condition are stated outright.

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, and the description reinforces 'Read-only' while adding real behavioral context: results are ranked best-first, the return is one line per match with kind and signature (with a sample), and the 'no matches' case is disclosed. It stops short of describing ranking/collation details or performance constraints, so not a top score.

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?

Four tight sentences, front-loaded with the capability, then usage, then return shape, then parameter note. Every sentence carries distinct information; no filler or repetition of the title.

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 two params, no output schema, and full schema coverage, the description supplies everything an agent needs: what is searched, how to phrase queries, routing to siblings for follow-up, result format, and match-count behavior including the empty case.

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 both parameters are already documented there, including the same example strings and the default/max for limit. The description restates the limit cap (default 10, at most 50) and query semantics but adds no format or syntax detail beyond the schema, so the baseline of 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?

States a specific verb and resource ('Search the Godot 4.7 class reference offline') plus exactly what fields are searched (class, method, property, signal names, keywords, descriptions). It differentiates itself from the named siblings godot_api (full entry) and godot_usages (project-local lookups).

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?

Explicit when-to-use with concrete example queries ('raycast 3d', 'change scene'), plus a clear next step ('call godot_api on the best match') and an explicit exclusion routing to godot_usages for project-local name usage. Nothing is left to inference.

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 annotations: discloses side effects ('Godot updates its import cache in .godot/, where Godotwright also puts its checker script'), reassures 'your scenes and scripts are not changed', states timeouts cap each run, and describes the error result when Godot errors or is missing. This is consistent with readOnlyHint=false and rich enough that the agent knows what it will leave behind.

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 and front-loaded with the core action, then defaults, then return values, then prerequisites and alternatives. Every sentence earns its place; it is a touch long and packs a lot of clauses into single sentences, but nothing 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?

Covers return values (errors/warnings with file:line, totals, printed output, error result), side effects on .godot/, prerequisites, cost relative to siblings, and alternative tools. With no output schema, the description fully carries the burden for a tool that shells out to an external engine.

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 schema lacks: the conditional default ('run_frames defaults to 0, or 120 when you pass scene') and how timeout_seconds applies ('caps each Godot run'). Minor gap: it doesn't explain res:// path semantics for scene, but the schema covers that.

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 ('Run Godot 4.7 headless on the project') and enumerates exactly what that entails: import, load/instantiate every script and scene, optionally run a scene for N frames, return printed output. An agent can distinguish it from godot_review, godot_play and godot_test purely from the description.

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?

Explicit when-to-use and when-not: 'review first' with godot_review, use godot_play to drive input and watch values, use godot_test for unit tests. Also flags the prerequisite ('needs Godot on this machine') and relative cost ('slower than godot_review'). Nothing is left to inference.

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, closed-world), and the description reinforces this with 'Read-only'. It adds genuinely new context the annotations cannot carry: the output format, the category grouping, the per-line rule+fix shape, and the premium-profile variation that adds id and severity.

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 tight paragraph that front-loads what is returned, then when to read it, then the sibling redirect, then the read-only note. Every sentence adds distinct information with 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 no parameters, no output schema, and simple annotations, the description fills exactly the gaps that matter: the return format, the category grouping, the premium-profile difference, and the boundary against godot_review. An agent can select and call it correctly from this text alone.

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?

The tool takes zero parameters, so the baseline is 4. The description correctly describes no inputs and instead spends its words on output shape, which is the only semantic a caller needs here.

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 ('List the fixed AAA checklist that godot_review applies') and immediately characterizes the payload (plain text grouped by category, one line per rule with its fix). It is unambiguous against the sibling godot_review, which it explicitly names as the tool that checks a project.

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 two concrete use cases ('before writing code to know the rules', 'look up a rule id from a finding') and an explicit exclusion plus redirect ('It does not look at the project; to check the project against these rules, use godot_review'). Nothing is left to inference.

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 annotations: wrong hides the finding in later reviews on this machine, right counts it as confirmed, and both teach the local learning system. It also discloses the local-file write scope, reset behavior, return format, and error conditions, which is strong transparency for a non-read-only mutation 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?

The description is dense but front-loaded and free of filler. Each sentence carries useful information: purpose, parameter meaning, side effects, usage conditions, reset behavior, and return/error behavior.

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 mutation tool with no output schema, the description covers everything an agent needs: what it does, when to use it, what each verdict changes, where data is written, how to undo it, and what the response or error looks like.

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?

Although schema coverage is only 50%, the description fully explains both parameters. It clarifies that `finding` is the exact line as godot_review printed it, and it explains what each `verdict` value does, adding meaning well beyond the enum and schema example.

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 action, resource, and effect: tell Godotwright that a godot_review finding was wrong or right. It explicitly names the related sibling godot_review and distinguishes the feedback role from code-checking siblings like godot_api and godot_check.

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 guidance: only after checking the code with godot_api or godot_check, and fix real findings instead of marking them. It also explains the consequences of each verdict, which routes the agent correctly between marking wrong versus right.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is largely carried by structured data. The description still adds real value on top: the no-write report-only default, the idempotency guarantee ('running it twice changes nothing more'), and the explicit list of what it deliberately leaves for manual fixes. It stops short of describing output shape or failure behavior, so this is solid but not exceptional given the annotation coverage.

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 and front-loaded: the mechanical-rewrite scope comes first, then behavior, then scope limits, then usage ordering. Every sentence carries information, though the run is long and several clauses could be tightened into a list without losing 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?

No output schema exists, and the description compensates fully: it says the tool reports changes, lists what still needs a hand (setget, move_and_slide arguments, rpc keywords, unknown export hints), and explains how `detail` shapes the report. Nothing an agent needs to invoke it correctly 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 baseline is 3. The description adds genuine meaning beyond the schema: 'write: true' rewrites scripts while omission only reports, `files` narrows to res:// scripts, and `detail` brief caps at 12 changes per file versus full showing everything.

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 (rewrite/migrate) and resource (Godot 3 GDScript to Godot 4), then enumerates the exact constructs handled and explicitly excludes strings, comments, node paths, scenes and project settings. An agent can tell it apart from godot_review, godot_rename, or Godot's own --convert-3to4 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 explicit ordering guidance: use it before fixing Godot 3 findings from godot_review one by one, and run godot_review afterwards. It also names the alternative for out-of-scope work (--convert-3to4 handles scenes and project settings) and states the dry-run default versus write:true.

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 safety is covered. The description adds genuinely new behavior: it returns plain text, targets small models, is fuzzy-tolerant ('typos and plurals work', English or Dutch), and covers both identify and spec in one call. No contradiction with 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?

The content inventory is front-loaded and the fallback routing comes after, which is the right order. The enumeration of eight briefing sections is dense but each item tells the agent what to expect; it is one long sentence-heavy block but with 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 no output schema, the description correctly explains that the return is plain text and inventories what that text contains, so an agent knows what to do with the result. Input tolerance and sibling routing are also covered; nothing needed to call it correctly 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 the schema example already illustrates the single `text` parameter, so the baseline is 3. The description goes beyond it by stating the parameter accepts a name or short description, that typos and plurals still resolve, and that Dutch is accepted — information absent 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?

The description states exactly what the tool returns — a one-page pre-build briefing — and enumerates its contents (what the thing is, ready-made starting kind with build command, node names, typical size, rules, common mistakes, tool order, spec cheat sheet). It explicitly distinguishes itself from godot_model_identify and godot_model_spec, so an agent can pick it 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?

It gives both sides of the decision: use this when you just want to start, and call godot_model_identify / godot_model_spec instead when you need every detail (all variants and sizes, or the full spec). The alternative and the condition that selects it are named explicitly.

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 genuinely non-obvious behavior beyond the destructive/idempotent annotations: `out` is replaced if it exists, builds are byte-stable, heightmap collision writes extra .tres/.tscn files, and an error result still leaves the file on disk. The one gap is that it doesn't say what specifically the lint errors imply for downstream use, but the critical surprise (file written on error) is disclosed.

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 action and tightly packed with useful constraints. Some parenthetical asides ('nobody remembers to add it by hand') and the run-on sentence about returns and error results add length without adding information, but nothing is redundant with the schema.

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 must describe return values — it does (size, triangle and node count, then the lint report, with `detail` controlling verbosity). For a destructive, multi-input build tool, the description covers inputs, outputs, side effects, and escalation paths.

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; the description earns extra by explaining the mutual-exclusivity of `kind`/`spec`/`spec_file` (not expressed in the schema, which only requires `out`) and by giving the purpose of `collision` and `contract_out` rather than restating their descriptions.

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?

Opens with a specific verb+resource (build a .glb from a kind or spec) plus the three side effects: write to `out`, lint it, optionally write a contract. It also explicitly carves out its boundaries against siblings, pointing to godot_model_lint for .glb files built elsewhere.

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 concrete routing rules: call godot_model_identify first, godot_model_spec for the format, godot_model_lint for files not built here. It also states the input alternatives (kind + optional params, or spec, or spec_file) so the agent knows which path to take.

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, closed-world, so safety is covered; the description redundantly says 'Read-only' but adds genuine behavior: ambiguous words are reported as ambiguous, unknown things return the nearest family marked generic, and input tolerates English/Dutch plurals, typos and compounds. It does not describe output shape or latency, keeping it short of a 5.

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 action and the returned content, then the alternative routing, then input flexibility. It is a long dense sentence-chain, but nearly every clause carries routing or behavioral information; only the trailing 'Read-only' is wasted given annotations.

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, so the description carries the return-value burden, and it does: family, required parts with movement/axis/pivot, size range with source and confidence class, variants, conventions, pitfalls. With one fully documented parameter and clear sibling routing, an agent has everything needed to call and interpret it.

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 schema description already gives examples ('a tractor', 'helikopter'), so the baseline is met by the schema. The description adds value by clarifying accepted input forms (English or Dutch, plurals, typos, compound words, or a freeform description like 'something with wheels and an engine'), which the schema does not.

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 ('say what a thing is') and enumerates exactly what it returns: family, parts, movement axes, pivots, size range with source and confidence, variants, Godot conventions. It explicitly distinguishes itself from godot_model_lint and godot_model_brief, so the agent can route without opening sibling 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?

Explicit when-to-use ('before you build or check a 3D model', for full facts) and names alternatives with the condition that selects them: godot_model_lint for the archetype name, godot_model_brief for a short page naming the ready-made kind and spec format. Nothing is left to inference.

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 readOnlyHint/idempotent/destructive=false, so the 'Read-only' line is redundant, but the description adds real behavioral detail: what `detail` changes at output level (first 40 nodes vs every node, plus materials and textures) and what estimates are produced. It doesn't describe pagination or output shape, which is a minor gap.

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: what it returns, then the detail modes, then use cases, then alternatives. Slight redundancy with 'Read-only' repeating the annotation and a run-on inventory sentence, but 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 no output schema, the description carries the return-value burden and does so by naming every reported field and how detail level affects them. For a 2-parameter read-only inspection tool, an agent has everything needed to call it and interpret results.

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 enum is already documented, but the description adds concrete meaning beyond it — the 40-node cap for `brief` and the fact that `full` also emits materials and textures. The default (full) is only in the schema, so it's slightly 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 ('Show what is in a .glb or .gltf') and enumerates the exact outputs: file size, triangles, nodes, materials, textures with memory estimate, bounds in metres, lowest point, and per-mesh node tree. It is unmistakably distinct from siblings like godot_model_view or godot_model_lint.

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 concrete triggering scenarios ('check a triangle budget or why a model floats') and explicitly routes to alternatives: godot_model_view for shape, godot_model_lint for problems. The when-to-use and when-not-to-use are both covered.

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 adds real value: it describes the return shape (overall score, per-category scores, findings), the brief vs full detail behavior, and the fact that an error result is returned when errors exist. The only redundancy is restating 'Read-only', which duplicates readOnlyHint=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-loaded with the core action and scope, and every clause carries information. It is dense — long comma-separated enumerations and a packed final routing sentence — but nothing is genuinely wasteful.

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 5-parameter read-only lint tool with no output schema, the description supplies the missing pieces: what is checked, what the optional parameters unlock, what is returned, how detail affects output volume, and when errors surface. An agent can call this correctly without opening any other tool.

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 goes further by explaining what archetype actually checks (required parts, pivots, wheel axes, size/unit mistakes, direction) and that archetype accepts a name or an id. That is meaning beyond the schema's bare 'what the model should be, e.g. car, helikopter'.

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 ('Score a .glb or .gltf') and immediately enumerates what is inspected: flipped faces, open edges, normals, UVs, tangents, textures, node names, budgets. It also differentiates itself from siblings by naming godot_model_build, godot_model_view and godot_model_inspect in the same breath.

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 routing: build already lints what it builds, use godot_model_view for shape and godot_model_inspect for raw contents. It also states the conditions for the optional parameters (archetype to check it is what it should be, contract to hold it to model.contract.json, max_triangles to flag a heavy model).

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 read-only, idempotent, closed-world behavior, so the safety profile is covered. The description adds substantive context beyond that: it discloses the exact return format (rules, a small-car JSON example, one line per kind with defaults), which is valuable since there is no output schema. No contradiction with 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?

Three compact sentences, front-loaded with the core purpose, then return shape, then usage routing and alternatives. Every sentence carries distinct value with 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?

For a zero-parameter, read-only educational tool with no output schema, the description covers purpose, output content, when to call it, when to skip it, and the lighter sibling alternative. Nothing an agent needs to select or use it correctly 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?

The tool takes zero parameters, so the baseline is 4. The description does clarify that the output documents each ready-made kind's parameters and defaults, which helps an agent understand what spec/param information it will get, though there are no tool arguments to explain.

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 — 'Explain the model spec' — and defines what the spec is: 'a JSON tree of named parts that godot_model_build turns into a .glb.' This distinguishes it from godot_model_build (the consumer) and godot_model_brief (the shorter cheat sheet) without requiring 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 explicit when-to-use ('Read it before you write a `spec` or pass `params` to godot_model_build') and when-to-skip ('skip it when a ready-made `kind` with its defaults is enough'). It also names the lighter alternative sibling, godot_model_brief, leaving nothing to inference.

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 adds substantial behavior beyond the annotations: it discloses that no Godot install or image is needed, what the output contains (per-part letters, sizes, heights, floating/detached-part detection), and restates "Read-only" consistently with readOnlyHint=true. It slightly repeats what the annotations already declare rather than adding new safety/permission context, which keeps it off a 5.

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 first clause front-loads the core purpose and the output description follows; nearly every sentence earns its place, including the routing sentence. It is dense and slightly run-on with the parenthetical examples ("a ladder away from its tree"), which costs a point but not readability.

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 compensates by describing the returned content in detail (three views, parts list with sizes and heights, detached-part detection). For a read-only, 3-parameter inspection tool it gives an agent everything needed to call it and interpret the result.

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 file, only, and width are already documented with types, enum, bounds and default. The description's "`only` shows one of the views; `width` sets the characters per view (default 48)" essentially mirrors the schema wording, so baseline 3 applies — it does not add format or edge-case semantics the schema lacks.

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: viewing a .glb/.gltf file without Godot or an image, rendered as three letter-drawn views plus a parts list. It fully describes the output shape and explicitly distinguishes itself from godot_screenshot, godot_model_inspect and godot_model_lint by naming what each of those does instead.

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 triggering condition ("Use it after building to check the shape, proportions and that everything is attached") and routes three alternatives with their distinguishing conditions — rendered picture vs. triangles/materials/textures vs. problem reporting. Nothing about when to pick this tool is left to inference.

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 context beyond the annotations: input is seen on exactly the given physics frame, runs are deterministic, an error result means the run did not finish or Godot reported an error, while an unknown action only warns. It also explains why readOnlyHint=false is safe here — the project is unmodified and the temporary script in .godot/godotwright/ is removed afterwards.

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 action and return value, then parameters, then use cases, then sibling routing — a sensible progression. It is dense but nearly every sentence carries information; a slightly tighter split into shorter sentences would help scanning.

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 multi-parameter simulation tool with no output schema, the description covers the return value (per-frame table plus errors and prints), failure semantics, determinism, and side effects on disk. An agent has everything needed to call it and interpret results.

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 already 100%, but the description still adds meaning: the `input` timeline grammars are (frame, verb press/release/tap/hold with count, action or event like Key:Space), `watch` entries are node path + dot + property or method call, and `every` controls sampling cadence. Useful reinforcement rather than pure repetition.

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 concrete verb-resource pair: run a res:// scene headless in Godot 4.7 for N physics frames, inject input on specific frames, and sample watched values per frame. It is clearly distinguishable from godot_test (in-project assertions) and godot_check (load errors), which it names explicitly.

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 concrete when-to-use cases (verify the player jumps, moves, takes damage, a timer fires — without a screen) and explicit alternatives with the selection condition: godot_test for assertions kept in the project, godot_check for load errors. Nothing is left to inference about 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 (destructiveHint=true, idempotentHint=false): it discloses the dry-run default, that only the lines of that entry change, that refusals and missing fields return an error and write nothing, and that with write it reports review errors before and after with an error result if errors increase. This is exactly the mutation-safety context annotations alone cannot convey.

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 safety model and the tool's scope before the dense op/field enumeration. Every sentence carries information, though the middle section is a long run-on that would read better as a list.

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 11-parameter destructive mutation with no output schema, the description covers what is returned in both modes (diff, warnings, before/after review errors), what happens on failure, and the validation rules for every op. Nothing an agent needs to call it safely 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 the op-to-field dependency mapping (set/key+value, input_add/action+events+deadzone, autoload_add/name+file+global) that the schema only implies, plus event string syntax with concrete examples. It does not restate path/write defaults, which the schema already covers.

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 (edit project.godot: settings, input map, autoloads) and immediately names the boundaries against siblings godot_scene_edit and godot_rename. An agent can distinguish this from every other godot_* tool 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?

Explicitly says to use it instead of hand-editing project.godot because the input map format is easy to break, and routes .tscn work to godot_scene_edit and renaming to godot_rename. The dry-run-first workflow ('without write it changes nothing and returns the diff') is also spelled out as 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?

Goes well beyond the annotations: default is a no-op dry run returning the exact lines that would change and what could not change; write:true applies and reports review errors before and after, erroring when post-count exceeds pre-count; it refuses when the new name is taken. This is consistent with destructiveHint=true and readOnlyHint=false (the danger only materializes under write: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?

Dense but front-loaded: the rename surface comes first, then the file-move mode, then dry-run/write behavior, then the safety refusal and sibling routing. Individual sentences are long and clause-heavy, but nothing 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?

With no output schema, the description carries the return-value burden and does so fully: exact changed lines, unchangeable locations, and before/after review errors. For a destructive, non-idempotent rewrite tool, an agent has everything needed to call it safely.

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 a real constraint the schema does not express: 'from and to are both names or both res:// paths,' and it clarifies write's semantics (default false = plan only). Path's project-root resolution is left 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 (rename) plus the full resource surface (functions, signals, variables, class_name, autoloads, input actions, groups, node names) and a second mode (moving a res:// file with .uid/.import and references). This is enough for an agent to distinguish it from godot_project_edit and godot_scene_edit 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?

Explicitly routes the agent: 'Call godot_usages first to see what it will touch' and 'For a setting value, an input event or a node property, use godot_project_edit or godot_scene_edit instead.' Both the when and the when-not-with-alternative are named.

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 readOnlyHint=false/destructiveHint=false; the description goes further, disclosing that it never mutates code but does persist side effects — the last review in .godot/godotwright/ and rule-hit counts in a local learning file. That is exactly the kind of state-change detail annotations cannot convey.

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?

Purpose and output shape are front-loaded and nearly every clause carries information (side effects, output format, sibling routing). It is dense to the point of being run-on and slightly harder to scan than it needs to be.

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 takes on the return-format burden and delivers: a 0-100 score per category plus the exact `res://file.gd:12: error [rule] message` line format. For a six-parameter, stateful review tool, an agent has everything needed to call it 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%, so baseline is 3, but the description adds usage-level meaning the schema lacks: `files` targets changed files, `code`+`file` reviews unsaved GDScript, `only_new` collapses already-seen findings and reports a fixed count, and `detail: full` inlines fixes. Only `path` is left 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 — 'Static AAA review of the project, no Godot needed' — and enumerates exactly what it checks (API correctness, performance, quality, structure). It explicitly distinguishes itself from siblings: godot_check handles 'errors only the engine finds' and godot_checklist 'lists every rule.'

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 concrete when-to-use modes: pass `files` for changed files, `code` + `file` to review GDScript before writing to disk, `only_new: true` during a fix loop. It also names the complementary alternative (godot_check) and when to escalate to it.

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 the description reinforces that with the higher-value fact that no Godot process is required ('without running Godot') and that it errors when no project.godot exists at or above `path` — a failure mode the annotations cannot express. It stops short of describing output shape or cost/scale for large projects, which is the remaining gap.

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 purpose, then when-to-use, then sibling routing, then the `detail` tradeoff, then safety and the error case. Four dense sentences with no filler — every clause carries decision-relevant 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?

No output schema exists, so the description carries the return-value burden itself — and it does, enumerating the mapped artifacts and what each detail level emits. Combined with the error condition and read-only guarantee, an agent has everything needed to call it correctly on a two-parameter tool.

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; the description earns extra by spelling out what `detail` actually changes ('brief gives one line per scene and script; full adds node trees with line numbers, signal connections, input events and settings'), which is more concrete than the schema's 'short output with capped lists'. It also implicitly clarifies `path` behavior via the 'at or above `path`' walk-up reference, though that detail is mostly carried by 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+resource ('Map a Godot 4 project from its files') and enumerates exactly what is extracted: scenes with node trees, scripts with class_name/signals/functions/exports, autoloads, input actions, settings, broken references. It also carves out the sibling territory explicitly ('For one name use godot_usages; for engine classes use godot_api'), so an agent can distinguish it from godot_usages and godot_api 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 explicit timing ('Call this first in a project, and again after large changes') plus named alternatives and the condition that selects each. Nothing about when to prefer a sibling is left to inference.

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?

Beyond the destructiveHint/readOnlyHint annotations, the description discloses that writes are opt-in via `write`, that dry-run returns diff plus warnings, that validation occurs against Godot 4.7 (signal existence, method arity, script base-type refusal), that only the lines of the change are touched, and that refused/incomplete changes write nothing. This is exactly the mutation context an agent needs and it is 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-loaded with purpose and the destructive/alternative routing, and every clause carries information (validation rules, write semantics, op-field mapping). It is a dense single paragraph, though quite long for one breath; a small structural break would aid scanning without losing 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?

For a 15-parameter mutating tool with no output schema, it covers the essentials: dry-run vs write, return of diff and warnings, before/after review errors, and no-write-on-error behavior. Minor gaps remain, such as whether a preview diff is stable enough to approve blindly or how concurrent edits are handled, but nothing required to call it correctly 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 baseline is 3, but the description adds cross-field semantics the schema cannot express per-property: which fields each `op` requires (add_node needs parent/name plus type or instance, etc.) and the node-path convention ('relative to the scene root, which is "."'). Value formats (enums by name, res:// resources) partially duplicate the schema's `value` description, keeping it below 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?

Opens with a specific verb+resource ('Change a .tscn safely, without the editor') and then enumerates the six concrete mutations supported. It explicitly names the sibling tools it is not (godot_project_edit, godot_rename), so an agent can route correctly 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?

States explicit when-to-use ('Use it instead of editing .tscn files by hand'), when-not ('For project.godot use godot_project_edit; to rename a node everywhere, use godot_rename'), and the dry-run vs write decision rule ('Without `write` it changes nothing... with `write: true` it writes'). Nothing is left to inference.

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 past the annotations by disclosing the renderer (Godot 4.7 Compatibility, software OpenGL), the xvfb-run fallback on headless Linux, the exact output paths written (.godot/godotwright/screenshot.png, or car.png beside car.glb), and the fact that a coverage-metadata text accompanies the image so empty or off-screen renders are detectable. The filesystem write is consistent with readOnlyHint=false, and the idempotent/non-destructive profile is implicitly supported by the deterministic per-view semantics.

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 and front-loaded — capability, then inputs, then output behaviour, then alternatives. A few sentences are fragments ("An error result when Godot is missing or the scene cannot run.") and the output-path sentence is slightly buried, but essentially no padding.

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 still explains both return components (the PNG and the coverage text) and where the file lands, plus failure mode. For a 7-parameter tool with zero required params, that is enough for an agent to call it correctly on the first attempt.

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: width/height are per-view (matters when several views grid up), frames is for letting the scene settle, and multiple views compose a grid. It doesn't define the view directions in param terms beyond 'front (from +Z, where models face)', which is still useful orientation context.

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 gives a specific verb and resource — render a scene or .glb/.gltf model to a PNG — plus the engine and renderer used. It clearly separates the two input modes (scene vs. model) and is distinguishable from siblings like godot_model_view and godot_play.

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?

Explicitly states the primary use ("Use it to look at what you built") and names two alternatives with the conditions that select them: godot_model_view when Godot is unavailable, godot_play when behaviour rather than looks matters. Both when-to-use and when-not-to-use are covered.

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 prerequisites (Godot installed, addons/gut or addons/gdUnit4 present), the error-result contract (error when a test fails or a dependency is missing), and the on-disk side effects (test files untouched, reports written to a temp folder or .godot/godotwright/). That last point usefully explains why readOnlyHint is false despite the tool being non-destructive and idempotent.

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 purpose and return shape, then prerequisites, then parameters, then alternatives — a sensible ordering with no filler sentences. It is a dense single paragraph with heavy backtick usage, which makes it slightly harder to skim than a short bulleted split would be.

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, so the description carries the return-value burden, and it does: totals, failing tests with locations and messages, plus script errors from the run. Combined with prerequisites, failure semantics, and side effects, an agent has everything needed to decide and invoke 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 already 100%, so the baseline is 3; the description adds real meaning on top by explaining resolution order for `framework` (picked explicitly when both are installed), the defaulting cascade for `dirs` (framework config, else res://test and res://tests), and that `filter` is GUT-only. It does not touch `path` or `timeout_seconds`, but the schema handles those adequately.

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 (run the project's GUT/GdUnit4 tests in Godot headless) and pins down return content (totals plus failing tests with res://file:line and messages). It also explicitly distinguishes itself from godot_play and godot_check by naming when each of those is the right tool instead.

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?

"Use it after a change to see whether the tests still pass" gives the trigger, and the final sentence names two alternatives with their selecting conditions (godot_play for trying input without writing tests, godot_check for load errors only). "Use when both frameworks are installed" for `framework` resolves the one common ambiguity.

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 read-only/idempotent/non-destructive, but the description adds substantial context beyond them: works offline without the editor, skips comments, searches specific lookup contexts (connect, emit_signal, get_node, load), and warns that very common names are capped. It even describes the return layout, which is valuable since no output schema exists.

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 action and scope, then the routing guidance, then the return format. It is a dense paragraph with multiple clauses, but each sentence carries actionable information; only the trailing 'Read-only.' is redundant with the annotations.

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 (definition location, then per-file line number, use kind, line text) and the capping caveat. Combined with the scope and alternative routing, an agent has everything needed to invoke and interpret results.

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 both parameters are documented and the baseline is 3. The description nonetheless adds semantic breadth by clarifying what 'name' can be (class_name, autoload, uid://, input action), helping an agent choose the right query form beyond the schema's examples.

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 ('find every place a name is used') and enumerates the exact resource domains covered (function, signal, class_name, autoload, input action, res:// path, uid://). It also explicitly distinguishes itself from godot_rename and godot_api, so an agent can route correctly 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 a concrete when-to-use trigger ('Call it before you rename, move or delete anything') and names the alternatives with their selecting conditions: godot_rename for making the change, godot_api for engine API names. Nothing is left to inference.

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