new_element

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

No annotations are provided, so the description carries the full burden. It adds useful context that the node is returned, editable, and must be placed manually, and that it is structurally-valid. However, it doesn't disclose side effects, authentication needs, or error behavior.

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?

One sentence that is front-loaded and efficient. Every clause adds meaning: what is built, where it comes from, what to do with it. No filler or redundant statements.

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 factory tool, it covers creation, editing, and placement. It correctly defers valid types to list_elements. It could mention return type details or validation behavior, but the schema fills in parameter specifics, making it complete enough.

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?

The input schema has 100% coverage with rich descriptions, especially for 'opts' which enumerates all fields and explains 'align' behavior. The description reinforces the role of specials/style. This goes beyond a plain schema listing.

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 uses a specific verb 'Build' with the resource 'element node' and clarifies that it comes from the builder factory. It clearly distinguishes from sibling tools like new_section and update_page_element by describing the creation of a node that must be placed afterward.

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 explicitly states the workflow: build the node, edit it, then place it in a section's children. This provides clear context for when to use it (creating new elements), though it doesn't explicitly name alternative tools or exclusion criteria.

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