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

Annotations declare destructive/non-idempotent, and the description adds substantial context beyond them: validation-before-execution, the exact failure/rollback semantics (a failed batch changes nothing, prior steps undone), the error format naming step index, the return shape, and the side effect of cooking touched SOP networks so `check` must be read afterward.

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 constraints are front-loaded in the first two paragraphs, failure semantics follow, and return behavior closes. Despite length, every paragraph carries a distinct operational fact with no filler.

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

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

For a complex multi-step mutation tool with no output schema, the description covers the essentials: atomic rollback, error identification, return ordering, cook side effects, and capture file behavior. Nothing critical to calling 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 the schema documents that each step is {"tool": ..., "params": ...} with any tool except batch. The description reinforces ordering ('in the order of the operations') but does not add syntax or format beyond the schema, so the baseline of 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 first sentence states a specific verb and resource: run several Houdini tools in one call. It is unmistakably the batch executor among siblings like cook, parm_set, and connect, which run one operation each.

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 (building a network in one round trip and one undo group) and an explicit when-not-to-use condition: 'Do not use it when a later step needs to read what an earlier step made.' The branching limitation is stated as a hard rule.

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 view and display flag are restored afterward ('Nothing here changes the scene for good'), that headless Houdini has no viewport and runs in a new hython with no camera or ROP, that flipbook/movie return paths rather than pictures, that frames cook in order, and that certain inputs emit warnings. This is exactly the temporary-mutation nuance that the readOnlyHint=false/destructiveHint=false annotations only hint at.

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 mode list are good, but the prose is long and stylistically loose, and the headless 'no window has no viewport' point is made twice (once in the mode block, once later), which is wasted space for a 31-parameter tool.

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

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

No output schema exists, yet the description explains the return (the picture plus JSON with frame, open file, selection, visible network, and display/render/template flags) and the headless failure path that names the next action. For a zero-required-parameter tool with 100% schema coverage, the agent has what it needs.

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 cross-parameter routing the schema lacks: which parameters each mode consumes (sheet uses count/start/step/columns/tile_width, movie uses fps/frame_range/resolution), that step>2 hides movement and warns, and the aiming-equivalents among frame/fill/target/azimuth/elevation/camera. It stops short of documenting every parameter, so not 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?

States a concrete verb+resource ('Make a picture of the scene and look at it') and immediately distinguishes itself from the sibling that would otherwise be confusable, render, plus node_inspect for graph reading. An agent can pick this over render 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 ('confirm your own work', 'before you report that a task is done'), an explicit when-not ('Do not use it for a final picture: render does that through a ROP'), and names the alternative for the network-editor case. 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 cover the safety profile (readOnlyHint=false, idempotentHint=true), and the description adds genuinely new behavioral context: a wire into an occupied input is replaced, a batch of wires lands in one undo group and one round trip, and invalid input indices are reported rather than silently dropped. That is exactly the kind of operational detail the annotations do not carry.

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

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

Well front-loaded: purpose, then when-to-use/when-not-to-use, then mode semantics, then return shape. The mode block is somewhat verbose and partially duplicates schema descriptions, but every line is functional for a 9-parameter, 3-mode tool.

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

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

Covers all three modes, batching via `items`, index conventions, conflict resolution, and return format, and it even notes the outcome for invalid indices despite an output schema existing. An agent has everything needed to call it correctly on the first try.

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 3 is the floor, and the description earns above it by explaining what the indices mean behaviorally (count from 0, dst_input_index picks the input, replacement on conflict) and which keys each `items` entry takes per mode. It still restates a fair amount of what the schema already says, keeping it out of 5 territory.

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 names the resource (node wiring) and the mode list makes the specific operations concrete: connect, disconnect, reorder, each with the exact semantics of src_path/dst_path/indices. 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?

Explicit sequencing ('Use it after node_edit made the nodes') plus two named exclusions with the alternative to use instead: node_edit mode "create" for wiring a node made in the same call, and scene_overview mode "network" for reading wires. 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?

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 declare a destructive, non-idempotent mutation, and the description goes well beyond them: it explains playbar restoration, sim_reset's silent-stale-result failure mode, that a timeout does not stop the cook, and that a long cook should be split into parts. It also discloses the `ok`/`failed` upstream-error reporting and empty-simulation failure condition.

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 a one-line summary, then usage, then a mode table, then returns; each section is purposeful. It is dense and occasionally restates schema text (playbar restoration, frame_range semantics), which keeps it from a 5.

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

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

For a complex seven-parameter, multi-mode, destructive tool, the description covers every mode's behavior, the return contract, failure semantics, and timeout guidance. Nothing needed to invoke it correctly is missing, even though an output schema already exists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains how mode selects the meaning of frames vs frame_range, that parameters writes report which changes had no effect, and the default range behavior for cache_write. This is above the schema-only 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?

States a specific verb and resource ('Force work to happen, and report what the work said and what it cost') and enumerates the five modes with distinct semantics. It explicitly differentiates itself from the sibling geometry_inspect, so an agent can select it 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 a concrete use case ('run a test: write a few parameters, cook a range of frames, and read the seconds'), and an explicit exclusion ('Do not use it to read the result: geometry_inspect does that, and it cooks the node as well'). When-to-use, when-not, and the alternative are all named.

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?

Annotations declare destructive/openWorld/non-idempotent, but the description adds concrete consequences beyond them: code runs with Houdini process rights and can write files, delete nodes and quit Houdini; writes to expression-driven, disabled/hidden, or range-clamped parameters silently do nothing; channel-reference writes affect other nodes; write_warnings must be read. It also discloses blocking behavior ('Houdini answers nothing while a script runs', 'other calls are refused' during a background job) and that a timed-out script's changes persist.

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 capability, the danger, and the routing rule before the mode enumeration. Dense and mostly waste-free, though the mode list makes it long enough that some readers may skim past the write_warnings and blocking notes.

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

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

For a 10-parameter, output-schema-bearing power tool, it covers everything an agent needs: mode semantics, safety consequences, blocking/timeout behavior, and the write_warnings field it must read. Nothing essential 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 baseline is 3, but the description goes further than the schema by explaining what each `mode` actually does — stdout/stderr retention on python, that vex_check compiles without running, that env reads a Houdini variable, that job reports running/output/done state. It also clarifies file/args/globals interplay and timeout persistence, adding real meaning over the terse schema strings.

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 code in Houdini') and immediately qualifies scope with 'with the full `hou` module and no guard', which distinguishes it from the named node/parameter tools. It also positions itself against siblings: 'Use it for what no other tool covers.'

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 rules: 'Prefer a named tool when one exists', use `file` for re-run scripts, use `background` with a large `timeout` for long work, and session action='interrupt' to stop it. It even tells the agent what to do when it finds itself repeating a script (report the missing named tool in session feedback).

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?

Discloses side effects beyond the annotations: cooking the node, that 'export' overwrites an existing file while 'the other modes write nothing', that 'try' leaves the scene unchanged, that an empty summary carries the node's errors/warnings, and a performance warning ('A large read is slow: keep count small and page with start'). This is consistent with readOnlyHint=false and adds real 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?

Front-loaded with purpose, then when-to-use, then a scannable mode list, which is the right structure for a 19-mode tool. It is long, and some mode entries duplicate the schema's own parameter descriptions (bins, limit, reduce), but almost every sentence carries operational information.

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

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

For a 28-parameter, 19-mode tool this covers the selection surface thoroughly: mode purposes, defaults, side effects, performance guidance, and multi-path/frames behavior. An output schema exists, so return-value shape is correctly left out.

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 already 100%, so baseline is 3, but the description goes further by binding parameters to specific modes and explaining behavior the schema states only tersely (e.g. 'unique=True returns each value that occurs and how many elements carry it', 'An array past limit numbers is thinned', the skeleton 'pattern' filter). It is largely a restatement of the per-mode parameter map rather than new syntax 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?

Opens with a specific verb+resource ('Read the geometry that a node produces') and immediately scopes it against the closest sibling ('Do not use it to read parameters: node_inspect does that'). An agent can distinguish this from node_inspect 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?

Explicitly states when to use it ('confirm that a node made what you expected'), when not to ('read parameters'), and gives a recommended starting mode ('summary ... Start here'). It also routes the agent to the right mode for a given question (e.g. 'compare' to prove a replacement node matches, 'try' to learn what a node would make).

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; the description adds the key scope warning that 'install' and 'uninstall' change every node of that type in the session, and notes the return type (JSON). It does not call out which modes are read-only vs mutating explicitly, but the destructive blast radius is 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?

Front-loaded with purpose and routing, then a well-structured mode-by-mode list where each line adds actionable detail. Slightly verbose overall 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?

An output schema exists so return values needn't be explained, and the description covers all ten modes with their parameter bindings plus the session-wide side effect. Complete enough for correct invocation, with only minor gaps in per-mode read/write labeling.

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 binds each parameter to its modes (the baseline would be 3). The description adds semantic value by explaining what each mode does with the parameters, e.g. section_set writes `content` into `section_name` and install loads the file at `file_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?

States a specific verb+resource ('Read and change Houdini digital assets') and immediately scopes the domain to .hda files. It explicitly distinguishes itself from the sibling node_inspect, 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 explicit when-to-use ('when a node type comes from a .hda file') and when-not ('Do not use it for the parameters of one node in the scene: node_inspect does that'), naming the alternative. The mode list further maps each intent to an action.

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, readOnlyHint=false. The description adds real value beyond them: undo-group batching, the warning that 'layout' moves hand-placed nodes, that delete also removes sticky notes/boxes, copy wire-following behavior, and the critical Houdini auto-suffix caveat plus 'never look the node up again by the name you asked 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?

Long, but for a 26-param, 15-mode dispatcher the length is justified and heavily structured with a mode-to-arguments table. The purpose and the parm_set/connect routing are front-loaded. Slightly dense but no clearly wasted sentence.

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, nested params, and 15 modes, the description is complete: it covers argument selection per mode, undo semantics, and the key post-call invariant about reading the returned path. An output schema exists, so return-value details are not required here.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by grouping arguments by mode and stating cross-parameter interactions (path vs destination_path for move, replace's 'must appear exactly once' rule, code_file for long snippets) that the flat schema 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?

States a specific verb (change/edit) and resource (nodes in a network) and immediately distinguishes itself from siblings by naming parm_set for values and connect for wires. The mode list makes the full scope of the tool concrete.

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

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

Explicitly routes the agent: build the network with this, set values with parm_set, make wires with connect, and 'Do not use it to set parameters: parm_set does that.' This is textbook when/when-not/alternative guidance.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint), yet the description still adds real behavioral context: a failed node in a list does not abort the rest and each result names its path, the playbar is restored after multi-frame reads, and an empty geometry with no error line means the node cooked and produced nothing. That is disclosure beyond what the annotations provide.

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

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

Front-loaded with purpose, usage and exclusion before the mode reference, which is well structured as a scannable block. The size is largely justified by 20 mode values, though several lines are chatty ('and nothing else', 'Read this first when you do not know the name to write') and could be tightened.

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 13-parameter, 20-mode inspection tool with an output schema and full annotation coverage, the description covers mode semantics, pre-write usage, failure behavior and list semantics. Nothing an agent needs to select a mode and 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 per-parameter terse descriptions already exist; the description adds value by binding parameters to modes ('With `frames` it times each one', '`channel`, `start` and `end` read the samples of one channel', 'give pattern or fields' for solvers) and by expanding every `mode` value beyond the schema's flat list. It stops short of adding format/syntax detail beyond that.

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 then explicitly distinguishes itself from the sibling that could be confused with it: 'Do not use it to list a network: scene_overview does that.'

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 usage trigger ('Use it before you write: to confirm a parameter name, to see whether a parameter carries an expression...'), an explicit exclusion, and names the alternative tool (scene_overview) for the excluded case. It also routes within itself ('Read this first when you do not know the name to write', 'Read it after you add nodes').

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 supply the generic destructiveHint/readOnlyHint/idempotentHint profile; the description adds substantial non-obvious behavior: the six causes of a silently-accepted no-op write, the refusal of writes through channel references unless follow_reference=true, the instruction to read warnings and not_applied before reporting success, snapshot overwriting an existing record, and diff being a no-op. This is exactly the context annotations cannot carry.

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

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

Long, but it is front-loaded (purpose, prerequisite, failure modes, then mode-by-mode arguments) and nearly every sentence carries operational weight. The mode enumeration partly restates the schema's mode enum, which is the main redundancy, but the per-mode argument detail justifies the length for a 15-mode tool.

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

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

An output schema exists, so return values need not be explained, and the description still adds the key caveat that success must be verified via warnings and not_applied. With 15 modes, 22 optional parameters and nested objects, nothing an agent needs to invoke this correctly appears to be 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 goes well past the schema: it maps every mode to the arguments it reads, clarifies menu/bit-field token syntax, and documents the spare control dictionary (name, label, type, default, min, max, strict, help, value, expression, items) with per-type defaults like ramp as [position, value]. That is meaning beyond the schema's per-field strings.

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 — 'Write parameter values, or press a button' — and immediately scopes batching ('One write, or a list in one undo group'). It also positions itself relative to sibling node_inspect ('Use it after node_inspect has confirmed the parameter name and the type'), so an agent can route between inspection and mutation 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 a real prerequisite (confirm name/type via node_inspect first), mode-selection guidance ('Use it instead of numbers typed into VEX' for spare), and workflow guidance ('In a sweep, restore before each variant, not once at the end'). It does not name alternative siblings for overlapping mutations (e.g. node_edit), so it stops short of explicit when-not-to-use routing.

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 behavior beyond the annotations: cook is asynchronous and returns immediately, cancel stops the currently running cook, dirty_all deletes outputs on disk (the concrete destructive action behind destructiveHint=true), and failed items carry a command plus log path. Nothing contradicts the readOnlyHint=false / destructiveHint=true / idempotentHint=false annotations.

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

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

Front-loaded with purpose then routing, followed by a clean mode list — every line earns its place. The multi-line indented mode block is slightly heavy for a four-parameter tool, but there is no filler or repeated 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?

An output schema exists, so return values need not be spelled out, yet the description still flags the actionable failure detail (command + log path) and warns to read it before mutating the network. All five modes, the async cook lifecycle, and the destructive dirty_all path are covered.

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 defining the semantics of each mode value and how `state` filters results (e.g. "failed") and what `dirty_all` actually removes. It stops short of documenting the `path` parameter's accepted forms beyond 'TOP network or TOP node'.

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 pair ('Cook a TOP network, and read what its work items did') and immediately differentiates itself from the sibling tools cook (SOP/DOP) and render (ROP). An agent can pick this over cook/render 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?

Explicitly scopes usage ('Use it for a TOP network only') and routes alternatives by node type: cook for SOP/DOP, render for ROP. It also enumerates every mode with a when-to-use condition, including the async cook pattern ('start the cook... read status after it to follow the work').

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 persistent side effects: a frame set here 'stays for the person and for every later call', and 'range' also alters flipbook coverage and ROP ranges bound to $FSTART/$FEND. It also notes playback requires a GUI. It does not, however, clarify how 'get' versus mutation modes interact with the declared idempotentHint for playback actions, leaving one small behavioral ambiguity.

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

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

Front-loads the one-line purpose and the key timing constraint before the mode enumeration, and every sentence carries information. The mode list is necessarily long for a five-mode tool, though the parenthetical explanation of the 'play' action values duplicates the schema slightly.

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-mode read/write session tool with an output schema available, the description covers timing, alternatives, per-mode semantics, persistence, and the GUI prerequisite. An agent has everything needed to choose a mode and 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 real meaning: each mode value is glossed ('range' sets the scene frame range vs 'playback' sets the playback range inside the scene range), which the schema's bare enum list does not convey. The start/end/frame/action roles are also tied to specific modes.

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

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

States a precise verb pair and resource ('Read or set the time of the session') and immediately names the operational context (SOP cooks at the current frame). It is clearly distinguishable from siblings like node_edit or render, which do not touch the session playhead.

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

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

Gives an explicit when-to-use ('before you read geometry that changes over time') and an explicit when-not-to-use, naming three alternatives (geometry_inspect, node_inspect, stage_inspect) and the parameter ('frames') that makes them preferable. 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?

The description goes beyond the annotations by detailing each mode's behavior, such as that a render can take a long time, that 'watch' counts processes and checks file existence, and that it works even when Houdini is busy. It also explains failure conditions and how to debug. Annotations only provide generic hints, while the description adds substantial operational 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?

The description is well-structured, front-loaded with the main purpose, then details modes, returns, and error handling. It is concise and every sentence adds value.

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 (7 parameters, multiple modes) and the presence of an output schema, the description provides all necessary context: mode behaviors, return format, failure diagnosis, and alternative tool. It is complete for an agent to use correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds some mode-specific context (e.g., what frame_range means, what output_path is for) but largely repeats what is in the schema descriptions. Baseline of 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 clearly states the tool starts, reads, or watches a render, and it explicitly differentiates itself from the sibling 'capture' by explaining that render is for a final picture through a ROP node, while capture is a faster viewport look. This distinguishes it from 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?

It gives explicit guidance on when to use this tool versus the alternative ('capture'), and it details the different modes and their purposes, including when to use 'watch' (for monitoring without Houdini). It also explains failure condition and how to diagnose it.

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 (destructiveHint=true, readOnlyHint=false) by spelling out that 'load' discards everything in the session and the undo history, and by defining what constitutes an undo step (one scene-changing tool call, a batch as one step except when it waits on capture/render). This is exactly the behavioral detail 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?

Front-loads the one-line purpose, then a usage hint, then a clean mode list. The undo-step paragraph is somewhat verbose but each sentence carries operational meaning, so little 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?

Output schema exists so return values need no elaboration, and the description still notes 'Returns JSON' plus which mode returns undone labels. Destructive 'load' behavior and undo semantics are disclosed, leaving no gap for correct invocation.

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% (baseline 3), but the description adds real meaning: it explains what each mode does with `path` (save over open file when empty, open .hip on load) and what `count` means per undo step. This exceeds the schema's terse per-parameter notes.

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

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

States a specific verb set and resource (read/save/load the scene file, step its undo history) and enumerates all five modes with their exact effect. An agent can distinguish this from siblings like scene_overview or session 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?

Gives explicit when-to-use guidance for two modes: 'save' before a hard-to-undo change, and 'info' to check for unsaved work. It does not name alternative tools or state when NOT to use this one (e.g. versus scene_overview), so it stops short of full routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld=false), yet the description still adds a concrete behavioral fact the annotations do not: a nonexistent path returns an error rather than an empty list. It also documents recursion behavior per mode. It stops short of cost/performance or output-shape hints, but the safety-critical ground is already covered by annotations.

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

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

Front-loaded purpose, then usage constraints, then the mode catalog, then a return-behavior caveat. The long mode list is necessary because the schema exposes mode as a free-form string with no enum, so every line 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?

An output schema exists, so return-value detail is unnecessary; the description still notes JSON output and the error-vs-empty-list distinction. All 12 modes are enumerated and mapped to their parameters, which is exactly what is missing from the schema for this multi-purpose tool.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description meaningfully binds parameters to modes (pattern/node_type only for search, category only for node_types, recursive only for children), which the flat schema does not convey. This is genuine added meaning beyond the schema, though it largely paraphrases the per-parameter text.

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 action and resource ("List what the scene holds") and positions itself as the entry point ("Start here, before you touch a node"). It explicitly names the two siblings it is not (node_inspect for one node, geometry_inspect for geometry), so an agent can discriminate without opening any schema.

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

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

Gives an explicit ordering instruction plus two explicit when-not clauses routed to named alternatives. The per-mode breakdown further tells the agent which mode to pick for which question, leaving little to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so 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?

Despite coverage from annotations (destructiveHint=true), the description adds substantial behavioral detail: start does not touch an already-running Houdini, stop only kills the bridge-started headless instance, start_gui waits up to 4 minutes and stays open after the bridge stops, interrupt restores Houdini responsiveness. No contradiction with a process-control tool being flagged destructive.

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 guidance, then a scannable per-action breakdown. It is long, but nearly every line carries operative information; only the _session explanation edges toward repetition of the result-handling theme.

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 formatting need not be described, and the description still notes that results name the answering session in `_session` and that the report says what to do when nothing answers. For an eight-action stateful tool this is complete enough to invoke safely.

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 it: version accepts a partial release like '21.0' and defaults to the running window's version, and port's role differs per action (attach vs interrupt). hip is tied specifically to start_gui.

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: reporting, choosing, starting, stopping, or interrupting Houdini sessions. It explicitly distinguishes itself from sibling scene_overview, so an agent can tell it apart 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 explicit triggers ('Use it first when a tool says that Houdini is not reachable') and an explicit exclusion ('Do not use it to read the scene: scene_overview does that'). Each action's use case is spelled out, e.g. attach 'when list shows more than one', interrupt for a runaway 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 already declare readOnly, idempotent, closed-world, but the description adds two non-obvious behaviors: "This cooks the node" (a read that triggers evaluation and can have side effects) and "The playbar goes back after" for frame reads. These are real behavioral facts not derivable from the annotations, though return-shape and cost details are absent (partly covered by the output schema).

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

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

Front-loads the core purpose and the SOP exclusion before the long mode enumeration, and each mode entry is one tight clause. The twelve-mode block is lengthy but the entries carry distinct semantics; only light redundancy with the schema's own mode prefixes keeps it from a 5.

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

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

An output schema exists so return values need not be explained, and the description covers everything else an agent needs: LOP vs SOP routing, the cooking side effect, playbar restoration, and a complete mode-to-parameter contract. Nothing required for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by mapping each mode to the parameters it consumes (e.g. "search" pairs with pattern and type_name, "modified" uses count, "prim" pairs with include_attrs) and clarifying semantics like the recursive world transform composed through every parent. This is mode-routing meaning beyond the flat per-param schema text.

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 USD stage at a LOP node") and immediately scopes it to Solaris/LOP networks. It explicitly names the sibling it is not (geometry_inspect) so an agent can separate it from the SOP-geometry inspection tool 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") plus an explicit exclusion ("Do not use it for SOP geometry: geometry_inspect does that"), naming the alternative. The mode list further tells the agent which selection to make for each intent.

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