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

Goes well beyond the annotations: it discloses the dry-run-by-default behavior, the write pattern (one element written and read back first, then the rest), and the direction audit — meaningful safety context for a mutating tool flagged readOnlyHint=false. This is exactly the operational detail annotations cannot express.

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 the calculation and the write target, then the mechanics and the preview switch. It is dense and em-dash-heavy but every clause carries information; a light restructuring would improve scanability without cutting content.

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 no-output-schema mutation tool with 18 params and nested geometry, it covers the essentials: what gets written, where, in what order, and that it previews by default. Gaps remain around overwrite behavior for existing EC1W_ cases, failure/rollback semantics, and the purpose of confirmPlanHash, which an agent would need before a real apply.

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 18 parameters at 56% schema coverage, the schema carries most of the burden. The description adds real value on target selection (elementIds vs group vs implicit deck) and the directions default of all six, but says nothing about co, vb0, nationalAnnex, terrainCategory, confirmPlanHash, or cscdOverride, leaving several params unexplained in both places.

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 and resource ('Calculates §8 wind on the deck and writes it with the Eurocode Wind Loads plugin's adapter') and specifies the concrete output artifacts: one EC1W_ load case per global direction plus beam loads or pressure + fascia nodal loads. An agent can distinguish this write operation from read/remove siblings without opening the schema.

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?

The 'Previews unless apply: true' clause is an explicit usage condition and the target-resolution rule (elementIds, group, or default deck) tells the agent what inputs select which target. It stops short of naming alternatives such as ec_wind_bridge for geometry-only calculation or ec_wind_remove for cleanup.

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