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?

Beyond the simple 'Read-only' annotation, the description details the immense scope of the analysis, including textures, import settings, and how file paths are constructed. This specific technical detail is a rich disclosure of behavioral capabilities.

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?

Although long, every sentence is packed with technical, high-density information and is logically structured from overall function down to specific operational details.

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?

Given the complexity of Godot's internal dependency graph, the description is extremely complete, covering scope, implementation logic, and the exact data returned by each operational query.

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?

With 100% schema coverage, the description adds maximum value by defining the semantic meaning of each enum value for the 'op' parameter. It explains exactly what result the AI should expect for 'why' versus 'of'.

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 immediately establishes the tool's high-level purpose: treating project files as a dependency graph. It clearly outlines the four distinct operations (unused, why, of, cycles) available under this tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The tool provides specific guidelines by defining the use case for each operation (e.g., when to look for an unused file vs. when to trace a load chain). The broad scope mentioned ('from project.godot' to 'godotwright.json') also provides clear boundaries for usage.

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 cover the safety profile (read-only, idempotent, non-destructive), and the description adds substantially beyond that: Godot execution is conditional on installation, duplicate findings are collapsed by cause ('twenty findings from one missing file are one problem'), output is severity-ordered with Godot errors before review errors, and it ends with numbered next steps. The only redundancy is the phrase 'Read-only', which merely restates readOnlyHint.

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 decision cue before any mechanics, and every clause carries information (grouping, ordering, per-finding payload, automation handoff). It is a long run-on sentence with nested parentheticals that slightly slows parsing, 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?

With no output schema, the description carries the burden of explaining returns, and it does: grouped findings, urgency ordering, and the four fields each finding carries. What it leaves unclear is how `limit` (problems shown in full) and `detail` (brief vs full) interact with the grouping, so an agent cannot predict truncation behavior.

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 an extra point by giving `symptom` real meaning beyond the schema's 'what you see going wrong, in plain words' — it explains that the value is matched against lessons, with a concrete example ('helicopter bounces on the moving deck'). The remaining parameters (path, files, godot, limit, detail) are 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 — runs the review, optionally loads every script and scene with Godot, groups findings by cause, orders them by urgency, and attaches place/lesson/fix/automation per finding. It explicitly distinguishes itself from godot_review (full list) and godot_check (raw Godot output), so an agent can pick it 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?

Opens with two concrete triggering conditions: a project you do not know yet, or something broken with no obvious starting point. Closes by naming the two alternatives and the condition that selects each, 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?

Annotations already cover read-only, idempotent and non-destructive, yet the description adds substantive domain behavior: no export is performed, Godot silently drops excluded files even when preloaded (so the build fails), plain data files must be named in include_filter while JSON and imported CSV are safe, and run-time built paths under excluded folders are flagged. It also discloses the export-template check. This is information an agent could not get from the 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 core action and the critical caveat ('without exporting') are front-loaded, then details follow. The long middle enumeration of file types and failure modes is dense but each item maps to a concrete warning the agent would otherwise miss. There is mild repetition in restating 'Read-only'.

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 burden of telling the agent what comes back, and it does so by enumerating the finding categories (excluded-but-loaded files, unexported plain data files, run-time paths, missing export templates). What it omits is the result shape (list of issues? per-preset summary? severity?) and whether defaults include all presets when 'preset' is omitted.

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; the description only restates that 'preset' limits the run to one preset by name or number. The 'path' parameter (project folder, walk-up to project.godot) is not mentioned in the description at all. Baseline 3 applies when the schema carries the parameter detail.

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 opens with a specific verb and resource: 'Compare the export presets (export_presets.cfg) with what the scripts and scenes load, without exporting.' That is far more precise than a tautology and an agent can immediately tell it is an export-readiness audit. It never names the adjacent siblings (godot_check, godot_doctor, godot_review), so the differentiation from generic check tools is inferred rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The final sentence gives explicit timing guidance: 'Run it before an export and after changing what the game loads.' That is a clear usage context with a concrete trigger. There are no stated exclusions or named alternatives for when a different tool would be better.

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 context beyond the annotations, including the local-only write scope, the downstream effects of each verdict, ranking/hiding behavior, reset semantics, and the exact return/error conditions. It aligns with the annotations: it is a non-read-only local write, not an open-world or destructive project operation.

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 well-structured: purpose first, then parameter exclusivity, behavioral effects, usage restriction, side effects, and return/error behavior. Every sentence adds operational value for a tool with nuanced verdict semantics.

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 the return value as a one-line confirmation and lists the key error cases. Combined with its side-effect and usage guidance, an agent has everything needed to invoke 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?

It explains the semantics of all three parameters far beyond the schema: `finding` must be the exact line printed by godot_review, `lesson` is a lesson id, and `verdict` has different meanings for findings versus lessons. The schema has only 67% description coverage, so this param-level detail is especially valuable.

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 precise verb and resource: telling Godotwright that a godot_review finding was wrong/right or whether a godot_lessons lesson helped. It clearly distinguishes this feedback action from sibling tools like godot_review, godot_lessons, 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?

It gives explicit usage conditions: use only after checking the code with godot_api or godot_check, fix real findings instead of marking them wrong, and pass either `finding` or `lesson` but not both. These are clear when-to-use and when-not-to-use rules tied to concrete 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 only say destructive and non-idempotent; the description supplies the nuance an agent needs: fixes touch only the flagged line and only when it matches expectations, safe fixes are purely subtractive while `check` fixes can convert callers into coroutines or introduce guessed types, writes trigger a re-review, and unfixable lines are reported with reasons. No annotation contradiction — destructiveHint=true is consistent with a write-capable fixer.

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 action, and every clause carries information, but it is one long run-on paragraph with dense parentheticals enumerating rule semantics. Grouping the safe/check catalog into a shorter form would improve scanability 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 write-capable tool with no output schema, the description covers mode selection, preconditions, side effects, post-write behavior, and what the response reports (applied vs remaining vs unfixable with reasons). Nothing essential to 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 baseline is 3; the description earns extra credit by explaining what `write`, `include_check`, and `rules` actually mean in terms of fix categories (safe vs check) and that non-listed rules are out of scope. It stops short of describing `detail` or `files`/`path` resolution, which stay schema-only.

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 ("Apply the mechanical fixes for review findings") and immediately distinguishes itself from manual editing and from the sibling review/check tools. The enumerated rule IDs and the safe/check taxonomy pin down scope precisely.

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 workflow: "Run godot_review first to see the findings, and godot_check after writing." It also states the default gating behavior (dry-run without `write`, safe-only unless `include_check: true`), so the agent knows exactly which mode to choose.

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 behavioral detail beyond the annotations: time advances only on step, answers end with printed errors and warnings, reload preserves node values and leaves non-compiling scripts unchanged, and runtime errors include call chains. These are exactly the operational traits an agent needs for a stateful live-game 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 and long, but the length is justified by twelve operations and twenty-one parameters. It front-loads the core purpose and keeps detail focused, though a bulleted op list would improve scanability.

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 live-game inspector and driver with no output schema, the description covers operation semantics, defaults, determinism, error reporting, and reload behavior. It is complete enough for an agent to know what the tool can do and how to invoke 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%, so the parameter schema already carries most semantics. The description still adds useful op-level meaning, including examples for watch/until/input/sizes and mappings from each operation to its relevant parameters.

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 gives a precise verb-and-resource purpose: inspect and drive the running game started by godot_session. It enumerates all supported operations, making clear this is a multiplexed live-game control tool rather than a session launcher or playback tool.

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 provides clear usage context: try a fix live, reach hard-to-reach states, or watch a long scenario in parts. It also distinguishes itself from godot_session and godot_play, though it does not explicitly state when not to use 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 only declare non-read-only, idempotent, non-destructive, closed-world; the description adds substantially more: redaction of names/paths/links/emails/keys/source before storage, refusal for name-heavy lessons, dedup-by-title behavior, local-only storage never sent anywhere, and the error conditions (refused, learning off). This is behavior an agent cannot infer from the 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?

Front-loaded with the core action and the payoff, with no filler sentences. It is a dense single block covering purpose, field guidance, privacy, dedup, side effects and return values — all relevant, though splitting privacy/return details would aid 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?

With nine parameters and no output schema, the description covers what is returned ('the stored lesson and what was replaced'), the failure modes, the privacy transformation, and the upsert rule. An agent has everything needed to call it correctly 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 the baseline is 3, but the description adds guidance the schema lacks: write in general words, title is one line, fix is what to do instead, and `error` should be 'the Godot message as printed, kept as a template'. It also states which fields are optional and worth filling 'when you can'.

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 — keep/store a lesson learned in this project — and distinguishes itself from godot_lessons (which shows lessons) and godot_check. The upsert semantics ('same title again updates that lesson') further sharpen what the call does.

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 when to use it ('Add one whenever a fix took more than one try') and when not to ('not for what a review rule already reports'), and names the sibling tools whose output it feeds (godot_check, godot_lessons).

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?

With readOnlyHint=false the side effect would otherwise look contradictory to a lookup tool, but the description explicitly explains it: 'It counts which lessons were shown in the local learning file (GODOTWRIGHT_LEARN=0 turns that off).' It also discloses the return format (plain text, locally-learned lessons marked) and what detail levels yield. Lacks limits/pagination nuance, but the key non-obvious side effect is covered.

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 usage, and most sentences carry weight. However it re-enumerates all twelve topic enum values verbatim from the schema and packs multiple modes into long run-on sentences, which adds length without new 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?

Seven optional parameters and no output schema, yet the description explains the four lookup modes, the list fallback, the gaps mode, the detail levels, and the return type. An agent can call it correctly without guessing; only the interaction between limit and detail is left implicit.

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 3 is the baseline, but the description genuinely adds semantics: query accepts free words like 'helicopter slides off moving ship' or a lesson id, error must be 'a Godot message exactly as printed', gaps:true switches the whole result set to unlearned errors, and no parameter at all means list mode. That mapping of modes to parameters goes beyond 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: 'Answer from lessons learned in real Godot 4 projects and on this machine', with the shape of an answer (what went wrong, why in Godot terms, the fix, how to test it). This is clearly distinct from sibling godot_lesson_add (which writes lessons) and from godot_fix/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 concrete triggers: 'Use it when Godot shows an error you do not understand, and before you build moving platforms, vehicles, ships, large worlds, runtime-loaded models, shaders or headless tests.' It also closes the loop by naming godot_feedback as the follow-up. It does not explicitly say when to reach for godot_fix or godot_check instead, so the routing is not fully exhaustive.

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?

Exceeds the annotations usefully: 'out is replaced if it exists' explains the destructiveHint, 'same bytes every time' explains idempotency, and it discloses the Godot-import side effect of `collision` plus a `contract_out` artifact for future lint runs. It also says what is returned (size, triangle/node counts, then lint report) and that the file is still written even when the result is an error, which is exactly the kind of nuance an annotation cannot carry.

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 output artifact, and nearly every clause carries information (determinism, collision imports, contract file, error-on-lint behavior). It is dense, with several multi-clause sentences and parenthetical asides, so it reads heavier than it needs to, but there is little outright 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 9-parameter, nested-object tool with no output schema, the description still covers the input modes, the side artifacts, the Godot import consequences, the return payload, and the error-but-file-written case. Nothing an agent needs in order 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 the baseline is 3, but the description adds real meaning on top: it explains the kind/params vs spec/spec_file alternatives, that `contract_out` writes a model.contract.json that godot_model_lint can later hold versions to, and that `detail=full` lists every finding with its fix. Minor gap: it does not mention the `textures` parameter at all.

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: build a .glb from a `kind` or a `spec`, write it to `out`, and lint it, with concrete output properties (UVs, tangents, one node per part, deterministic bytes). It also names the sibling that covers the overlapping case (godot_model_lint for a .glb not built here), so an agent can route between them 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?

Gives explicit preconditions ('Call godot_model_identify first and godot_model_spec for the format') and an explicit exclusion with the alternative to use instead ('To check a .glb you did not build here, use godot_model_lint'). It also spells out the input alternatives (kind+params, spec, spec_file), 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?

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?

Discloses a hard limitation (headless measures CPU-side scripts/physics/scene work, not GPU), where state is persisted (.godot/godotwright/perf/), and the precise failure condition (error when p95 exceeds budget or is >10% worse than last run) — all consistent with readOnlyHint=false, since baseline files are written. This goes well beyond what the annotations 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?

The core measurement scope is front-loaded and every sentence carries information, but the opening sentence is a long comma-spliced run-on that forces the reader to parse several distinct facts at once. Tightening it into shorter clauses would improve 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?

With no output schema, the description shoulders the full burden and does so — it describes the return payload (percentiles, per-frame deltas, node counts, named lessons) and error semantics. Combined with the annotation-declared write of baseline state, an agent has everything needed to invoke 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%, so the baseline is 3, but the description adds real meaning: `input` is clarified as a played timeline equivalent to godot_play, `budget_ms` is tied to the error threshold, and `baseline` persistence is explained. Remaining params (frames, warmup, timeout_seconds) are 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 (run + measure) and resource (a scene), and enumerates exactly what is measured: frame-time p50/p95/p99/max, physics step isolation, slowest-frame attribution, node/orphan counts, and delta vs the last run. It also distinguishes itself from the sibling godot_play by noting that `input` 'plays a timeline as godot_play does' and that godot_play is the tool for interactive 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?

Gives clear context for use: 'Measure before and after every performance change' and 'to measure while something happens' via the input timeline. It does not explicitly state when NOT to use it (e.g. use godot_test for correctness, godot_play for interactive runs), so exclusions 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?

Annotations say readOnlyHint=false, and the description explains exactly why: a temporary script is written under .godot/godotwright/ and removed afterwards, and the user's scenes and scripts are untouched. It further discloses determinism, frame-exact input timing, error-vs-warning semantics, and that expect failures turn the result into an error.

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 return shape are front-loaded, and nearly every clause carries information about a distinct parameter. It is one dense paragraph with heavy semicolon chaining, so a reader scanning for a specific knob has to parse the whole block; the table-vs-summary point is also made twice.

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 tool with no output schema, the description covers the return shape (per-frame table plus errors and prints, or a compact summary), failure modes, and the deterministic execution model. It also reassures the agent that running it does not mutate project files, which is the main risk when calling a headless runner.

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 still adds meaning beyond the schema by explaining the 'hold' verb's frame count, that every sets the sampling cadence, and that summary yields start/end/min/max/first-change per watched value. It does not fully specify watch-entry resolution rules (node path from scene root plus a property or method call is stated, but not scoping edge cases).

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 and resource: run a scene headless for N physics frames, inject inputs on given frames, and return watched values plus errors and prints. It immediately separates itself from godot_test (project-stored assertions) and godot_check (load errors), 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 an explicit use case ('check that the player jumps, moves, takes damage or that a timer fires, without a screen') and explicit exclusions with named alternatives: 'For assertions kept in the project use godot_test; for load errors use godot_check.' It also states when to prefer summary mode over a table.

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?

Beyond the annotations, the description discloses important behavior: the session persists between calls, is paused at frame 0, is reachable only via a loopback port with a token, does not modify the project, stores its script under .godot/godotwright/, and auto-quits after idle_minutes. These details materially affect how and when an agent should use the 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 front-loaded with the core purpose and then covers operation modes, sibling comparison, security, and cleanup. It is dense but every sentence carries useful information, with no obvious 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 complex lifecycle tool with no output schema, the description covers the important context: persistence, security, project isolation, idle shutdown, and operation modes. It does not describe what the `status` operation returns, which leaves a small gap for an agent invoking that op.

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 the schema already documents op, path, scene, restart, idle_minutes, and timeout_seconds. The description repeats defaults for scene, restart, and idle_minutes but adds little semantic detail beyond the schema, and it does not mention path or timeout_seconds at all.

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: load a Godot scene headless and keep the session running between calls, paused at frame 0. It explicitly distinguishes this from godot_play, which reloads the world on every call, so an agent can tell the two apart 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?

The description gives a clear use case: use this when godot_game needs a live game to inspect and step frame by frame, especially when loading is slow. It names godot_play as the reload-every-call alternative and says to stop the session when done, though it does not explicitly state when not to use 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?

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?

Goes well past the annotations: discloses the journal location and its 40-write cap, the conflict guard that stops an undo when a file changed afterward, and that `force` destroys those later changes. This is exactly the destructive-behavior context an agent needs beyond 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 the action and scope, then behavior, then when to use. Dense but each clause carries information; the nested parentheticals make it slightly run-on.

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 destructive multi-mode tool with no output schema, it covers what is restored, the retention limit, the safety guard, the override, and the inspection mode. Nothing needed 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 schema already documents all four parameters. The description restates steps default 1, list-only mode, and force overriding the conflict guard, which matches but does not meaningfully extend the schema text.

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 ('Undo what Godotwright wrote, newest first') and enumerates the covered write categories: scene/project edits, renames, migrations, fixes, model builds. No sibling tool performs undo, and the description makes the resource boundary unmistakable.

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 trigger ('Use it when a write made things worse') and names the alternative it replaces ('instead of repairing by hand'), plus the `list` mode for inspection before acting. It does not spell out when not to undo (e.g., after a conflict), though the force semantics imply 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 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.