Create composite structures

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

Annotations only state read/write and idempotency flags; the description goes further by disclosing that it runs in one undo step, that failures are per-item and do not abort remaining items, that basedOn copies an existing composite, and that names are localized (Russian Archicad). This is exactly the kind of behavior the annotations cannot convey.

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?

Front-loaded with purpose, then the key semantic rule (skin ordering) and a worked example, which is efficient for a complex nested schema. The get_attributes reminder appears twice and the example is verbose, costing some tightness.

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 2-parameter tool with a deeply nested item schema and no output schema, the description closes the gaps that matter: it documents the return shape ({results: [...]} in input order with created/existed/error variants), partial-failure behavior, and the undo grouping.

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 only 50%, but the description compensates substantively: skins are ordered outside→inside, total thickness is the sum, a concrete worked example shows thickness/buildingMaterial/core/finish usage, and basedOn semantics are clarified. It omits usage, folder and skinLines, which the schema does document.

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?

Opens with a specific verb+resource ('Creates composite (multi-skin) structures for walls, slabs, roofs and shells'), immediately distinguishing it from sibling attribute creators like create_building_materials and create_surfaces by naming the element types involved.

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?

Explicitly routes the agent: fetch material names with get_attributes type BuildingMaterial, then attach the composite via the 'composite' field of create_walls / create_slabs / create_roofs, and look existing attributes up first for localized names. Prerequisites and downstream consumers are named, not implied.

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