cocos_create_node

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

With no annotations provided, the description carries full burden. It discloses that the operation creates a new entity ('Append a new cc.Node'), returns an array index, and that the node starts without components. It doesn't mention permissions, error conditions, or whether this is a destructive operation, but covers the core behavior adequately for a creation 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?

Three sentences with zero waste: first states purpose and output, second explains layer defaults, third provides critical follow-up guidance. Each sentence adds essential information, and the structure is front-loaded with the core functionality.

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 9 parameters with 0% schema coverage and no annotations, the description does well by explaining layer behavior and component follow-up. However, it doesn't address all parameters or potential error cases. The presence of an output schema means return values are documented elsewhere, so this is acceptable.

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. It explains the 'layer' parameter's default (UI_2D) and special value for camera nodes (1073741824), and implies that 'parent_id' determines hierarchy. However, it doesn't clarify other parameters like 'scene_path' or 'name' semantics, leaving some gaps.

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 specific action ('Append a new cc.Node'), target resource ('under parent_id'), and output ('return its array index'). It distinguishes from sibling tools like 'cocos_create_scene' (creates scenes) or 'cocos_duplicate_node' (copies existing nodes) by focusing on creating a basic node with positioning and layer defaults.

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 provides explicit when-to-use guidance: 'The new node has no components yet — call cocos_add_uitransform, cocos_add_sprite etc. to attach them.' This tells the agent to use this tool for initial node creation and other tools for adding functionality. It also specifies layer defaults and camera node usage.

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