run_shelf_tool

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

There are no annotations, so the description carries the full burden, and it discloses substantial behavioral detail: the up-front refusal, the blocking hazard, the always-watched networks, and how kwargs are merged into synthetic kwargs. It also explains why multiple networks are watched, using largeOcean as a concrete example.

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

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

The first sentence delivers the core purpose, the warning paragraph is dense but necessary, and the Args list is compact and directly actionable. There is no filler or redundant restatement of schema fields.

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

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

For a side-effecting execution tool with no annotations and no output schema, this is quite complete: it covers purpose, failure modes, alternatives, watched networks, and parameter roles. The only gap is that it does not specify the exact return shape of the node report beyond 'report the nodes it created.'

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 0%, but the description documents all three parameters with meaningful semantics: tool_name is the internal name from list_shelf_tools, kwargs are overrides merged into the synthetic kwargs, and parent_path is an extra network to watch beyond the always-watched defaults. This fully compensates for the empty schema descriptions.

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

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

The description states a precise action ('Run a shelf tool') and its outcome ('report the nodes it created'), which clearly identifies the tool's function. It also differentiates it from siblings like get_shelf_tool_script and build_network by explaining which kinds of shelf tools are refused and why.

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

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

It explicitly says when not to use the tool: shelf tools that wait for viewport selection or dialogs are refused up front because they would block Houdini. It then names the alternative path — read the recipe with get_shelf_tool_script and build with build_network — and confirms that node-creating tools run fine.

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