Add Poietic node

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

Since no annotations are provided, the description carries the full behavioral disclosure burden. It reveals the return shape ({objectId, planeId}), warns that duplicate names resolve arbitrarily, and explains that formulas may be constants or expressions. It could mention failure modes or side effects in more detail, but the key behavioral caveat is well covered.

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 deliver the core action, typical attributes with examples, return value, and a critical ID-preference warning with no filler. The most important information is front-loaded and every sentence earns its place.

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 return value even though there is no output schema, explains the most important attribute semantics, and gives a warning about duplicate names. It remains slightly incomplete in that it does not clarify how design selection interacts with node creation or describe potential validation errors, but for this tool's complexity the coverage is solid.

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 coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema by naming typical attributes (name, formula, position) and clarifying that formula accepts constants or expressions. This helps an agent construct valid attribute objects that the generic schema alone would not convey.

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 a specific action ('Create a new node') and concrete type examples (Stock, FlowRate, Auxiliary), making the tool's purpose unmistakable. It is clearly distinguished from sibling tools like poietic_connect or poietic_set_attributes, which perform different operations on nodes.

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 useful operational guidance—thread the returned objectId into later calls and prefer IDs over names—but it does not explicitly state when to choose this tool over alternatives such as poietic_set_attributes or poietic_auto_parameters. Usage context is implied rather than directly contrasted with siblings.

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