stage_inspect

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

Goes well past the readOnlyHint/idempotentHint annotations: it discloses that reading cooks the node, that a layer rewritten by another process (hython cache) is reloaded and reported in reloaded_layers, and that frames temporarily moves the playbar and restores it. Those are exactly the side effects an agent would otherwise not anticipate from a read-only tool.

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

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

Front-loaded with purpose and the mode list, then a scannable indented mode table; the negative guidance is placed before the bulk. The opening mode enumeration largely duplicates the schema's mode description, which is mild redundancy across a fairly long body, but the length is justified by 13 distinct modes.

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

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

For a 12-parameter, 13-mode tool this covers what an agent needs: cooking cost implications, playbar restoration, layer reload behavior, mode selection, and a hard boundary against SOP geometry. Return values are handled by the existing output schema, so their absence from the description 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?

Schema coverage is already 100%, so the baseline is 3; the description earns more by binding parameters to modes and explaining effect rather than just type (include_attrs adds attributes, frames returns "the path of a moving prim", layer_index walks the stack, max_depth controls tree depth). It does not restate format details already in the schema, but it also adds no validation or edge-case behavior for conflicting mode/param combinations.

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

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

States a specific verb+resource ("Read the USD stage at a LOP node") and immediately names the sibling it must not be confused with ("Do not use it for SOP geometry: geometry_inspect does that"). The mode enumeration makes the read surface concrete, so an agent can pick this over geometry_inspect/node_inspect 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 positive context ("Use it in a Solaris (LOP) network to see the prims, the layers and the composition that a node produces"), an explicit exclusion with the alternative tool named, and per-mode guidance including when a mode is specifically warranted ("Use it to see what one LOP did", "It names the node that makes an export or a render start slow"). Nothing about routing is left to inference.

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