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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds real behavioral context beyond them: 'Uses Undo' tells the agent the mutation is reversible, and the duplicate warning signals the operation is not self-deduplicating. It omits what happens on failure (e.g., component already 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?

Three short sentences, front-loaded with the action and followed by the undo note and a compact example. Slightly redundant since the example restates the schema's own field examples, but there is no padding or wasted prose.

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

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

For a two-parameter mutation with annotations covering safety and an explicit undo note, the definition is nearly complete. The remaining gap is failure/return behavior on duplicate or invalid component types, which is not addressed despite the warning about duplicates.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema, and the inline example duplicates those field examples rather than extending them. Baseline 3 is appropriate; the example adds only marginal call-shape value.

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

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

States a specific verb+resource+target: 'Add a component by type name to a GameObject.' An agent can distinguish it from the read-side sibling unity_get_components and from unity_attach_script, which the description implicitly excludes by scoping to generic component types.

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

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

Gives an explicit precondition: 'Check unity_get_components first to avoid duplicates,' naming the sibling to consult. It does not clarify when to prefer this over unity_attach_script for script components, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=true, but the description adds genuinely new context: that the operation is Undo-able and that it propagates to all instances once saved, plus a specific failure mode. That side-effect disclosure is exactly the kind of behavioral value annotations don't carry.

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

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

Two front-loaded sentences: the main action with its caveat first, then the argument note. It is tight and wastes little, though the parenthetical caveat slightly interrupts the flow.

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

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

For a single-parameter mutation tool with no output schema, the description covers purpose, side effect, reversibility, and failure behavior, which is nearly everything an agent needs. Only explicit sibling routing is absent.

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

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

Schema description coverage is 100% with the single parameter fully documented, including an example path, so the schema does the heavy lifting. The description restates the same 'Level/Enemy_1' example without adding format or constraint details beyond it, so 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 ('Apply') and resource ('an instance's overrides back to its prefab source'), clearly distinguishing it from siblings like unity_instantiate_prefab. An agent can immediately tell this pushes instance-level changes up to the prefab asset.

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

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

Provides a clear precondition ('Fails with hint if the object is not a prefab instance') and a consequence warning ('affects all instances once saved'), which frames when the tool is appropriate. It stops short of naming an alternative sibling or an explicit when-not scenario, so it lands at 4 rather than 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered by structured data. The only behavioral addition is the recursion/dependency semantics, which the schema itself also states via the recursive default. It discloses nothing about output shape, cycle handling, or performance on large graphs.

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 plus a short args line; the core purpose is front-loaded and the 'Use when' guidance follows immediately. Every sentence earns its place and nothing is padded.

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, fully-annotated, 3-parameter tool with 100% schema coverage and no output schema, the description supplies everything an agent needs to call it correctly: what it returns, that it is recursive by default, and when to reach for it. No meaningful gap remains.

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 path, recursive and response_format are already fully documented in the schema. The description merely restates the Args list, adding no syntax, format, or edge-case meaning beyond what the structured field provides — 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 ('List what an asset depends on') and grounds it with concrete examples (textures of a material, scripts of a prefab), which separates it from the sibling unity_list_assets. An agent knows exactly what this returns 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?

The 'Use when:' clause gives two concrete decision contexts — impact analysis before moving/deleting an asset, and diagnosing why a prefab pulls in the project. It stops short of naming an alternative tool or an explicit when-not-to-use condition, so it is clear context rather than 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?

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=false), so the description isn't carrying that burden. It adds genuine behavioral detail beyond the annotations: the operation is Undo-able, it requires prior compilation, and it fails with a hint on class-not-found. It doesn't cover what happens if the class already exists on the object.

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?

Extremely tight: one sentence for purpose, one for the precondition, one line of args, one line for the failure mode. The core action is front-loaded and every sentence earns its place.

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

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

For a 2-param mutation with no output schema, the description covers purpose, precondition, and failure behavior, which is close to complete. The main remaining gap is the lack of a stated distinction from unity_add_component.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the same 'Player'/'PlayerController' examples. The description adds nothing beyond that baseline, so a 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: 'Attach a MonoBehaviour class to a GameObject'. An agent immediately knows this attaches a script component to an existing object. It does not explicitly differentiate itself from the sibling unity_add_component, which is the nearest ambiguous neighbor.

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

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

Gives a real precondition ('Script must be compiled — no compile errors in console') and a failure path, which is useful context. However, it never states when to prefer this over unity_add_component or what to do if the GameObject path is invalid, so the when-to-use guidance is only implied.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral detail by naming the two buffers affected (bridge log cache and Editor log view), telling the agent what is actually lost. It does not say whether the prior logs are recoverable or whether a specific mode is required.

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 stated first and the usage condition second. Nothing repeats the tool name or title verbatim.

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 parameterless, non-returning action with annotations covering safety and idempotency, the description supplies what and when. The only minor gap is not stating the result of the call (e.g. that nothing is returned), which is low-stakes for this operation.

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, which is the baseline-4 case: there is nothing for the description to disambiguate. The schema is a closed empty object, so no parameter semantics are needed.

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 ('Clear the Unity console buffer') and scopes it further ('log cache in the bridge + Editor log view'), which is more precise than the bare name. It is clearly distinct from the read-side sibling unity_get_console_logs, but never names that sibling, 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?

The 'Use when' clause gives a concrete triggering scenario: establishing a clean baseline before reproducing an error. That is real context rather than an implied usage. It offers no when-not guidance or named alternative, so it is short of a 5.

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

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

Annotations already declare the safety profile (not read-only, idempotent, non-destructive), and the description adds real behavioral detail beyond them: what state is mutated (override flag, throttle/steer values) and that queued shots are discarded. It does not cover auth/permission needs or what happens if no override is active, so it stops short of a 5.

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

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

A single sentence with the human-facing intent front-loaded and three concrete effects trailing it. Every clause carries information; 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?

With no parameters, no output schema and a simple state-reset scope, the description gives enough for correct invocation and covers the side effects an agent should anticipate. Only minor gaps remain (error/no-op behavior when no override is active).

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

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

The tool takes zero parameters, so there is no schema surface for the description to compensate for; the baseline for a no-param tool is 4. The description correctly conveys that the operation is argument-free.

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 and enumerates the concrete effects: disables the override, zeroes throttle/steer, drops queued shots. It reads clearly as the inverse of the sibling unity_set_player_input, but never names that sibling, so differentiation is inferred rather than 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?

"Hand control back to the human" implies the situation (an override is currently active and you want to release it), but there is no explicit when-to-use/when-not statement and no alternative tool is named. Usage 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?

Annotations declare the mutation/safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds genuinely useful context beyond them: the operation uses Undo and is revertible, and results are not saved until unity_save_scene runs. That persistence and undo behavior is not derivable from the annotations.

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

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

Well-structured and front-loaded: a purpose sentence, a compact Args line, a Returns line, and a follow-up action. Every sentence earns its place with no filler.

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

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

For a mutation tool with no output schema, the description covers the operation, key args, the return shape ({ path, name }), and a required follow-up (save). It's largely complete; only the prefab-vs-primitive routing gap keeps 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?

Schema description coverage is 100%, so all six parameters are already documented in the schema. The description's Args line restates them with defaults but adds no syntax or format detail beyond what the schema provides, which is the baseline-3 case.

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+resource ('Create an empty GameObject or a Unity primitive') and even enumerates the supported primitive types. However, it doesn't differentiate from the similar sibling unity_instantiate_prefab, which also creates objects, so an agent can't fully route by reading this alone.

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 a workflow cue ('Save with unity_save_scene when done') that implies changes are not persisted until saved, and mentions Undo reversion. But it never states when to use this versus alternatives like unity_instantiate_prefab, leaving selection to inference.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), so the bar is lower. The description adds real behavioral context beyond that: the AssetDatabase refresh side effect, the resulting Unity compilation, and the ordering constraint that you must wait for compilation before attaching. It does not, however, describe failure modes when overwrite is false and the file exists.

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

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

Front-loaded with the action, then the side effect, then a compact Args block and a closing workflow note. It is efficient, though the Args enumeration partly duplicates what the schema already says.

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

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

For a mutating creation tool with annotations and no output schema, the description covers the essential behavior: template-based creation, AssetDatabase refresh, and the compilation-wait step needed before attaching. Missing only edge-case handling such as existing-file behavior, which the overwrite flag partially implies.

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 all four parameters including the class_name/file-name constraint and enum values. The description largely restates those fields (example path, template list, defaults), so baseline 3 applies with no meaningful addition.

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 clear verb+resource: 'Create a script from a Unity 6 template.' This distinguishes it from read/update/list siblings by action. It does not explicitly name an alternative (e.g. unity_update_script), 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?

There is workflow guidance ('After creating, wait for compilation (console check) before attaching'), which implies this is a prerequisite step for unity_attach_script. However, there is no explicit statement of when to use this versus unity_update_script or unity_list_scripts, so usage 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?

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuine non-obvious context the annotations cannot convey: the operation is Undo-able in the Editor but becomes file-wise destructive once the scene is saved. It omits failure modes (e.g., behavior when the path doesn't exist) but adds real value.

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 core action and its destructive caveat are front-loaded, and the second sentence is a directly actionable instruction.

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

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

For a single-parameter destructive tool whose annotations carry the safety hints and with no output schema to explain, the description covers what it does, how to obtain the argument, and the durability risk. The only gap is error/not-found behavior, which is minor 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%, so the path parameter's format and example are already documented, giving a baseline of 3. The description adds meaning beyond that by naming the canonical source of the value (unity_find_gameobjects) and stressing that it must be exact, which reinforces correct usage.

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 (Delete) and resource (GameObject) with the identifying key (path). It is unambiguous against siblings like unity_create_gameobject or unity_set_transform, and the parenthetical scope note clarifies what deletion actually means.

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

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

Explicitly tells the agent to source the path from unity_find_gameobjects and to double-check before calling, which is real routing guidance to a sibling. It stops short of stating when-not to use it or what to do if the path is ambiguous, so it is clear context rather than full when/when-not guidance.

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

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

Goes far beyond the annotations: enumerates the sandbox blocklist (filesystem, processes, network, reflection-load, Application.Quit, while(true)), warns that it runs on the main thread and infinite loops hang the Editor, and states the opt-in gating. destructiveHint=true is consistent and richly substantiated.

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

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

Front-loaded with purpose and the polling contract, then cleanly segmented into 'Code rules', 'Sandbox blocks', and 'Requires'. Slightly long and the code rules partly duplicate the schema, but every section carries essential caveats for a sandboxed code tool.

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 high-risk execution tool with no output schema, it covers the async result path, latency, sandbox constraints, thread behavior, and the opt-in prerequisite — everything an agent needs to call it safely and correctly.

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

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

Schema description coverage is 100%, so the schema already documents both params, including the bare-statement/return semantics for 'code'. The description largely restates those code rules and never mentions timeout_s, so it adds little parameter meaning beyond the schema.

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

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

States a specific verb+resource ('compile and run bare C# statements inside the Unity Editor') and names the execution mechanism (Roslyn/AssemblyBuilder). It is unambiguously the only code-execution sibling among read/set/create/delete tools.

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 the async workflow explicitly ('Returns a job_id immediately — poll unity_get_code_result'), the compile latency, and the hard prerequisite ('Requires: mutations ON + Enable C# execution... off by default'). It doesn't explicitly say when to prefer a dedicated sibling (e.g. unity_set_transform) over writing raw C#, so it stops short of full when-not guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context by stating the operation is paginated and by describing the return shape.

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

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

The description is front-loaded with the purpose and constraint, then gives compact examples and a return-shape summary. Every element is useful 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?

It helpfully covers the search intent, filter examples, pagination, and return fields despite there being no output schema. However, it does not resolve the critical gap that the input schema defines no filter or pagination parameters, leaving invocation details incomplete.

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 description references filter parameters (name_contains, tag, with_component) and says at least one is required, but the input schema exposes zero parameters. This mismatch prevents an agent from knowing how to pass filters or pagination inputs correctly.

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: search GameObjects by name substring, tag, or component type. This clearly distinguishes it from siblings like unity_get_hierarchy or unity_get_object_info, which retrieve rather than search.

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

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

It states that at least one filter is required and provides filter examples, which gives some usage context. However, it does not explain when to use this tool instead of alternatives such as unity_get_hierarchy or unity_get_scene_info.

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, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds a real behavioral trait beyond the structured data: large folders are truncated with a note, and detail requires drilling into subfolders. Return-format behavior is not described, keeping this from a 5.

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

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

Front-loaded with the core purpose and kept to three tight sentences. The 'Args:' line largely restates the schema defaults and is the one mildly redundant element.

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 tree tool whose annotations carry the safety profile and which has no output schema, the description covers purpose, defaults, and the truncation caveat. Only the shape of the returned tree (markdown vs. json) is left unexplained.

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 is 3. The description echoes folder default 'Assets' and the depth 1-5 (default 3) range that the schema already documents, and it omits any mention of the response_format enum parameter.

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

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

States a specific verb and resource ('Map the project folder tree') and scopes it ('up to a depth', 'Read-only overview of how the project is organized'). An agent can tell this is the folder-tree mapper, but the description never names or contrasts a sibling like unity_list_assets, 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?

'Read-only overview of how the project is organized' implies the context of use, and the truncation note gives practical guidance ('drill into subfolders for detail'). However, there is no explicit when-to-use vs. when-not or any pointer to unity_list_assets / unity_asset_dependencies for alternative views.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: the polling model, the three terminal/intermediate states, and what output/logs contain. It stops short of stating timeout or backoff behavior, so not a 5.

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

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

Front-loads the state model, then the usage condition, then the return semantics. Three tight sentences with no wasted words.

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

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

There is no output schema, so the description must explain returns, and it does: output is the JSON of the 'return' value and logs are Debug.Log lines from Run(). Combined with the state enumeration, an agent has everything needed to call and interpret this 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% and the single job_id parameter is fully documented in the schema. The description only reinforces its origin ('job_id returned by unity_execute_code'), which adds marginal value over the schema. 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+resource ('Poll a code-execution job') and enumerates the three result states (running | done | error). This clearly distinguishes it from unity_execute_code (which starts the job) and unity_get_console_logs (which reads the console directly).

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

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

Explicitly states when to use it ('after unity_execute_code returned a job_id') and what to do on the running state ('wait and poll again'). The triggering condition and the predecessor tool are named, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description contributes the useful detail that results include enabled flags, but says nothing about result shape, ordering, or limits on large hierarchies. With annotations doing the heavy lifting, a 3 is appropriate.

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 core action stated first and the usage condition immediately after. Every sentence earns its place.

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

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

For a simple read-only inspection tool with full annotation coverage, a fully documented schema, and no output schema, the description covers what it does and when to reach for it. The only gap is the exact shape of the returned list, which is minor given the tool's simplicity.

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% - both 'path' (with format examples) and 'response_format' (enum) are fully documented in the schema. The description adds no parameter-level meaning beyond that, 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?

The description gives a specific verb and resource ('List all components on a GameObject') plus a scope detail ('with enabled flags'). It is clearly distinguishable in intent from siblings like unity_get_object_info or unity_add_component, though it never names them 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?

It provides an explicit 'Use when:' trigger - inspecting an object's behaviour/rendering before modifying it - which is a clear context for invocation. It stops short of stating when not to use it or naming an alternative (e.g. unity_get_object_info) for adjacent needs.

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

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

Annotations already establish the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), so the lower bar applies. The description still adds real behavior: entries are buffered rather than live, returned most-recent-first, and default to warning+error. The note that json includes stackTrace is a genuinely useful disclosure not present in the structured data.

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?

Five terse fragments with zero filler, and the core action (reading buffered entries, ordering, filtering) is front-loaded before the usage and format notes.

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

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

There is no output schema, so the description must carry the return semantics, and it does so partially by noting stackTrace inclusion under json and warning+error defaults. It does not describe the markdown entry shape or how truncation interacts with max_logs, leaving minor 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 is 3 and the schema already carries most parameter meaning. The description adds value by explaining what the json response_format actually yields (stackTrace included) and restating the default type set, going slightly beyond the enum's 'machine-readable' phrasing.

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

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

States a specific verb and resource: 'Read buffered Unity console entries, most recent first' plus the ability to 'Filter by type.' This clearly separates it from write-side siblings like unity_clear_console, though it never names a sibling explicitly to sharpen 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?

Provides concrete usage triggers: 'summarize warnings/errors', 'check console after my change', and 'verifying a fix.' That is clear when-to-use context, but there are no explicit exclusions or pointers to alternative tools (e.g., unity_get_code_result for execution output).

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, idempotentHint and non-destructive, so the safety profile is covered. The description adds useful behavior the schema cannot: it is a single-call full snapshot (avoiding per-tank polling) and the return is parse-friendly JSON. It does not disclose snapshot timing or coordinate-frame caveats.

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 dense sentences: the return contract first, the usage cue second, with 'reload fraction (1 = ready)' giving a precise unit inline. No filler.

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

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

With no output schema, the description carries the burden of describing the return value and does so field by field, plus format guidance. Minor gaps remain around the JSON envelope shape and when the snapshot is taken, but nothing that would cause a mis-call.

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

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

The tool takes zero parameters, so there is no parameter surface for the schema to document and the baseline is 4. The description correctly spends no effort on arguments and instead documents the shape of what comes back.

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 ('one-call snapshot') and enumerates the exact returned state: per-tank team, hp/maxHP, alive, position, yaw, reload fraction. That field-level specificity makes it unmistakably distinct from generic siblings like unity_get_scene_info or unity_get_hierarchy.

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

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

Gives a clear usage window tied to a named sibling: 'Use in the drive loop before each unity_set_player_input.' It supplies the sequencing context an agent needs but names no exclusions or alternatives (e.g., that unity_get_object_info is for single-object inspection instead).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that: it discloses pagination behavior and enumerates the returned envelope fields (total, count, offset, items, has_more, next_offset), which is more than the annotations provide.

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

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

Front-loads the one-line purpose, then args, then usage and return shape; every sentence is functional. The Args block partly duplicates the schema descriptions, which is mild redundancy but aids fast scanning.

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

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

With no output schema, the description takes on the burden of describing the return: a markdown list plus a structured object with total/count/offset/items/has_more/next_offset. Combined with the pagination parameters and usage routing, an agent has everything needed to call and consume the result correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds semantics beyond the schema: it specifies that root_only=false surfaces one level of children under a 'children' key, whereas the schema only says 'include full tree'. That added precision is useful, though it also slightly diverges from the schema wording.

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

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

States a specific verb and resource ('List root GameObjects of the active scene') plus scope qualifiers (components summary, paginated). It explicitly distinguishes itself from the sibling search tool, so an agent can route 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?

'Use when: exploring what is in the scene' gives the positive trigger, and 'For search use unity_find_gameobjects' names the alternative and the condition that selects it. Both when-to-use and when-to-use-something-else are present.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the useful scoping fact that it returns exactly one object by path, but says nothing about failure modes (invalid path), or cost of traversal. With annotations carrying the behavioral burden, this is adequate but not rich.

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

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

Two short sentences, front-loaded with the primary capability, then the path syntax, then the sibling hand-off. Zero filler.

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

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

With no output schema, the description carries the return-value burden and does list the returned fields (transform, tag/layer, components), which is sufficient for a simple read tool whose annotations already cover safety. Only the absence of error/path-not-found behavior keeps it short of 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 100% and both parameters are documented with examples and an enum, so the schema does the heavy lifting. The description's path example ('Level/Enemies/Orc') duplicates the schema's own example, adding no new semantics.

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 (get full details), a specific resource (one GameObject), and the scoping constraint (by hierarchy path), plus enumerates the returned contents (transform, tag/layer, components list). It distinguishes itself from unity_find_gameobjects, but the 'components list' overlap with unity_get_components is left unaddressed.

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

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

Gives an explicit routing rule: use unity_find_gameobjects first when searching, then call this with the resolved path. That is clear context, but there is no guidance on when to prefer this over unity_get_components or unity_get_hierarchy, and no exclusion conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds non-obvious behavioral context beyond the annotations: play-mode edits being discarded on stop, which materially affects downstream decisions.

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 no wasted words. The return values are front-loaded and the usage rationale follows immediately, so the most decision-relevant information comes first.

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

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

With no parameters, no output schema, and full annotation coverage, the description covers what an agent needs: what is returned and why to call it. A brief note on state-transition timing or refreshed-after-call behavior would make it 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?

The tool takes zero parameters, so the baseline of 4 applies. The description usefully documents the shape of the return value as an enum-like state, which is meaningful given no output schema exists.

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 (Report) and resource (play mode state) plus the exact response vocabulary (stopped|playing|paused), so the agent knows precisely what it returns. It does not, however, distinguish itself from the similarly named sibling unity_get_game_state, leaving a small ambiguity.

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

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

Explicitly tells the agent when to call it: 'Use before set or before assuming edits apply'. It even supplies the reason (edits in play mode are discarded on stop), which is exactly the kind of when-and-why guidance that prevents wrong sequencing with unity_set_play_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?

Annotations already declare readOnly, idempotent, non-destructive, and non-open-world behavior, so the safety profile is fully covered without the description repeating it. The description adds genuine value beyond the annotations by spelling out the return payload shape in the absence of an output schema.

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

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

Three short, front-loaded lines: the what, the when, and the return shape. Every sentence 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?

With no output schema, the description compensates well by listing the return fields, including the nested activeScene sub-fields. Minor residual gap: the meaning of values such as playMode (e.g., which states exist) and isDirty is left implicit.

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

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

The tool takes zero parameters, so there is nothing for the description to document beyond what the (empty) schema conveys; the baseline for a parameterless tool is 4. No syntax or format detail is needed.

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 ('Get') and resource ('project info') and enumerates exactly which fields are returned (name, path, version, active scene, play mode), which separates it from generic object/component getters. It does not, however, explicitly differentiate itself from siblings that overlap on returned data, such as unity_get_scene_info and unity_get_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?

'Use when: starting a session to orient yourself in the project' gives a clear triggering context, which is exactly the right guidance for an aggregate orientation call. There is no statement of when NOT to use it or which sibling to prefer when the agent only needs play-mode or scene data.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations by enumerating the returned fields (name, path, dirty flag, root count, build index), which helps an agent understand the payload without an output schema.

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

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

Two sentences with zero filler; the returned fields are front-loaded and the usage condition follows immediately. 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?

For a no-parameter, read-only, idempotent tool with full annotation coverage but no output schema, the description supplies the missing return-field detail and a clear usage trigger. Nothing an agent needs to invoke it correctly is absent.

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

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

The tool takes zero parameters, so parameter semantics are moot and the baseline is 4. The description correctly does not waste space explaining 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 ('Get') and resource ('active scene'), then enumerates the exact fields returned: name, path, dirty flag, root object count, build index. This clearly differentiates it from sibling tools like unity_get_hierarchy or unity_get_object_info, which target different resources.

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

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

Explicitly says 'Use when: you need to know which scene is open before querying hierarchy,' giving a concrete precondition. It does not name alternative sibling tools or state when-not to use it, but the context is clear enough for correct 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?

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description's note that 'reimporting twice is harmless' echoes idempotentHint but adds a concrete operational reassurance rather than pure repetition. It doesn't mention the read-only/write nature or side effects on the asset database beyond what annotations cover.

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 with purpose front-loaded and the idempotency note as a useful suffix. No wasted words.

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

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

A single-param tool with full schema coverage and annotations covering safety/idempotency needs little more. The description covers what and a key behavioral trait; only minor usage guidance against the refresh sibling 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 description coverage is 100% and the schema documents the path param with format and example. The description's example is redundant, adding no meaning beyond the schema.

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

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

States a specific verb (reimport) and resource (an asset), and clarifies the purpose with 'picks up external file changes'. The sibling unity_refresh_assets is adjacent but the description's focus on a single asset vs. a global refresh gives enough distinction.

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 parenthetical 'picks up external file changes' implies when the tool is useful, but there's no explicit when-to-use vs. unity_refresh_assets or unity_list_assets. Usage is inferable but not stated.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent, so the bar is lower; the description adds two useful traits beyond them: the operation is Undo-able and the prefab link is preserved for later overrides. It omits whether edit vs. play mode is required and what happens on a duplicate path.

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

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

Front-loaded with the core action and two key behavioral facts in one sentence, then a compact Args summary and a routing hint. The Args line partially duplicates the schema, so it isn't perfectly waste-free, but nothing is padded.

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

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

Covers purpose, required input discovery, side-effect profile, and prefab-link behavior for a 5-param mutation tool with no output schema. The remaining gap is the return value (instance identity/handle) and any play-mode precondition, which an agent would likely want.

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 every parameter including defaults (name, position, rotation, parent_path) is already documented in the schema. The description's Args line restates the same fields without adding format or constraint detail beyond the example path already in the schema. Baseline 3.

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 (instantiate) and resource (prefab from asset path) plus the target scene, and the prefab-link retention clause distinguishes it from unity_create_gameobject and unity_apply_prefab. An agent can route to 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?

Explicitly routes the agent to unity_list_assets type='Prefab' to obtain the required prefab_path, which is real precondition guidance. It stops short of stating when not to use it (e.g., vs. create_gameobject or apply_prefab) and doesn't mention scene/play-mode prerequisites.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description adds that results are paginated and the default folder scope, but says nothing about return shape, ordering, or behavior when no assets match.

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 compact, front-loaded sentences with a usage trigger; nothing is padded. The Args recap is somewhat redundant with the 100%-covered schema but remains brief.

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 paginated read with full schema coverage and rich annotations, the definition is nearly sufficient. The only real gap is that the response_format parameter (markdown vs json) and the resulting output shape are not mentioned, which matters since no output schema exists.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema; the description's Args line largely restates them. It adds no syntax or format detail beyond what the schema provides, matching the baseline of 3.

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 (browse/find) and resource (AssetDatabase assets), plus the filtering dimensions (folder, name substring, type) and pagination. An agent can distinguish it from scene-object tools like unity_find_gameobjects, though the description never names that distinction 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?

"Use when: locating prefabs, materials or textures before instantiating or assigning them" gives a clear contextual trigger. There are no explicit exclusions or named alternatives (e.g. vs unity_folder_structure or unity_find_gameobjects), so it falls short of 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds useful behavior beyond that: results are paginated, default folder is 'Assets', and each entry carries a size. Return-field detail is still absent, but with annotations handling the safety profile this is a solid addition.

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 lines: purpose first, then args, then usage. Every sentence carries information and nothing is padded.

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

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

No output schema exists, but the description compensates by naming the returned content (file paths plus sizes) and the pagination model. It does not specify ordering of results or how 'sizes' are reported, which is a minor remaining gap for a listing 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%, so the schema already documents folder, filter, limit, offset and response_format with defaults and bounds. The description only restates default 'Assets', 'filter substring (optional)' and 'limit/offset', adding no syntax or formatting meaning beyond the schema.

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

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

States a specific verb (List), resource (.cs files), scope (under a project folder), and extras (sizes, paginated), which an agent can distinguish from unity_read_script or unity_list_assets. It does not explicitly name a sibling it is not, 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?

The 'Use when: finding where game code lives before reading or editing it' line gives a clear activation context and implicitly routes to unity_read_script/unity_update_script as the follow-ups. No explicit exclusions or named alternatives are provided, so it is not a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds value by disclosing what the check returns (reachability plus Unity/editor versions) and by advising against redundant re-pinging, though it does not detail failure modes or latency.

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 with the action front-loaded, followed by tightly labeled Use/Don't-use guidance. Every clause earns its place with no filler.

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

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

For a zero-parameter health-check tool with no output schema, the description supplies everything needed: what it verifies, what it reports, and when to invoke it. Nothing an agent needs 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?

Zero parameters with 100% schema coverage, so the baseline of 4 applies. There is nothing for the description to clarify beyond what the empty schema already conveys.

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 (check) and resource (Unity Editor bridge reachability) plus an extra behavior (report Unity/editor versions). It is unmistakably the health-check tool and cannot be confused with any of the mutating or querying 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?

Explicitly names when to use it (before any other Unity tool, on connection errors) and when not to (already have a fresh successful response). Both the trigger and the exclusion are spelled out, leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real behavior: pagination via start_line/max_lines, the line-number prefix format, and the read-before-write requirement. It doesn't mention error behavior for missing files, but the added context is substantive.

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 purpose in the first sentence, usage rule second, then a compact Args/Returns block. No filler sentences; every line 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?

With no output schema, the description usefully documents the return shape ({ path, total_lines, start_line, content }) and the line-prefix convention. It omits the response_format parameter and any note on pagination end conditions (total_lines matters for continuing), leaving a small gap for a paginated reader.

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 all four parameters are already documented, including defaults and the path example. The description restates default values for start_line and max_lines without adding format or edge-case meaning, 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+resource ('Read a script') plus the distinguishing scope ('with line numbers, paginated'), which cleanly separates it from unity_list_scripts, unity_create_script, and unity_update_script. An agent can identify the operation 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?

'Always read before updating' gives explicit workflow guidance and implicitly routes the agent here before unity_update_script. It stops short of stating exclusions (e.g., when to use unity_list_scripts instead for discovery), so it is clear context without full when-not coverage.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so 'Idempotent' in the description merely repeats structured data. The description does add the effect scope (reimport + recompilation), but omits practical side effects such as domain reload or Editor blocking, which matter for a non-readOnly trigger.

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 with zero waste: the purpose and API anchor come first, the usage condition follows. Nothing redundant beyond the single repeated 'Idempotent' token.

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, no-output tool whose annotations already carry the safety profile, the description covers what it does and when to invoke it. The only shortfall is the absence of any caution about the cost of a full reimport/recompile.

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; there is no parameter meaning for the description 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?

States a specific verb and resource: 'Trigger Unity asset reimport + script recompilation', anchored to the named API AssetDatabase.Refresh. The scope is concrete, but it never differentiates itself from siblings like unity_import_asset or unity_list_assets, so an 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?

Gives an explicit when-to-use condition: files written from outside the Editor (scripts, models, textures) that Unity hasn't picked up yet, with a concrete example of unfocused background work. It offers no when-not or named alternative, but the trigger condition is clear enough to act on.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so the safety and repeat-call profile is covered. The description restates idempotency (redundant with annotations) and adds the underlying implementation (AssetDatabase + EditorSceneManager.SaveOpenScenes), but says nothing about failure modes, e.g. what happens outside play mode or on unsaved new scenes.

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 lines, front-loaded with the action, then the trigger condition, then the repeat-call behavior. No filler or restatement of the title.

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

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

For a zero-parameter, no-output tool whose annotations already carry the safety profile, the description covers purpose, trigger and idempotency adequately. Only the absence of any note about error conditions keeps it from being fully complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter-related gaps exist.

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 ('Save the active scene to disk') and even names the underlying APIs used. No sibling tool performs a save, so the agent can immediately distinguish it from the get/create/transform tools.

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

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

'Use when: after create/delete/transform batches so work is not lost' gives a concrete trigger condition tied to specific sibling operations. It stops short of naming alternatives or stating when-not to call it, but no plausible alternative exists in this toolset.

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

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

Annotations already establish readOnly=false, idempotent=true, destructive=false, so the safety profile is covered. The description adds real behavioral value beyond that: it discloses that values are parsed as JSON and that a non-settable property fails with an allowed-type hint that should be read and retried. Remaining gaps are minor (no return-value or edit-vs-play-mode scope notes).

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

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

Purpose is front-loaded in the first sentence, followed by examples and a single actionable error note — each element earns its place. The example payloads overlap with the schema's own examples, which is mild redundancy but still useful for showing the fields in combination.

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-required-param mutation tool with no output schema, the description covers the operation, value encoding, and the failure/recovery path, while annotations carry the safety profile. It stops short of stating what is returned or whether the change takes effect in play mode, but nothing critical to invoking 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 description coverage is 100%, so every parameter is already documented with examples in the schema. The description's example payloads restate the same field semantics rather than adding new constraints, which is the expected baseline 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+resource: 'Set one serialized property/field on a component,' with concrete examples for Rigidbody.mass and Light.intensity. The operation is unambiguous, but it never differentiates itself from siblings that also mutate component state (notably unity_set_transform), so an agent can't tell whether Transforms should go through here or the dedicated tool.

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

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

The examples imply the usage pattern (single property writes on a component) and the closing sentence gives an error-recovery hint, but there is no explicit when-to-use statement and no named alternative for the same job. 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?

Annotations declare this is a non-readonly, non-idempotent, non-destructive write, and the description adds genuinely non-structured context: the physical keyboard is ignored while override is on, and fire is edge-triggered so one call queues exactly one shot. It stops short of describing override persistence/expiry or the shape of the polled result, so it is strong but not exhaustive.

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

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

Two short, front-loaded blocks: the behavioral rules first, then the invocation loop and exit path. Every sentence carries actionable content with 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?

With no output schema and a 3-parameter fully-documented input, the definition covers the essentials: what it controls, how fast to call it, and how to relinquish control. The only soft spot is 'poll result', which does not name the tool that returns the outcome, leaving a small gap for an agent mid-loop.

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 each parameter already documents its semantics (fire edge-triggered; steer/throttle -1..1). The description restates the throttle/steer mapping and the one-shot fire rule without adding syntax, units, or edge cases beyond the schema, so 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?

The description states a specific verb and resource ('Drive the player tank remotely') and explains exactly how the inputs map ('throttle/steer become the TankController input'). It also names the counterpart sibling (unity_clear_player_input) and the related read tool (unity_get_game_state), so an agent can distinguish it without opening any schema.

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

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

It gives an explicit operating loop (get_game_state -> decide -> set_player_input, repeated ~2-5x/sec -> poll result) and states when to stop overriding ('Call unity_clear_player_input to hand control back to the human'). The control-transfer alternative is named with its trigger condition, leaving little to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so safety profile is partly covered. The description adds real value beyond that by warning that scene edits made during play are lost on stop, which is the key operational risk. It does not explain error behavior (e.g. what happens if play is already active) or that state persists across calls.

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 padding, with the action enumeration front-loaded and the caveat immediately after. 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?

For a single-enum mutation tool with annotations covering safety and no output schema, the description supplies the one thing structured data could not: the data-loss consequence of playing. It could go slightly further on error/state conditions, but nothing critical 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 enum parameter is already fully documented in the schema. The description merely repeats the enum values verbatim (play|stop|pause|unpause) without adding syntax, side effects per value, or state requirements, so it is the baseline 3.

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 (enter/exit) and resource (play mode) and enumerates the four transitions, so the action space is unambiguous. It does not explicitly distinguish itself from the read-side sibling unity_get_play_mode, so it falls short of the 5 bar.

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?

"prefer stopped for structural changes" gives explicit when-not guidance that steers the agent away from editing during play. It lacks any compatibility/prerequisite note (e.g. editor must be connected) and does not name a sibling as alternative, so it is clear but not complete.

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

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

Annotations declare non-readOnly, idempotent, non-destructive, which the description does not contradict. The description adds genuinely useful behavior beyond the annotations: the coordinate space per field (position world, rotation world euler degrees, scale local) and the partial-update contract, both critical to getting correct results.

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, front-loaded sentences: the operation, the partial-update rule, then a concrete example. Every sentence earns its place with no filler.

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

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

For a mutation tool with no output schema and a completely empty input schema, the description supplies the essential calling information (fields, spaces, partial semantics, example). It omits error behavior and what happens if the named object is not found, which are minor but real 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?

The input schema is empty, so the description carries the full burden and does supply the meaningful field names (path, position, rotation, scale), their coordinate spaces, and a concrete call example. It stops short of a formal field list, defaults, or required-vs-optional markers beyond the example's implication that path is needed.

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 (set) and resource (transform) and enumerates the three affected properties with their coordinate spaces, so the agent knows exactly what changes. It does not, however, distinguish itself from close siblings such as unity_set_component_property or unity_create_gameobject, which also mutate scene objects.

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?

"Provide only fields to change" implies partial-update semantics, which is useful usage guidance. But there is no statement of when to prefer this over unity_set_component_property or unity_execute_code, and no prerequisites (e.g., the target object must already exist).

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

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

Goes beyond the annotations by disclosing the exact failure condition ('Fails unless old_text occurs exactly expected_occurrences times'), the return shape ({ path, replaced, total_lines }), and the side effect that Unity recompiles after the change with a nudge to check the console. Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so this added failure/side-effect context is the valuable increment. It does not mention permission or concurrency considerations.

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

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

Three tight sentences, front-loaded with the core behavior, then a labeled Workflow line, then the return/side-effect note. No filler; every sentence carries actionable 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 mutation tool with annotations present and no output schema, the description covers purpose, sequencing, failure mode, return shape, and post-call side effects. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds meaning beyond the schema by stressing that old_text must match exactly ('copy old_text verbatim (whitespace matters)') and by explaining that expected_occurrences acts as a match-count guard that causes failure, reinforcing the per-parameter contract.

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 ('Replace an exact text block in a script') and clarifies the mechanism with a memorable analogy ('like a focused diff hunk'). This clearly distinguishes it from siblings like unity_read_script, unity_create_script, and unity_execute_code, which could otherwise seem like overlapping ways to modify code.

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 'Workflow' line gives concrete when-to-use guidance: call unity_read_script first, copy old_text verbatim (whitespace matters), then call this tool. This sequences the tool against a named sibling. It stops short of explicit exclusions (e.g. when to prefer unity_execute_code or unity_create_script instead), so it is strong but not exhaustive.

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