ue_pcg_add_node

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

With no annotations, the description carries the full burden. It discloses that the tool returns the node's pins and that the position parameter only affects visual readability. However, it does not mention whether the graph asset is saved, potential errors, or side effects. This is useful but not comprehensive behavioral disclosure.

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 concise and well-structured: a one-sentence summary, a short explanatory paragraph about the PCG convention, and an Args block. Every sentence adds value, and it is not bloated.

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?

The description covers the essential steps for adding a node, including the critical concept of settings_class and the meaning of position. It lacks explicit mention of which parameters are required (though schema shows two required) and does not describe the structure of the returned pins. Still, it is largely complete for the tool's purpose.

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 each parameter: graph_path as the asset path, settings_class with concrete examples (PCGSurfaceSamplerSettings, etc.), and position with accepted formats and its purely readability-oriented role. This is exactly the semantic richness needed.

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 opens with 'Aggiunge un nodo al grafo PCG e restituisce i suoi pin' (Adds a node to the PCG graph and returns its pins), clearly stating the action and resource. It further distinguishes itself by explaining the settings_class convention and how it relates to PCG node types, differentiating this add-node tool from sibling PCG tools like ue_pcg_connect or ue_pcg_remove_node.

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 description gives clear context on how to use the tool: you specify a settings_class, and it provides examples of valid values. It explains that the node type is its settings class, giving a mental model. However, it does not explicitly mention when not to use it or compare with alternatives, so it stops short of a 5.

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