create_node_group

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

With no annotations provided, the description must disclose behavioral traits itself. It only states the action 'Create' and does not explain side effects (e.g., whether selected nodes are moved or duplicated), any required context (e.g., active node tree), or what happens to the original nodes. The existence of an output schema is not mentioned, and there is no information about permissions or reversibility. This is a significant gap for a mutation 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?

The description is a single sentence with no filler words, making it efficient and front-loaded with the core action. However, it is overly sparse; while conciseness is good, it sacrifices essential detail. It could be more informative without becoming verbose, so it earns a 4 rather than 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 tool with 3 parameters, no annotations, and an output schema, this description is severely incomplete. It does not explain the role of the required 'material' parameter, how 'nodes' are referenced, the meaning of the optional 'name', or what the output represents. It also fails to distinguish from the many node-related siblings. An agent cannot reliably invoke this tool based on this description alone.

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 must compensate by explaining parameter meanings. It does not mention 'material', 'nodes', or 'name' at all. The description adds zero value beyond the schema, which already lists parameter names and types. This leaves the agent guessing what 'material' represents (e.g., a shader material, a material slot) and what the 'nodes' array expects.

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 clear action ('Create') on a specific resource ('a node group') and specifies the source ('from selected nodes'), making the core purpose understandable. However, it does not differentiate from sibling node tools like create_shader_node or create_geonode, nor does it clarify whether this is a shader node group, geometry node group, or generic, leaving ambiguity about its scope.

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?

No guidance is given on when to use this tool versus alternatives such as add_node_group_instance or create_shader_node. It does not state prerequisites like having nodes selected or being inside a specific node tree, nor does it mention any exclusions. The only implied usage is 'create a node group', which is too vague to route an agent correctly.

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