Create node

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this mutates the scene. The description adds no behavioral context beyond that: it says nothing about what happens on name collisions, whether an omitted name is auto-generated, whether the operation is undoable, or what errors surface for invalid parent paths or types.

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

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

Two short sentences with the action front-loaded and a compact concrete example following it. There is no padding and nothing that could be cut without losing meaning.

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

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

An output schema exists, so return values need not be explained, and an example anchors the call. The only real gap is the optional 'name' parameter's default behavior and the lack of a pointer to list_node_types for valid type strings, which matters because the schema itself documents nothing.

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%, so the description carries the burden, and the worked example does map all three parameters to concrete values (parent=/obj, type=geo, name=geo1), implying that parent is a scene path and type is a node type string. However, it never states that name is optional or what the default naming behavior is, leaving the nullable/default=null case unexplained.

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 ('Create a Houdini node') plus a scoping detail ('under parent'), which cleanly separates it from get_node, list_nodes, set_parameter, and delete_node. It stops short of explicitly naming a sibling or contrasting with alternatives, so it is clear but not maximally differentiating.

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?

The example shows how to call the tool, but there is no guidance on when to create versus reuse an existing node, no mention of prerequisites, and no reference to siblings such as list_node_types (to discover valid types) or set_parameter (the natural follow-up). Usage is demonstrated, not explained.

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