omniverse-mcp

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

Annotations only declare non-read-only, non-destructive, closed-world; the description goes far beyond that by disclosing articulation/link behaviour, friction effects, the tensor-API path under suppressReadback, the replace-on-second-push semantics before the next physics step, and the exact refusal conditions.

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

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

Front-loaded with the core action and the key distinction from the sibling, then progresses through behaviour, caveats, and refusals. It is dense and long, but nearly every sentence carries operational information; minor tightening is possible.

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

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

An output schema exists, yet the description still sketches the answer (point pushed at, path taken, method: physx vs tensor). Combined with the edge-case coverage, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so force/impulse/position/prim_path are already documented, including the impulse-vs-force meaning and the centre-of-mass default. The description reinforces the physical interpretation ('its mass counts', impulse over whole mass) but adds no syntax or format details beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource – pushing a rigid body through PhysX with force or impulse – and immediately distinguishes it from set_prim_transform ('To place a body rather than push it'). An agent can tell which sibling to use without inspecting schemas.

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

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

Explicit preconditions (simulation playing or paused), explicit exclusions (no RigidBodyAPI, disabled/kinematic bodies, bodies fixed to the world), an explicit alternative for positioning, and guidance to combine pushes into one per step. This is close to exhaustive routing information.

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 by disclosing the state machine (cancelling during finally-block cleanup, then cancelled), the idempotent retry pattern when cancellation is swallowed by a bare except, and the side effect that a sweep restores the stage while retaining captured shots in its manifest. These are exactly the non-obvious behaviors an agent needs and none of them are recoverable from readOnlyHint/destructiveHint.

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

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

The action is front-loaded and every clause carries distinct information: cancellation timing, cleanup state, polling, retry-on-swallowed-cancel, sweep manifest behavior, and the already-ended case. The phrasing is sometimes garbled (missing relative pronoun in 'a job run_script_job or capture_sweep started', dense colons and run-ons), which costs a little readability but not content.

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

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

For a single-parameter mutation with an output schema and annotations, the description covers timing, intermediate and terminal states, verification via get_job, retry semantics, and side effects on sweeps. What remains unstated is minor: whether the call returns immediately, and any permission or concurrency constraints on cancelling another caller's job.

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 job_id property already explains the expected format and provenance ('as run_script_job or capture_sweep answered it, such as j3'). The description only reuses job_id in the get_job polling example and adds no new syntax or constraint beyond the schema, 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 (cancel) applied to a specific resource (a job) and names the exact origin of that resource: jobs started by run_script_job or capture_sweep. It also implicitly distinguishes itself from get_job, which only observes status, so an agent can tell the two apart without opening either schema.

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

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

Gives real when-to-use context: call it to stop a running job, call it again if the job's code caught the cancellation, and expect a no-op if the job has already ended. It points at get_job(job_id, wait=10) as the way to confirm the outcome, but it never states an explicit exclusion such as a precondition on job ownership or a case where cancel should not be attempted at all.

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

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

Annotations only say readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description goes well beyond by disclosing that selections are applied in the session layer 'which no save writes', that all state is restored afterwards including after cancel_job, that every shot is validated before anything changes, and that an existing sweep folder is refused. Strong disclosure for a mutation tool, though it never states the permissions or time/cost expectations of a long multi-shot job.

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

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

It is front-loaded with the core action, but several sentences are spliced run-ons ('Its lens is focal_length and the apertures in mm, the vertical one fitted...') and the paragraph has stray line breaks that hurt scanability. Nearly every sentence carries unique information, so the length is justified by tool complexity, but the packaging could be tighter.

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,000-shot batch job tool, the description covers output location (mcp_output/sweeps/<name>/ with PNGs and manifest.json), how to monitor via get_job(id, wait=100), what failure looks like, state restoration semantics, and reuse of the manifest. With an output schema present, nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the prose adds real meaning: vertical_aperture is fitted to the image shape and refused when it doesn't fit, a manifest.json passed as shots_file re-takes shots and needs the first sweep's width and height, and shots/shots_file are mutually exclusive with a 2,000 ceiling on shots. These are behavioral constraints the schema alone does not convey.

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 ('Capture many shots in one call, each with its own camera pose, lens, variant selections and timeline time, as a job') and explicitly contrasts itself with the sibling capture_viewport ('where one capture_viewport picture costs a turn each'). An agent can distinguish it from both capture_viewport and get_job without inspecting schemas.

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

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

Gives conditions for use (checking a scene's looks and switches from many viewpoints), names the alternative it replaces, explains the shots_file reuse path across scenes and after changes, and states operational constraints ('one job runs at a time') plus the interaction with cancel_job and sim_control for repeating agents. That is explicit when-to-use plus real exclusions and follow-ups.

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 readOnlyHint=true, and the description is consistent with a non-mutating capture. Beyond annotations it discloses what would otherwise be surprising: the render is isolated so the user's viewport camera and size are preserved, an all-black image or inactive lighting returns a warning, and omni.syntheticdata is required for boxes and segmentation (image only without it).

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

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

The numbered output list is well structured and the usage guidance is front-loaded. The final paragraph is dense and packs several separate facts (isolation, aiming, lighting warning, syntheticdata prerequisite) into one block, but nearly 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?

With no output schema, the description fully enumerates the return artifacts and file locations, plus the degraded-mode prerequisite and failure warnings. Nothing an agent needs to invoke and interpret the capture 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 width/height/camera_path/include_image are already fully documented in structured fields. The description only reinforces the render-size behavior and the empty-camera_path fallback, adding little per-parameter meaning beyond the schema, 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 (render one frame) and resource (camera), and enumerates the three artifacts it writes (image, bounding boxes TXT, instance segmentation PNG), so the agent knows exactly what the tool produces versus siblings like inspect_prim or get_scene_tree.

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 ('see the scene and tell which prim is where'), which output to prefer for which question (boxes for places, segmentation for overlapping prims), and routes to alternatives: set_camera to aim first, inspect_prim for one prim from every side, viewport_light for lighting problems.

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 (which only say it is a non-readonly, non-destructive, closed-world write), the description discloses exactly what is copied (root-layer contents including references), what silently fails ('a source whose position can't be written copies nothing'), and that target collisions are rejected before any copying happens. The offset naming scheme and the fact that the first/single copy is never displaced are also spelled out.

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

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

The core behavior is front-loaded, but the offset rules are stated twice in slightly different wording ('each next one moves by offset from the one before' vs. 'copy n moves n times offset from the source'), and the opening sentence's clause about a single copy never being moved is syntactically tangled. Trimming the duplicated offset explanation would make it sharper.

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 four parameters and an output schema, this covers purpose, alternatives, failure modes, and transform semantics without needing to describe return values. An agent has everything required to call it correctly and to know when it will not work.

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 prose adds genuine meaning: offset is applied cumulatively through the copy's own translate op or matrix while all other ops and placement are preserved, and the schema's _001/_002 naming for count is reinforced. It does not restate every parameter, which is appropriate given the schema already documents them.

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

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

The opening sentence gives a specific verb (copy) plus resource (prim) and scope ('with everything under it', 'once or as a row of count copies'), which no sibling does. The closing sentence explicitly separates it from create_prim, so an agent can route without inspecting 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?

It names concrete alternatives and the conditions that select them: set_prim_transform for moving a single copy, create_prim for a new prim. It also states hard when-not conditions (sublayer or referenced-asset prims can't be copied whole, existing target paths are refused), so the agent can predict failures before calling.

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

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

Goes well past the annotations by disclosing that variant mode temporarily switches variants in Kit's session layer and then restores the layer exactly, with no file or selection changes — consistent with destructiveHint=false and readOnlyHint=false. It also documents refusal behavior (unknown variant set/variant listed back; prim inside an instance refused and the instance named), which annotations cannot convey. It does not cover cost or side effects on concurrent session state, so it falls just short of the top.

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 output fields, then cleanly segmented into numbered modes, then caveats. Dense but nearly every clause carries information; the session-layer restoration sentence is slightly long but justifies itself as the only statement that this call does not leave side effects.

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

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

An output schema exists, so return values need not be described, and the description instead covers the things an agent must know to call correctly: mode selection, precedence, restoration of session state, and the two refusal conditions. Nothing material is missing for a comparison tool of this complexity.

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 per-parameter meanings are already given and the baseline is 3. The description adds real value on top by grouping the six flat parameters into two mutually exclusive modes and stating a precedence rule (all four variant params present means variant mode wins), which the schema does not express.

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

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

States a specific verb (compare) plus the two resources it operates on (two prims, or two variants of one prim) and enumerates the compared metrics: mesh, face, vertex and triangle counts, world bounds, bound materials, B minus A deltas. It explicitly routes single-prim counting to get_mesh_stats, so an agent can separate it from that sibling without opening either schema.

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

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

Gives two numbered modes with the exact parameter sets that select each, and resolves the ambiguity an agent would hit: variant mode wins when all four variant parameters are given. It also names the alternative (get_mesh_stats) for the one-prim 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?

Annotations only declare non-readonly, non-destructive, closed-world; the description goes well beyond them by disclosing implicit parent creation, type-conflict refusal, that a failed transform write aborts creation, upAxis/metersPerUnit/kilogramsPerUnit conversion of referenced files, and unopenable-file errors. The one gap is that it never says what create_prim returns, though an output schema exists to cover that.

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

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

The purpose is front-loaded in sentence one and each subsequent sentence carries distinct behavioral information, so nothing is filler. It is dense and some sentences chain several clauses (the reference-file conversion sentence especially), which costs a little readability.

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

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

For a 7-parameter creation tool this covers the important surface: type resolution, transform writing, physics enablement, reference-file normalization, failure modes, and sibling alternatives. An output schema exists, so the absence of return-value prose is not a gap.

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 description coverage the baseline is 3, but the description genuinely adds meaning: it enumerates valid prim_type values, explains that usd_path references a file instead of a type and how that reference merges into an existing prim, and clarifies that enable_physics applies only to the prim itself, not to descendant meshes.

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

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

The first sentence gives a specific verb plus the full range of resources (shape, Xform, camera, light, any USD type, or a file reference) and names the exact creation location parameter. It is immediately distinguishable from clone_prim and create_robot because the description explicitly says what those are 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?

It routes the agent to alternatives by name: clone_prim for copies, create_robot for robots, set_prim_transform for rewriting a transform, and set_physics_properties' collision=True for meshes under an Xform or reference. It also states the condition under which a same-type prim is accepted versus refused, which is real 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?

The annotations only say the tool is non-read-only and non-destructive. The description adds a lot beyond that: the default prim naming rule, the error cases (prim already exists, file can't be opened), and up-axis correction that is reported in the answer. It also covers unit and physics conversion matching Kit's metrics assembler, and notes that position and rotation stay in the stage frame.

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

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

It is front-loaded with the purpose, but the middle is a dense run-on paragraph about up-axis and unit handling. The phrasing is awkward in places ("stood upright on it", "the answer says so"). That content is useful but could be tighter or structured as a list.

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

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

An output schema exists, so return values need no explanation. Inputs, defaults, error conditions, side effects and related tools are all covered, which makes the description complete for this moderately complex mutation 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%, yet the description still adds real meaning. It gives the full list of valid robot names, which the schema lacks as an enum, and the accepted path forms: local path, URL, or /Isaac/ library path. It also explains how the default prim_path is derived, e.g. /World/Franka or /World/MyBot.

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?

It states a specific verb and resource: add a robot to the stage as a USD reference, either from Isaac Sim's asset library by name or from a USD file. It also separates itself from create_prim, which is for anything but a robot.

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 the alternative explicitly ("For anything but a robot, use create_prim") and names the follow-up tool, get_robot_info, for listing joints. It also states a prerequisite: library names need Isaac Sim.

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, closed-world. The description adds genuinely new behavior beyond that: merge semantics ('kept and added to, never replaced'), that variants start empty, and the error condition when the prim doesn't exist. It doesn't cover return shape, but an output schema exists so that's acceptable.

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 paragraphs, front-loaded with the action, then merge semantics, then the authoring pointer. Minor inefficiency in the fragment 'An error when the prim doesn't exist.', 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?

For a mutation tool with annotations and an output schema, the description covers creation, selection, merge behavior, follow-up authoring, and the failure mode. The only gap is what the returned structure contains, which the output schema presumably covers.

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 documented in the schema, including the default_variant fallback to the first entry. The description reinforces that one variant is selected at creation but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Add a variant set of empty variants to a prim and select one'. It also names the complementary sibling, set_variant_selection, so an agent can distinguish creation from switching without opening either schema.

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

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

Gives clear operating context: variants are empty until authored via execute_script, and existing sets are added to rather than replaced. It stops short of an explicit 'do not use this when...' exclusion, but the creation-vs-switching split with set_variant_selection is implied well enough.

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, but the description adds several traits they cannot express: the refusal is atomic ("nothing changes"), the error message explains why, Kit's undo does not record the delete, and the on-disk file keeps the prim until save_scene. It also notes an error when the prim is absent. This is exactly the extra context the annotation bar asks for.

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

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

Front-loaded with the action and mechanism, then failure modes, then persistence caveats—a sensible order with no filler. The second sentence is convoluted ("one a reference or payload on a prim above brings, such as a part of a referenced asset") and could be tightened without losing meaning.

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

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

For a destructive single-param tool with an output schema, the description covers everything an agent needs before calling: what is deleted (including descendants), what blocks deletion, irreversibility via undo, and the required follow-up save. Return values are handled by the output schema, so nothing material is missing.

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

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

The schema has one required parameter with 100% description coverage including a concrete example ("/World/Robot"), so the baseline is 3. The description refers to "that path" but adds no format or validation detail beyond the schema.

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

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

States a specific verb and resource ("Delete a prim and everything under it") plus the exact mechanism ("removing what the stage's edit layer holds at that path"). An agent can distinguish this from set_visibility or save_scene without consulting any schema.

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

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

Explicitly enumerates the cases where the call is refused (prim defined by another layer, brought in by a reference or payload) and names the alternative, set_visibility, for those cases. It also points at save_scene as the step needed to persist the change, so both when and when-not 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?

Goes well beyond annotations by disclosing a shared-state side effect: expired drawings also remove lines other code drew via isaacsim.util.debug_draw, and a new stage drops the previous stage's drawings. Also clarifies that nothing is added to the stage, which materially changes how an agent treats this versus create_prim.

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

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

Front-loaded with the action and rendering contract, then usage, then caveats. Every sentence adds a distinct fact (shape rendering, integration with capture, stage non-persistence, side effects) with no repetition of the 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?

With annotations present and an output schema, the description covers safety, persistence, lifetime and side effects well. The remaining gap is per-shape parameter requirements, which the description leaves entirely to the schema.

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 a 3; the description earns above that by explaining that a sphere renders as three crossing lines and each point as a cross, plus the fixed 2px width. It does not state which shape-specific params are mandatory per shape, which stays with 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 plus resource ("Draw debug lines in the viewport") with the exact rendering semantics (2px wide, `duration` seconds) and an enumeration of the four shapes. An agent knows exactly what the call produces, and no sibling tool competes for this job.

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

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

Explicitly states the use case ("mark points, rays or paths, such as a raycast's hit, for a capture or the user to see") and names the integration point (capture_viewport on Isaac Sim 6.x). No when-not-to-use or named alternative for persistent geometry, so 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?

Goes well beyond annotations: main-thread execution, a 120 s call timeout, the fact that the script keeps running after the call gives up, and that a blocking script freezes Kit. It also documents the return contract ('assign to result' for JSON-serialisable data, else str), stdout/stderr capture, and exception-as-error with the traceback's last lines. The destructiveHint/openWorldHint annotations are consistent with arbitrary code execution.

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 primary constraint (prefer dedicated tools) before the escape hatches, and each paragraph maps to one decision: whether to use it, how results come back, timeouts, and the mcp bridge. The mcp method enumeration is long but is functional API reference the agent cannot get elsewhere; minor cost is dense backtick-cluttered 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?

Covers everything an agent needs for a powerful escape-hatch tool: safety framing, timeout and freeze semantics, return/error conventions, and an in-script tool bridge with exact call syntax and awaited-handler pattern. With an output schema and annotations already present, nothing material 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?

Only one parameter, and schema coverage is 100%, so the baseline is 3; the description still adds real meaning by explaining the 'result' convention, what serialisation rules apply, and how stdout/stderr and exceptions surface. It does not restate the parameter needlessly, though it could say whether the code runs in a fresh namespace.

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

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

States a specific verb and resource ('Run Python inside the Kit app ... on its main thread') and gives a scope qualifier ('for what no tool does') that separates it from the ~45 siblings. It also names the environment variants (Isaac Sim, USD Composer) so the agent knows the runtime context.

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 prefers dedicated tools ('Prefer a tool that does the job') with a reason (validated input, bounded waits), making this the fallback. It also names the concrete alternative and the condition that selects it: work that may outlast 120 s, such as settling physics, should use run_script_job with get_job for progress.

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

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

Annotations already flag this as a destructive, non-read-only write, but the description adds far more: the output file is overwritten, flattening is applied, outside material bindings are pulled in, textures are NOT copied, and writing over a loaded file is an error. These are non-obvious side effects and failure modes not captured anywhere in the structured fields.

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?

Content is front-loaded — purpose first, then usage, then error conditions — and every sentence carries information. The heavy colon-separated sentences in the back half make it denser than it needs to be, but nothing is filler.

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

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

For a destructive export with an output schema present, the description covers the transformation performed, the naming convention, side effects (materials in, textures not), and both error conditions. Nothing an agent needs before calling correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics: the prim becomes /<its name> and the file's default prim, inherits the stage's up axis and units, a missing extension defaults to .usd/.usda/.usdc, and output_path must not be a loaded file. Only prim_path gets no extra treatment beyond the schema.

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

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

The opening sentence gives a specific verb (write), resource (one prim's subtree), and precise scope (flattened, plus externally-bound materials, so the file opens standalone). It also names the two siblings that do something similar but different — flatten_usd and save_scene — so the agent can tell them apart immediately.

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 it to hand one asset to another tool or project; flatten_usd writes the whole stage, save_scene the root layer as it is.' It also states when the call fails (output_path already loaded by the open stage, prim doesn't exist) and what to do instead ('name another path'), which is exactly the when-not guidance an agent 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 flag destructiveHint=true and readOnlyHint=false, but the description goes well beyond them: it says exactly what gets overwritten, what constitutes a forbidden overwrite (own file, sublayer, referenced or payload file), that unsaved edits are included, that the open stage is left untouched, that an unopenable USD is an error, and that textures are not copied. That is unusually rich disclosure 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?

Purpose is front-loaded in the first sentence, followed by alternatives and then the error semantics, which is the right ordering. Some clauses are run-on and grammatically rough ("one USD can't open is an error") and a few rules restate the schema, costing a little tightness.

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

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

An output schema exists, so return values need no explanation; what an agent still needs — input resolution rules, overwrite safety, error conditions, and the side effects on the open stage — is all covered. Nothing material is missing for a correct 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?

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by spelling out the consequences of each parameter choice (empty input_path = open stage including unsaved edits; output_path overwrite vs. error). It overlaps noticeably with the schema's own parameter descriptions rather than adding genuinely new syntax or format detail.

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

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

States a specific verb and resource ("Write a stage flattened into one USD file") and immediately explains what flattening means: references, payloads and sublayers resolved into a single layer. It explicitly distinguishes itself from the two sibling tools that could be confused with it (save_scene, export_prim_as_file), so an agent can route correctly without opening schemas.

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

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

Gives an explicit use case ("hand the whole scene to another tool as one file") plus named alternatives with their differing behavior: save_scene keeps references and writes only the root layer, export_prim_as_file writes one prim's subtree. It also states when-not: an output_path the open stage has loaded is an error, with the remedy (name another path, or use save_scene).

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 and openWorldHint=false, but the description goes further by enumerating the state machine (working, cancelling, completed, failed, cancelled), explaining what a sweep's result contains (folder, black or failed shots, current shot message), and stating that reading changes nothing in Kit. That is meaningful behavioral context beyond the annotations, though it repeats the read-only point the hint already makes.

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

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

The purpose is front-loaded in the first clause, and each sentence carries useful information about states, waiting, and sweep results. The prose is dense and somewhat run-on, with several clauses chained into single sentences, which costs some readability but not enough to waste space.

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

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

For a two-parameter read tool with an output schema, the description covers everything an agent needs: what is returned in each phase, the full state list, the wait semantics, and the fallback behavior when job_id is absent. It also pre-empts the sweep-specific output shape, leaving no material gaps.

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

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

Schema description coverage is 100%, so both parameters are already fully documented, including the wait ceiling of 100 seconds and the meaning of an empty job_id. The description echoes those semantics ('With wait, the call returns when the job ends or changes state', 'with no job_id it reads the running job or the last one') but adds little beyond what the schema descriptions already say, 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?

The description opens with a specific verb and resource ('Read a job run_script_job or capture_sweep started') and enumerates what it returns: state, runtime, last line, printed lines, result or error, and per-stream output. It explicitly names the sibling tools that create such jobs, so an agent can distinguish it from cancel_job or get_logs 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?

It gives clear when-to-use context: the wait parameter is explained as a way to wait for a long job 'without a call every few seconds', and omitting job_id is framed as recovering the running or last job after conversation compaction. It stops short of naming cancel_job as the alternative for stopping a job or stating when-not to use it, 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.

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

Annotations already declare readOnlyHint and closed-world, so safety is covered. The description adds real behavior beyond that: entries are truncated to 200 characters with a remainder count, matches past the truncation surface as a matched: line, and verbose lines require startup flags. It does not discuss the 2000-entry buffer limit or ordering, which the schema partially covers.

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 filter axes, then behavior, then the script-log caveat. Dense but every sentence carries information; the long compound sentences around truncation and verbosity take a second read.

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

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

A read-only, four-parameter tool with an output schema and full schema coverage needs modest description, and this supplies truncation format, match behavior, and level gating. The only notable omission is ordering/pagination beyond the schema's buffer note, which is minor.

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%, including enum values for min_level and per-parameter descriptions, so baseline applies. The description does add value on `search` semantics (matches the whole message, not just the visible excerpt) and on the level gate, pushing it just past a pure baseline read.

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 (get the latest log entries), names the source (Kit app's log file since the bridge extension started), and enumerates the filter axes (level, channel, text). No sibling tool reads logs, so an agent can identify it immediately.

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

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

Explains the practical condition for verbose output (Kit must be started with --/log/level=verbose and --/log/fileLogLevel=verbose) and explicitly routes script output away to execute_script, telling the agent when this tool will not have the data it wants. It stops short of naming a full alternative for log browsing, but the exclusions are concrete.

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, and the description adds substantial context beyond them: only UsdGeom.Mesh prims count, meshes inside instances are included, implicit shapes like Cube and Sphere have zero faces, and prims below max_depth are excluded from the listing yet still counted in totals and ancestor subtree_faces. It also discloses output behavior — totals are always inline, but an oversized tree is written to a file whose path is returned.

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 scope and purpose come first, followed by usage guidance and then caveats, so it is well ordered and every clause carries information. It is dense to the point of being a wall of prose, and a short enumerated clause list for the caveats would be easier to scan, but there is no filler to cut.

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

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

An output schema exists, so return values need not be restated, yet the description still flags the file-spill path behavior that an agent must handle. Combined with the depth/counting rules and instance handling, nothing needed to invoke the tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real semantics: prim_path can be any prim and its descendants are counted, and max_depth controls what is listed versus what still contributes to totals and subtree_faces — a distinction the schema description does not make. This meaningfully clarifies the effect of the depth 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?

The description opens with a precise verb+resource: count faces, vertices and triangles for every mesh at or under a prim, returning totals plus per-prim counts. It explicitly differentiates itself from siblings by noting that instances are not listed by get_scene_tree and that compare_prims is the side-by-side alternative.

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 names three concrete use cases (geometry budget, measuring what a simplification saved, finding heavy subtrees) and tells the agent the actionable next step: a heavy prim is the next call's prim_path. It also routes the comparison use case to compare_prims, so the when/when-not boundary is explicit.

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

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

Far beyond the readOnlyHint/openWorldHint annotations: it discloses the 90 s cap, the load-wait, the blocking interaction with captures, the temporary lifting of the frame-rate limiter (and that a playing fixed-time-step stage runs faster than real time meanwhile), the release of a prior capture's render, and the built-in warnings for >10% variance and eco mode. The only slight tension is that readOnlyHint=true while the tool has transient environmental side effects (limiter state, discarded capture render) — not a data mutation, so not a contradiction, but the description is what makes that nuance visible.

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 well organized: purpose, then usage, then side effects, then interpretation caveats. Every sentence carries content, though the metrics enumeration in the first paragraph is long and a few phrases are awkward ('the GPU's render time a frame', 'the conditions to compare two answers by'), costing some readability.

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

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

For a measurement tool with an output schema (so return shape needn't be explained), it covers what an agent needs to call it correctly: prerequisites, isolation requirements, timeout, machine-specificity of results, and how to tell when the numbers are untrustworthy. Nothing material is left implicit.

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

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

Schema coverage is 100% and the schema already explains both parameters in nearly the same words ('app updates to let pass first, once the stage has loaded, so shaders and caches settle'). The description reinforces that the warmup precedes measurement and adds the 90 s overall cap, but adds no format, tuning, or interaction guidance for the two parameters beyond 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?

Opens with a specific verb and resource: 'Measure how fast the Kit app runs the open stage', then enumerates exactly the metrics produced (FPS/frame time percentiles, GPU render time, physics step timing and sim-to-real ratio, GPU memory, prim/mesh/instance counts, render products, and the conditions for comparison). It is clearly distinct from siblings like get_mesh_stats or get_sim_state, which cover only a slice of this.

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 ('check a frame-rate target, such as 15 FPS with a robot's sensors on'), a precondition ('Play the simulation first... a stopped timeline gives no physics numbers'), and an exclusion ('Measure alone: a capture called meanwhile waits for the measurement, and any other call's work counts in its frames'). This is the rare case where when-to-use, how-to-prepare, and what-not-to-do are all 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?

Adds valuable behavior beyond the annotations: descendants are included, values are in the stage's units, and geometryless prims such as empty Xforms return a 0.1 box at their position rather than an error. This is exactly the kind of edge-case context an agent 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-loads the core operation, follows with usage guidance, then the sibling comparison and edge case. Every sentence earns its place and there is no 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?

Complete for the task: it defines the measurement, its inclusion of descendants, units, return components, the alternative tool, and fallback behavior for non-geometric prims. The output schema handles return structure.

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 single prim_path parameter has 100% schema description coverage, including an example path. The description adds useful scope about which prim is measured but does not add syntax or format details 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?

States a specific verb and resource: gets a prim's world-space axis-aligned bounding box including descendants, and names the returned components. It also distinguishes itself from get_prim_properties, which returns the same box among other values.

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

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

Gives clear use cases: placing things and measuring what rests on what, gaps, and sizes. It also names the closest alternative, get_prim_properties, though it does not state an explicit when-not-to-use condition.

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 and openWorldHint=false, so safety is covered and the description's job is to add context. It does add real behavioral detail: quaternions have scale factored out, zero-scaled prims have no rotation, unset attributes and empty relationships are omitted rather than null, and variant set selection provenance (session/root/file) is reported. A 3 reflects that the annotations plus the added edge-case semantics combine well, though most of the added text is return-shape material rather than operational behavior such as cost or failure modes.

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

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

The purpose and routing sentence is correctly front-loaded, which is good. But the remaining two dense paragraphs are almost entirely return-value formatting detail, and the tool already ships an output schema, so that material is largely redundant and makes the definition longer than it needs to be.

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

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

For a one-parameter, read-only inspection tool with full schema coverage and an output schema, nothing needed to call it correctly is missing. Selection rules, edge cases, and sibling routing are all present, and the return format is definitionally covered by the output schema even if the description over-explains it.

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

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

There is a single required parameter, prim_path, with 100% schema description coverage and an example path already in the schema. The description adds no syntax, wildcarding, or path-resolution guidance beyond what the schema states. Baseline 3 applies when the schema does all the parameter work.

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

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

Opens with a specific verb and resource ("Get one prim as a prim block") and then enumerates exactly what the block contains: type, transform, bounds, physics flags, API schemas, variant sets, attributes, and relationships. It explicitly names the siblings it is not (get_prim_bounds, get_scene_tree, include_properties), so an agent can separate it from near-neighbors 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 routing rule: use this to read one prim, use get_prim_bounds when only size and place matter, use get_scene_tree to find paths, and use include_properties for many prims written to a file. Both the when-to-use and the when-to-use-something-else conditions are stated, including the single-vs-batch boundary.

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 give readOnlyHint=true and openWorldHint=false, but the description adds substantive behavior the annotations cannot convey: the tool writes a new PNG into mcp_output/captures/, simulation time is only returned once recording has stopped, and a missed frame yields an empty file rather than an error. The relative-path resolution rule (read from this server's working folder, matching start_recording/stop_recording) is also disclosed.

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

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

The core action and return values are front-loaded in sentence one, and later sentences are organized around frame provenance, path resolution, error cases, and the alternative tool. The middle sentence ("with Kit on this machine you can also open them there, and with Kit on another this brings one here") is slightly convoluted and could be tightened, but no sentence is filler.

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

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

For a two-parameter tool with an output schema and annotations that already pin down safety, the description covers everything else an agent needs: source of frames, default session selection, path semantics, return values, and failure modes. Nothing material is left to inference.

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 goes beyond the schema by explaining the meaning of the empty session_dir default (the last recording started since the Kit extension started, including the running one) and how relative paths resolve on this machine versus Kit on another. That is real added semantics rather than a restatement of the parameter titles.

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

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

The first sentence gives a precise verb, resource and destination: "Copy one recorded frame to a new PNG in mcp_output/captures/, and return its path and, once the recording has stopped, the frame's simulation time." It also explicitly separates itself from the sibling capture_viewport ("For a picture of the scene now, use capture_viewport"), so an agent can choose between them without opening either schema.

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

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

It states when to use this tool versus the alternative (capture_viewport for live scenes), where frames originate (start_recording, frame_00000.png onward in the session folder), and what happens when session_dir is omitted. It also names two failure conditions — an empty file for a frame Kit failed to capture, and an error past the last frame — which is exactly the routing information an agent 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 only declare readOnlyHint and openWorldHint=false, so the description carries real weight and delivers: unit conventions (degrees vs radians vs stage units), that limits reflect USD values rather than live values, ordering rules for the Joints list vs the DOF-ordered joint states, and the truncation-to-file fallback with the path echoed back. It also discloses the degraded path when the sim is stopped or Isaac Sim is absent.

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?

Content is front-loaded with the tool's purpose and every clause carries distinct information about units, ordering, or fallbacks. The long semicolon-chained sentences are dense and could be split into a short list of invariants for faster 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?

Despite an output schema, the description supplements it with the ordering and truncation semantics an agent needs to interpret results correctly, plus the no-sim and too-long response cases. Nothing material for correct invocation or interpretation is missing.

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

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

Schema coverage is 100% and the single parameter is documented as the root prim, so the baseline is 3; the description goes further by explaining that joint states are taken from the first articulation at or under that path, which resolves genuine ambiguity about sub-articulation prims.

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

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

The opening sentence names a specific verb and resource (read a robot) and enumerates exactly what is returned: articulation status, link/DOF counts, per-joint name/type/limits/drive, and live joint positions/velocities. It clearly distinguishes robot articulation reads from generic prim reads, though it never names inspect_prim or get_prim_properties as the narrower/wider alternatives an agent might otherwise pick.

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

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

"Use it before driving a robot, and to see where its joints are now" gives an explicit use context, and the repeated contrast with set_joint_targets (radians/degrees) steers the agent to the right tool pairing. There is no explicit when-not guidance, e.g. that non-robot prims should go to get_prim_properties.

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 readOnlyHint/openWorldHint it discloses truncation semantics ('children = N (truncated)'), that instanceable prim contents are omitted, the effective default depths, that three of the parameters silently switch output to mcp_output/scene_dump.txt and overwrite the previous file, and that the file lands on Kit's machine rather than the caller's. It also explains that positions/rotations track simulation state, which is non-obvious behavioral context an agent could not infer from annotations or 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?

The core statement is front-loaded and no sentence is pure filler, but the middle section is a run-on with tangled clauses ('replacing the last, each with the prim's rotation, world box and physics flags...'), and defaults are repeated from the schema. It is dense rather than tight — appropriate information, poor sequencing.

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 five-parameter read tool with an output schema, it covers everything that matters: defaults, truncation, instance behavior, the file-output branch including its path, size and remote-host caveat, and the simulation-frame caveat on returned transforms. Even though an output schema exists, the alternate file return path is explained, which the schema alone would not convey.

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 cross-parameter meaning the schema does not convey: any of include_properties/filter_types/property_filter redirects output to a file, filter_types still walks the children of excluded prims, and property_filter=["variant_sets"] is a special switch-listing mode. The only weakness is that it restates default depths already documented 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?

The first sentence gives a specific verb and resource — 'List the stage's prims under root' — plus exactly what each entry carries (path, type, world position) and the depth bound. It also differentiates against siblings by name: get_mesh_stats 'looks inside' instances and get_prim_properties 'reads one prim inline', so an agent can tell them apart 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 states the intended use case plainly ('find prim paths before acting on them') and characterizes the tool as 'the lightest look at a scene', then routes property reads to get_prim_properties and instance interiors to get_mesh_stats. That is strong alternative routing, but it never frames an explicit when-not-to-use condition (e.g. large scenes where the file dump is always preferable), so it stops short of a full 5.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description goes far beyond by disclosing conditional return behavior: a looping timeline resets time so a wait for the end never completes, a non-looping timeline pauses at its end along with physics, and a range of one frame or less produces a note. It also explains when the answer names a version-matching command, why a recording's frames stopped early, and when a run_script_job job is named — all context an agent needs to interpret the result.

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

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

The purpose is front-loaded, but the description runs three dense paragraphs and much of the middle section reads as a list of return fields that an output schema already covers. Some sentences are telegraphic to the point of ambiguity ('A range of one frame or less gets a note', 'while a job run_script_job started runs, it names it'), costing clarity rather than saving space.

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

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

For a zero-parameter read tool with a full output schema and read-only annotations, this is more than sufficient — the behavioral caveats about timeline looping and fps-vs-frame-rate are the genuinely load-bearing additions. The remaining gap is that it never says the practical precondition for calling it, so completeness is high but not exhaustive.

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

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

The tool takes zero parameters and the schema is an empty object, so there is no parameter meaning to add; the baseline of 4 applies. The description correctly spends no space on argument 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?

The opening sentence names a specific verb (get) and resource (simulation's state), then enumerates exactly what is returned: play state, timeline time, up axis, meters_per_unit, prim count, Kit/app/OS versions, and extension/server versions. It distinguishes itself from siblings by naming get_performance, sim_control, and run_script_job where their domains overlap.

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

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

It clearly routes away from itself where appropriate — 'sim_control changes the state' and 'get_performance measures the frame rate' — which tells the agent which sibling to pick for mutation or performance data. What's missing is an explicit statement of when to call this tool (e.g. before issuing sim commands, or to check unit scale before transforms).

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 the tool moves whichever camera the viewport looks through and leaves it at the last angle, that isolate hides then restores other objects, an ~80 s per-call budget, per-angle failure semantics ('an angle that fails says why, and the angles after it say Not captured'), and warning conditions for all-black angles. These are exactly the side effects and limits an agent needs before committing to a mutating capture.

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

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

Purpose and output path are front-loaded, then usage, then mechanics, then failure behavior — a sensible order with little filler. It is dense and a couple of clauses (the warning-sentence detail) could be tightened, but nothing is redundant with the 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 7-parameter capture tool with an output schema, this covers everything an agent needs: what is produced, where it lands, camera side effects, runtime budget, failure reporting, and refusal/warning conditions. Return-value details are correctly left to the output schema.

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 real meaning by tying width x height to the fitted framing distance and explaining how zoom_offset modifies that fit, plus the cube-geometry rationale behind the angle set. It stops short of syntax detail beyond what the schema already lists.

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 ('Capture a prim from up to 14 angles around it'), the framing rule, and the output location (PNG in mcp_output/captures/). It also explicitly contrasts itself with the nearest sibling, capture_viewport, so the agent can route between them without opening either schema.

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

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

Gives an explicit selection rule: 'Use it to see one object from every side; capture_viewport takes one picture from a camera as it stands.' It adds preconditions that change tool choice (an orthographic camera is refused) and points to viewport_light when lighting is wrong.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description substantiates exactly why: enable/disable mutate the running app, persist only until Kit restarts, and can break other tools or cut off the MCP bridge. It also discloses the response semantics (enabled=False after an enable means it didn't take) and the list truncation behavior (first 50 with the total), which annotations cannot convey.

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

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

The purpose and default behavior come first, then the read path, then the mutation semantics and safety warnings, in a logical order. It is dense and slightly overlong, but nearly every clause (restart persistence, enabled=False signal, bridge warning) carries information an agent would otherwise have to infer.

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

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

An output schema exists, so return values need no explanation, and the description still covers what the agent needs beyond it: the three modes, the required id for mutation, transient lifetime of changes, and the failure/breakage modes. For a 4-parameter tool with destructive semantics, nothing material 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 action, search, enabled_only, and extension_id are already fully documented with per-action applicability. The description reinforces that enable/disable need extension_id but adds no format or edge-case detail, and it never mentions the search or enabled_only filters, so it sits at the baseline for a fully-covered schema.

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

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

The description names the specific resource (the Kit app's extensions) and the three concrete operations: list, enable, disable. It also states the default action, so an agent can distinguish the read path from the two mutation paths without opening the schema.

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

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

It gives an explicit trigger for enable ("Use enable when a tool names an extension it lacks, such as omni.syntheticdata for segmentation") and concrete when-not-to guidance for disable (disabling extensions other tools use breaks them; disabling ovmcp.bridge severs this server). That is when/when-not/alternative guidance in one place.

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

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

Annotations already flag destructive=true, but the description adds real substance: unsaved changes are lost, the default prim is /World Xform, the new stage has no file so save_scene requires a file_path, an active recording stops taking frames, and draw_debug drawings are cleared. That is concrete disclosure of side effects beyond the annotation.

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 destructive action and default prim are front-loaded, then defaults and caveats follow logically. It is dense but almost every sentence carries information; the viewport camera and recording/debug side-effects could be tightened but are not filler.

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

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

An output schema exists, and the description still states what is returned (up_axis and meters_per_unit read back). For a destructive two-parameter tool with defaults, everything needed to call and follow up correctly is present.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by explaining why the defaults matter (Z-up metres matching Isaac Sim robots/SimReady assets and physics) and what Y or 0.01 implies (USD Composer-style Y-up, centimetres). Minor extra value over the enum and default already 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 (discard and open) on a specific resource (the open stage), and explicitly says the result is an empty stage with a /World Xform default prim. This is distinguishable at a glance from open_scene (opens a file) and save_scene (persists).

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

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

Gives clear when-to-use context: it names save_scene as the prerequisite to keep the old stage and set_camera as the follow-up when units differ from the app's own. It does not explicitly contrast with open_scene for loading an existing file, which is the one sibling an agent might confuse it with.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false; the description goes well beyond that by naming what is lost (unsaved changes, running recording frames, draw_debug drawings) and that the simulation is stopped first. It also enumerates refusal conditions (missing/unreachable file, unsupported type, LFS pointer, Kit busy), the no-stage-left-open failure mode, and the 80 s timeout behaviour — unusually rich 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?

The destructive consequence is front-loaded in the first clause, then alternatives, then failure modes — good ordering with no filler. It is dense and long, but nearly every clause carries operational information an agent needs.

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

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

For a destructive, one-parameter stage-replacement operation, everything needed is present: prerequisites, side effects, refusal cases, timeout behaviour, and a summary of returned fields (path, replaced stage, up axis, meters_per_unit, default prim, prim count). An output schema exists, so the return-value sketch is a bonus rather than a requirement.

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 already documents the accepted path forms (local, relative, URL, /Isaac/ asset library), so baseline is 3. The description adds a non-obvious semantic: passing the currently open stage's own file reloads it from disk rather than erroring.

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: 'Open a USD file as the stage, in place of the open one.' It immediately contrasts with siblings new_scene (empty stage) and save_scene (writes the open one), so an agent can route correctly without opening a schema.

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

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

Explicit when-to-use ('work on a scene from a file'), explicit alternatives (new_scene, save_scene), and an actionable prerequisite: 'call save_scene first to keep it.' It also flags the special case where the path equals the current stage's own file (reload from disk).

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, and the description goes well beyond them: only colliders registered with the Collision API are hit, not plain meshes, and the sim must be stepped first or the call may return no hit or fail. It also explains that the returned prim is the rigid body hit or a static collider itself.

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 operation and return contract, then follows with alternatives and prerequisites. Three paragraphs is slightly more than needed, but each carries distinct, non-redundant 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?

Given a simple three-parameter tool with an output schema, the description covers behavior, prerequisites, filtering (colliders only), and failure modes. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by specifying that the returned distance is in stage units, tying the ray result back to max_distance semantics. It does not re-explain origin or direction, which the schema already documents fully.

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 precise verb+resource pair ('Cast a ray through PhysX') and enumerates the exact return values: prim, hit point, surface normal, distance, or 'No hit'. It distinguishes itself from get_prim_bounds, which is a different operation on a known prim.

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 names concrete use cases ('find what lies along a line, such as the ground under a point or what a robot faces') and explicitly contrasts with the alternative get_prim_bounds. It also states the precondition that the simulation must be played or stepped once first, otherwise it may find nothing or fail.

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

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

Annotations already flag this as non-read-only, destructive, and open-world, but the description adds substantial behavioral context beyond them: it runs on Kit's main thread, must await at least once at top level or be refused, can become uncancellable if it loops after awaiting or calls world.step, and only one job runs at a time. It also explains progress via printed lines and result assignment. This is unusually complete 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?

The purpose and sibling comparison are front-loaded, and most sentences carry necessary constraints. However, several sentences are dense and awkwardly packed, especially the await/update/timeline passage, which could be split for faster parsing.

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

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

For a destructive arbitrary-code execution tool with concurrency constraints, the description covers the key operational facts: the 120 s alternative, main-thread scheduling, the await requirement and refusal behavior, one-job-at-a-time semantics, progress reporting, and cancellation. An output schema exists, so return values do not need further explanation.

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 two parameters (code and file) are already documented by the schema as alternatives. The description does not add syntax, precedence, or conflict-resolution rules for code versus file beyond what the schema says, so the baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Start a long Python script inside the Kit app as a job,' and immediately contrasts it with execute_script's 120 s limit. An agent can distinguish it from both execute_script and get_job without opening any schema.

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

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

Explicitly names the alternative (execute_script) and the condition that selects this tool: work that may outlast the 120 s limit. It also gives concrete uses such as dropping and settling many physics objects, and later names get_job and cancel_job as the read/cancel companions.

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

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

Annotations already flag destructiveHint=true and openWorldHint=false, and the description goes further by saying exactly what is overwritten, which files may not be targeted, and that only the root layer is written (sublayers/references untouched, session layer excluded). The remaining gap is that the variant-selection remark in the return discussion is hard to parse, but behavior around destruction and failure is otherwise well disclosed.

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

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

The core behavior is front-loaded in the first sentence, but the following paragraph is a dense run-on with stacked clauses (session layer, variant selections, set_variant_selection default) that a reader must untangle. Content mostly earns its place, yet the phrasing could be split into shorter, ordered statements.

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

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

For a one-parameter tool with an output schema, the description covers prerequisites, overwrite semantics, error conditions, scope of write, and alternatives. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so a 3 would be the floor, but the description adds real semantics beyond the schema: empty means overwrite the stage's own file, an explicit path must not name a loaded sublayer/reference, and the path is on Kit's machine. That is meaningful added meaning for the single optional 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 concrete verb and resource ('Write the open stage's root layer to a USD file') and immediately splits the two behavioral modes (empty path = save in place, path = copy). It also names the siblings it is not (flatten_usd, export_prim_as_file), so an agent can distinguish it without reading 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?

Explicitly covers when to use each mode, the failure case for an unsaved stage ('fails for a stage never saved, such as new_scene's'), the error case for loaded sublayer/reference files, and routes to alternatives for whole-file and per-prim exports.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds real behavioral context beyond that — it moves whichever camera the viewport looks through, including a scene camera, and the user visibly sees the move. It also enumerates the error conditions (missing prim, position equal to target, mixed forms). It stops short of saying whether the prior camera state is recoverable, which is the one remaining gap for a mutating 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 the core action, then two tight lines for the modes, then alternatives, then failure modes. Dense and useful throughout, though the closing clause 'saying what to drop' is slightly indirect phrasing for 'the error tells you which parameter set to drop'.

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

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

With an output schema present, return values need no explanation, and the description covers mode selection, side effects, alternatives, and failure modes. For a 6-parameter all-optional camera tool, nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100% and already documents defaults (45° azimuth, 30° elevation, 2.5× largest side, world origin), so the baseline is 3. The description adds semantics the schema does not encode: the two parameter sets are mutually exclusive and mixing them is an error, plus prim mode forbids position/target.

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

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

The opening sentence names a specific verb and resource ('Move the viewport's camera and aim it') and immediately scopes the two targeting modes: a world point or a prim. That is enough for an agent to separate it from capture_viewport and inspect_prim 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 states exactly when each form applies (position+target for a point; prim_path with distance/azimuth/elevation for a prim) and names the alternatives with the condition that selects them: inspect_prim for multi-side capture, capture_viewport's camera_path for capturing from another camera without moving the viewport.

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

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

Beyond the annotations, it discloses that a dict skips unknown joint names, a list uses get_robot_info's Joints order, missing drives are created with stiffness 1000 and damping 100, USD is written, and the call works before physics. These are meaningful side-effect and operational details not present in the annotations.

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

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

The description front-loads the purpose and then packs dict/list behavior, auto-drive side effects, and read/write context into a few dense sentences. There is minor repetition about simulation playing, but no sentence is wasted.

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

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

For a two-parameter write tool with an output schema, it covers units, ordering, missing-joint behavior, auto-drive creation, USD write behavior, and return count. It omits what happens if targets is null or omitted and does not discuss error cases for an invalid prim_path, leaving a small gap.

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%, but the description adds semantics beyond the schema: dict entries set only named joints and skip missing names, and list order follows get_robot_info's Joints list rather than joint states. It does not elaborate on prim_path beyond the schema, but the targets nuances are valuable.

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

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

The description uses the specific verb "Set" with the resource "position targets of a robot's joint drives" and explains that physics drives the joints toward them during simulation. It also distinguishes this write operation from get_robot_info's read of joint positions, so an agent can identify the tool's role without 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?

It gives clear context for use: during simulation or stopped before physics starts, and it distinguishes setting targets from reading joint positions via get_robot_info. It does not explicitly name alternatives such as apply_force or sim_control or state when not to use it, so it is clear but lacks exclusions.

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

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

With annotations covering safety hints, the description adds substantial non-obvious behavior: opacity/roughness/metallic reset to defaults on every call, default material naming at /World/Looks/<prim name>_Mat with name-based aliasing, replacement of the existing binding, and inheritance to children unless they have their own bindings. The aliasing/overwrite risk is disclosed even though destructiveHint is false, so there is no contradiction, just useful context.

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

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

Two tight paragraphs: the action summary is front-loaded, then the gotchas (default reset, shared material naming, child inheritance) and sibling routing. No filler sentences; every clause contributes a constraint or a caution.

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 6-parameter mutation tool with an output schema already defining return values, the description covers the risky behaviors (binding replacement, default reset, material aliasing) that an agent must know before calling. Nothing material is left to inference.

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 per-parameter formats (e.g. [r,g,b] scaling) are already documented. The description still adds real meaning beyond the schema by explaining implicit-default semantics for omitted optional params and the sharing consequences of the material_path default, which the schema only states as an empty string.

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

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

The first sentence names a specific verb and resource ('Colour a prim with an OmniPBR material') and enumerates the sub-actions taken (create or update material, set colour/surface values, bind). It is clearly distinguishable from siblings like set_physics_properties and update_material_paths, which are named as out of scope.

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 routing: use set_physics_properties for friction/bounce and update_material_paths to repoint bindings after materials move. It also states the decision rule for material_path (omit to share by name, supply to keep prims apart or share intentionally), which is exactly the when-to-use guidance an agent 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 only say it is a non-read-only, non-destructive, closed-world call; the description goes far beyond that. It discloses side effects the annotations hide: mass implicitly adds RigidBodyAPI so a static collider starts to fall, friction/restitution creates a PhysMat child bound to the prim, shared legacy /World/PhysicsMaterials materials are migrated and possibly deleted, and a call with friction/restitution reads the whole stage at roughly 1 s per 100,000 prims.

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

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

The core action is front-loaded in the first clause, which is good, but the remainder is a dense wall of run-on clauses mixing material lifecycle, clone/inheritance rules, legacy migration, and performance cost without bullets or paragraph breaks. Nearly every sentence carries real information, yet the packing makes it hard to scan for the one rule an agent needs.

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

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

For a six-parameter mutation tool with an output schema, this covers everything an agent needs: which shapes collide, what APIs get applied, what the answer reports, cost of the call, and edge cases around instances, clones, and legacy materials. No material gaps remain.

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 each parameter, but the description adds genuinely new semantics: a null/omitted value leaves the current value untouched, collision=true yields a static collider with no rigid body while mass/density promotes the prim to a rigid body, and a mesh on a non-kinematic body gets a convexHull approximation unless one is set. That is meaning beyond the field-level descriptions, though the mass-vs-density precedence is left mostly to the schema.

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

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

The opening sentence names the exact verb and resources: setting a prim's mass/density, friction/restitution, or collision state for PhysX, and states that omitted values are left unchanged. It distinguishes itself from siblings by explicitly routing look-and-feel to set_material and first-time physical setup to create_prim with enable_physics.

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 alternatives (set_material for appearance, create_prim + enable_physics for new prims) and states the refusal conditions: an Xform cannot be a collider, instances and inactive prims cannot hold their own material, and collision on an inactive or instanced prim is refused. That is a complete when-to-use / when-not-to-use map.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=false; the description adds the substance: refusals occur 'with nothing written' for relationships, xform ops, animated attributes, stronger layers, instances/prototypes and inactive prims; a session-layer write blocks later edit-target writes until the stage reopens; physics values may reach PhysX only after the sim stops. It also discloses the return payload (before/after value plus layer written), which is behavior an agent cannot infer from the hints. No contradiction with destructiveHint=false — the described failure mode is always a no-op refusal.

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

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

The purpose and sibling exclusion are correctly front-loaded, and almost no sentence is padding — nearly every clause carries a distinct behavioral fact. However, the body is a single run-on block of colon-chained clauses ('The attribute must exist on the prim: get_prim_properties lists them, a schema's included, and ...'), which makes it hard to parse at speed and buries the high-value refusal and layer rules inside dense 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 mutation tool with 4 parameters and an output schema, this covers what an agent needs: attribute discovery, type coercion, refusal conditions, layer persistence tradeoffs, simulation timing, and even a domain hint that UsdLux sunlight defaults to 50,000 intensity while a few thousand suits a viewport capture. Nothing material about correct invocation 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 already 100%, but the description still adds real semantics: the name must exist on the prim and an unmatched name resolves to its closest names, the value is converted to the attribute's declared type and clamped to its range, and out-of-range tokens are written with a note naming the allowed ones. It also explains the non-obvious consequence that a shape size change updates the authored extent, so get_prim_bounds reflects it.

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

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

The description opens with a specific verb and resource ('Set one attribute of a prim') and immediately grounds it in concrete examples: light intensity or colour, camera focal length, shape size/radius, display colour. It explicitly differentiates from siblings by naming set_prim_transform, set_visibility, set_material and set_physics_properties as the tools that own their own attributes.

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 the selection rule precisely ('Use it for an attribute no other tool sets') and points to get_prim_properties as the way to discover valid attribute names. It also gives conditional guidance for the layer choice — layer='session' only 'for a check that must leave every file as it is' — and enumerates the cases where the call is refused rather than silently misapplied.

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, which only declare readOnly=false, destructive=false, openWorld=false. The description discloses exactly which xform ops get written (translate, rotate/orient in kind, scale), that missing ops are added, that untouched ops such as pivots are preserved, and the matrix fallback for imported assets. It also enumerates concrete error conditions (missing prim, animated op, stronger-layer override like a Kit camera, non-factorable matrix), which is unusually specific 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?

The core operation and the parent-space caveat are front-loaded in the first clause, then usage, then mechanism, then errors. The later sentences are long and densely packed with USD op vocabulary, but each carries distinct 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?

For a four-parameter mutation with full annotations and an output schema, this covers coordinate frame, op-level write behaviour, preservation of other ops, the matrix fallback, and failure modes. Return values need not be explained because an output schema exists, and the only remaining gap is minor granularity on some error cases.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by explaining that any of the three omitted values 'keeps its value' rather than resetting to zero, and by insisting the values are in the parent's space, not world space. Those are semantic clarifications the null defaults in the schema do not convey on their own.

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 ('Set a prim's position, rotation or scale relative to its parent') and immediately clarifies the parent-space frame, which is the key distinguishing trait versus a world-space or camera tool. An agent can identify this apart from set_camera, apply_force, and get_prim_properties without opening any schema.

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

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

Explicitly says what the tool is for ('move, turn or size a prim') and routes two near-neighbours elsewhere: set_camera for aiming the viewport, apply_force for pushing rigid bodies under physics. It also names get_prim_properties as the way to read world position, which resolves the most likely confusion about coordinate frames.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes far beyond by explaining persistence semantics (session layer never written by save_scene, lasts until cleared or stage reopened), refusal rules, the extension-version caveat that warns instead of clearing, and the 40-app-update deactivate/reactivate path under Fabric Scene Delegate.

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

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

The core action is front-loaded, but the prose is dense and run-on, packing several conditionals into single sentences. Nearly every sentence carries information, yet it would be far more scannable as bulleted points or short clauses.

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 an output schema and partial annotations, the description covers the edge cases an agent needs: layer persistence, clearing, refusals, instance behavior, delegate-specific timing, and sibling alternatives. Nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds parameter-level consequences not present in the schema: that edit_target may resolve to a sublayer and the answer names it, and that variant_name="" is required to clear before switching layers. This meaningfully raises it above baseline.

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

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

The opening states a specific verb and resource: 'Select a variant in a prim's variant set, or clear a layer's selection.' It also distinguishes itself from the related siblings create_variant_structure (which makes sets/variants) and compare_prims (which measures variants without changing selection).

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 states when to use which mode: session layer by default for a non-persistent check, edit_target when the selection must be saved. It also enumerates when-not conditions (clear with variant_name="" first if the session layer holds a selection, prim inside an instance refused, unknown set refused) and says to use this rather than execute_script.

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-read-only but non-destructive, and the description substantiates that by stating the prim persists in the stage. It goes further than annotations can by disclosing the hierarchical MakeVisible cascade (shows the hidden parent, hides the parent's other children) and the error case for prims with no visibility, such as materials.

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

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

Front-loaded with the action and scope, then alternatives, then edge-case semantics in descending priority. It is dense with three clauses carrying distinct information, but nothing reads as filler; a slightly tighter phrasing of the MakeVisible analogy would be the only trim.

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 visibility tool with an output schema, the description covers what changes, what does not change (the prim remains), the inheritance behavior, the alternative tools, and the failure mode. Nothing an agent needs in order to call it correctly or interpret failure 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 both parameters are already documented; the description still adds meaning by implying the boolean toggles a subtree rather than a single node. It could have noted the default of true explicitly in prose, which is the only small gap.

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

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

The opening clause names a specific verb ("Show or hide") and resource ("a prim and everything under it") and scopes the effect to viewport and captures while clarifying that the prim stays in the stage. This clearly separates it from delete_prim (removal) and inspect_prim's isolate (capture-only hiding), both named 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?

Explicit when-to-use ("to see inside or behind something, then show it again") plus explicit differentiation from the two most confusable alternatives, delete_prim and inspect_prim's isolate. The parent/child cascade rule tells the agent the precondition and side effects of the call before it runs.

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

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

Annotations only declare the generic non-read-only, non-destructive, non-open-world profile; the description adds substantive behavior the annotations cannot convey — that stop is restorative rather than destructive ('physics puts bodies back where play found them'), that step is bounded to two app updates, and that the first play triggers collision-mesh cooking during which Kit answers nothing. The blocking/latency caveat is a genuinely useful disclosure for an agent sequencing 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?

Front-loaded with the core scope, then per-action semantics, then cross-tool dependencies — a sound order with no filler sentences. It is dense and the per-action clauses run together mid-paragraph, so parsing takes a second pass, but nothing here is redundant.

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

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

For a single-enum mutation tool with an output schema already covering return values, the description covers everything an agent needs: action semantics, reversibility of stop, the mesh-cooking block, and which sibling tools depend on the play/pause state. 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 coverage is already 100% and the enum itself is enumerated, but the schema's own parameter text is only 'What to do'. The description supplies the actual meaning of every enum member, including the non-obvious duration semantics of 'step' — meaning that exists nowhere in the structured fields.

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

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

The opening sentence names a specific verb set and resource ('Play, pause, stop or step the simulation's timeline') and states the return contract ('return the state it is left in'). Later sentences explicitly separate this from get_sim_state, get_robot_info, and apply_force, so an agent can route 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 spells out what each action does and when each applies (play resumes physics, pause holds, stop rewinds, step is two app updates then pause). It also names the read-only alternative ('get_sim_state reads the state without changing it') and states a prerequisite condition ('get_robot_info's joint states and apply_force need it playing or paused'), which is exactly the routing guidance an agent 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 only declare readOnly=false/destructive=false/openWorld=false; the description adds substantial context the agent could not infer: PNGs written to mcp_output/recordings/, the render continues up to 30 s past the recording and is reused, app updates slow with frame size, frames abort if the stage changes or the camera is deleted, and viewport/camera/size are left untouched. The one real gap is that it does not say what happens to already-written frames when recording is stopped early.

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 correctly with the one-line purpose, and every paragraph carries real information, but sentences are convoluted ('through the render capture_viewport and inspect_prim keep when it is that size, else one of its own') and the 30-second render-retention aside interrupts the main flow. It is dense rather than wasteful, yet readability suffers.

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 stateful, side-effecting recording tool this covers the full operational picture: output location/format, timing model, one-at-a-time constraint, abort conditions, interaction with sim stop, and how to review frames. An output schema exists, so return-value detail is correctly omitted.

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

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

Schema coverage is 100%, so baseline is 3; the description adds meaning by tying track_prims and property_filter to a concrete artifact ('tracks prim state ... alongside video frames, in state.txt'), which the schema does not state. The clock semantics for fps (simulation vs wall clock) are also restated in prose form that clarifies the schema's shorthand.

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 precise verb+resource ('Start recording simulation frames to disk') and immediately scopes what is captured, at what size, and where it lands. It implicitly separates itself from capture_viewport (single frame) and names stop_recording/get_recording_frame as the follow-on lifecycle tools, so an agent can distinguish it from siblings 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 states when to use it ('Play it to record motion'), the refusal condition ('One recording runs at a time: another start is refused until stop_recording'), and the follow-up sequence ('Use stop_recording when done, then get_recording_frame to review any frame'). It also gives a concrete when-not/do-this-instead rule: pause the sim or call stop_recording before stopping, rather than just stopping.

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 it as a non-read-only, non-destructive, closed-world write; the description adds substantial context on top: it blocks until in-flight frames are flushed, writes metadata.json, returns render control with a 30 s grace period unless a capture still holds the render, and surfaces partial-failure notes. That is exactly the mutation behavior an agent needs before invoking it.

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

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

The lead sentence is well front-loaded, but the render-handback clause ("hand the render back to the captures, kept up to 30 s unless a capture's render is still kept at the stop, which stays instead") is tangled and hard to parse on first read. The lengthy enumeration of return fields is also partly redundant because an output schema exists.

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 mutation with annotations and an output schema, the description covers effects, failure modes, and the follow-up tool. Its remaining weakness is spending effort restating return values that the output schema already documents, while the render-handback rule stays ambiguous.

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 argument semantics to explain and the baseline is 4. The description does not need to compensate for anything here.

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

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

States a specific verb and resource ("Stop the running recording") and enumerates its effects: waiting on pending frames, writing metadata.json with per-frame simulation time, and restoring render ownership. This clearly separates it from start_recording and get_recording_frame without opening either schema.

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

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

Gives the error condition ("An error when no recording runs") and explicitly routes review work to a sibling: "Use get_recording_frame to review frames." It stops short of stating the obvious pairing with start_recording or any prerequisites for calling it, so it is clear but not fully exhaustive.

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

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

Annotations flag destructive=true and openWorld=false, but the description adds what they can't: nothing verifies the new paths exist, Kit's undo doesn't record the change, and a mid-way failure keeps the edits already made. Those are exactly the risk disclosures an agent needs before running a destructive rewrite.

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 operation in the first sentence, then when-to-use, then risk notes, then the return shape. The parenthetical examples are compact, and no sentence is filler.

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

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

Output schema exists, yet the description still briefly says the answer counts changed paths and names the prims. Combined with the partial-failure and undo disclosures, an agent has everything needed to call this safely. The destructive rewriter has no remaining informational gap for its complexity.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics beyond the schema: the match is a plain text prefix applied to any relationship or asset path, and prefixes should end with "/" to avoid over-matching. That meaningfully improves how an agent forms old_prefix.

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: rewrite every path under a subtree that starts with old_prefix to new_prefix. It further enumerates what gets rewritten (relationship targets like material bindings, asset paths like texture files), which lets an agent distinguish this from sibling mutators such as set_material or create_prim.

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: after materials or textures move, so bindings and textures point at their new place. It also gives a concrete usage caveat (end the prefix with "/" and keep it specific) because a plain-text match can hit unrelated paths. It doesn't name an alternative tool, so it stops 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 only declare non-read-only, non-destructive, closed-world; the description adds far more: 'set' does not alter the scene, rig modes require the omni.kit.viewport.menubar.lighting extension, an unavailable mode is an error, and 'get' truncates to the first 20 lights and omits rig lights. These are exactly the failure modes an agent 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?

Purpose is front-loaded and every paragraph carries information, but the second and third sentences are long run-ons that chain several clauses with parentheticals, making them slower to parse than needed.

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

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

An output schema exists, yet the description still sketches what 'get' returns (mode, modes on offer, stage lights with intensity) and flags the DistantLight 50,000 intensity pitfall. Nothing an agent needs to call this correctly in a lighting/capture workflow is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real semantics: the accepted mode values and their meanings ('stage', 'camera', 'off', named rigs), that an unlisted mode errors, and that 'enabled' applies only to the legacy set_camera_light action.

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 pair and resource: "Read or set the viewport's lighting mode," and immediately scopes it ("without changing the scene"). It is clearly separable from siblings like create_prim and set_prim_attribute, which the description explicitly routes stage-light work to.

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

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

Gives a concrete trigger condition: use it when a capture comes back black or warns that lighting lights nothing. It also states which tool to use instead for adding stage lights (create_prim then set_prim_attribute), and calls out the legacy set_camera_light alternative.

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