Create building materials

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

Goes well beyond the annotations by disclosing default inheritance behavior ('Unspecified settings are copied from basedOn or ... the first building material of the project'), undo semantics ('Runs in one undo step'), partial-failure handling ('one failing item does not stop the others'), the exact return shape, and localization constraints. This is rich behavioral context for a non-readOnly, non-idempotent 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 dense but front-loaded and every sentence carries useful information: purpose, defaults, undo behavior, return format, and localization advice. It could be slightly easier to parse if broken into shorter lines, but there is essentially no wasted text.

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 complex creation tool with no output schema, the description covers the essential behavior an agent needs: what will happen to unspecified fields, undo grouping, partial failure semantics, return structure, and a key prerequisite for name lookups. Annotations and the rich input schema handle the remaining safety and field-level details.

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 schema already documents many nested fields thoroughly, but the description adds genuine meaning: it explains the fallback behavior for unspecified settings, recommends which fields to provide for a meaningful material, and clarifies the role of basedOn. It does not cover every parameter or the batch array limits, but it adds real value beyond the structured schema.

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?

States a specific verb (Creates) and resource (building materials), and explains the domain concept ('material of elements and composite skins: cut fill + pens, surface, intersection priority, physical properties'). This clearly distinguishes it from sibling attribute-creation tools like create_surfaces, create_fills, and create_composites.

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?

Provides clear workflow guidance: 'look existing attributes up with get_attributes first,' and advises giving at least cutFill, surface and uiPriority for a meaningful material. It does not explicitly name alternatives or when-not-to-use conditions, which keeps it from a 5.

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