Create elements

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

Far exceeds the annotations (readOnlyHint=false, destructiveHint=true): it discloses that every call is a dry-run by default, that validation failures abort the whole batch while host/name failures skip individual items, what conditions trigger warnings, and that Archicad silently discards offset/useFixedAngle. This is exactly the mutation-specific context 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?

Dense but front-loaded: purpose first, then the type enumeration, then behavioral rules, then return shape. The long type list is necessary information rather than filler, though the single unbroken block makes it slightly hard to scan.

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?

Covers the hard parts of a complex batch-mutation tool: validation modes, partial-failure semantics, warnings, and version constraints. An output schema exists so the 'returns created GUIDs / by_index' sentence is mildly redundant, and the undocumented 'port' parameter leaves a small hole.

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?

With 0% schema description coverage the description must compensate, and it does: it enumerates valid element_type values, specifies that items use Tapir field names and metres/radians, and explains the items=[] discovery trick and the dry_run default. Only the 'port' parameter goes completely unmentioned.

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 ('Create elements of any type Tapir can create') and then enumerates the full element_type taxonomy, so an agent knows this is the general-purpose creation entry point rather than a specialized sibling like create_swept_beam or create_road_marking.

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?

Gives concrete usage conditions: call with items=[] to discover the item schema, and pass dry_run=false only when ready to commit. It does not explicitly route to the overlapping specialized siblings (create_swept_beam, create_road_marking) for beam/marking cases, which is the one real gap.

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