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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real value beyond them: the write-then-read-back verification that fails if CIVIL NX drops any loads, the empty-model guard, and the explicit warning that newDocument replaces the open model and loses unsaved work. It does not cover rollback semantics or mention the accompanying undo 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?

Three dense sentences, front-loaded with what gets built, then the safety constraint, then the preview default. The long enumeration earns its place because it defines scope, though the preview/apply note is somewhat buried at the end rather than stated up front.

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 destructive, deeply nested build tool with no output schema, the description covers the what, the safety profile and the verification behavior. The gaps are the unexplained confirmPlanHash workflow (presumably tied to a prior plan/preview step) and the absence of any reference to culvert_build_undo or how to recover from a bad build.

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%, and the description compensates for apply and newDocument (preview default, destructive replacement). However, confirmPlanHash is never mentioned in either the description or the schema, leaving a meaningful parameter entirely opaque on a destructive tool, and the nested project object relies wholly on its own schema text.

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 gives a concrete verb plus resource ('Writes the 2D Culvert model') and enumerates the exact contents written: units, material, sections, frame, soil springs, supports, load cases and EN 1990 Annex A2 combinations. It is unambiguous what is produced, though it never names the sibling preview/undo tools to sharpen the boundary.

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 states the operating conditions precisely: 'into the open model only if it is empty, or into a new document (newDocument: true)' and 'Previews unless apply: true', so the agent knows the preconditions and the dry-run default. What is missing is an explicit pointer to culvert_preview / culvert_build_undo as the alternatives for previewing or reverting.

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