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

Annotations already state readOnly/non-destructive/closed-world, and the description adds what they do not: PrintWindow can yield blank or stale GPU content, screen mode requires a foreground window, covered edges are cropped, interior overlaps with other apps are rejected, and the tool neither focuses windows nor sends input. These failure modes and the absence of side effects are exactly the context an agent needs to avoid trusting a bad capture.

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 dense sentences, each carrying distinct information, with the output promise front-loaded. It is tight, though the mode caveats pile up quickly and could be split for easier 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?

There is no output schema, and the description does state the return shape (inline PNG, original file, coordinate metadata) and the main trust caveats. What is missing is how to obtain a valid windowId and how the sizing parameters affect the result, which matters for a 4-parameter tool with 0% schema documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description has to carry the parameter burden, and it only partially does. It explains the two method values in behavioral terms, but it never covers maxWidth/maxHeight (defaults 1600x1200 with min/max bounds) or the windowId format (^\d+:\d+$). The phrase 'freshly discovered window' hints that windowId comes from a listing tool without saying so.

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 specific verb (capture) and resource (game/editor window) and states what comes back: an inline PNG plus original file and coordinate metadata. It reads differently from siblings such as list_editor_windows, focus_editor_window, and playtest_frames, but it never names those siblings or tells the agent how they relate.

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

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

It gives real guidance on choosing between the two modes: 'window mode uses PrintWindow; GPU content may be blank/stale', while 'screen mode requires foreground'. It also warns 'Inspect the image before assuming it is usable.' It leaves out when to prefer this tool over playtest_frames or other capture paths, but the within-tool mode choice is clear.

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, non-destructive, closed-world behavior, and the description adds useful context beyond that: data was read from the editor on a specific date and the records include domain-specific fields such as inItsHands and atMs. It does not cover errors, pagination, or rate limits, but it adds meaningful transparency for a catalog 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 purpose is front-loaded, but the description is a long, dense sequence of run-on sentences with parentheticals and Chinese terms. Much of the domain detail is useful, but the parameter behavior is buried rather than structured, making the definition harder to scan than necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does a substantial amount of work by naming returned fields and explaining the relationship to creature skills and animation timing. It is still somewhat ambiguous about the full output shape and the interaction between the two parameters, but it is largely complete for its use 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 0%, so the description must carry parameter meaning. It explains that omitting creature lists creatures and that query filters to creatures with matching animations, with useful examples like digging and attacks, but it never clearly states that the creature input is an integer creature id or how query behaves when creature is also supplied.

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 identifies the resource as the animations of complex creatures and states the returned fields (id, name, length, loops), plus the no-creature mode that lists creatures. It distinguishes the tool from the sibling that consumes animations (scene_add_creature_skill), though it never uses a crisp verb like 'list' and the phrase 'by creature' is slightly ambiguous.

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 explains the practical context: creature skills play these animations, and querying without a creature returns which creatures have known animations. It does not explicitly say when not to use it or name a competing catalog tool, but the intended discovery workflow is clear.

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, it discloses single-use capture IDs with a 120s expiry, that coordinates are in the returned preview image rather than the original PNG, that only ONE action is sent per call, the scroll sign convention, and foreground/rect/unobscured requirements. That is rich operational context an agent cannot infer elsewhere.

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 result, then constraints and coordinate system in dense, waste-free sentences. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter mutation tool with no output schema, the description covers the workflow, safety prerequisites, and return value well. It is still thin on failure behavior and the semantics of several input parameters.

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 0%, so the description must carry the load. It usefully explains x/y (preview pixels, not original PNG), delta sign, and captureId expiry, but leaves key chord syntax, text vs. literal Unicode handling, button, holdMs, clickCount and toX/toY for drag undocumented.

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 (send ONE click, key chord, text, scroll or drag) and resource (the window), and clarifies the one-action-per-call scope plus that it returns a new screenshot. No sibling tool provides input synthesis, so the distinction is unambiguous.

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 preconditions: a fresh captureId, target foreground, unchanged rect/title, unobscured click point, and verifying the fresh image. It implies the capture_editor_window workflow but does not explicitly name alternatives or 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: prerequisite game states (main world, Miliastra lobby, save list, editor), a blocking side effect ('takes over mouse and keyboard for about 80 seconds'), and an async job contract (runId + poll playtest_status, officialSave is the result). It doesn't clarify what the destructiveHint actually endangers — e.g. whether an existing save is ever overwritten — though 'as a new save' implicitly suggests it does not.

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 short sentences, front-loaded with the action and scope, then prerequisite, then cost, then return contract. Dense and purposeful; the parenthetical list of game states is slightly clunky but earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description supplies the return value (runId), the polling follow-up (playtest_status), and how to extract the useful artifact (officialSave). Combined with the prerequisite and blocking-duration notes, an agent has everything needed to invoke and drive 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 0%, so the single parameter mapPath is undocumented in the schema; the description only implies it is a path to a .gil file. It adds no detail on path form (absolute/relative), expected location, or failure behavior for an invalid path, so it only partially compensates for the coverage gap.

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 ('Import a .gil as a new save') plus the crucial scope qualifier 'leave it open in the editor, without playing it', which separates it from playtest_start. An agent can distinguish it from the many scene_* siblings 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 prescribes ordering against a named sibling: 'Do this before scene_import_assets when the scene should go into a particular map.' That is both a when-to-use and an implicit when-not (assets importing into the default map need not call this).

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 and readOnlyHint=false, and the description substantiates that with concrete side effects: it takes over mouse and keyboard for ~30s (90 with import), and with mapPath the save is imported and opened. It also pre-empts a real trap by noting client controls are drawn pre-script, not as the runtime renders them. It does not explicitly say what persists or is altered by the import, which keeps 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?

The core purpose is front-loaded, but the run-on parentheticals ('(what stands 700 to the side on a computer is off a phone's screen)', '(1600 x 900)...(1920 x 1080, also 21:9)') make it hard to scan, and the 'Most players are on phones' rationale is padding. Several genuinely load-bearing facts (runId, input takeover) are buried late in the paragraph.

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 how results are retrieved ('Returns a runId; playtest_status gives the pictures') and discloses the timing cost and the pre-script rendering limitation. For a two-parameter preview tool that is essentially complete, with only default/bound handling of canvases left undocumented.

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 0%, so the description must carry the load, and it largely does: it maps the device families and resolutions to the canvases enum values and explains mapPath's import/reuse semantics precisely. It is silent on the default set ([pc, mobile, console]) and the minItems/maxItems bounds, leaving minor gaps.

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 ('Show what the interface of a save looks like on other devices, in the editor itself, and return a picture of each canvas') and enumerates the device targets. It distinguishes itself from capture_editor_window and playtest_* by emphasizing that it renders device-specific canvases via the editor's own interface manager. The prose is convoluted, so an agent must read carefully, but the purpose lands.

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?

'This is the look to take before saying an interface is done' implies the use case, and the mapPath sentence explains the two entry conditions (import a save vs. show the open one). There is no explicit when-not guidance or a named sibling to use instead of this tool, so the agent must infer the boundaries against scene_check_client or capture_editor_window.

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 safety (readOnly, non-destructive, closed-world), yet the description still adds real value: row counts, that first rows include the editor thumbnail, that ids returns one picture per effect, that page serves contact sheets of the first 84 looping effects photographed on a character, that queries omits pictures, and that the result explains how to play and clear the effect in graph code. Provenance ("read from the editor's own lists on 2026-10-11") further grounds the data; only pagination/limit behavior is undisclosed.

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 purpose is front-loaded, but the middle is a semicolon-chained run-on that mixes parameter documentation into prose, and parenthetical example lists (fireworks, glows, question marks) pad rather than inform. Readable but not tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter, no-output-schema tool this is close: return content, provenance, and most modes are covered. Gaps remain on pagination/limit semantics and the pictures parameter, which an agent must guess from defaults.

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 0%, so the description carries the load and does explain query (Chinese name words), kind ("timed"/"looping"), ids, page, and queries. But limit, offset, and pictures (default 12, 0-30) are never explained, leaving three of eight parameters undocumented in both places.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states the resource precisely: a named catalog of platform special effects a node graph can show, split into 1986 one-off (限时) and 1209 looping (循环) effects with concrete examples of each. That is enough to separate it from sound_catalog/image_catalog without opening schemas, though it never names a sibling explicitly.

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

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

"Feedback is what makes a level feel like a game: give every action of the player one (picked up, bought, refused, hit, built, lost)" gives a clear use context, and the mode phrases (query, kind, ids, page, queries) show which entry point to pick. It stops short of any when-not guidance or explicit routing away from alternative catalogs.

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

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

Adds real behavior beyond the annotations: the operation may be denied by the OS and the agent should abort rather than continue, and a screenshot is returned as a side effect. It does not reconcile the surprising destructiveHint=true annotation by explaining what state is altered (foreground/z-order), which would have earned 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?

Two short sentences, front-loaded with the action and its effect, followed by the failure caveat. No wasted words.

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 rightly mentions the returned screenshot, but it leaves open how to obtain the windowId, what "observed" means, and why a focus operation is flagged destructive. Adequate to call the tool, incomplete for an agent that needs to chain 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?

One parameter with 0% description coverage; the schema's pattern ^\d+:\d+$ conveys the id format but nothing about provenance. The word "observed" hints the id must come from a prior listing call, which is marginal added meaning over 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?

A specific verb and resource ("Bring an observed game/editor window to the foreground") plus a stated side effect (returns a fresh screenshot). It is distinguishable from list_editor_windows and capture_editor_window, though it does not explicitly say when to prefer it over the sibling capture tool that also returns screenshots.

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 failure-path instruction ("do not proceed if it fails"), which is useful, but it never states when to call this instead of capture_editor_window or list_editor_windows, and it does not say how a window becomes "observed" in the first place. Usage is implied rather than specified.

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

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

Annotations already establish that this is a safe, read-only, closed-world operation. The description adds value by saying the response includes limitations and a recommended workflow, but it does not state whether the tool should be called before mutations or how current/authoritative the capability data is.

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 sentence with no filler, and the most important term ('Discover supported operations') is front-loaded. Every phrase maps to a concrete piece of returned 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?

With zero parameters, full annotation coverage, and no output schema, the description is nearly complete. It lists the main categories of returned information, though it could briefly clarify the response shape or call timing for an agent unfamiliar with the server.

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 there is no parameter semantics burden. The description does not need to explain inputs, and the schema is empty as expected.

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 verb 'Discover' is specific, and the description enumerates the exact resources the tool surfaces: operations, limitations, version, configured paths, and recommended workflow. It is clearly a meta-capability endpoint, though it does not explicitly contrast itself with the knowledge/search siblings.

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 phrase 'recommended workflow' hints that this tool should be used for orientation, but there is no explicit statement of when to call it, when not to call it, or how it relates to siblings such as read_knowledge or search_knowledge. Usage is implied rather than prescribed.

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 read-only annotations already establish the safety profile. The description adds useful return-format context ('four sheets to a page, each picture with its id under it') but omits the 20-page cap and does not clarify whether page is ignored when category is omitted.

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 a long single paragraph with poetic framing ('This is how a screen without words gets its meaning') and extensive example lists. The operative no-argument/with-category instructions are buried mid-paragraph rather than front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with no output schema, it covers the browsing workflow and return format reasonably well. It still leaves the page maximum and category validation unstated, so it is callable but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains that category selects a category and that page refers to sheets of four, but it never states page's 1–20 bound or category validation rules; it does at least explain that valid categories are listed by calling without arguments.

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 the resource ('The pictures a screen can show...') and identifies it as the image catalog for the image control, then specifies the no-argument and with-category behaviors. It never names adjacent tools such as scene_asset_images or scene_search_assets, so sibling differentiation is only implicit.

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

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

It explains the two modes clearly: no arguments lists categories with id ranges, and a category returns grid sheets to read ids from for use with scene_add_image. It also warns there are no names to search by, so browsing by eye is necessary. However, it gives no explicit when-not or direct alternative among the sibling asset/search tools.

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?

It provides valuable technical context by specifically mentioning reading the 'GIL header' and defining 'editorCount' relative to the 3000 limit. This adds specific behavioral traits about the underlying file structure and constraints that goes beyond standard 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 description is dense and efficient, using one sentence to pack a large amount of information about the data being retrieved, making very little wasted space.

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 that there is no output schema, this description is highly complete for providing context on the returned data structure (e.g., knowing that 'nodeCount' and 'editorCount' will be present). It tells the agent exactly what kind of payload to expect.

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 0%, meaning the description is critical. However, since there is only one parameter (`mapPath`), and the description doesn't add unique semantic meaning to how that path should be formatted or constrained, it meets the baseline adequacy.

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 clearly states the tool reads structural data from a map file, including GIL headers, IDs, names, types, and various counts. This is specific about *what* data is extracted, helping distinguish it from tools that might only list entities.

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

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

Usage is only implied by the action (inspect). It doesn't explicitly state that this tool should be used for validation or status checks, nor does it explain when a user might need to inspect versus listing entities or modifying the map.

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/non-destructive/non-openWorld, so the 'read-only' clause adds little; the genuine additions are the Windows 10 platform requirement and the 'visible' filter that scopes the result set. Returned fields are listed, which tells the agent what a call yields, though nothing is said about empty results or how 'physical rect' is encoded.

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?

Two sentences, zero filler, and the highest-value content (what is listed, and the returned identifiers) is front-loaded. The platform/read-only caveat is correctly relegated to the tail.

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 tool with no output schema, the description carries the return-value burden and does so by naming each field. It falls just short of complete because it says nothing about behavior when no editor windows exist.

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 there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly avoids inventing arguments.

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?

Specific verb ('List') plus a precisely scoped resource ('visible Genshin and Miliastra editor windows'), and it enumerates the fields returned (windowId, PID, rect, foreground, minimized). It never names a sibling, so an agent must infer on its own that the windowId feeds capture_editor_window / focus_editor_window.

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

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

Usage is only implied: given siblings like capture_editor_window and focus_editor_window, this is the discovery step that yields a windowId. There is no explicit 'use this first' statement, no when-not-to-use, and no named alternative.

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, non-destructive, closed-world), so the description correctly spends its space on things annotations cannot express: newest-first ordering, the returned fields, the exclusion of temporary and downloaded runtime maps, and the fact that imports silently add saves. The last point is genuinely non-obvious behavioral context; only pagination or size limits are missing.

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 ordering, followed by the fields returned and then the exclusion/side-effect caveat. Three sentences, each earning its place, though the field enumeration could be compressed slightly.

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 compensates by naming the returned fields (name, id, path, size, last-written) plus ordering and exclusions. For a zero-argument, read-only list tool this is essentially everything an agent needs to call and interpret 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?

The tool takes zero parameters, so the baseline is 4. The description correctly does not invent parameter text and instead spends the space on return-shape semantics, which matters more 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?

The description states a specific verb and resource ('List the saves in the game's save list') and clarifies that 'maps' means saves, which resolves the mild name/description mismatch. It stops short of differentiating from nearby siblings like inspect_map, which inspect a single map rather than enumerate them.

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

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

Usage is implied by the enumeration semantics, but the description never says when to pick this over inspect_map or editor_open_map, nor any prerequisites. An agent can infer it is the discovery step, but the guidance 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=true, openWorldHint=false and destructiveHint=false, so the trailing 'Read-only' is redundant. What the description does add is the snapshot provenance ('Read from the editor's music library on 2026-10-11') and the fixed catalog size, but it omits pagination behavior despite limit/offset parameters.

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 what the catalog is, then filtering, then provenance — a sensible order. One clause ('the result shows the call') is vague filler, but overall there is little waste.

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 usefully enumerates the returned fields and gives the category taxonomy, which is essential for building a valid filter. The main gap is pagination semantics for limit/offset on a 188-record catalog.

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 0%, so the description must carry the load, and it does for the two meaningful filters: query is 'words of the title' and category is one of four values (探索音乐 calm, 战斗音乐 tense, 任务音乐 story, 其他需求 events) that appear nowhere in the schema. limit and offset are left undocumented, which keeps 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?

Identifies the resource precisely as the platform's background music library, including its size (188 pieces) and record fields (id, title, length, category). It is distinguishable from sound_catalog by the 'background music' framing, though it never names that sibling explicitly.

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

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

Explains how the returned pieces are consumed downstream (setting day/night/last-wave music via f.modifyPlayerBackgroundMusic), which implies the lookup context. But it gives no explicit when-to-use-this-vs-alternatives guidance, and never mentions sound_catalog or scene_search_assets as the paths for non-music audio.

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=true, destructiveHint=false, openWorldHint=false, and the description's closing 'Read-only' merely restates that. It does add real context beyond annotations: the tool consumes pre-existing screenshots from a finished run and returns a single sheet ordered left-to-right, top-to-bottom. However, it omits what happens when no screenshots exist or when maxFrames truncates the selection.

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 function in the first sentence, then use case, then parameter semantics. Length is justified by eight undocumented parameters, though the parenthetical probe list ('is the weapon in the hand, does the blow land...') is stylistically loose and adds bulk.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter tool with zero schema descriptions and no output schema, the definition supplies most of what an agent needs: units, ranges hinted externally, layout order, and preparation steps. Gaps remain around maxFrames' truncation behavior and failure modes (missing or too few screenshots).

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 0% schema coverage the description carries the full load and mostly succeeds: fromSeconds/toSeconds are 'play seconds, the clock of the screenshots', every is 'each n-th', crop is [x0,y0,x1,y1] as screen fractions, columns and width are sheet layout in pixels. It also cites external limits (screenshotsAt up to 120, screenshotWidth up to 3840). maxFrames and runId are left undocumented, keeping it short of a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource: 'Put the screenshots of a finished playtest side by side in one picture, each cut to the same part of the screen and labelled with its play second.' The framing 'the way to look at motion' makes the tool's role unmistakable and distinct from any sibling, none of which produces composite frame sheets.

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 clear triggering condition (verifying motion, e.g. does the blow land when the number comes up) and concrete preparatory guidance: shoot a quarter/half second apart via playtest_start's screenshotsAt, zoom with scene_set_camera or rely on crop. It also advises iterating with two sheets (a wide one to find the moment, a close two-second one). No explicit 'when not to use' or named alternative tool for this function.

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 discloses far more than the annotations: it takes over mouse and keyboard, requires a monitor, imports or overwrites saves (replaceSave), injects a probe into a copy of the level, uses skill slot 4 (Z), has timing quirks in the editor and platform timers, limits teleports to 200, and describes several failure modes. This is consistent with destructiveHint=true and 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 description is extremely long and poorly structured, with a massive first sentence and nested parentheticals that bury key details. While much of the content is useful, it is not front-loaded or scannable, and the density makes it hard for an agent to extract the most important guidance quickly.

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 tool's complexity, the absence of an output schema, and the minimal annotations, the description is remarkably complete. It covers prerequisites, save import behavior, probe side effects, timing and clock differences, failure handling, output consumption through playtest_status, and many edge cases an agent must know before calling.

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 0%, so the description must carry parameter meaning, and it does so for most of the 18 parameters: inputs, teleport, look, click, clickText, holdMs, repeat, screenshotsAt, screenshotWidth, trackPlayer, startValues, expect, bursts, recordVideo, recordAudio, bakeNavigation, durationSeconds, mapPath, replaceSave, graphName(s), and readTextAt are all explained. However, a few parameters such as burstWidth, clientScriptLog, and noScriptErrors inside expect are not mentioned, leaving some gaps.

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 clause 'Run one full playtest through the official UI without further calls' gives a specific verb and resource, and the description distinguishes the tool from playtest_status and playtest_frames by explaining that it returns a runId immediately and that outcomes are read separately. An agent can identify the core operation despite the sentence's length.

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 extensive when-to-use guidance: teleport for precise positioning versus walking when movement itself is under test, bursts for fast motion versus ordinary screenshots, readTextAt for reading UI, startValues for jumping into a late section, and expect for print assertions. It also names alternatives like playtest_status and playtest_frames and points to platform rules before designing a test.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real behavioral detail beyond them: the max-8-image cap with even spreading, the 45-second blocking wait, and the levelEndedAt/serverMessage/warning fallbacks, but the behavioral layer here is mostly parameter mechanics rather than new information about side effects.

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 is front-loaded in the first clause and nearly every sentence carries operational information. It is, however, dense and parenthesis-heavy – 'imagesShown names their play seconds', 'the way to look at a stretch closely' – which slows parsing on an otherwise well-structured description.

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 takes on the job of describing the return shape: images, screenshots list with file and playSeconds, prints, levelEndedAt, serverMessage, warning. It is nearly complete for an 8-parameter polling tool, with the gaps being maxPrints and includeScreenshots.

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 schema description coverage at 0%, the description does the heavy lifting for prefix, graphId, waitSeconds, screenshotsFrom and screenshotsTo, including units and the clamping limit. It leaves maxPrints and includeScreenshots wholly unexplained and only implies runId, so three of eight parameters remain undocumented.

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 resource and outcome ('Progress or outcome of a playtest_start or scene_import_assets run') and enumerates what comes back: completed steps, log prints, screenshots. It also separates itself from the sibling playtest_frames by naming what that tool does instead ('shows any span of them side by side in one picture').

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 operating instructions: poll with waitSeconds while state is still "running", expect four or five calls instead of forty, use screenshotsFrom/screenshotsTo to retarget the eight images, and use playtest_frames to inspect a stretch closely. It also warns that a succeeded run does not mean the gameplay is right, which reframes how to interpret the result.

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 says the operation writes to <workspace>/publish/<name> and creates a listing.md, which is a filesystem side effect. That directly contradicts readOnlyHint=true, so this is an annotation contradiction despite the otherwise rich workflow details.

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 purpose is front-loaded, but much of the description is one very long nested sentence with parentheticals and checklist details. The content is useful, yet the dense run-on structure makes it harder to scan than necessary.

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 8-parameter tool with no output schema, it explains the output folder, listing.md, returned cover image, and screenshot expectations. The unmentioned mapPath parameter and unresolved read-only/write contradiction keep it from being fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining cover and images as {runId, playSeconds} screenshots, plus title, description, tags, optional video, and name via the folder path. It leaves mapPath and some length/array constraints unmentioned, but much of the 8-parameter surface is semantically grounded.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action: assemble a publish kit for a level from existing playtests, including cover, images, title, description, tags, optional video, and checklist. It explicitly says it does not publish, distinguishing it from the in-game publishing step.

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?

Says to use playtests that were already run and to deliberately capture screenshots at the best moments without debug markers. It also clarifies that this tool does not publish, but it does not name a sibling tool for creating the needed playtest or give explicit exclusion conditions.

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, non-destructive, closed-world behavior, so the description's job is to add context—which it does by disclosing that image links are stripped by default and that 'images' restores CDN screenshots of node graphs and editor panels. It doesn't mention response format or error behavior for bad ids, but the key default-off behavior is surfaced.

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?

One front-loaded sentence with no filler; the id source appears before the optional modifiers. The parenthetical about CDN screenshots is useful but makes the sentence slightly dense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-parameter read tool with no output schema, it covers the required id source, both optional parameters, and the default image-stripping behavior. Return shape (markdown vs JSON) and invalid-id behavior are unstated, a minor gap given the read-only annotations.

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 0%, so the description must carry parameter meaning—and it does for all three: id comes from search_knowledge, heading filters sections by heading substring, and images toggles image-link inclusion (default stripped). That is meaningfully more than the bare types in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read one knowledge-base page') and ties the required id back to a named sibling tool, search_knowledge. An agent can distinguish this from search tools without inspecting 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?

The id provenance ('the id that search_knowledge returned') implicitly routes the agent to search first, and the optional heading filter is described. It doesn't explicitly say when not to use this or name alternative read paths, so it stops short of a full 5.

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 annotations already declaring destructiveHint=true, the description adds rich context beyond them: it writes a new .gil in the workspace without touching the official save, discloses the defaults applied (no cooldown, no use limit, default icon, question mark), names the event raised (whenUiControlGroupIsTriggered) and its evt fields, and warns that each button needs its own key.

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, then organized into event mechanism, coordinate semantics, defaults, and verification. It is dense and slightly long, but nearly every sentence adds a fact an agent would otherwise get wrong; minor redundancy around the key/coordinate explanations.

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 fills that gap by explaining the file output, the raised event, and its evt fields. For a 6-param mutation tool it is nearly complete, with the only shortfall being the undocumented mapPath and outputName params.

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 0%, so the description carries the burden and does so well for the most consequential params: position is [x,y] from screen centre on a 1600x900 canvas with y up, size is [width,height], and key is the number key that presses it (default 1, and should be unique per button). It leaves mapPath and outputName undocumented in both schema and description, so it does not fully compensate.

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 ('Put an interaction button on the screen in a copy of a save') and immediately differentiates the concept from an option tab. The distinction from sibling widgets (progress bar, text box, client UI) is implicit through the event/behavior description, so an agent can identify it without opening a schema.

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

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

Gives clear context for when this is the right widget: a round button the player clicks 'at any time and anywhere, unlike an option tab that needs the character next to something.' This is a useful use-case contrast. It does not name sibling tools as alternatives or give explicit exclusions, which keeps it below a 5.

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?

Far exceeds the annotations: annotations only say destructive/not-read-only, while the description discloses that it writes a new .gil, the exact window contents (title, countdown, cards row, 放弃选择/确认选择), the two graph hook points for input and completion, the default-on nature of the four flags, the level-start timing bug, playtest click sequences, and an account-level gating requirement ('奇匠 level 2 and up'). This is unusually rich behavioral context with no contradiction of the destructiveHint.

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 is largely valuable but delivered as a dense run-on with parenthetical Chinese terms, dated sample references, byte-for-byte provenance and an icon catalog that will rarely affect a call. It is front-loaded with the core purpose, but the middle paragraphs bury operational rules (graph hooks, timing bug) inside prose rather than organizing them.

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 12-param mutation tool with no output schema and no schema descriptions, the description covers the important behavior: what gets written, how the selector is driven by graphs, when it fails to appear, and default flag values. The only notable omissions are the auxiliary params (outputName, mapPath, warnSeconds, revealUnknown) that affect file placement and warning timing.

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 0%, so the description must carry the load, and it does explain cards (the {title, description, icon, label} vs {unknown:true, label} shapes), seconds, canGiveUp, canFold, pauseWhenAlone and showTime. However, five parameters — name, title, mapPath, outputName, warnSeconds and revealUnknown — are never explained in prose, leaving a substantial gap toward the 12-param surface.

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 ('Add a card selector ... to a copy of a save') and immediately scopes what the selector is (a platform window where a player picks cards). It is distinct from every sibling in the list (no other deck/card tool exists), so an agent can identify it unambiguously.

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 usage conditions: the selector 'stands in no layout', only appears when a graph opens it via f.invokeDeckSelector, and must not be opened in the first seconds of a level (with empirical evidence of the failure at second 3 vs success at second 14). No explicit alternatives are named, but there are no rival card-selector tools, so the guidance is functionally complete.

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 a write operation with destructiveHint=true, and the description adds useful file-level context: it writes a new .gil in the workspace and the records are byte-for-byte copies of editor-saved templates, not yet tested in play. However, it never explains what the replace parameter destroys or overwrites, which is the key destructive behavior an agent needs to know.

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 is front-loaded but delivered in dense, run-on sentences with interrupting parentheticals (the Chinese term, the runtime API calls, the templateIndex aside). It is difficult to scan and would benefit from shorter sentences or a structured breakdown of parameters and caveats.

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 four-parameter tool with a deeply nested schema and no output schema, the description usefully explains the template concept, runtime instantiation model, and the return templateIndex. It is incomplete regarding the working map/output target and replace semantics, and it does not address destructive behavior despite the annotation.

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 0%, so the description must carry parameter meaning. It covers the template object fairly well (control kinds, children, name semantics, scripts that start with every copy) and notes the result gives templateIndex, but it says nothing about mapPath, replace, or outputName semantics, leaving three of four top-level parameters undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource: adding a client-control template into a copied save. It also distinguishes the tool from scene_add_client_ui by explaining that grids use a template for itemTemplate and references use one for template. The purpose is clear, though the sentence is tangled enough that an agent must parse it carefully.

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 clear usage context: templates are for runtime-spawned items whose count is unknown (bullets, cards, list rows) and must be added before the interface that uses them. It links to scene_add_client_ui via itemTemplate/template usage. It does not state when not to use this tool or name alternative ways to achieve the same effect.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds real value beyond that: it states the tool 'Writes a new .gil in the workspace' and that client controls are destroyed and recreated on teleport/reconnect, which a script must be able to redraw. It omits what the `replace` flag does to existing UI, which is the main residual gap for a destructive write.

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 is front-loaded, but the body is a single wall of run-on text with heavily nested parentheses that is hard to parse and well past what an agent needs in one pass. Nearly every clause carries information, yet structure and scannability suffer badly.

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 very complex, no-output-schema tool, this covers the model (canvas sizes, positioning units, control tree, per-device overrides) and even describes the returned offPhoneCanvas field. Only the effects of `replace`/`outputName` and a few device-preview behaviors are 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 description coverage is 0% across 12 top-level params and a deep nested control schema, so the description carries the whole burden — and it explains a great deal: kind semantics, position/size coordinate system, anchor, devices overrides, script/values, states, text, grid, fill, feather, showCursor, blockKeys, blockCursor, hidden. It leaves several schema-only fields (mapPath, replace, outputName, isolateNavigation, sound, padKey, below, mask, focusable) unexplained, so not 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 concrete verb and resource: 'Put a tree of client controls on the screen, in a copy of a save,' and enumerates every control kind it can build. An agent knows exactly what the tool produces. It does not, however, distinguish itself from narrow siblings like scene_add_text_box, scene_add_button, or scene_add_progress_bar, which apparently build single controls.

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 references related tools by name (scene_set_client_script, image_catalog, editor_preview_interface) and explains that controls behave as the editor's defaults unless overridden, which is useful context. But it never says when to prefer scene_add_client_ui over the single-control sibling tools, nor any prerequisite/exclusion, so the routing guidance is 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?

The description adds substantial behavior beyond the annotations: it says it writes a new .gil in the workspace and leaves the official save untouched, explains replacement and merge semantics, and documents many verified play-test caveats and failure modes. These details are fully consistent with readOnlyHint=false and destructiveHint=true; there is no contradiction.

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 a single enormous block of prose, roughly thousands of words, with many narrative asides and repeated verification dates. It front-loads the purpose, but the length and lack of structure make it far from concise and hard to scan.

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 a 22-parameter nested schema, no output schema, and destructive write behavior, the description is more than complete enough: it covers targets, replacement semantics, persistence, component behavior, and practical caveats an agent needs to invoke the tool 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?

With 22 nested parameters and 0% schema description coverage, the description carries the full semantic burden and largely succeeds, explaining collisionTriggers, motions, nameplates, textBubbles, projectiles, hitDetection, loot, launcher, forceField, and many others with units, examples and defaults. While a few parameters such as mapPath and outputName are not explicitly explained, the overall compensation for the schema gap is exceptional.

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: adding the platform's own components to a prefab or placed entity in a copy of a save. It is unambiguous about scope, though it does not explicitly distinguish itself from sibling tools such as scene_update_prefab or scene_add_prefab.

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 explains the intended usage pattern extensively, including that this is how interaction is done instead of comparing positions on a timer, that static pieces carry no components, and that calling it again replaces each supplied component kind while leaving other kinds intact. It lacks explicit when-not-to-use guidance versus sibling tools, so it stops short of a 5.

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 declare destructiveHint=true, but the description clarifies the actual blast radius: 'Writes a new .gil in the workspace; the official save is not touched,' which changes how an agent should weigh the destructive hint. It also discloses that the graph cannot tell which of several graphAtMs moments it is running at, and that the result repeats a hint when graphAtMs is far from the moment observed in play. It stops short of covering failure modes or mapPath/outputName effects.

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 purpose is front-loaded and nearly every parenthetical earns its place by disambiguating a Chinese asset name or giving a concrete value. However, the sentences are extremely long and the closing note about byte-for-byte compatibility with the 2026-10-11 editor save is trivia that slows a reader without changing a call decision.

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 12-parameter mutation tool with a nested object, no output schema and zero schema annotations, the description supplies the graph semantics, the animation-selection model, the effect lifecycle, the downstream consumer (scene_set_creature_logic for cooldown) and the write target. An agent could call this correctly without any other source.

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 0% schema description coverage, the description carries the full burden and does so: creature must match the animation's model, animation accepts id or name, animations is a played-in-sequence list, graphAtMs may be a scalar or up to eight moments with a concrete triple-stroke example, effect takes an attachment point like GI_WeaponR, and animationPortion=0.62 trims the trailing idle. Only mapPath and outputName go unexplained.

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: 'Define a skill of a complex creature ... in a copy of a save: an animation of that creature and a client graph that runs at a chosen moment of it.' It immediately distinguishes itself from the sibling scene_add_skill by scoping to complex creatures and from scene_add_graph by naming graphId as an input to 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?

It routes the agent explicitly: find the creature with scene_search_assets {group:"怪物(AI版)"}, list animations with creature_animations {creature}, build the graph with scene_add_graph {kind:"creatureSkill"}, then attach the finished skill via scene_set_creature_logic. It also draws a real exclusion line – items held permanently must be mounted by a server graph (f.mountLoopingSpecialEffect) rather than passed as effect.

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 writes a new .gil in the workspace, leaves the official save untouched, places the backpack on the character template for every character, creates a ten-slot backpack when needed, and notes that the change event fires at level start. It also discloses runtime APIs and event behavior, which is unusually rich for an agent deciding whether and how to invoke it.

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 action and affected entities, and most sentences carry useful domain or runtime information. It is somewhat overpacked with API signatures, sample parity, and a verification date, but remains readable and well ordered.

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 mutation tool with no output schema and low schema description coverage, the description is largely complete on effects, target entity, backpack behavior, file output, and event semantics. The main remaining gap is that two parameters, mapPath and outputName, are not explained.

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 0%, so the description must carry parameter meaning. It explains icon in detail and gestures at name and startAmount, but mapPath and outputName are not described at all, leaving important invocation details undocumented.

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: define a currency in a save copy and equip characters with a currency-holding backpack. It also distinguishes the concept from player entities and ties it to shops, item prices, drops, and character inventory, so an agent can tell exactly what this tool creates.

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

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

Usage context is clear: use this when defining platform currency for a copied save, including optional starting amounts. However, it does not explicitly name alternatives such as scene_list_currencies or state when not to use it, so routing guidance is strong but not complete.

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?

Highly transparent about side effects: writes a new .gil in the workspace, the official save is not touched, the new configuration applies to nobody until a graph switches to it, and it returns environmentId. The only minor gap is that it doesn't reconcile the destructiveHint=true warning with its 'official save is not touched' framing, though writing a new file is consistent with a mutation.

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 what the tool does before the rationale and workflow, and most sentences add real value. Slightly overlong with some editorial detail (the 2026-10-13 washed-out-sky anecdote) that could be trimmed 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?

For a 7-param, no-output-schema mutation tool, it covers the key behavior, side effects, return value, and the night/day workflow. It falls short on explaining the name/mapPath/outputName parameters, but the operational picture is otherwise complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry all 7 params, but it only clarifies hour (0-23, 0 is midnight), stars, milkyWay, and clouds. It leaves name (required, 1-30 chars), mapPath, and outputName undocumented, so roughly half the parameters remain unspecified.

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 (add) and resource (an environment configuration / second sky) on a copy of a save, and explicitly distinguishes it from just changing the level clock. Combined with the mention of f.modifyEnvironmentSettings, an agent knows exactly what this produces vs. scene_set_level_settings.

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?

Explains the core use case (night sky), why the alternative (level clock) fails, and gives an explicit workflow: make two configs, one for night and one for day (hour 11, stars/milkyWay false), and switch between them. It even warns that the map's own config follows a clock stuck at the last fixed hour, so going back after night stays dark.

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 write/destructive/openWorld flags; the description adds the crucial scope qualifier that the official save is untouched and only a new .gil is written. It also discloses runtime lifecycle behavior — a stage-held timer counts down on level load before graphs start, fires whenGlobalTimerIsTriggered at zero, and can be restarted via f.startGlobalTimer — which an agent could not infer from any structured field.

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 holder distinction are front-loaded, and each clause carries information. It is dense and the trailing verification sentence, while genuinely useful, is long enough to dilute the core instruction.

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 tool with annotations, 6 params and no output schema, it covers safety scope, runtime behavior, and the companion display tool. Remaining gap: two parameters (mapPath, outputName) are undocumented anywhere, so an agent must guess what outputName controls in a workspace that already writes a new .gil.

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 0% schema description coverage across 6 params, the description carries the load: it explains holder values ('player' vs 'stage'), what countdown=false means (stopwatch), and how name is referenced by f.startGlobalTimer. It leaves mapPath and outputName entirely unexplained, and seconds is only loosely defined ('a countdown of some seconds') despite a 86400 maximum in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (define a global timer in a copy of a save) and immediately distinguishes the two holder variants: player template (one per player) vs stage entity (one for the level). An agent can tell this apart from scene_list_global_timers and scene_add_timer_display 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 an explicit use case ('the length of a round or of a day'), an explicit alternative to avoid ('instead of counting ticks in a graph'), and names the follow-on tool (scene_add_timer_display) plus the graph calls (f.startGlobalTimer, whenGlobalTimerIsTriggered) that consume the timer. Routing is fully specified.

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 that it writes a new .gil in the workspace, that the official save is not touched, that names receive the _GSTS_ prefix, and that graphs with that prefix are the ones these tools may overwrite. This adds concrete operational context not captured by destructiveHint/readOnlyHint alone.

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 long and dense, but that length is largely justified by the complexity of seven graph kinds and multiple attachment modes. It front-loads the core action and usage condition, though some sentences are run-on and could be more clearly structured.

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 complex behavior, zero schema descriptions, and no output schema, the description is substantially complete: it explains the workflow, attachment semantics, file-writing behavior, and returned graphId/path. The remaining gap is that mapPath and outputName are not explicitly described.

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 0%, so the description must carry parameter meaning. It explains kind at length for all seven enum values, and explains attachToPrefab, attachTo, and the name-prefix behavior, but it does not directly explain mapPath or outputName, leaving a gap for two of the six 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 states a specific verb and resource: add an empty node graph to a copy of a save, and attach it when it is a server graph. It explicitly distinguishes this tool from write_graphs by explaining that write_graphs needs a graph created here first.

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 an explicit when-to-use condition: a new map has no node graph and write_graphs needs one, so call this then use the returned graphId as targetGraphId. It also explains the attachment alternatives and the non-attached kind options with their downstream wiring tools.

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: insertion into a copy of a save, drawing order, hidden controls starting off-screen, and graph-based toggling via modifyUiControlStatusWithinTheInterfaceLayout. It also notes play verification and the level-1 text limitation, which materially helps an agent understand consequences.

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 a clear purpose, but the single dense paragraph is overlong and packed with parenthetical examples and verification notes. Much of it is useful, yet it could be structured and trimmed for faster agent parsing.

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 9-parameter UI mutation tool with no output schema, the description covers purpose, visual parameters, related selection tools, and behavioral caveats well. It is not fully complete because name, mapPath, and outputName are not explained and return behavior is not addressed.

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 0%, so the description must carry parameter meaning. It explains image, colour, opacity, position, size, and hidden well, but omits the required name parameter and the optional mapPath and outputName parameters, leaving important semantics undocumented.

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: putting an image on the screen in a save copy, including default rectangle and platform-picture variants. It distinguishes the tool from text-based UI and points to scene_list_interface and image_catalog for related choices.

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 clear usage context, including the key case where custom text is unavailable and this tool supplies visual meaning instead. It also tells the agent to choose images via image_catalog or knownImages from scene_list_interface, though it does not explicitly name when not to use this tool or contrast it directly with scene_add_text_box.

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 it discloses the write target and blast radius ('Writes a new .gil in the workspace; the official save is not touched') and non-obvious event semantics (item events arrive only in the item's own item graph, not the character's or player's). It does not address what happens on duplicate names or overwriting an existing outputName, which is the main 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?

It is a single run-on block that mixes the core definition, graph-script API signatures, event routing, UI click instructions ('presses B ... clicks the item, 使用 and 确认'), and repeated verification dates. The important content is front-loaded, but splitting the graph/event detail from the definition would make it far more scannable.

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 10-parameter, no-output-schema mutation tool this covers the creation semantics, the currency prerequisite, the consumable/useGraphId path, and the script-facing API. Only the secondary parameters (stackLimit, outputName, mapPath, description) are left to the schema, which is a minor gap given how much context is supplied.

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 0%, so the description must carry the load, and it does for the hard parameters: value (currency by name or id), icon (numeric ids with examples 90001/90015), category ("consumable" activates use), useGraphId (must be an item graph from scene_add_graph), and useCooldownSeconds (default 10). stackLimit, outputName, mapPath, and description still receive no mention, keeping it from 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?

The first sentence gives a specific verb and resource ('Define an item (道具) in a copy of a save') and immediately bounds the concept: a thing held in a backpack in numbers, sellable in a shop. It explicitly disambiguates from siblings by naming scene_add_currency, scene_add_prefab {drop}, and stating 'Equipment is not made'.

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 an explicit prerequisite ordering ('Define a currency first'), names the alternative tool for ground drops (scene_add_prefab {drop}), excludes equipment, and explains the conditional path (category "consumable" with useGraphId) that changes how the item behaves. An agent can choose between item, currency, and prefab without further 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 the annotations: it says a new .gil is written into the workspace, the official save is untouched, and discloses the runtime conditional (lit under its own configuration, off under any other), backed by a playtest verification date. This meaningfully clarifies the destructiveHint=true annotation by scoping what is actually modified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what the tool does and then layers in semantics and the sibling dependency; nearly every clause carries information. It is slightly run-on, and the verification-date sentence, while useful as a trust signal, is the most expendable part.

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 8 parameters, no output schema and no schema descriptions, the definition covers the core behavior, the owning-configuration model and the save-copy side effect. The remaining gap is the three undocumented parameters (name, mapPath, outputName), which an agent must infer.

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 0% schema description coverage across 8 parameters, the description carries the load and explains environment (name or id), position ([x, y, z]), radius (metres of reach), intensity (strength) and range (draw distance). It leaves name, mapPath and outputName undocumented beyond the hint that a .gil is written, so it compensates substantially but not completely.

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 ('Add a point light') plus its scope constraint (belongs to one environment configuration, written into a copy of a save). It explicitly distinguishes itself from the sibling scene_add_environment, which it names as the tool that creates the configuration the light attaches to.

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?

Provides a clear usage condition: a light only shines while a player is under its owning environment configuration, so night lamps must be added to the night configuration created via scene_add_environment. It routes the agent to the prerequisite sibling, but gives no explicit 'do not use this when...' exclusion.

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 and readOnlyHint=false; the description adds the crucial scope caveat that work happens 'in a copy of a save' and 'the official save is not touched', plus the return contract (new prefabId and a new .gil in the workspace) and playtest-verification notes. It does not say why the operation is destructive (existing prefab overwrite? workspace file replacement?), so it stops short of fully covering the destructive hint.

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 purpose is front-loaded, but the body is a single sprawling run-on riddled with nested parentheses and digressions (the target dummy's 300 health, verification dates). Most facts are substantive, yet the density and lack of segmentation make it hard to scan for the one branch an agent needs.

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 10-parameter, zero-coverage, no-output-schema tool, it covers the mechanism/preset system, health semantics, drop semantics, the return shape and playtest-validation loop. What is missing is any statement of what happens when neither asset nor fromEntity is given, and the roles of name, mapPath and outputName.

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 0%, so the description must carry all meaning — and it does for asset, scale (number or [x,y,z], 1 = natural size, defaults to entity scale with fromEntity), fromEntity, health (with concrete damage examples), presetStatusId/presetStatusValue, and the nested drop object (item, amount, pickupSize). However name, mapPath and outputName are never mentioned, leaving three of ten parameters unexplained anywhere.

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: making a prefab (元件) in a copy of the save so a node graph can instantiate it at run time. It is clearly distinguishable from scene_list_prefabs, scene_update_prefab and scene_import_assets, and even explains the alternative in-graph route (f.createPrefab with a bare asset id).

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 between the two creation paths — 'asset (an object asset id or unique name from scene_search_assets)' versus 'fromEntity (the name of something already placed, from scene_list_entities)' — and gives the concrete creature-prefab recipe (place with createAtStart false, import, then prefab from it). It also flags when health matters (needs a hurtBox) and when drop applies (loot component).

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 that this is a write with destructiveHint=true; the description adds the critical qualifier that it writes a new .gil into the workspace and leaves the official save untouched, which materially changes the agent's risk assessment. It also discloses the return value (pointId) and provenance ('Verified in play on 2026-10-10'). Not a 5 because the size/limits of the new file and overwrite behavior for an existing preset name are unstated.

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 resource, then the motivation, then the side effect and return value—a sensible ordering. The single very long sentence with embedded parentheticals and Chinese gloss makes it denser than necessary, but nothing is 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?

It covers purpose, side effect, and return value, which is most of what a 5-parameter mutation without an output schema needs. The gap is that two of five parameters (mapPath, outputName) are left entirely to a bare schema with no descriptions, so an agent cannot confidently supply them.

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 0% across 5 parameters, so the description must carry the semantic load. It clarifies name, position, and rotation (and their role in graph lookups) but says nothing about mapPath or outputName, which are exactly the parameters an agent would guess wrong on.

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 ('Add a named preset point ... to a copy of a save') and immediately explains what that resource is: a position and rotation readable by graphs via f.queryPresetPointPositionRotation(pointId). This is concrete enough to separate it from scene_list_preset_points or scene_set_spawn 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 clear rationale for when to use it ('so that places ... live in the map and not as numbers inside graphs'), which tells the agent the design intent behind choosing this tool. It does not explicitly name an alternative or a when-not-to-use case, so it falls short of a 5.

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

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

Adds real context beyond the annotations: it clarifies that a new .gil is written to the workspace and the official save is not touched, which bounds the scary destructiveHint=true. It also discloses the hidden-until-switched-on lifecycle and names the runtime calls (f.setCustomVariable, f.modifyUiControlStatusWithinTheInterfaceLayout) needed to drive or reveal the bar. It does not say what happens if outputName collides with an existing file.

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 purpose is front-loaded, which is good, but the body is a dense run-on with stacked parentheticals ('(measured)', '(shows "value")') and provenance trivia about bars restyled on 2026-10-13 and an examples/images file that adds little for an agent. It is informative but hard to scan, and the style guidance could be bulleted or trimmed.

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 16-parameter, no-output-schema tool, the description covers behaviour, coordinate conventions, enum semantics and side effects well enough to call it correctly. Gaps remain around name/outputName/mapPath and around what the call returns or where the .gil lands, which matter because outputName looks like it controls the artifact name.

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 0% schema description coverage across 16 parameters, the description carries the load well: it explains variable (integer custom variable, auto-created with start value min), min/max, the position coordinate system with concrete examples, size, all three shape values, all four shows values, colour/backColour/textColour/fontSize and the backOpacity 0.5 default. It leaves name, mapPath and outputName (the file-naming parameter) completely unexplained.

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 concrete verb and resource — 'Put a bar on the player's screen that follows one of the player's custom variables, in a copy of a save' — and lists concrete uses (purse, countdown, health of the thing to defend). It implicitly separates itself from scene_add_text_box by explaining that text boxes render nothing in play on level-1 accounts while bars do.

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 states a clear triggering condition: use this when you need to show a number to the player on an account whose 奇匠 level is 1, where text boxes show nothing. The alternative (text boxes) is named by contrast, though no explicit 'do not use when…' exclusion or reference to sibling tools like scene_add_text_box is given.

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 context beyond the annotations: the revive flow, falling out of the world, addition to level settings and the player template list, and graph-controlled activation/deactivation. It does not explicitly describe overwrite behavior, reversibility, or permission requirements, but the destructiveHint=true annotation already flags mutation risk.

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 purpose is front-loaded, but the description is overlong and includes extensive game-system detail and API function names that are not necessary for invoking this specific tool. Much of the latter half does not earn its place in a tool description.

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?

The description provides rich domain context for a complex mutation tool and covers the core revive behavior. However, with six undocumented parameters, no output schema, and only broad annotations, it still omits important invocation details such as mapPath, outputName, name semantics, and explicit sibling alternatives.

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 0%, so the description must carry parameter meaning. It explains position, rotation, and point (id or name of a preset point), but it leaves name, mapPath, and outputName undocumented, even though the schema has six 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 states a specific verb and resource: 'Add a respawn point (复苏点) in a copy of a save: where a character that went down comes back.' It clarifies the point's gameplay role and distinguishes position-based vs preset-point-based creation, but it does not explicitly differentiate the tool from siblings such as scene_add_preset_point or scene_set_revive.

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

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

Usage is implied by 'Without a respawn point there is nowhere to come back to' and by the instruction to provide either position/rotation or point. However, there is no explicit guidance on when to use this tool instead of related siblings like scene_add_preset_point, scene_set_spawn, or scene_set_revive, and no when-not 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?

Beyond the annotations, the description discloses that it writes a new .gil in the workspace and leaves the official save untouched, which is important for a destructiveHint=true tool. It also describes runtime behavior, events fired in graphs, and what was verified in playtest, giving the agent substantial behavioral context.

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 contains useful detail, but it is a single dense paragraph with extended playtest and UI verification notes. Those details add transparency, but the lack of structure and some repetition make it less concise than it could 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?

For a complex shop-creation tool with nested buy/sell arrays, no output schema, and destructive annotations, the description is largely complete: it explains the write effect, events, graph integration, and playtest behavior. The main remaining gap is that mapPath and outputName are not described, which leaves some operational context unspecified.

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 schema description coverage at 0%, the description compensates for some parameters: it explains sell and buy line structure {item, currency, price}, name-or-id item/currency references, the optional stock field defaulting to 1, and that prefab is a stall prefab from scene_add_prefab. However, it does not explain the name, mapPath, or outputName parameters, so parameter semantics remain incomplete.

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 uses a specific verb and resource: make a prefab a shop that provides the platform's buying/selling screen. It distinguishes the tool from data-creation siblings by explaining that the shop moves items and currency without a graph, and it names related tools such as scene_add_item, scene_add_currency, and scene_add_prefab.

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 explains how sell and buy lists are used, what prefab should be, and how a graph opens the shop with f.openShop and closes it with f.closeShop. It gives clear usage context but does not explicitly state when not to use this tool or name a direct alternative for the same outcome.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false; the description adds real value on top by stating 'Writes a new .gil in the workspace; the official save is not touched', by disclosing the 'client:' name prefix restriction, and by explaining the compiler-unknown client-signal node the server injects. It does not say what happens if a signal with the same name already exists (overwrite vs duplicate), which matters for a destructive write.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded with the purpose, which is good, but the body is a dense run-on with parenthetical glosses in three scripts and at least one awkward sentence ('The answer says how graphs and client scripts send and read them...'). Substantive information is present, but the signal-to-noise ratio is mediocre.

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 mutating, no-output-schema tool this covers the conceptual model, the client-script path, and the write target, which is substantial. However it leaves mapPath/outputName undefined and never addresses overwrite behavior or what a caller gets back beyond the vague 'The answer says how graphs and client scripts send and read them'.

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 0%, so the description must carry the load, and it does well for three of five parameters: name (including the 'client:' constraint absent from the schema), parameter (single string with sender/listener mechanics), and parameters (the {name,type} shape and the eighteen types). mapPath and outputName are never mentioned, leaving the file-selection and output-naming parameters undocumented anywhere.

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 specific verb and resource ('Define a signal (信号) in a copy of a save') and explains conceptually what a signal is: a named, level-wide broadcast. That makes it unmistakable versus other scene_add_* tools. It does not explicitly differentiate from the sibling scene_list_signals, but the create-vs-list split is implicit.

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

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

The night/lamps/gates/enemies example conveys exactly when a signal is the right mechanism (one sender, many unknown listeners), which is strong contextual guidance. There are no explicit exclusions or named alternatives, and no statement about when to prefer a direct reference instead.

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 annotations marking this as destructive and non-read-only, the description adds critical context: it writes a new .gil in the workspace and does not touch the official save. It also discloses client/server graph behavior, slot assignment, animation behavior, effect display, and cooldown mechanics with verified examples.

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 purpose is front-loaded, but the description is a very long single block dense with sample names, exact dates, slot key mappings, and verification details. Much of it is useful for a complex tool, but it exceeds what is needed for concise selection and invocation.

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 9-parameter mutation tool with no output schema, the description covers the creation flow, graph requirements, hit-box integration, server-side skill assignment, cooldown behavior, and output artifact. An agent has enough information to call it correctly and understand its side effects.

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 0%, so the description must carry parameter meaning; it explains type, graphId, animation, graphAtMs, animationPortion, and the nested effect fields with concrete examples. It leaves mapPath, outputName, and name semantics largely unexplained, so it does not fully compensate for the coverage gap.

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: 'Define a skill (技能) in a copy of a save.' It also scopes the tool to player/character skills, distinguishing it conceptually from creature-skill siblings even though it does not name them directly.

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 explains the two supported skill types and explicitly excludes long-press, combo, aiming, cooldowns, and use counts. It also states the prerequisite that graphId must be a client skill graph made first with scene_add_graph. It does not explicitly name when to use this versus scene_add_creature_skill or scene_list_skills.

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 significant non-obvious behavioral trait: text only renders on accounts with 奇匠 level 2+, and level-1 accounts show an empty box. Annotations already flag readOnly=false/destructive=true, and 'in a copy of a save' hints at the save-copy scope, though it doesn't spell out what the destruction entails.

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 variable-format and level-gating details are valuable, but the prose is rambling with run-on sentences, embedded Chinese, and parentheticals (e.g. the 2026-10-13 measurement note) that dilute the front-loaded core instruction.

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 7-param mutation tool with no output schema, it covers the critical rendering and coordinate semantics well, but omits what name/mapPath/outputName do and what 'a copy of a save' implies for side effects, leaving gaps an agent would need filled on first invocation.

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 0% schema coverage, the description carries the full burden and delivers on the hardest params: variable syntax for text, position as [x,y] from screen centre on a 1600x900 y-up canvas, size as [width,height], and fontSize. It leaves name, mapPath, and outputName undocumented, so it doesn't fully compensate.

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 ('Put a text box on the screen') and explains the content it can carry (words, numbers following custom variables). It's clear what it does, though it doesn't explicitly differentiate itself from the sibling scene_add_progress_bar except as a fallback when text fails to render.

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 usage context: test one box before relying on text, and if nothing shows, use scene_add_progress_bar, markers, or effects instead. No explicit 'when not to use' beyond the level-2 caveat, but the conditional guidance is actionable.

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 false and destructiveHint true. The description adds meaningful behavior: it writes a new .gil in the workspace and does not touch the official save, plus coordinate-system details and a verification note. It does not clarify overwrite behavior for outputName, but it substantially supplements 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 purpose is front-loaded in the first clause, and the paragraph is compact. The closing verification sentence is minor metadata but does not significantly hurt 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?

For a write tool with six parameters and no output schema, the description covers the core action and file-output safety, but it omits enough parameter detail (especially timer, mapPath, and outputName) that an agent would still need to inspect the schema and may misunderstand how 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 description coverage is 0% and there are six parameters. The description explains position ([x, y] from screen centre, 1600x900 canvas with y up) and size ([width, height]), but leaves name, timer, mapPath, and outputName undocumented, including the required timer parameter.

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: 'Put a clock on the player's screen that shows a global timer'. It explicitly ties itself to the sibling tool scene_add_global_timer and distinguishes itself from custom-text displays, so an agent can identify its role without opening 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?

It implies a use case ('a way to show time left on an account whose 奇匠 level is 1') and notes a limitation ('shows digits, not custom text'), but it never says when not to use it or points to alternatives like scene_add_text_box or scene_add_progress_bar.

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

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

Adds substantial context beyond the annotations: it writes a new .gil in the workspace while leaving the official save untouched, the status lasts until removed unless seconds is set, and it returns statusId for use with add/removeUnitStatus. Play-verified numbers (9.4 m in 1.2 s at speedPercent 40, two-second root, 2000 damage absorbed) give the agent concrete behavioural expectations the 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?

Front-loaded with the core definition, which is good, but the body sprawls into dated verification anecdotes and exact metrics that dilute the essential parameter guidance. It is informative but over-long for a tool description; several sentences could be compressed without loss.

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 12-parameter mutating tool with no output schema, the description covers purpose, side effects, runtime return value, effect semantics and duration behaviour thoroughly. The gaps are the three unmention ed structural parameters (mapPath, outputName, stackLimit), which an agent must infer from the schema 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?

Schema coverage is 0%, so the description must carry the load, and it explains most parameters well: outline/seeThrough colour semantics and the unmapped-code caveat, maxHealth per-stack, speedPercent's +40 editor ceiling and negative slowdown, invincible, superJump [horizontal, vertical], rooted, and seconds. It leaves stackLimit, mapPath and outputName unexplained, so not 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 ('Define a unit status (单位状态) in a copy of a save: an effect that a graph puts on an entity and takes off again'), immediately distinguishing it from listing tools like scene_list_unit_statuses. The conceptual framing of what a status is makes the resource unambiguous.

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 usage context ('what pickups and hazards are made of: a boot that speeds up, a star that makes invincible, tar that slows, a snare that holds') and the runtime pairing (f.addUnitStatus / f.removeUnitStatus). It stops short of explicit when-not-to-use guidance or naming a sibling alternative, so it lands at 4 rather than 5.

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/non-destructive, and the description's 'Read-only' merely restates that. It adds real value beyond the annotations: photos are normalized to a similar scale, so visual look and true sizeMetres must be judged separately, and failed captures are reported as having no image. It doesn't say how images are delivered (inline/base64 vs. reference), 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?

Four tight sentences ordered by importance: what it returns, when to use it, how to interpret the photos, and the failure case. No filler; the only redundancy is the trailing 'Read-only' already covered by 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?

For a single-parameter tool with no output schema, the description covers return fields, interpretation guidance, and the missing-image edge case. What's absent is the 12-id batch limit and the image transport mechanism, both of which matter when actually invoking 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 0%, so the description must compensate: it does explain that ids are asset ids from scene_search_assets and that each is echoed back with name/group/size. However, it omits the schema's hard constraints (1–12 items, positive integers), which an agent could violate when batching a long result list.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource ('returns a small photo of each asset id') and names its upstream sibling scene_search_assets, which is exactly how an agent would obtain the ids. It is clearly distinguishable from catalog/search siblings like scene_search_assets and image_catalog.

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 selection scenarios: disambiguating assets that share a name (the 'dozens of 乔木' example) and inspecting unfamiliar assets, plus the precondition that ids come from scene_search_assets. An agent knows both when to call it and what input to feed 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 say destructive/not read-only; the description adds the failure model (stops at first failing step and reports which and why), the resumability contract (mapPath holds the partially-applied save and can be re-run with the remaining steps), and the return shape. This is exactly the context annotations cannot carry for a destructive batch 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?

Front-loaded with the core action, then reference syntax, then failure semantics, then scope. The inline example and sibling lists are dense but each earns its place by removing ambiguity that would otherwise cause malformed calls.

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, but the description specifies returns (the last mapPath plus each step's returned fields minus explanations). Combined with the failure and resumption rules, an agent has everything needed to invoke, chain, and recover 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 0%, so the description carries the full burden and does: steps is [{tool, args}] with args as the target tool accepts them minus mapPath, plus the "$<step>.<field>" cross-step reference syntax with a worked example and zero-based indexing. It also explains mapPath's resumption role, which the schema only types as a string.

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: run a list of scene_* tool calls in one call, chaining each on the save the previous returned. It names precisely which sibling tools it wraps (scene_add_*, scene_set_*, scene_update_prefab, scene_remove_entities), so it cannot be confused with any single scene_* 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?

Explicitly enumerates when to use it (the save-mutating tools), when not to (read-only tools, editor drivers like scene_import_assets and editor_open_map), and calls out an alternative for graph writes (write_graphs, which already batches). Both inclusion and exclusion criteria are stated.

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/closed-world/non-destructive, so the safety profile is covered. The description adds value by disclosing the shape of the result — the four fields and that colour is only approximate and size is native — which matters when an agent previews layout before building.

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?

Two short sentences: the first states contents, the second states the action to take. The 'read this before' directive is appropriately placed at the end as the call-to-action, with zero 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 compensates by naming the returned fields and their approximate nature. It could go slightly further (e.g. whether the template IDs are the exact values scene_build_blocks expects, and whether the catalog is static or map-dependent), but an agent has enough 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?

The tool takes zero parameters, so there is nothing to disambiguate beyond the schema's empty object; baseline for a 0-param tool is 4. No parameter guidance is needed or missing.

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?

Specific verb (List) plus specific resource (building blocks placeable by scene_build_blocks), and it enumerates the exact fields returned: name, template ID, approximate colour, native size. It also implicitly separates itself from the other catalog siblings (image_catalog, effect_catalog, sound_catalog) by naming the consuming 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?

'Read this before designing a scene' gives a clear trigger and names the downstream tool (scene_build_blocks) whose inputs come from here. There is no explicit exclusion (e.g. when to prefer image_catalog or scene_search_assets instead), so it stops short of full when/when-not 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 far beyond the annotations: createAtStart:false defers creation to a node graph by GUID, the editor reassigns GUIDs on import, solid:false disables native collision, and patrol is flagged as non-functional since the 2026-10-09 importer change. This is exactly the mutation-side context an agent needs on a destructiveHint=true 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?

Purpose and core parameters are front-loaded, but the text sprawls into a semi-colon chain and ends on a tangent about a 1.56 m fence and a 2.4 m wall that is level-design lore rather than tool semantics. Those sentences do not earn their place in a tool definition.

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, nested-array mutation tool with no output schema, the description does the heavy lifting and even promises a return value ('the pack's bounds'). The gaps are the unexplained `install` and `entityIdStart` parameters, which an agent cannot infer from the schema 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?

With 0% schema coverage the description carries the load, and it does well: units for position/rotation, the size-vs-scale distinction, the anchor-point difference between blocks and other models, and offset semantics are all explained. However `name`, `install`, and `entityIdStart` get no mention at all, so coverage is incomplete.

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 concrete verb and artifact: 'Turn a list of pieces into an official asset pack (.gia) and put it in the editor's import folder.' That is clearly distinguishable from the import sibling it later names, and the scope of the tool is unambiguous.

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

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

It explicitly routes template lookup to scene_block_catalog or scene_search_assets and states 'Nothing changes in the game until scene_import_assets runs', making the two-step pipeline clear. What is missing is an explicit statement of when NOT to use this (e.g. modifying an existing pack, or a single piece).

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