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

With only readOnlyHint available in annotations, the description carries the burden well: it discloses that output goes to a scratch folder, that nothing in the project is changed (consistent with readOnlyHint), that it can run while the editor is open and during play mode, and that an 'unavailable' result means the module was never built, with Reason explaining why. These are exactly the non-obvious behavioral traits an agent needs before calling a compile 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?

Three sentences, front-loaded with the action verb and scope, with no filler. Some return-value detail (passed/failed/unavailable, structured error fields) duplicates what the output schema already conveys and could be trimmed, but overall it is dense and purposeful.

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 tool with an output schema, this covers what the agent needs: what it does, where output goes, effect on the project, and result semantics. The one real gap is disambiguation from sibling compile tools in a crowded build-* and editor_* family.

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 and the schema is empty, so there is nothing the description could add. Baseline of 4 applies; the description implicitly confirms no targeting or argument options exist by saying it reuses the arguments Flax.Build last used.

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: it compiles the project's script modules plus those of referenced projects, outside the editor, into a scratch folder. The 'outside the editor' and 'with the compiler arguments Flax.Build last used' qualifiers give it real specificity. However, it never names the closely related siblings build_compile_scripts or editor_compile, so an agent must still infer which of the three compile-family tools to pick.

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 implied rather than stated: it works while the editor is open and during play mode, which suggests a check-without-disruption scenario. But there is no explicit 'use this when... instead of build_compile_scripts/editor_compile' guidance and no exclusions, despite three plausible compile alternatives among the siblings.

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 usefully discloses the underlying command line flags being invoked, which is real behavioral context beyond the single readOnlyHint=false annotation. However it omits important traits: whether an editor instance is launched/blocked, whether clearing caches forces a full rebuild, and how long it takes.

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 front-loaded sentence with zero filler; the primary action and the optional variant are both stated compactly.

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 process-spawning mutation tool, the definition is thin: it doesn't say whether the editor must be closed, what gets deleted, or expected duration, though the presence of an output schema reduces the need to describe returns.

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% and the sole parameter alsoClearCooker has no schema description. The prose 'optionally -clearcooker too' does map the parameter to its effect, partially compensating, but it adds no detail on cost or consequences of clearing the cooker cache.

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 and mechanism: runs FlaxEditor.exe with -clearcache and optionally -clearcooker to clear build caches. An agent can tell this is a cache-clearing operation distinct from build_compile_scripts or build_generate_projects, though the description does not explicitly name those 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 'to clear build caches' hints at intent but gives no explicit when-to-use guidance, no prerequisites, and no alternatives among the many build_* siblings. The agent must infer that this is for stale-cache recovery situations.

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 readOnlyHint=false, and the description usefully clarifies the output is parsed structured errors rather than a raw log dump, which is real added context. It does not disclose side effects of a non-read-only compile (artifact writes, project state changes, or prerequisites such as a prior build_generate_projects run), leaving a meaningful gap for a mutation-flagged 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?

Two tight sentences with zero waste; the core action is front-loaded and the output characteristic follows immediately. Nothing in the description is filler.

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

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

With an output schema present and no parameters, the description carries little burden and covers purpose plus the distinctive return-value character. The main omission is any indication of prerequisites or relation to the build pipeline siblings.

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 and the schema coverage is 100%, so there is nothing to disambiguate. Baseline 4 applies for a no-parameter tool.

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 ("Compiles game scripts") plus a scope qualifier ("headlessly"), so the agent knows exactly what operation it performs. It does not, however, distinguish itself from sibling tools like build_check_scripts or editor_compile, leaving the agent to infer the difference.

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 no when-to-use or when-not-to-use guidance. With build_check_scripts, editor_compile, build_generate_projects, and build_game all present as siblings, an agent has no stated criterion for choosing this tool over those.

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

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

Adds genuinely useful behavior beyond the lone readOnlyHint=false: the call is asynchronous, returns a job handle immediately rather than the result, and the build outcome only surfaces later via job_status/job_wait. Permission requirements and failure modes are not covered, but the async contract is the key non-obvious trait and it is stated plainly.

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 tight sentences: the action and async return come first, then the follow-up workflow. No filler, and every clause adds either mechanics or routing 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 an output schema present, the description is not obliged to detail the returned job shape, and it correctly does not. Combined with the async explanation and parameter example, an agent has what it needs to invoke and then poll; only discovery of valid preset/target values is left unaddressed.

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: it explains that preset and target compose a <preset>.<target> build string and gives a worked example ('Development' / 'Windows'). It misses where valid values come from (e.g. project_targets), which would have fully closed the 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 concrete verb+resource ("Starts a game build") and even shows the underlying command form with an example preset/target, which makes the action unambiguous. It does not explicitly contrast itself with near siblings like build_generate_projects or build_compile_scripts, so an agent must infer that this is the full game-build step rather than a project or script 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?

Gives clear follow-up guidance: use job_status or job_wait after calling, and explains why (a real build takes minutes). It does not state exclusions or when to prefer the sibling build_* steps instead, leaving that routing to the agent.

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?

readOnlyHint=false already signals a mutating operation; the description adds real value by disclosing the underlying process (spawns FlaxEditor.exe) and the artifact it rewrites (IDE project/solution files). It stops short of stating whether existing customized project files are overwritten, whether the editor must be closed first, or whether the call blocks until generation finishes.

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 front-loaded sentence with the action and the literal command line; no filler, nothing that could be trimmed without losing 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?

For a zero-parameter tool with an output schema and a declared mutation hint, the description covers what it does and how. The only gaps are operational preconditions (editor state, overwrite behavior), which keep it from being fully self-sufficient.

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 and the baseline applies. The description correctly implies the build target is implicit rather than configurable.

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?

Names a specific action (regenerate IDE project/solution files) and the exact mechanism (FlaxEditor.exe -genprojectfiles). This is clearly distinct from sibling build_* tools such as build_compile_scripts or build_game, so an agent can pick it 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?

Usage is only implied: an agent can infer it should be run when project/solution files are stale (e.g., after adding scripts), but the description never states when to use it, when not to, or how it relates to build_compile_scripts. No prerequisites or ordering guidance are 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 readOnlyHint annotation already establishes this as a safe, non-mutating read. The description adds value by naming the exact metadata fields returned, but says nothing about behavior on an invalid or missing GUID (error vs empty result) or about path formatting/casing.

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 front-loaded sentence with the return fields enumerated inline; every clause earns its place and there is no filler.

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

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

An output schema exists, so return-value shape need not be restated in prose. For a simple one-parameter read tool this is nearly sufficient; the only missing piece is failure behavior for a bad GUID and a pointer to how GUIDs are obtained.

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 does clarify that the opaque 'id' string is the asset's GUID. However, it gives no hint on where a GUID comes from (content_search/content_resolve_guid) or its format, so the single parameter remains only partially disambiguated.

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 (Returns) and resource (metadata for the content asset with the given GUID) and enumerates the returned fields (Id, TypeName, RelativePath, Extension). It is clearly distinct from content_search or content_resolve_guid in intent, though it does not explicitly name those siblings as alternatives.

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?

There is no guidance on when to use this tool versus siblings like content_search (find an asset) or content_resolve_guid (obtain a GUID). The only implied rule is that the caller must already hold a GUID, which is already encoded by the required 'id' parameter in the schema.

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 no annotations, the description carries the full behavioral burden and mostly doesn't. 'Through the live Flax Editor' hints at an editor-session dependency, but it never says whether an existing asset at that path is overwritten or errors, whether the editor must be in a specific state, or what side effects occur — all critical for a create/mutate 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?

Two tight sentences, front-loaded with the action and followed by the one hard constraint. Nothing is padded or redundant.

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

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

For an 8-parameter creation tool with nested color objects and optional texture GUIDs, the description is thin: it omits overwrite semantics, editor-session prerequisites, and how texture GUIDs are obtained (presumably via content_resolve_guid). The presence of an output schema excuses return-value documentation but not these gaps.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description only restates the relativePath constraint already documented in the schema and adds no meaning for the texture GUIDs, UV tiling, or emissive 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?

States a specific verb and resource: creates a surface Material asset via the live Flax Editor. The qualifier 'surface' implicitly separates it from content_create_material_transparent, but the description never names that sibling or content_create_material_instance, so differentiation is left to inference.

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?

No when-to-use guidance is given. The only constraint offered ('paths are relative to Content/ and must end in .flax') is a parameter rule, not a routing rule, and nothing tells the agent when to prefer this over content_create_material_transparent or content_create_material_instance.

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?

No annotations are supplied, so the description carries the full disclosure burden. It does contribute real behavioral facts: overrides are validated and applied atomically, so a failed override should not leave a half-configured asset. It omits other mutation-critical behavior such as what happens if relativePath already exists, whether the asset is saved/registered immediately, and what errors surface.

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 the verb and resource front-loaded and no filler. Every clause (source material, validation, atomicity) carries information 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 3-parameter creation tool with 100% schema coverage and an output schema (so return values needn't be described), the description covers source, destination semantics, and failure atomicity. The remaining gap is overwrite behavior and sibling routing, which is a usage-guideline issue rather than incompleteness.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: overrides are keyed by public parameter names, are validated, and are applied atomically as a set. That tells the agent failures are all-or-nothing rather than per-parameter, which is genuine added value.

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

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

States a specific verb and resource ("Creates a MaterialInstance asset") plus its source ("from a live surface material") and its effect ("applies validated parameter overrides atomically"). This is enough to distinguish it from content_create_material and content_set_material_instance_parameter, though it never names those siblings to make the distinction explicit.

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?

There is no guidance on when to choose this tool versus content_create_material (plain material creation) or content_set_material_instance_parameter (updating an existing instance). The phrase "from a live surface material" implies baseMaterialId must reference an existing material, but the agent must infer that rather than being told.

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 no annotations, the description carries the full burden and does well: it discloses the blend mode and lighting model, that the material traces screen-space reflections, and the precondition that 'No asset may exist at the path' (i.e. no overwrite). It does not state what happens on a path collision, nor whether the editor/project must be open, which keeps it below 5.

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

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

Front-loaded with the core purpose, then layered detail on refraction and instances. Dense but nearly every sentence carries actionable information; the refraction explanation runs slightly long relative to the rest.

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?

Output schema exists so return values need no explanation, all five parameters are documented in-schema and reinforced in prose, and the description covers creation semantics, effect behavior, and the path precondition. An agent has enough to call this correctly without further context.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: opacity 0 is fully clear, refraction 1 bends nothing, and it quantifies the effect (1.03 shrinks background objects to ~40% width). It also names the four public parameters (BaseColor, Opacity, Roughness, Refraction), which the schema alone does not label as material inputs.

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 with distinguishing attributes: 'Creates a transparent surface Material (blend mode Transparent, Lit)'. The use cases (glass, water, film) and the contrast with content_create_material_instance for variants make it unambiguous versus the generic content_create_material sibling.

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 selection guidance for the refraction value ('Use 1.0 for thin glass with something inside... values above 1 only for a lens effect') and routes variant creation to content_create_material_instance. It stops short of explicitly saying when to choose content_create_material over this tool for opaque materials, so it is clear context rather than a full when/when-not 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?

The readOnlyHint annotation already covers the safety profile, and an output schema exists, so the return payload is documented elsewhere. The description's main added value is the word 'live,' which implies a prerequisite that the material be currently loaded in the editor and may fail otherwise, but this constraint is not spelled out with any failure mode or permission detail.

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, front-loaded sentence with no filler; every clause maps to a distinct category of returned data.

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 annotations covering read-only safety and an output schema covering return values, the definition is functional but thin: it never clarifies the 'live' prerequisite's implications or how it relates to content_asset_info for the same asset, leaving an agent to infer those boundaries.

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

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

Schema coverage is 100% and the materialId property already documents that it is a FlaxEngine.Material GUID sourced from content_search. The description adds nothing about the parameter, so the baseline 3 is appropriate when the schema does all the work.

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 names a specific verb (Returns) and enumerates concrete outputs: typed values, texture references, UV tiling, and exposed parameters for a Material asset. This clearly differentiates it from mutation siblings like content_create_material, though it doesn't explicitly distinguish itself from content_asset_info, which likely also returns asset metadata.

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 scope ('live surface Material asset'), hinting that the material must be loaded in the editor, but there is no explicit when-to-use or when-not guidance, and no sibling (e.g., content_asset_info) is named as an alternative for non-live inspection.

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?

readOnlyHint=true already declares the safe-read profile, so the description's marginal contribution is the relative-path normalization convention, which is useful. It says nothing about behavior for an unknown/stale GUID (error vs. empty) or whether paths use forward slashes, which are the realistic failure modes for a resolver.

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 sentence, no filler, and the output contract is placed immediately after the verb+resource so it is 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?

An output schema exists, so return values need no explanation, and the input is a single documented-in-prose parameter. The only meaningful omission is not-found/error behavior for a resolver, which is a small gap for a tool this simple.

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% and the single parameter is a bare 'id' string, so the description carries real weight by clarifying that it is a content asset GUID rather than an actor/asset-registry id. It stops short of stating the GUID format or where to obtain one.

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 (resolves) and resource (content asset GUID) plus the exact output shape (path relative to Content/). An agent knows precisely what it does, though it never contrasts itself with siblings such as content_asset_info or content_search that also take asset identifiers.

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?

No guidance on when to use this versus content_search/content_asset_info, and no precondition noted (e.g. needing a GUID already in hand from another call). Usage is only inferable from the tool name.

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?

readOnlyHint=true already establishes safety, so the description only needs to add beyond that, and it does: it discloses that Id/TypeName come back null for unrecognized formats or unmatched .flax headers. Useful, but nothing on result limits, ordering, or cost of a partial scan.

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, front-loaded with the search purpose and followed by the caveat. Efficient, though the caveat is dense and could be trimmed or moved after the selection guidance that is missing.

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?

An output schema exists, so return shape need not be described, and the version-verified caveat is a nice touch. Still missing for a search tool: whether an empty query enumerates everything, any result caps, and how this relates to the content_* lookup siblings.

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 is the only source of parameter meaning, and it does map all three params (partial path match, TypeName, extension) while implying they can be combined with 'and/or'. It omits matching semantics such as case sensitivity, substring vs prefix, and behavior when all three are null.

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 (searches) and resource (the Content/ index) plus the three matching criteria, so the agent can tell it apart from lookup-style siblings like content_asset_info or content_resolve_guid. It does not explicitly name those siblings, keeping it below a 5.

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?

No guidance on when to prefer this over content_asset_info or content_resolve_guid, nor any note on whether criteria are ANDed or optional in practice. The only conditional sentence is about a data-quality edge case, not about tool selection.

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 no annotations, the description carries the full burden. It does usefully disclose that the value is validated and that the asset is saved (a persistent side effect), but it does not say what happens on validation failure, whether other existing overrides are preserved, or what the save touches.

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 mutation plus its persistence effect are front-loaded. Slightly clipped for a state-changing tool, but every clause 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?

Output schema exists and all three params are documented, so return values need no explanation. However, for an unannotated mutation the description should say more about validation failure behavior and whether unrelated overrides are disturbed.

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

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

Schema description coverage is 100%, and the schema already explains materialInstanceId (GUID from content_search), parameterName (existing public parameter), and value (matching declared type). The description adds only the 'one parameter' framing, so the baseline 3 applies.

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

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

States a specific verb ('Sets'), a specific resource ('parameter override on a MaterialInstance'), and the persistence side effect ('saves the asset'). It is clearly distinct from content_create_material_instance or editor_set_member, though it does not name those siblings 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?

'on an existing MaterialInstance' and 'one validated parameter override' imply preconditions (instance must already exist, one parameter per call), but the description never states when to prefer this over content_create_material_instance or editor_set_member, nor any exclusions.

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 readOnlyHint annotation already establishes the safety profile, so the description only needs to add context. It contributes the useful 'live' qualifier (a snapshot of current editor state rather than cached data) and names the data domains returned, but says nothing about failure behavior for an unknown actorId, edit-mode vs play-mode requirements, or read cost.

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 sentence, front-loaded with the verb and scope, then a dense enumeration of returned data. No filler, no restatement of the tool name, and no duplication of schema content.

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

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

With an output schema covering return values, a fully documented parameter, and a readOnlyHint annotation, the description only needed to convey scope and data domains, which it does. The remaining gap is that error/precondition behavior is unstated, which is minor for a single-actor read tool.

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

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

Schema description coverage is 100% and the single actorId parameter is already documented with its source (editor_scene_graph or editor_get_selection). The description adds no further parameter semantics such as format validation or whether partial GUIDs are accepted, so the baseline 3 applies.

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

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

States a specific verb ('Returns') and a precisely enumerated payload (identity, hierarchy, activation, layer, tags, transforms, scripts) scoped to 'one actor loaded in the Flax Editor'. The field enumeration implicitly separates it from component-specific siblings like editor_static_model_details and editor_box_collider_details, though no sibling is named 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?

Usage is only implied: 'one actor loaded in the Flax Editor' signals it operates on an existing actor, and 'live' signals current editor state. The description never says when to prefer it over editor_static_model_details, editor_box_collider_details, or scene_find_actor, nor any precondition such as needing an ID from editor_scene_graph (that routing lives only in the schema).

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?

No annotations are provided, so the description carries the full burden and does well: it discloses idempotency ('no-op if already present'), the dirty-scene side effect that makes editor_save persist the change, and that componentType is fuzzy-resolved against the type registry. What it omits is whether the operation is undoable or what the failure mode looks like when the type resolves ambiguously, keeping it at 4 rather than 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 sentences, front-loaded with the verb and resource, then the caveat and side effect. Zero filler and nothing buried.

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 an output schema present, the description need not explain return values, and it covers the two non-obvious behaviors (no-op semantics, dirty-scene marking) plus type resolution. It could say more about execution context requirements (e.g., whether a scene must be open), but it is close to complete for a 3-parameter tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics the schema lacks: componentType accepts short names resolved by fuzzy match, not just exact type strings as the schema's example implies. orderInParent is left to the schema, which fully documents it.

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 says exactly what the tool does: 'Adds a script-type component to an actor', with the idempotency caveat and the edit-mode side effect. An agent can immediately distinguish it from editor_remove_component or editor_set_component_property.

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 routing rule: use this to add a component, but use editor_set_component_property instead when the goal is to change properties on an existing component. The named alternative actually exists among the siblings, so the guidance is actionable rather than decorative.

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 framing matches readOnlyHint=true, so no contradiction. It adds the meaningful condition that the collider must be 'loaded' and names the returned fields, but says nothing about behavior on a missing/non-collider actor, which matters for a lookup tool keyed on a GUID.

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 sentence, front-loaded with the action and resource, with the field list attached rather than split into filler prose. Nothing is wasted.

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 simple single-parameter read tool with an annotation and an output schema, the description covers what is returned and the loaded-collider precondition. Only failure-mode behavior is missing, which is a minor gap here.

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

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

Schema coverage is 100% for the single actorId parameter, including the note that the GUID comes from editor_scene_graph. The description adds no additional meaning about the parameter, so the baseline 3 applies.

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

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

States a specific verb ('Returns') and resource (BoxCollider details for a loaded actor) and enumerates the fields returned, so it is clearly distinguishable from mutation siblings like editor_set_box_collider. It does not explicitly contrast with editor_actor_details or editor_static_model_details, so it stops short of full sibling differentiation.

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: the word 'loaded' hints at a prerequisite, and the schema points to editor_scene_graph for the actorId. There is no explicit statement of when to choose this over editor_actor_details or what to do if the actor has no BoxCollider.

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 no annotations, the description carries the full burden and does so: it discloses the destructive side effect ('Replaces an existing file'), the environment prerequisite (folder must exist, per schema), the unavailability in headless mode, and what the image will and will not contain (post effects included, editor and screen-space UI excluded).

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 scope, then camera selection, then output characteristics, then constraints. Terse fragments are used deliberately and each sentence contributes a distinct fact; 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?

For a 5-parameter tool with an output schema (so return values need not be explained) and no annotations, the description covers action, scope, defaults, environment limits, and file side effects. An agent has everything needed to invoke it correctly, plus the 'Read the PNG to see it' hint that the result must be inspected separately.

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

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

Schema description coverage is 100%, so the schema already documents path, width, height, cameraId and warmUpFrames with ranges and defaults. The description's camera sentence ('Camera: the given Camera actor. Without one: the main camera...') largely restates the cameraId schema text rather than adding new meaning. Baseline 3 is appropriate.

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: 'Renders a camera into its own render target and saves a PNG'. The follow-up clause 'It does not read an editor window' explicitly separates it from the sibling editor_screenshot, so an agent can route between them without opening either schema.

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

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

Gives clear when-it-works context (editor covered, small, minimised, play mode, edit mode) and an explicit exclusion ('Not available in headless mode'), plus the default camera selection rule. It stops short of naming the alternative tool (editor_screenshot) outright, so the alternative is implied rather than 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?

With no annotations, the description carries the full burden and does so well: it discloses the blocking wait for editor reload, the side effect 'Stops play mode first', the fact the editor is untouched on an early check failure, the structured error shape (file, line, column, code), and the three outcome classes reported via Check. These are the exact traits an agent needs before invoking a disruptive operation.

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

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

The core action and the stop-play-mode warning are front-loaded and every sentence adds information. It is dense and slightly garbled in one spot ('its outcome is reloaded, unchanged or failed'), which costs a little readability without wasting 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?

For a zero-parameter tool with an output schema and no annotations, the description covers the whole behavioral story: prerequisites, side effects, sequencing, failure modes, and where error detail surfaces. Nothing an agent needs in order to call it safely is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline is 4 by rule. The description's references to compiler arguments and BuildErrors fields are descriptive context, not parameter explanation.

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

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

Opens with a specific verb+resource ('Compiles the project's scripts') plus a precise completion condition ('returns when the editor has reloaded and settled'). It then distinguishes the two internal phases, so an agent can tell it apart from the pure-check siblings build_check_scripts and build_compile_scripts.

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

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

Gives clear operating context: the check runs outside the editor first, and only a clean check proceeds to the editor compile that reloads the editor. It never explicitly routes the agent among the near-identical siblings (build_check_scripts, build_compile_scripts, build_generate_projects), so the choice still requires 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?

No annotations are provided, so the description must carry the full behavioral burden. It discloses that creation happens in a loaded scene and returns live details, but omits permissions, side effects, reversibility, failure modes for invalid sceneId/parentId, and what happens on name collisions.

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 single sentence is front-loaded with the core action and resource, and every clause contributes useful information without 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?

An output schema exists, so return values need not be explained. However, for a 7-parameter mutation tool with nested objects and no annotations, the description is far too sparse regarding parameter semantics, preconditions, and side effects to be 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 only 14%, with just actorType documented in the schema. The description adds no meaningful semantics for name, sceneId, parentId, translation, orientation, or scale, leaving most required parameters undocumented beyond their types.

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 ('Creates') and precise resource ('allowlisted EmptyActor or StaticModel') within a loaded scene, plus the return behavior. It is clearly a creation tool rather than duplication or modification, though it does not explicitly name sibling alternatives.

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 'in a loaded scene' implies a precondition and 'allowlisted' hints at constraints, but there is no explicit guidance on when to use this versus editor_duplicate_actor, editor_add_script, or other creation siblings. Usage is inferable but not well delineated.

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?

No annotations are supplied, so the description carries the full disclosure burden. It usefully notes the operation is scoped to a loaded parent and that the response returns the collider's effective properties, but says nothing about name collisions, reversibility, permissions, or whether the collider is immediately active in play mode.

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 well-formed sentence with the action front-loaded and zero filler. Its brevity is close to under-specification rather than verbosity, so it earns a 4 rather than a 5.

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?

An output schema exists, so the return value needn't be described, and the nested size/center shapes are covered by the schema. However, for a 5-required-param mutation tool with no annotations, the description omits isTrigger semantics, name uniqueness behavior, and any guidance on obtaining a valid parentId beyond what the schema says.

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 60%: size, center, and parentId are documented in-schema, but the description adds no parameter meaning at all. The two undocumented params, name and isTrigger, get no clarification — in particular isTrigger's behavioral effect (trigger volume vs solid collision) is left unexplained 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?

States a specific verb+resource ("Creates a BoxCollider") and the placement target ("under a loaded parent actor"), which separates it from the sibling modifier editor_set_box_collider and reader editor_box_collider_details. It does not explicitly name those siblings, so it stops short of full differentiation.

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: the verb "creates" signals this is for adding a new collider rather than editing an existing one, and "loaded parent actor" hints at a precondition. There is no explicit when-to-use vs editor_set_box_collider / editor_box_collider_details, and no stated failure 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?

With no annotations provided, the description carries the full burden and does disclose important behavior: deletion goes through editor Undo/Redo history, and the boolean controls whether child actors cause rejection or are deleted. It does not cover every edge case, such as invalid actor IDs or undo limits, but it gives substantial behavioral context for a destructive operation.

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

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

The description is two tight sentences with no wasted text. It front-loads the action and then immediately clarifies the only ambiguous parameter behavior.

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

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

For a two-parameter destructive tool with an output schema and no annotations, the description covers the essential behavioral details: undo/redo integration and hierarchy handling. It could be slightly more complete with explicit preconditions or failure behavior, but it is sufficient for correct 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?

Schema coverage is only 50%, and the description compensates by fully explaining the otherwise undocumented deleteDescendants parameter, including both true and false behavior. The actorId parameter is documented in the schema as coming from editor_scene_graph, so the description does not need to repeat it.

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: 'Deletes a loaded actor.' It also adds the meaningful scope detail that deletion happens through the editor Undo/Redo history. It is clear, but it does not explicitly differentiate this delete operation from nearby actor-modification 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 description explains the key conditional behavior of deleteDescendants: true deletes the hierarchy, while false rejects actors with children. However, it does not explicitly state when to choose this tool over alternatives or list preconditions such as an open scene or loaded actor context.

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 no annotations, the description carries full behavioral burden. It discloses only that the result is the duplicate's 'live details'; it says nothing about whether the source actor is untouched, how the duplicate is named, whether the operation is undoable, or what happens if the target scene/parent is invalid.

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 well-formed sentence with no padding, front-loading the action and resource. Efficient, though it could have spent the saved space on parameter or usage detail.

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 output schema excuses it from explaining return values, but for a 7-required-parameter mutation with nested transform objects and an ambiguous nullable sceneId/parentId pair, the description leaves too much for the agent to infer on its own.

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% across 7 required parameters, so the schema gives only types and names. The description does not explain any of them, and critically does not clarify the required-but-nullable sceneId/parentId pair (presumably pass one and null the other) or how translation/orientation/scale are interpreted relative to the parent.

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 ('duplicates') and resource ('a loaded actor') plus the destination ('into a loaded scene or parent'), which differentiates it from editor_create_actor (create new) in the sibling list. It stops short of explicitly naming that sibling, but the duplicate-vs-create distinction is inferable.

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?

Implies the prerequisite that both source actor and destination scene/parent must already be loaded, and the verb 'duplicates' hints at the use case. However, it never states when to choose this over editor_create_actor or editor_reparent_actor, nor any exclusions.

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

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

With readOnlyHint already covering safety, the description adds substantial non-structured behavior: a 4096-event rolling buffer held across script reloads, Truncated=true when events after sinceSeq were overwritten, and HostStartedUtc signaling an editor restart that reset the sequence. It also clarifies that 'log' covers managed lines only, with native engine lines (compiler output) remaining in the log 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?

Front-loaded with purpose and ordering in the first clause, then operational caveats. The long kind list is dense but load-bearing since no enum exists; no sentence is filler, though the block is heavier than ideal for a single stream read.

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?

Output schema exists, so return-shape explanation is unnecessary; the description still volunteers the two semantically important output fields (Truncated, HostStartedUtc) that govern correct pagination and reset handling. Retention limits, ordering, and kind scope are all covered for a 4-param, zero-required read tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: it enumerates the valid kind strings even though the schema's `kinds` items have no enum, and it defines the sequence space (reset on host start, gap detection via Truncated). `limit` and `waitSeconds` are left entirely to the schema.

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

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

States a specific verb and resource ("Returns the editor's recorded events"), plus ordering ("oldest first") and a cursor ("after a sequence number"), which pins down exactly what this stream is. The enumerated Kinds make it trivially distinguishable from siblings like logs_tail or editor_wait_for.

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 rather than stated: the retention/truncation and HostStartedUtc notes imply polling and restart-recovery patterns, and the 'log' kind note implies 'use this rather than logs_tail for engine output.' But no sentence explicitly says when to pick this over logs_tail, logs_errors, or editor_wait_for, and there are no exclusions.

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?

readOnlyHint=true already establishes the safety profile, and the description adds real value beyond it: which scene is searched during play mode, that types match by full or short name, what fields come back, and that Truncated signals the limit was exceeded. It does not mention ordering of results or behavior with multiple loaded scenes, but the core behavior is well disclosed.

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

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

Two tight sentences, with the search scope and optional-combination rule front-loaded before the return-value note. The return explanation is somewhat redundant given the tool has an output schema, which keeps this from a 5.

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 read-only filter tool with a full schema and an output schema, the description covers scope, filter combination, type-name flexibility, and truncation. Missing only edge-case behavior such as which scene wins when several are loaded, which the agent would likely need in practice.

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

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

Schema coverage is 100%, so the baseline is 3; the description raises it by explaining that the filters are optional and combined, and that type strings accept either full or short names. The only gap is that limit semantics are left entirely to the schema.

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

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

States a specific verb and resource (finds actors) plus the search scope (loaded scenes, the play-time scene during play) and the filter dimensions. It does not name or contrast with the close sibling scene_find_actor, so an agent still has to infer which search tool to pick.

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?

"all optional and combined" tells the agent that filters are conjunctive and that an unfiltered call is valid, which is useful implied usage guidance. However there is no explicit when-to-use/when-not-to-use statement and no routing to the alternative scene_find_actor or scene_outline 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?

Annotations only declare readOnlyHint=true, so the safety profile is already covered; the description adds genuinely new behavior: private members are readable (an access-scope expansion beyond what annotations convey) and unknown member names return a list of valid members rather than a bare failure. It does not describe the returned value shape, but an output schema exists to cover that.

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

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

Three short sentences, front-loaded with the verb and resource, with the example and the error fallback each carrying distinct information. No filler or repetition.

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 an output schema and a readOnly annotation, the description covers addressing, access scope, and failure behavior. A brief pointer to the set/read counterpart would make it fully self-sufficient, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% and both the dotted-path format and the scriptType override are already documented in the schema with the same example. The description restates the dotted-path idea and hints at script targeting, adding little syntax or edge-case meaning beyond the structured fields.

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 ("Reads") and resource ("a field or property of an actor, or of one of its scripts") plus the addressing mechanism (dotted path with example "Clock.Steps"). The read framing cleanly separates it from the sibling editor_set_member without either schema being opened.

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 note "Unknown names list the members that exist" implies an exploratory use case, and the script-scoped read is implied by the description, but there is no explicit statement of when to use this versus editor_actor_details or editor_set_member. Usage is inferable rather than 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?

The "live Flax Editor" phrasing usefully signals that this reflects interactive editor state rather than a scene file, and it is consistent with readOnlyHint=true. However, it says nothing about behavior when no editor is connected or when the selection is empty, which is the main failure mode for a live-state query. With annotations already covering the safety profile, this lands at an adequate 3.

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 sentence, front-loaded with the verb and resource, with zero filler. Nothing could be removed without losing 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?

The output schema presumably documents the returned actor list, so return-value detail is not required here. For a zero-parameter read tool the description is nearly sufficient, with the only real gap being disconnected-editor behavior.

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

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

The tool takes zero parameters and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies; a note about whether the selection can span multiple actors would have pushed it higher.

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 names a specific verb ("Returns") and a precise resource ("the actors currently selected in the live Flax Editor"), so there is no ambiguity about what is retrieved. The read-vs-write split with the sibling editor_set_selection is easy to infer from the wording, though the description 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?

Usage is only implied: an agent can reason that this is the read counterpart to editor_set_selection, but the description states no when-to-use condition and no alternative. There is no mention of the prerequisite that the editor must be running, which is the main thing that would govern calling this versus a scene tool.

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, so the safety profile is covered. The description adds meaningful context beyond that: the host is a pipe server that outlives script reloads, and collect=true triggers a full GC that is slow on a large heap. That performance caveat is exactly the kind of behavioral detail annotations cannot express.

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

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

One front-loaded sentence that leads with the resource and then the returned fields; nothing is padding. It is dense and slightly run-on, packing return fields and a parameter caveat into a single sentence, but every clause carries 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?

A read-only, single-parameter diagnostic with a full output schema, so return-value documentation is not strictly needed — though the description restates the fields anyway, which is mildly redundant but helps an agent judge relevance. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the single parameter is already documented, so the baseline is 3. The description goes further by explaining the rationale ('so that count is a measurement') and the cost of setting it, which tells the agent why and when to enable it rather than just what it does.

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 ('Returns the state of the bridge host') and enumerates exactly what that state includes: version, start time, plugin generation, attach/detach counts, memory/GC, and leaked load contexts. It does not explicitly distinguish itself from nearby diagnostics siblings like server_info or flax_status, which keeps it from a 5.

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

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

The description gives a clear cost/benefit signal for the one parameter ('collect=true ... takes long on a large heap'), which is genuine usage guidance. However it never says when to prefer this tool over server_info, flax_status, or logs_tail, so the when-to-use routing 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?

With no annotations, the description carries the full burden and discloses strong traits: asynchronous return, single-job serialization, and the specific error (job_conflict naming the running job). It also describes what 'compile' does operationally (waits until the editor reloads and settles). It does not cover failure recovery, cancellation, or permission requirements, but the key behavioral profile is present.

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

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

Front-loaded with the core purpose and non-blocking semantics in the first clause, then layering kinds, conflict behavior, and follow-up. Every sentence, including the compile parenthetical, carries actionable information; nothing is redundant.

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

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

An output schema exists, so return values needn't be explained, and the description still ties results to the sibling sync tools. Combined with the async/conflict/follow-up guidance, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning by mapping each kind value to behavior ('compile ... wait until the editor has reloaded and settled', 'open_scene (path)') and tying path to the open_scene kind. This is meaning beyond the raw enum list 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 (Starts) and resource (a long editor operation as a job) and immediately clarifies it returns at once rather than blocking. The enumerated kinds and the note that its result matches editor_compile/editor_play_mode/editor_open_scene make it distinguishable from those synchronous siblings without opening their schemas.

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

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

Clearly establishes the usage context (long operations, non-blocking return) and names the follow-up tools (job_wait, job_status) plus the one-at-a-time constraint. The alternative blocking siblings are referenced only indirectly ('its result is what editor_compile... return'), so the explicit selection rule between this and those sync tools 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?

With no annotations, the description carries the full burden, and it does disclose the key trait that this is a full replacement, not a partial update, plus the read-before-write mitigation. It omits other consequential behavior: whether the actor must be in play mode (only hinted by "live"), what happens on an invalid or destroyed actorId, and whether the change is undoable.

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 waste. The operation and its return are stated first, then the safety instruction, so the most important constraint is 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?

An output schema exists, so return values need no explanation, and all four required nested parameters are covered by the schema. What remains thin is failure and precondition behavior for a mutation tool with no annotations; "live" gestures at a play-mode requirement without confirming 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 description coverage is 100% and each of the four parameters already documents its world-space meaning, so the schema does the heavy lifting. The description reinforces the replacement (all-or-nothing) semantics but adds no coordinate conventions, units, or quaternion normalization rules beyond the schema.

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

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

The description names a specific verb ("Replaces") and resource ("an existing live actor's world transform"), so an agent knows this is a full-overwrite transform mutation rather than a rename or reparent. It references editor_actor_details but as a prerequisite, not as a competing sibling, so no alternative-modifier tool is explicitly ruled out.

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 workflow: read with editor_actor_details first so unchanged transform components can be carried over. That is actionable context rather than inference. It stops short of stating when not to use this tool (e.g. for non-live or non-existent actors) or which sibling handles those cases.

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 no annotations, the description carries the full behavioral burden. It usefully discloses that the call is synchronous ('returns when it has loaded') and that it is refused during play mode. However, it does not explain what happens to any currently open scene or unsaved changes, which is important for an editor-state 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?

The description is three tight sentences with no wasted language. The core purpose is front-loaded, followed by path semantics and the play-mode restriction.

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 one-parameter editor tool with a full input schema and an output schema, the description covers the essential call behavior: what it does, how paths are resolved, and when it is refused. The main missing context is how it handles unsaved state in the currently open scene.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds useful meaning by explaining that the path can be absolute or relative to Content/ and by providing an example such as Scenes/Main.scene.

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: 'Opens a scene in the live Flax Editor.' It also states the synchronous completion behavior ('returns when it has loaded'), making it clearly distinguishable from listing or inspecting siblings such as scene_list and scene_outline.

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 path resolution relative to the project's Content folder and an example path. It also provides an explicit exclusion: 'Refused during play mode.' It does not name an alternative tool, but the when-to-use and when-not-to-use conditions are 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?

With no annotations present, the description carries the full burden and does meaningful work: it discloses that the call is synchronous ("Returns when the editor has reached the requested state") and bounded ("up to 30 seconds, so a heavy scene can load"). It does not mention side effects of entering play mode (script execution) or what happens if the 30-second window elapses without reaching the state, leaving a gap for a state-changing 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?

Three short sentences, front-loaded with purpose, then the constraint, then the blocking behavior. Every clause earns its place with no filler or redundancy.

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?

An output schema exists, so return values need not be explained. For a one-parameter state-transition tool, the description covers purpose, allowed values, blocking semantics, and the timeout bound, which is enough for an agent to call it correctly.

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

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

Schema coverage is 100% and the single parameter's schema description already lists start/stop/pause/resume, so the description's enumeration is largely a restatement. It adds no meaning beyond the schema, such as whether 'resume' is only valid from a paused state or whether 'start' is idempotent; baseline 3 applies when the schema does the heavy lifting.

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 ("Controls play mode in the live Flax Editor") and immediately enumerates the valid actions, so the tool's scope is unambiguous. It is clearly distinguishable from siblings like editor_wait_for or game_command, which deal with waiting or in-game commands rather than editor play mode.

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 implies usage (you invoke it with one of four actions to transition the editor's play state) but never states when to use it versus alternatives such as game_command, game_commands, or editor_wait_for. No exclusions or prerequisites (e.g., editing mode required) are given, so guidance is only implied by the enumeration of actions.

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 no annotations, the description carries the full burden. It usefully discloses that the rename is recorded in Undo/Redo history and that updated details are returned, which is real behavioral context. However, it says nothing about failure modes (e.g., duplicate name rejection), permission requirements, or whether 'loaded' implies an active scene prerequisite.

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 well-formed sentence with the mutation front-loaded and the two behavioral facts (undo history, return of updated details) appended efficiently. No wasted text.

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?

An output schema exists so return values need not be explained, and params are fully covered by the schema. But for a mutation tool with zero annotations, the description omits prerequisite conditions (active scene, actor existence) and error behavior, leaving meaningful gaps.

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

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

Schema description coverage is 100%, so both actorId and name are already documented in the schema, including the non-empty constraint and the GUID source (editor_scene_graph). The description adds no meaning beyond the structured fields, so the baseline 3 applies.

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

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

States a specific verb and resource ('Renames a loaded actor') and adds that it goes through the editor Undo/Redo history and returns updated details. It is clearly distinguishable from siblings like editor_delete_actor or editor_create_actor, though it does not explicitly contrast with editor_modify_actor, which could plausibly also rename.

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 'loaded actor' implies the actor must exist in the current scene, but there is no explicit when-to-use guidance or comparison to alternatives such as editor_modify_actor or editor_set_member. Usage is inferable from context rather than 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?

With no annotations, the description carries the full burden. It does disclose one important behavioral trait — the move is recorded in Undo/Redo history — and implies that all entities must already be loaded. It stays silent on failure behavior (e.g., invalid or cross-scene parents) and any confirmation or 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?

Two sentences, no filler, with the target-selection rule and the transform decision both front-loaded. Every clause contributes operational information.

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

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

An output schema exists, so return-value detail is not required. Still, for an unannotated mutation tool the description leaves gaps: it does not state what the unused ID should be set to (null vs omitted), what happens if the parent is in a different scene, or whether the actor must be unselected or unlocked.

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 only 25% (only actorId is documented), so the description must compensate, and it does: the mutual-exclusivity rule between sceneId and parentId and the meaning of preserveWorldTransform are both stated. This is real added value the schema alone does not convey, since the schema marks both ID parameters as required.

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 ('Moves a loaded actor') plus the destination targets (parent or scene root). It does not name or contrast with any sibling, but the operation is distinctive enough among the listed tools that misselection is unlikely.

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?

'Set exactly one of sceneId or parentId' is an explicit invocation constraint, and 'loaded' implies a prerequisite state for the actor, parent, and scene. However, there is no guidance on when to reparent versus use editor_modify_actor or editor_create_actor, and no when-not 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?

With no annotations to lean on, the description carries the load well: it discloses that API-made changes the editor does not mark as modified are still saved, that all modified content assets are included, and that play mode causes a refusal with a concrete reason (writing play-time scene state and runtime-created actor scripts). It does not cover edge cases like an empty scene list or permission/disk-error behavior, keeping it below 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 sentences, both front-loaded with the important information: the scope of the save first, the play-mode refusal second. Every clause earns its place—the parenthetical about unmarked API changes and the play-mode rationale are both non-obvious and actionable.

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?

An output schema exists, so return values need not be explained, and with zero parameters the schema imposes no burden. The description covers scope, side effects, and the one blocking precondition (play mode) thoroughly; only minor operational details (e.g., behavior with no open scenes) are absent.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no parameter semantics to add or omit.

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 ("Saves every open scene ... and all modified content assets") and scopes it to the live Flax Editor, so an agent immediately knows this is a persistence operation. It does not explicitly contrast itself with any sibling (e.g., scene_list, editor_open_scene, or build tools), so it falls short of the 5 bar for sibling differentiation.

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 clearly states the context of use (persist changes across open scenes and modified content assets) and gives an explicit exclusion: the tool is refused during play mode. It stops short of naming an alternative workflow (e.g., exit play mode first, or that in-editor edits must be marked modified), so there is no full when/when-not/alternative triad.

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 readOnlyHint=true; the description adds real value beyond that by disclosing that the result includes unsaved runtime state and by quantifying the truncation behavior (500 nodes or 32 levels) with the meaning of the truncated flag. It does not discuss payload size, cost, or whether truncation loses whole subtrees versus leaf nodes, which keeps it off a 5.

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

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

Two sentences, zero waste. Scope and the 'live/unsaved' qualifier come first, and the truncation caveat follows as a compact second sentence.

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 an output schema present, return-value shape needn't be restated, and the one non-obvious output trait (truncation) is explained. No parameters, read-only annotation, and the live-vs-saved distinction are all covered, so 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 for the description to disambiguate; the baseline for a 0-param schema applies. The description correctly avoids inventing parameter talk and instead spends its words on output behavior.

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: 'Returns the live actor tree from every scene loaded in the Flax Editor.' The 'every scene / including unsaved runtime state' scoping distinguishes it in substance from per-scene tools, but it never names the near-siblings (scene_outline, scene_list, editor_find_actors), so the agent must infer the boundary.

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?

There is no explicit 'use this when' or 'do not use for' statement. The phrase 'every scene loaded... including unsaved runtime state' implies the case where a whole-project live snapshot is wanted rather than a single-scene or single-actor lookup, but routing between this and scene_outline/editor_find_actors 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?

Since no annotations are provided, the description provides vital behavioral context. It explicitly mentions the environmental restriction (not headless mode) and a dependency on external state (output directory must exist).

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 concise, stating the function in the first sentence followed immediately by the critical operational constraints in the second.

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 the output format (PNG) and the necessary preconditions (existing directory, non-headless environment) are all detailed, the definition is contextually complete for an agent.

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 schema already provides a thorough description of the 'path' parameter (absolute/relative, .png). The description does not add further semantic meaning to the path itself, relying on the schema for structure.

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 tool clearly states its action: 'Captures the visible Flax Editor scene viewport to a PNG file.' This is specific and immediately distinguishes it from other editor functions like saving or manipulating actors.

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 provides two explicit conditions that dictate when this tool can or cannot be used: the output directory must exist, and it is unavailable in headless mode.

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 no annotations, the description carries full burden, and it does disclose the key behavioral trait that the mutation is routed through Undo/Redo history, plus that the target must be loaded. It does not say what error arises from an invalid actorId, whether the operation requires a specific editor state, or that existing values are overwritten.

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 sentence, front-loaded with the verb and resource, with no filler. The undo/redo clause is the only extra and it 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?

An output schema exists, so return values need not be explained. However, for a 4-required-parameter mutation tool with zero annotations, the description should cover prerequisites and failure modes; the nested vector objects and the undocumented isTrigger flag leave gaps.

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 75%, so the schema already explains size, center, and actorId (as a GUID from editor_scene_graph). The description restates the same three fields and adds only the "local" qualifier already present in the schema, leaving isTrigger 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?

States a specific verb (Updates) and resource (a loaded BoxCollider's local size, center, and trigger mode), which is precise enough to separate it from editor_create_box_collider and editor_box_collider_details. It never names those siblings explicitly, so differentiation is inferred rather than declared.

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 word "loaded" hints that the collider must already exist, but there is no explicit when-to-use statement, no exclusion pointing at editor_create_box_collider for new colliders, and no note about editor vs. play mode. The agent must infer call conditions entirely.

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 no annotations, the description carries the full burden and does so well: it discloses intermediate struct write-back, undo integration, scene-dirty marking and its interaction with editor_save, and that play-mode writes evaporate when play ends. It also notes the return is the value read back, covering mutation-reversibility and lifecycle questions an agent would otherwise have to guess.

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

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

Three dense sentences, each earning its place: what is written, what the value looks like, and the edit-mode/play-mode lifecycle difference. The core action is front-loaded in the first clause.

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 4-parameter mutation tool with no annotations but an output schema, the description covers the missing pieces — persistence, undo, mode-dependent lifetime, value encoding, and path traversal — without redundantly explaining return values beyond the one-line read-back note.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: dotted-path traversal with struct write-back, the concrete JSON shapes a value may take (number, true, "text", enum name, {"X":1,"Y":2,"Z":3}), and that scriptType targets a script member rather than the actor. Only the actorId semantics remain purely schema-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?

States a specific verb and resource — writes a field or property of an actor or its script by dotted path — which cleanly distinguishes it from the read-side sibling editor_get_member and from broader mutators like editor_modify_actor. The scope (actor vs. script member, dotted traversal) 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 operative context: edit mode routes through undo and marks the scene edited (with editor_save named as the persistence path), while play mode changes are transient until play ends. It does not explicitly name when to prefer a sibling such as editor_modify_actor or editor_set_selection, so it stops short of full routing 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?

With no annotations, the description must carry the behavioral burden. It does disclose the key overwrite semantic ('Replaces' rather than appends or toggles) and the clear-selection case, but says nothing about permission/auth needs, what happens with invalid or stale GUIDs, or whether the change is undoable in the editor.

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, zero filler. The primary action comes first and the edge-case behavior (empty list) follows, which is the right ordering for an agent scanning for the main effect.

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 a single fully-documented parameter and an output schema covering returns, the description is close to sufficient. The remaining gap is failure-mode behavior for invalid GUIDs, which matters somewhat for a state-mutating editor call but is not disqualifying.

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

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

Schema coverage is 100%, so the parameter's type and source are already documented. The description adds real meaning beyond the schema by defining the empty-array case as 'clear the selection', which is behavior the schema cannot express.

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 names a specific verb and resource ('Replaces the live Flax Editor actor selection') and the GUID-based input, which lets an agent distinguish it from the read-only sibling editor_get_selection. It stops short of explicitly contrasting itself with siblings by name, so it lands just below the top mark.

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: call this when you want to change the current selection, and empty the list to clear it. There is no explicit guidance on when not to use it, no mention of alternatives (e.g. editor_get_selection to read state first), and no prerequisites such as a live editor connection.

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 no annotations, the description carries the burden and does disclose two meaningful traits: the change goes through Undo/Redo history (reversible), and modelId is validated for compatibility before the scene is mutated. It does not cover failure behavior (what happens if validation fails) or whether the undo entry requires a transaction boundary.

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 waste, with the action and its mechanics front-loaded and the validation caveat following immediately.

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 tool is a simple two-parameter mutation with an output schema and full parameter documentation, so the description covers nearly everything needed. The remaining gap is failure/error behavior, which matters for a scene-mutating tool with no 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 100%, so baseline is 3; the description goes beyond it by stating that modelId must resolve to a compatible model before use and that the actor must already be loaded, adding validation semantics not present in the schema text.

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

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

States a specific verb (assigns), a specific resource (FlaxEngine.Model asset → StaticModel actor), and the mechanism (Undo/Redo history). It is clearly distinguishable from siblings such as editor_set_static_model_material or editor_set_member.

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 rather than stated: 'existing' asset and 'loaded' actor hint at prerequisites, and the schema points to editor_scene_graph and content_search as GUID sources. However, the description never names alternatives or states when not to use this tool (e.g., versus editor_set_member or the material setter).

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 no annotations, the description still discloses that the operation is tracked through Undo/Redo history and that the bridge validates the actor, slot, and material before mutating the scene. That covers the main mutation safety and reversibility traits, though it omits failure behavior, permissions, and other 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?

Two sentences, front-loaded with purpose and followed by the key behavioral caveat. There is no filler or repetition.

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?

An output schema exists and all parameters are fully described in the schema, so the description need not explain return values or parameter formats. It covers the mutation, Undo/Redo, and validation well, though it lacks explicit usage guidance and failure-mode details.

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

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

Schema description coverage is 100%, so actorId, slotIndex, and materialId are already fully documented in the schema. The description mentions actor, slot, and material in prose but adds no parameter syntax or format beyond what the schema provides.

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 ('Assigns') and resource ('existing FlaxEngine.MaterialBase asset to one slot of a loaded StaticModel'), so the purpose is unambiguous. It does not explicitly differentiate from sibling tools such as editor_set_static_model, which keeps it from a 5.

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 no explicit when-to-use, when-not-to-use, or alternative-tool guidance. The agent can infer that this tool is for assigning a material to a loaded StaticModel slot, but the description does not route it against alternatives.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds the useful qualifier 'live' (runtime actor state, not just the asset reference) and that it covers both the model reference and actor details, but says nothing about failure behavior when the actorId is invalid or not loaded.

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 front-loaded sentence with no filler. The resource type and the two returned artifacts are stated immediately, so nothing needs to be 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?

An output schema exists, so return values need not be explained, and the tool is a simple one-param read with full schema coverage. The only remaining gap is not positioning it relative to editor_actor_details, but for a read-only detail lookup the description is essentially sufficient.

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

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

Schema description coverage is 100% and the actorId property already documents its origin ('StaticModel actor GUID from editor_scene_graph'), so the schema carries parameter semantics. The description adds no further detail on the identifier or on what happens with a non-StaticModel actor, making baseline 3 appropriate.

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 ('returns') plus a precise resource ('assigned model reference and live actor details for a loaded StaticModel actor'). It is clearly distinguishable from editor_set_static_model (which mutates) but doesn't explicitly contrast itself with the adjacent editor_actor_details, which plausibly covers overlapping ground.

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