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

Annotations declare destructiveHint=true, so the agent already knows this mutates state; the description adds substantial context on top: atomicity ("A failed batch changes nothing", full pre-validation), rollback semantics (prior steps undone when a later step fails), one-undo-group behavior, and cooking of display nodes. It also notes that a capture step with no output writes its own file, which is a real side effect an agent must anticipate.

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 the key exclusion are front-loaded, and every paragraph carries different information (undo grouping, no mid-list branching, atomicity, return shape, cooking). Some sentences are wordier than necessary ("...and a person can undo the whole thing with one keystroke"), and the paragraph on failure modes is dense loop-prone 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?

There is no output schema, so the description carries the return contract itself: one result per operation in order, plus the picture of every capture step, plus the cooked display node's point/primitive counts and touched nodes with errors, and advice to read that before building on the result. Failure reporting (error names the step index and its error) and the multi-capture case are also covered, which is complete for a 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?

With a single parameter at 100% schema coverage the schema already documents the shape, but the description adds real semantics: ordering, the rule that any server tool except batch is allowed, and how id/"$id" (or "$id/child") lets a later step consume an earlier step's node path instead of guessing names. It doesn't add argument-level detail for the individual sub-tools, which is appropriately left to 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?

"Run several Houdini tools in one call" names a specific verb and resource, and the description immediately frames the scope (many nodes, wires and parameters in one round trip and one undo group). It is unmistakably distinct from the single-purpose siblings like node_edit, cook or parm_set.

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 positive use case (build a network), an explicit exclusion ("Do not use it when a later step needs to read what an earlier step made"), and the reason (the list runs without the agent in the middle, so nothing can branch on a result). It also spells out the one exception, the id/"$<id>" path substitution, so the agent can decide between batching and sequential calls.

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

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

Beyond the annotations, the description discloses that the view is restored, that nothing changes the scene permanently, that flipbook returns a path rather than a picture, that sheet/movie use an OpenGL ROP working without a window, that headless capture runs in a new hython, and that the return includes JSON window state. This is far richer than the readOnly/idempotent hints alone.

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

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

Front-loaded with purpose, then usage, then exclusion, then a mode list, so the agent can stop reading early. It is long, and some details (grey background, no-window behavior) are restated in more than one place, but for a 34-parameter tool the length is largely earned.

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 34 optional parameters and no output schema, the description carries the burden well: it explains what is returned (picture plus JSON window state), the headless fallback behavior, and how a picture's staleness points to a display flag issue. An agent can call this correctly without further documentation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic guidance the schema lacks: flipbook returns a file path, sheet with step > 2 hides motion and warns, azimuths produces a turntable, bounds can isolate just the hands, and how to aim the view via several parameter combinations. This is genuine value beyond the structured fields.

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

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

States a specific verb and resource ('Make a picture of the scene, or of the network editor') and enumerates all seven modes, so an agent knows exactly what it produces. It also explicitly contrasts itself with the sibling 'render' tool, removing 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?

Gives an explicit positive trigger ('confirm your own work... before you report that a task is done') and an explicit exclusion with the named alternative ('Do not use it for a final picture: render does that through a ROP'). No inference is left to the caller.

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 (readOnly=false, idempotent=true, destructive=false), the description discloses that a wire into an occupied input replaces the existing one, that a list of wires lands in one undo group and one round trip, and that invalid input indices are reported rather than silently dropped. These are operationally important facts an agent would otherwise have to guess or test.

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

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

Front-loaded with purpose, then alternatives, then a mode-by-mode breakdown – each block is short and every sentence carries information (replacement semantics, undo grouping, return shape). No filler or restatement of the title.

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

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

For a 9-parameter, zero-required, mode-driven mutation tool with an output schema, the description covers purpose, mode semantics, item/default behavior, alternatives, and a brief return outline. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is 100%, so parameter meaning is already documented; the description nonetheless adds mode-to-parameter mapping that the schema only signals via name prefixes, and restates that both indices count from 0 and either end may be a network dot. Much of this is reinforced rather than new, but the per-mode grouping genuinely helps select the right 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?

Opens with a specific verb and resource ('Change how nodes feed each other') and immediately enumerates the three modes (connect, disconnect, reorder). An agent can distinguish this from node_edit and scene_overview 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 to use it after node_edit has created the nodes, then names two alternatives with the conditions that select them: node_edit mode "create" with input_path for wiring a node being made now, and scene_overview mode "network" for reading wires. When-to-use and when-not-to-use are both stated.

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

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

It discloses the crucial destructive trait absent from annotations: 'Each call takes the log entries away, so a call returns only what is new since the call before it.' This is a consumption side effect that matters operationally and is consistent with idempotentHint=false. The readOnlyHint=true annotation sits alongside, and the description clarifies the non-persistent read nature rather than contradicting 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?

Front-loaded with purpose, then usage, then exclusions, then behavior. Every sentence earns its place except the trailing 'Returns JSON.', which is redundant given an output schema exists. Efficient overall with only that minor waste.

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

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

With an output schema present, the description need not explain return structure. It fully covers purpose, routing to siblings, and the log-consumption behavior, so an agent has everything required to call it correctly.

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

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

Schema description coverage is 100%, so every parameter (limit, source, severity, root_path, node_limit, node_errors) is already fully documented in the schema. The description adds the relationship hint that root_path is 'the network that node_errors walks' but otherwise introduces no parameter 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?

The opening sentence gives a specific verb (Read) and two concrete resources (the Houdini log and node errors). It is immediately distinguishable from cook (which returns live cook errors) and scene_overview (which lists erroring nodes), both named later in the description.

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 it ('when something did not do what you expected', with the empty-geometry cook-error example), when NOT to use it ('Do not use it for the errors of nodes that you cook now'), and names the two alternatives (cook, scene_overview mode "errors") with the condition selecting each.

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, readOnlyHint=false and idempotentHint=false, and the description is consistent with them: cache_clear removes cached files, sim_reset discards simulation state. It also adds genuinely valuable behavior that annotations cannot express: cooks can take hours, the call blocks, Houdini answers no other call until the cook ends, MCP task clients get a task immediately, and session action='interrupt' stops it. That blocking/interrupt information is non-obvious operational behavior beyond the 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?

Front-loaded with modes, then usage, then returns; each mode entry is a tight line. It runs long, and the 'Returns JSON' paragraph partly duplicates the output schema that already exists, which is the only real waste. The opening metaphor costs a sentence before the concrete content arrives.

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, six-mode, destructive and potentially hours-long blocking tool, the description covers everything an agent needs: mode semantics, the stale-error/recook case, sim_reset's silent-stale-result trap, failure reporting through 'failed', and how to interrupt. Output shape is covered by the output schema, so the description need not carry it.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns a step above by explaining what each mode value actually does (schema only lists the strings), what frames/frame_range do across modes and that the playbar is restored, and that parameter writes report which ones changed nothing. It adds real semantics rather than restating field descriptions.

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

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

The opening sentence is stylized, but the mode list immediately pins down concrete verbs and resources: cook nodes, write/clear file caches, step/reset DOP simulations, recook errored nodes. It explicitly contrasts itself with geometry_inspect ('Do not use it to read the result'), so an agent can separate 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?

It gives an explicit positive recipe ('write a few parameters, cook a range of frames, and read the seconds'), an explicit exclusion with the named alternative (geometry_inspect for reading results), and an explicit anti-pattern ('Cook frames here, not in an execute loop of hou.setFrame and geometry()') with the reason. When-not guidance is as strong as when guidance.

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

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

Annotations only cover the safe-read profile (readOnly/idempotent/not open-world). The description adds real behavior: pages come from the local install so they match the build, the first search indexes a build in a few seconds and persists to disk, and page reads never wait on the index. It also discloses return formats (markdown for a page, JSON for a search).

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 purpose, then usage rules, then operational behavior, then the parameter contract. Short paragraphs, no filler; each sentence carries a distinct instruction or disclosure.

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 only light mention, and the description still summarizes them. Combined with the mode contract, build defaulting behavior (session build, then $HFS, then newest), and the indexing caveat, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning beyond the schema by stating the mutually exclusive mode contract ('give exactly one of query, page, or node') which the schema does not express as a oneOf, and by noting that 'node' is the only input needing a live Houdini session. It does not add detail for part/build/section/limit/category.

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

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

States a specific verb and resource ('Read the official Houdini documentation') and immediately scopes it ('the authority on every node, parameter, VEX function and HOM call'). This clearly separates it from all siblings, which manipulate or inspect the live scene rather than read reference docs.

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 ('read the page before you use an API that you have not confirmed in this session'), why it matters (names and enum members change between releases and wrong ones fail silently), and explicit exclusions ('do not answer from memory, do not read sidefx.com yourself'). Nothing is left to inference.

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

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

Beyond the annotations, it discloses that code runs with Houdini process rights, can write files, delete nodes, and quit Houdini. It also explains silent write failures and `write_warnings`, blocking behavior during execution, timeout side effects, and that background jobs refuse other calls until they end.

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

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

The description is long but front-loaded and organized by purpose, alternatives, warnings, and mode list. It is appropriately sized for a destructive multi-mode execution tool, though some sentences duplicate schema detail and the end-of-session feedback advice is slightly tangential.

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

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

Given the tool's complexity, destructive annotations, 11 parameters, and output schema, the description covers the critical gaps: modes, side effects, silent parameter-write behavior, blocking behavior, timeout semantics, and when to use alternatives. An agent has enough context to call it safely and correctly.

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

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

Schema coverage is 100%, so the schema already documents parameters thoroughly, but the description adds useful mode-specific meaning: what each mode does, that Python does not return the last line's value, how `file` and `args` relate to `sys.argv`, and the semantics of `background`, `wait`, and `timeout`.

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: 'Run code in Houdini, with the full `hou` module and no guard.' It enumerates all supported modes and distinguishes itself from siblings by saying it is for what no other tool covers and explicitly warning against rebuilding networks that `node_edit` handles.

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

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

It gives explicit when-to-use guidance ('Use it for what no other tool covers', 'confirm an API in the live session') and when-not-to-use guidance ('Do not use it to build a network...', 'Prefer a named tool when one exists'). It also routes long-running work to `background` and interruption to `session action='interrupt'`.

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 the tool cooks the node, that "try" runs verbs or temporary hidden nodes with no scene change, and that only "export" writes and silently overwrites an existing file while all other modes write nothing. Read-only-looking usage is thus clearly scoped. Minor deduction: the overwrite behavior sits in tension with destructiveHint=false and is buried in one mode's paragraph rather than flagged near 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?

Long but front-loaded: purpose and the sibling exclusion come first, then a mode catalogue with per-mode paragraphs. The full 25-mode list is repeated verbatim from the schema's mode enum, which is redundant weight, but the structure is otherwise disciplined and each mode paragraph earns its place.

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

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

For a 25-mode, 31-parameter tool, the description covers every mode's intent, key parameter, notable defaults, and the paging/performance caveat ("keep count small and page with start"). An output schema exists, so return shapes need not be explained, and the remaining complexity is handled.

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 cross-parameter guidance: which parameters each mode consumes (bins for the volume modes, limit for attrib/voxels/stretch, threshold with different defaults per mode), the "token or index" rule for menu values in steps, and wildcard syntax for pattern. Most of this duplicates the schema text, which keeps it below 5.

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

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

"Read the geometry that a node produces. This cooks the node." names a specific verb and resource, and immediately states the side effect. It explicitly contrasts itself with node_inspect (parameters vs geometry), so an agent can route 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?

States when to use it ("confirm that a node made what you expected: the point count, an attribute a wrangle wrote, the shape of a volume") and when not to ("Do not use it to read parameters: node_inspect does that"). It also names a default entry point, "summary" — "Start here."

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 non-idempotent, and the description goes beyond them by disclosing the blast radius: install and uninstall "change every node of that type in the session." That is exactly the kind of context annotations cannot express. It still doesn't say whether section_set overwrites existing text, what happens when a file_path is missing, or how errors surface, so it stops short of a 5.

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

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

Front-loaded with the purpose, then a compact mode index, then one-line bullets per mode, then a return/impact note. Every bullet earns its place, but the bare mode list at the top partially duplicates the per-mode bullets below it, costing a little 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?

With an output schema present, the description needn't explain return values, and a one-line "Returns JSON" suffices. For a 10-mode destructive mutation tool it covers triggers, mode semantics, and cross-session impact well; the remaining gap is overwrite/error semantics for the write modes (reload, update, create, section_set).

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 each property already carries a mode-prefixed description, so the baseline is 3. The description adds real value by organizing parameters by mode and thereby implying the per-mode required combinations (install needs file_path, create needs node_path plus name/label/file_path) even though the schema declares zero required parameters. It omits that mode defaults to "list".

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 pair and resource ("Read and change Houdini digital assets") and immediately enumerates the ten modes, so the agent knows the full surface of the tool. It also names the sibling it is not (node_inspect) and the domain boundary (.hda files), making it clearly separable from node_edit/parm_set/node_inspect.

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 ("when a node type comes from a .hda file: to find the file, to load a new one, or to read the scripts and help inside it") plus an explicit exclusion that redirects to node_inspect for scene-node parameters. The per-mode list further disambiguates internal alternatives so the agent can pick the right mode.

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

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

Annotations already declare destructive/non-idempotent, and the description goes well beyond them: house-rule violations return `house_rule`, deletes of still-feeding nodes are refused with the reader list, layout moves user-placed nodes and the result says so, split rewrites embedded paths and reports unresolvable ones, and undo grouping is specified. It also warns that Houdini adds numeric name suffixes and the caller must use the returned path.

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

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

Purpose and routing guidance are correctly front-loaded, but the 18-line 'mode, and the arguments that each mode reads' block duplicates parameter documentation that is already at 100% schema coverage, inflating an already long description. Structure is scannable, but a meaningful fraction of the text does not earn its place.

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

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

For a 30-parameter, 18-mode, destructive, non-idempotent mutation tool this is complete: it covers mode selection, argument roles, failure modes, name-resolution behavior, and return-value quirks. An output schema exists, so return-format detail is rightly not expanded further.

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 3 baseline is already met by structured data; the description adds real meaning on top, e.g. that copy returns a `copies` map that must be used instead of list order, that each `old` in replace must appear exactly once, and that a note without position is placed to the right. However, the long per-mode argument enumeration largely restates what the schema descriptions already say.

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 ('Change the nodes in a network') and then enumerates all 18 modes, so the agent knows the full action space. It explicitly distinguishes itself from parm_set (values) and connect (wires), which are the two siblings an agent could plausibly confuse it with.

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 is given: 'Use it to build a network. Then use parm_set for the values, and connect for the wires' plus the negative 'Do not use it to set parameters'. It also states when-not conditions ('Do not compute positions') and per-mode preconditions such as the delete refusal unless force=true.

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

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

Annotations already declare readOnly/idempotent/closed-world, but the description adds traits they cannot express: a list keeps going after a failing node and each result names its path, cook errors come back inside the result payload rather than throwing, an empty geometry with no error line means the node cooked and made nothing, and the playbar is restored after `frames`. These are genuine behavioral disclosures beyond 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?

Front-loaded with purpose, then the exclusion, then mode semantics, so a reader can stop early. The mode name roll-call in the opening line is then repeated and expanded in the bullets, which is a modest redundancy in an otherwise tight, scannable layout.

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

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

An output schema exists so return values needn't be spelled out, and the description still covers the salient error semantics. For a 13-parameter, 20-mode inspection tool, the guidance on mode selection, prerequisites per mode, partial-failure behavior, and the validation mode's motivating failure mode leaves nothing an agent needs 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 goes further by explaining what each mode requires of the parameters (parm for expression/keyframes/readers, channel+start+end for channels, object_name+field_name for simulation, frames for time_dependency, pattern/fields for solver-sized parameter sets). It adds practical selection guidance such as "A solver has hundreds of parameters: give pattern or fields." It stops short of 5 only because the per-mode text largely restates the terse schema hints rather than adding new syntax or defaults.

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 plus scope: "Read one node, or a list of nodes, without changing anything." It also explicitly separates itself from the sibling that lists networks (scene_overview), so an agent can pick it without opening another schema.

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

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

Gives explicit when-to-use ("Use it before you write: to confirm a parameter name, to see whether a parameter carries an expression, to read what a node reports after a cook") and an explicit when-not with the named alternative ("Do not use it to list a network: scene_overview does that"). It additionally sequences modes for the agent ("Read this first when you do not know the name to write").

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 non-idempotent, and the description adds substantial undisclosed-by-schema behavior: silent no-op writes with six named causes, refusal to write through channel references unless follow_reference=true, snapshot overwriting a same-named record, and the instruction to read `warnings` and `not_applied` before reporting success. Excellent coverage of what gets destroyed and where writes may silently fail; it stops short of stating permissions/auth needs, but the safety profile itself is thoroughly enriched.

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

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

Front-loaded with purpose, then the silent-failure taxonomy, then mode-by-mode argument detail, then return shape – a sensible ordering for a 22-parameter multi-mode tool. It is long and the mode enumeration partially duplicates the schema's `mode` description, but nearly every line 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 tool with 22 parameters, nested objects, 15 modes and an output schema, the description supplies exactly what the structured fields cannot: mode-to-argument mapping, failure-mode diagnosis, prerequisite sequencing, and workflow caution for sweeps. The return contract is summarized ('value before, the value after, and a reason') without duplicating 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, and the description goes beyond it by naming the exact argument set each mode reads and adding semantics the schema cannot express: a menu takes its token ('custom'), a bit-field menu takes a token or a list, a ramp defaults to a list of [position, value], and a second 'spare' call safely replaces a control in place. Remaining overlap with the schema's per-mode prefixes keeps it from a 5.

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

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

The first sentence names the specific verb and resource ('Write parameter values, or press a button') and states the batching scope ('One write, or a list in one undo group'). The mode list enumerates the full surface, and it is clearly distinguished from the read-only sibling node_inspect, which it references as a prerequisite.

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 sequencing ('Use it after node_inspect has confirmed the parameter name and the type'), explicit substitution guidance ('Use it instead of numbers typed into VEX'), and a concrete sweep workflow ('restore before each variant, not once at the end'). Each mode also carries its own when-to-use context, e.g. 'press' is for buttons whose work fails later and in silence.

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 destructive=true, but the description adds the context that matters: 'cook' returns at once and must be followed by a status read, 'dirty_all' removes outputs on disk, 'cancel' stops the running cook, and failed items carry the command and log path. This is genuine behavioral detail beyond the annotation flags.

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

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

Front-loaded purpose, then modes, then a returns note; the mode list is a scannable structure. Slight redundancy between 'Use it for a TOP network only' and 'A TOP node does not cook like a SOP' costs a point.

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

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

With an output schema present, the description needn't document return shape, yet it still flags the actionable payload of a failed item (command and log path) and the async nature of the cook. Nothing needed 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; the description goes further by explaining the semantics of each mode value and how 'state' filters workitems ("failed") and how 'dirty_all' removes on-disk outputs. That is more than the schema's one-line field descriptions, though it largely mirrors 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?

States a concrete verb and resource ('Cook a TOP network, and read what its work items did') and immediately scopes it to TOP networks as distinct from SOP/DOP/ROP. An agent can distinguish it from cook and render 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 when to use it ('Use it for a TOP network only') and routes to the alternatives with conditions: 'For a SOP or a DOP, use cook. For a ROP, use render.' The mode list further tells the agent which mode answers which question.

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 substantial state-change context beyond annotations: frame changes persist across calls and for the user, 'range' alters flipbook coverage and any ROP following $FSTART/$FEND, and 'play' requires a GUI. Annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) already flag mutation and idempotency; the description complements rather than contradicts, though it does not say what 'play' does to an in-progress cook or how long it blocks.

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 usage constraints are front-loaded in two short blocks, with the mode enumeration after — the right ordering for an agent deciding whether to call. The mode list duplicates the schema's enum, which is some redundancy, but each line adds a behavior not stated in the schema (e.g. playback range sits inside the scene range).

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 prerequisites (GUI for playback), blast radius (persistence for the user, flipbook and $FSTART/$FEND ROP ranges), and the alternative tools to prefer for non-persistent reads. With an output schema present, no return-value explanation is needed, and 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 the baseline is 3; the description earns one better by mapping each parameter to the modes that consume it (frame for 'frame', start/end for 'range' and 'playback', action for 'play') and listing the action values, giving a coherent per-mode picture. Much of this restates the schema's own parameter descriptions, so it is not a large increment.

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 or set the time of the session') and immediately enumerates the five modes, so the agent knows exactly what surface the tool covers. It is clearly distinct from the read-only inspectors named as 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 ('before you read geometry that changes over time: a SOP cooks at the current frame') and explicit when-not-to-use (geometry_inspect, node_inspect, stage_inspect take `frames` and restore the playbar). The rationale for the distinction — a frame set here persists for the person and for later calls — makes the tradeoff legible.

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 non-read-only, non-destructive, non-idempotent, closed-world; the description adds far more: wait returns after up to ~28 minutes, without wait husk can continue after the call, background requires a saved .hip with no unsaved changes and returns a pid/log at once, watch works while Houdini is busy, and the failure signature of a render that writes no file with no process running. These are exactly the operational traits an agent cannot infer from 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?

Front-loaded with the mode list and organized per mode with indentation, so an agent can jump to the relevant block. A few lines are dense tangents (CPU Quality controls, the 0% GPU note), though they do aid interpretation rather than pad. Overall efficient but longer than strictly necessary for any single call.

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 spelled out, yet the description still sketches what each mode yields (pid and log, render stats, mean/max AOV differences, process counts). For an 11-parameter, seven-mode, side-effecting tool with modest annotations, nothing needed to call it correctly appears 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 beyond the schema: that output_path and res_scale apply to this render only while the ROP retains the user's output and size, that frame_range accepts [start, end] or [start, end, step], and that background operates on the saved .hip. Some mode text still restates what the schema descriptions already say, which keeps it from a 5.

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

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

Opens with a specific verb set and resource ('Start a render, read its settings, or watch it run') and immediately enumerates the seven modes, so the agent knows the full scope of the tool. It explicitly names the sibling it is not ('For a fast look at the viewport, use capture instead'), which disambiguates it from capture 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?

States when to prefer capture over render ('much quicker') and when to prefer render ('a final picture through a ROP node'). Per-mode guidance includes when to use background+watch versus blocking wait, and when res_scale/output_path are appropriate ('test renders'). No mode is left without a cue for selection.

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

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

Even though annotations declare destructiveHint=true and readOnlyHint=false, the description adds critical behavioral detail: load removes everything including undo history, merge renames conflicting names and is one undo step, list_file uses a separate hython and takes seconds. This goes well beyond 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?

Despite its length, the description is front-loaded with a one-line summary followed by a clean mode list and per-mode explanations. Every sentence carries useful information for a tool with seven modes and destructive operations.

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

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

Given the complex multi-mode behavior, destructive load, undo-step semantics, and the existence of an output schema, the description is complete. It tells the agent what each mode does, the risks, and the expected side effects.

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 meaningful mode-specific semantics for path, count, and nodes, e.g., save over the open file when path is empty, merge brings children and wires, list_file lists networks. It enhances the schema rather than merely repeating it.

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

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

The description states a specific verb and resource (read/save/load the scene file, step undo history) and enumerates seven distinct modes. It is clear enough to distinguish from most siblings, though it does not explicitly name alternative tools like scene_overview or session.

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 mode-specific usage guidance: use "save" before hard-to-undo changes, use "info" to check for unsaved work, and warns that "load" wipes the session and undo history. It lacks explicit exclusions or sibling-tool alternatives.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description adds non-obvious behavior beyond them: a missing path returns an error rather than an empty list, `changes` excludes your own edits, and the first `changes` call begins watching. These are exactly the operational details an agent needs before relying on the output.

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

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

Front-loaded purpose and routing first, then the mode semantics, then return-value caveats — a logical order with no wasted sentences. The mode block is long but every entry earns its place given thirteen dispatch options.

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 format needn't be spelled out, yet the description still notes the JSON/error contract. All modes, the path-error behavior, and the stateful `changes` lifecycle are covered, leaving no gap an agent would need to guess.

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 above that by explaining what each mode actually returns and how pattern/node_type/compact/recursive modify behavior per mode. The per-parameter schema docs already carry syntax, so the gain is semantic rather than syntactic.

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

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

States a specific verb and resource ("List what the scene holds") and front-loads its role as the entry-point discovery tool. It explicitly distinguishes itself from node_inspect and geometry_inspect, so an agent can route correctly without opening any schema.

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

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

Provides explicit when-to-use ("Start here, before you touch a node", find a node path, see a network, learn node types) and explicit when-not-to-use, naming both alternatives (node_inspect, geometry_inspect). The modes list doubles as a selection guide for 13 distinct query shapes.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the description's job is to add context beyond that, which it does: an invalid path aborts the call and leaves the selection unchanged, and the return is JSON with the selected paths. It stops short of stating permission or concurrency implications of a mutation, so a 4 rather than a 5.

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

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

Front-loaded with the core read/write distinction, then usage, then the path format contract. The line-broken layout is slightly choppy but every sentence carries distinct information and none 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-parameter dual-mode tool with annotations covering the safety profile and an output schema covering return shape, the description supplies everything needed: both modes, usage conditions, the alternative for searching, path format, and failure behavior.

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

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

Schema coverage is 100% and the schema already documents the three modes (omit to read, one/list to replace, empty list to clear). The description adds value on top of that by giving the path format with a concrete example ("/obj/geo1/mountain1") and the error behavior for a non-node path.

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 states a specific verb and resource with both modes: 'Read the node selection, or set it.' It then explicitly distinguishes itself from the sibling that could be confused for it (scene_overview mode "search"), so an agent can pick correctly 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 explicit when-to-use contexts ("see what the person works on before you change the scene, and to show them your result when you are done") and an explicit when-not-to-use with the alternative named ("Do not use it to find nodes: scene_overview mode 'search' does that"). Nothing is left to inference.

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

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

Annotations mark the tool non-read-only and destructive, and the description goes well beyond them: it says start never touches a running Houdini, stop only kills bridge-started headless sessions, start_gui waits up to 4 minutes and survives bridge exit, interrupt may send Escape on Windows, and an interrupted simulation leaves a partial cache. It also discloses the per-result `_session` field, which explains confusing empty-scene results.

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

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

It is front-loaded with a one-line summary, an action index, and usage guidance before the long action glossary, so the most important content comes first. It is long for a single description, but the length is warranted by eight distinct actions; a few phrases are marginally redundant 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 multi-action lifecycle tool this covers everything an agent needs: which action to pick, what each does to processes and files, timeout behavior, and how to detect the wrong session. An output schema exists, so return format is correctly left out, with only the `_session` convention noted because it affects interpretation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: version accepts partial or full releases and defaults to the running window's version, port comes from list and is used differently by attach vs interrupt, and hip is only meaningful for start_gui. These per-action scoping details are not 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 opening line gives a specific verb set and the exact resource: report Houdini sessions, pick one, start/stop/interrupt. It further distinguishes itself from scene_overview and lists all eight actions up front, so an agent can tell what it does 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 names concrete trigger conditions ('use it first when a tool says that Houdini is not reachable', 'use it to learn the Houdini version before an API that changed') and an explicit exclusion ('Do not use it to read the scene: scene_overview does that'). It also tells the agent when to use attach ('when list shows more than one').

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 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.