UEAgent

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

Goes well beyond the annotations: every call adds a node (non-idempotent, consistent with annotations), event/custom_event reuse existing nodes, Blueprints compile only with compile=true and are never saved, calls are refused during PIE with the force caveat, and it warns that an async/latent node returned as K2Node_CallFunction silently does nothing. That is exactly the behavioral context an agent needs for a mutation tool.

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

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

Front-loaded with purpose and return shape before the per-type details. It is dense and long, but nearly every sentence carries unique operational information (sources, precedence, PIE refusal, return fields); minor deduction for the volume and run-on density that could be organized into tighter sections.

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 31 parameters and no output schema, the description fully covers the return object shape and per-node_type extra fields, the asset-type-specific semantics, and failure modes. Nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real precedence rules beyond the schema: function_library wins over target_class, node_position wins over position_x/position_y, and where each value must be read from. These overrides are described in prose rather than only in schema descriptions.

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

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

States a specific verb+resource ('Create one node in a graph and return it with node_id and pins') and enumerates the supported asset/graph types. It clearly differentiates itself from build_blueprint_graph, connect_pins, set_pin_default_value and remove_graph_node.

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

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

Explicit routing: use build_blueprint_graph for multi-node single-undo wiring, use the listed read tools (list_overridable_functions, get_class_functions, get_blueprint_variables, etc.) to source each value, and stop PIE before calling. It also documents edge cases (event/custom_event do not add new nodes, interface functions with returns need add_blueprint_function).

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

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

Annotations already declare destructive, non-read-only, non-idempotent, and open-world behavior, but the description adds substantial context: the invoked tool runs with the same validation, guards, readback, effects, and destructive capacity as a direct call. It also lists refusal conditions, renamed-tool behavior, and that the reply is passed through unchanged.

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 definition is front-loaded with the core purpose and example, followed by routing guidance, behavioral caveats, refusal cases, and return semantics. Every sentence adds operational value for safe invocation of an arbitrary meta-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 complex arbitrary-dispatch tool with no output schema, the description is complete enough to call correctly: it explains discovery flow, argument structure, validation behavior, refusal modes, destructive potential, rename handling, and that the named tool's own reply is returned unchanged.

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

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

Although schema coverage is already 100%, the description adds meaningful parameter semantics beyond the schema: a concrete example, acceptance of a JSON string for `arguments`, unknown-name errors with closest matches, and the fact that an old name of a renamed tool will run the new tool with an explanatory reply.

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: it runs any server tool by name, with `name` identifying the tool and `arguments` carrying that tool's parameters. It clearly distinguishes itself from siblings by saying to use it only for tools not in the tool list, after `find_tools`, and to call listed tools directly.

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

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

It explicitly gives the when-to-use condition (a tool not in the tool list), the prerequisite discovery flow (`find_tools`, then `describe_tool` when parameters are unclear), and the alternative (call a listed tool directly). No relevant routing decision is left implicit.

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

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

Annotations only flag destructive/not-idempotent; the description goes far beyond with blocking-the-editor behavior, dependent recompilation, reinstancing, GC side effects, dirty packages, undo not reverting a compile, PIE refusal, and false-negative cases (wildcard pins, "was pruned"). That is exactly the kind of consequence detail an agent needs before invoking a destructive operation.

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

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

Front-loaded with purpose and timing, then parameters, then runtime consequences, then return shape — a sensible order. It is long but dense with useful content; the main waste is the PIE-force caveat appearing both here and nearly verbatim in the force schema description.

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

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

No output schema exists, yet the description fully specifies the return fields and when messages appear. For a destructive, editor-blocking compile with 4 optional params, an agent has everything needed: preconditions, side effects, failure modes, and return contract.

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

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

Schema coverage is 100% so baseline is 3, but the description adds real value beyond the schema: the ambiguity risk of short names ("a short name shared by two assets compiles one of them"), the preferred full-path form, and what return_messages messages carry (node_id and graph). Force is largely restated rather than extended, keeping this short of a 5.

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

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

"Compile a Blueprint to regenerate its class and return the real outcome" names a specific verb, resource, and effect, and the follow-up sentence about succeeded/error counts sharpens it. It is clearly distinguishable from check_blueprint_errors, find_erroring_blueprints, and save_asset, which are named as different operations.

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

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

Explicit when-to-use (after adding nodes/functions/variables/RPCs, before calls or PIE), explicit alternatives for the look-without-compiling case (check_blueprint_errors, find_erroring_blueprints), and explicit boundary versus save_asset ("It does not save"). Exclusion and routing are both 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 only say mutating/destructive/non-idempotent; the description goes far beyond by disclosing that the graph schema type-checks the pair so an incompatible link is an error not a silent no-op, that exec-output/data-input pins hold one link so linking replaces the old one, that each call is one undo step and undo restores the old link, that wildcard pins get reconstructed, and that a Blueprint is neither compiled nor saved (compile_blueprint then save_asset). This is exactly the post-call consequence information a destructive tool needs.

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

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

Front-loaded with purpose, then usage, example, semantics, behavior, and returns — a sensible order with no filler sentences. It is on the long side and the PIE/force mention partly duplicates the force parameter's own schema description, which keeps it from a 5.

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

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

For a 9-parameter destructive tool with no output schema, the description covers the return shape ({ connected, source_node_id, target_node_id, graph_kind? }), notes that failures surface as errors rather than connected=false, explains cross-asset return differences, and states the required follow-up tools for persisting a Blueprint. An agent has everything needed to invoke and follow up correctly.

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

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

With 100% schema coverage the baseline is 3, and the description earns above that by explaining the @input/@output sentinel values, giving a worked JSON example, and clarifying per-asset meaning (on a sound cue @output makes the source the cue's first node and target_pin is a slot index; on MetaSounds they are graph inputs/outputs). It does not re-explain force, graph_name, or the alias parameters, which the schema already covers well.

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 precise verb+resource — link a source node's output pin to a target node's input pin — and enumerates the asset families it applies to (Blueprint, material, sound cue, MetaSound, PCG, Control Rig). It explicitly names the siblings it is not (validate_pin_connection, disconnect_pin, build_blueprint_graph), so an agent can route correctly without opening any schema.

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

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

Gives explicit sequencing ('Use it after add_graph_node, or on nodes that get_graph_nodes lists'), a three-way exclusion list with the alternative tool named for each case, and a runtime precondition (refused during Play-in-Editor, force=true to override). Nothing about when to select this tool is left to inference.

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

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

Annotations already declare read-only/idempotent/non-destructive, yet the description adds genuinely new behavior: the catalog is loaded once at startup, repeats are cheap, there is no rate limit, and results stay stable until restart. It also documents the error path for unknown names (an error listing up to five closest names) and the rename/retirement resolution rules.

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

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

Purpose and routing guidance are front-loaded, and the second paragraph covers input edge cases before the return shape. It is dense but nearly every clause carries information; the sentence about the catalog being loaded once is slightly buried but not wasted.

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

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

There is no output schema, so the description enumerates the return fields ({ success, name, domain, description, inputSchema, annotations?, retired_name? }) itself. Combined with the error behavior and caching notes, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so the schema already documents `name`, but the description adds real meaning beyond it: the name must come from find_tools, surrounding spaces are ignored, a current tool's name always wins, and old or retired names resolve with `retired_name` reporting the mapping. That resolution logic is not expressible in the schema.

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

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

States a specific verb and resource: returns one tool's description, input schema and annotations. It explicitly positions itself between find_tools (discovery) and call_tool (invocation), so an agent can distinguish it from every sibling without opening a schema.

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

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

Gives an explicit trigger ('use it before call_tool when find_tools' parameter line does not say how to fill an argument, such as its format or allowed values') and an explicit exclusion ('a tool already in your list has its schema there'). The alternative it replaces is named directly.

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 readOnly, idempotent and non-destructive, and the description adds exactly the context they cannot carry: it affects only the connection's tool listing, never the editor or project, persists until session end, and re-enabling adds nothing (consistent with idempotentHint). It further discloses the client re-read handshake and that unknown names produce an error listing valid packs and domains.

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 effect and the pack-vs-domain trade-off, then behavior, then return shape. The pack inventory is long but earns its place by letting an agent pick without an extra find_tools round trip; the domain enumeration is left to the schema rather than repeated.

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

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

No output schema exists, so the description inlines the return shape including per-pack/domain already_listed and tools, tools_added, list_changed and note. Combined with the discovery pointer to find_tools and the error behavior, an agent has everything needed to invoke correctly.

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

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

Schema coverage is 100% with enums for both arrays, yet the description still adds real meaning: it distinguishes a pack (a few job-specific tools the core omits, with member examples) from a domain (an entire editor area that can add ~100 tools to context), which is the key trade-off an agent must weigh before choosing a value.

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

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

States a specific verb and resource ('Adds packs or whole domains to this connection's tool list') and immediately contrasts with the sibling call_tool, explaining that enabled tools are then called directly. The parenthetical pack inventory makes the resource concrete rather than abstract.

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

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

Explicitly says to give 'packs, domains or both', warns 'Prefer a pack when one covers the job', and points to find_tools with no arguments to discover domains and sizes. It also names call_tool as the fallback path when the client does not re-read the list, so both the choose-this and choose-other cases are covered.

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

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

Annotations already declare destructive/non-idempotent/open-world, but the description adds substantive behavior the annotations cannot convey: exceptions fail the call with the traceback in command_result, the PIE guard raises RuntimeError and fails with pie_refused even if caught, and globals persist across calls. These are exactly the non-obvious traits an agent needs before invoking a script executor.

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

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

Dense but front-loaded: purpose, mode, logging, error debugging, PIE guard, then alternatives-in-reverse. It is on the long side and the returns block plus some diagnostic prose could be trimmed, but every section carries actionable information rather than 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?

There is no output schema, yet the description enumerates the return fields (command_result, engine_log, log_cursor_before, pie_refused, hint) and explains how to chain them (log_cursor_before into get_output_log_lines). For a high-flexibility, destructive executor this covers everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by contrasting the three `mode` values with a concrete EvaluateStatement example and by tying engine_log_level to the diagnostic workflow. The aliases (code/script) and capture_output are left to the schema, which is a reasonable division given coverage.

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

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

Opens with a specific verb and resource ('Run Python in the running Unreal Editor') and immediately scopes it against siblings ('for what no tool does: search find_tools first'). The domain (Unreal `unreal` API) is stated explicitly, so an agent knows exactly what this tool is and is not for.

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

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

Gives explicit routing advice: search find_tools first, use get_actors_by_class / get_properties / raycast_scene / watch_pie_property instead for common enumeration cases, and reserve Python for 'several classes in one round trip, values correlated in one tick, or anything that mutates.' Both when-to-use and when-not-to-use are covered.

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

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

Annotations already mark this as a safe, idempotent read, but the description adds operational behavior beyond them: match mode reporting, truncation behavior, scan-pending handling, and the warning that max_results can abort enumeration. These are meaningful behavioral traits an agent needs before invoking the tool.

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

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

The first sentence front-loads purpose and scope, then usage guidance, alternatives, examples, and return shape follow in a logical order. Despite being fairly long, every section contributes useful information for a search tool with several matching modes and operational caveats.

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

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

The tool has five optional parameters and no output schema, so the description compensates by explaining return fields, match_mode, truncation indicators, and scan status. Combined with the fully documented input schema, an agent has enough information to invoke it correctly and interpret the response.

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 parameter meanings are already well documented in the input schema. The description still adds practical examples for search_pattern and case_sensitive, plus guidance on lowering max_results and using wait_for_scan after editor startup, though much of this overlaps with the schema's own parameter descriptions.

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

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

The description gives a specific verb and resource ("Find assets by name") and explicitly states scope across every mounted content root. It distinguishes the tool from related searches like get_assets_by_type and resolve_asset_by_name, so an agent can identify its role without opening schemas.

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

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

It explicitly says to use this before reading or writing an asset whose path is unknown, and names the alternative search tools with their distinct selection criteria: folder, class, tag, and exact-name homonyms. The examples further clarify when substring versus wildcard matching applies.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds real behavioral context: it 'only reads the catalog, so it is cheap to repeat', it explains the internal ranking order (exact name word > word prefix > domain > description, more matched words ranks higher), and it states the failure mode (unknown domain is an error listing the domains; no matches return `next` with what to try). The only weakness is mild repetition of the 'read-only' idea already in annotations.

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

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

Front-loaded with purpose and the skip condition, then examples, then return shape. Every paragraph carries information, but the three dense paragraphs with inline return-schema notation are heavier than needed for a 3-parameter search 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?

There is no output schema, and the description compensates by documenting both return shapes (matches list and the no-argument domain/pack listing) including `more` and `next`. Combined with the follow-up path to describe_tool/call_tool/enable_toolset, an agent has everything needed to call it and act on the result.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds genuine semantics the schema does not: that `domain` with no query lists the whole domain, that plurals match singulars, that a query spelling a tool's name puts it first, and the interaction between `limit` and the returned `more` count. Most of this is additive rather than restated.

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 ('Searches this server's 1547 Unreal Editor tools and returns the best matches') plus the shape of the result. It explicitly differentiates from siblings by naming describe_tool and call_tool as the right tools once a name is known.

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 ('before guessing a tool name or writing Python'), an explicit when-not-to ('when you already know the name, skip it'), and names the alternatives with the condition that selects them. It also documents the no-argument discovery path, which is a distinct usage mode an agent would otherwise never find.

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

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

Beyond the read-only/idempotent annotations, the description discloses that it reads unsaved editor state, loads from disk if needed, compiles nothing, and still lists nodes for uncompilable Blueprints. It also explains token costs, max_nodes/truncated behavior, and the dirty-package side effect under read-only vendor roots with a cleanup 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?

The description is front-loaded with purpose and then proceeds through node identity, read workflow, runtime behavior, and return shape in a logical order. Despite its density, the detail is earned by the tool's complexity and the absence of an output schema.

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

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

For a complex nine-parameter read tool with no output schema, the description is complete: it covers supported assets, workflow, parameter interactions, truncation, side effects, and the exact return shape. Nothing material is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents all nine parameters in detail. The description adds meaningful usage context beyond schema text, especially the two-step asset_path/node_id workflow and how object_path is consumed by get_object_info and set_properties, though much parameter detail is duplicated.

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

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

The first sentence states a specific verb and resource: 'Read the nodes of one graph without changing it.' It enumerates the supported graph/asset types and identifies the tool as the read operation behind add_graph_node, connect_pins, and set_pin_default_value, clearly distinguishing it from those sibling mutation 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?

It gives explicit workflow guidance: read the graph with compact=true for topology, then read one node by node_id for full pin detail. It also warns when compact is wrong, explains graph_name and expand_composites, and points to get_object_info/set_properties for node settings.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description goes well beyond them: responses over 40,000 chars spill to a file with report_path consumed by get_mcp_audit_report, missing objects/worlds produce an error naming what was searched, and the reply names which world answered. That is exactly the operational context annotations cannot express.

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

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

Front-loaded with purpose and routing before mechanics, and each paragraph covers a distinct concern (selection, path forms, oversize/error behavior, return shape). It is dense and long, with the enumerated Returns block doing necessary work in the absence of an output schema, but a few schema-echoing details could be trimmed.

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

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

With no output schema, the description fully enumerates the return fields and flags which are conditional (properties/property_count/components only with include_properties; array form with include_property_metadata; super_class is "None" for UObject). Combined with the error and oversize behavior, 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%, so the baseline is 3, but the description adds real meaning on top: object_path's accepted provenance (find_assets_by_name, get_graph_nodes readers, "Actor.Component" dotted form), and why include_property_metadata matters (type/editability/replication/clamp tell you whether set_properties can write it). Much of the world-selector detail is echoed from the schema rather than added.

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

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

Opens with a concrete metaphor that resolves to a specific verb and resource: identity, class, class flags, interfaces, reflected properties, and components for actors. It explicitly positions itself against get_properties, get_class_properties, and get_actor_components, so an agent can discriminate it from siblings without opening a schema.

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

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

"Use it first on anything unfamiliar, then write with set_properties using the names it lists" gives an explicit ordering, and it names the condition that selects the cheaper alternative ("once you know the names, get_properties reads only those and is far cheaper"). It also routes away for class-only and components-only queries, and the include_properties=false form is framed as the "what is this?" case.

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

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

Beyond the annotations, it explains verification signals (still_dirty_after_save false and file_on_disk true, not merely saved), the single-package write behavior, the Play-in-Editor refusal risk, readonly-root enforcement, and failure diagnostics like file_read_only. These are meaningful behavioral details not supplied by the annotations alone.

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

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

The description is front-loaded with the core action and verification proof, then proceeds through usage, parameters, failure behavior, and return shape. Despite its length, it is structured and each section contributes necessary context for a destructive save tool with several edge cases.

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

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

Given the lack of an output schema and the tool's complexity, the description includes the return object fields, verification checks, PIE refusal behavior, readonly-root handling, and failure diagnostics. An agent has enough context to invoke it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful workflow context not in the schema: path may come from find_assets_by_name's path or package, and readonly_roots/refuse_readonly can be omitted to use the project's Read Only Content Roots. It largely reinforces the schema rather than replacing missing information, so it stops short of a 5.

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

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

The description states a specific verb and resource: write one asset's package to disk and verify the result. It distinguishes this from siblings by naming save_level and reload_asset_package and clarifying that it saves exactly one package rather than a level or an in-memory edit.

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

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

It gives explicit when-to-use guidance: after an edit you want to keep, because most edit tools change the asset only in memory. It also names alternatives (save_level, reload_asset_package) and operational warnings, such as running list_dirty_packages before a bulk save and checking git status afterward.

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

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

Beyond the annotations, the description discloses critical behavior: the write is refused during PIE unless `force=true`, MetaSound and Control Rig writes save/compile assets, struct values are canonicalized and invalid tags are rejected, and the read-back value is the oracle for what actually landed. It also warns about the FormatText trap where the literal is written but `{argument}` pins are not created.

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

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

The description is long but appropriately sized for a complex, multi-asset mutation tool, and it is front-loaded with the core action and return semantics. The Blueprint/MetaSound/Control Rig structure makes dense constraints scannable, and each sentence carries operational value rather than restating schema fields.

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

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

Given 9 parameters, a dangerous write/compile/save operation, no output schema, and sibling alternatives, the description is complete: it covers asset-type differences, refusals, traps, return shape, and read-back behavior. An agent has enough context to call this correctly or avoid it when another tool is appropriate.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: MetaSound values are read as the input type, Control Rig values use export text like `(X=1.0,Y=0.0,Z=0.0)`, `node_id=@input` sets a graph input default, and `value_json` is the only way to put several tags in a GameplayTagContainer. It does not fully document every alias/parameter, but it materially improves parameter understanding.

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: write the literal default of an unconnected input pin and read it back, across Blueprint, MetaSound Source, and Control Rig. It distinguishes the tool from `set_properties` by routing material expressions, sound cue nodes, and PCG nodes to that sibling, so an agent can identify the correct tool without schema inspection.

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

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

It gives explicit when-to-use and when-not-to-use guidance, including refusal cases such as array/set/map pins, split sub-pins, and Play-in-Editor sessions. It also names concrete alternatives: use a MakeArray/MakeSet/MakeMap node, call `recombine_blueprint_pin` first, or use `set_properties` for material/sound cue/PCG node values.

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

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

Beyond annotations, the description discloses that writes are undoable, dirty the package, re-register components, and may trigger asset-specific finishing behavior such as graph reconstruction, sound recache, Niagara recompile, and blend-space resampling. It also explains refusal conditions, PIE restrictions, save refusal for level objects, and clamp/save side effects.

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

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

The description is long but front-loaded and structured around purpose, alternatives, parameters, side effects, and returns. Some sentences repeat schema details, but for a complex mutation tool the density is largely justified.

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

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

The tool is complex, destructive, and has no output schema, but the description delivers the missing return shape, failure reporting, side effects, and refusal conditions. An agent has enough information to decide when to call it and how to interpret results.

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

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

The schema already has 100% description coverage and carries strong per-parameter detail, so the baseline is 3. The description still adds useful semantics: the precedence of properties{} versus property_name/value, partial struct update behavior, example object paths, property name sourcing from get_object_info, and the meaning of clamp/save/force in practice.

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

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

The description opens with a specific verb and resource: write editable properties of one object in the editor world, and explains the object forms supported. It clearly distinguishes this tool from siblings such as set_component_property, set_blueprint_component_properties, set_widget_property, and call_function.

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

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

It gives explicit when-to-use guidance for any light, fog, sky, decal, camera, post-process volume, sound, Niagara system, material expression, and other assets. It also includes an explicit 'Not for' list naming the alternative tool for each excluded case.

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

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

Goes well beyond the annotations: it discloses that undo affects objects in memory and not files (a saved edit stays on disk until the next save), that it stops early at stack bottom or an undo barrier, and that `success` can be true with nothing undone so the caller must read `applied`. Those are exactly the non-obvious behavioral traits an agent needs for a destructive operation.

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

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

Front-loaded with the core action, then usage, then edge cases, then a compact returns block. Dense but almost every sentence earns its place; the only waste is mild overlap between the description and the `count` schema on early stopping.

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

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

There is no output schema, and the description compensates by enumerating the return fields (applied, requested, actually_undone, undo_count, can_undo, next_undo) and explaining the trap of `success` being true when nothing was undone. For a single-parameter destructive tool, nothing material 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 coverage is 100%, so the schema already carries the core meaning of `count` (minimum 1, default 1, early stop at barriers). The description still adds value with a concrete example ({"count": 3}) and by tying the count to the early-stop/actually_undone semantics, though it partly restates 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?

Specific verb (step back) plus resource (the editor's undo stack) with explicit scope (one transaction or `count` of them) and a familiar analogue (Ctrl+Z). It also states what it returns on top, which separates it cleanly from get_undo_state and set_undo_barrier mentioned in the text.

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

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

Explicitly says when to use it (revert an edit made by a tool or a person), names the prerequisite (read get_undo_state first to see the label you are about to revert), and explains the transaction granularity including begin_transaction/end_transaction. That is genuine when/how guidance rather than implied usage.

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