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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful context: it uses the plugin's own engine, performs applicability checks, requires no model, and returns the four states with force, peak pressure, resultant and moment per metre. It does not specify persistence behavior, but the model-free note and read-only hint make that clear enough.

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 front-loaded with the core purpose and packs the key differentiators (Route A, no model, four output states) into a single dense sentence. It is appropriately sized for a complex calculation tool, though it could be split for readability; no sentence is purely redundant.

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 20-parameter tool with no output schema, the description covers the high-level purpose, route conditions, no-model requirement and the four output states. However, it leaves most parameter semantics to a schema with only 45% coverage and does not fully explain the return object structure. It is minimally adequate but has clear gaps for correct invocation.

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 description coverage is only 45%, so the description should compensate for the many undocumented parameters. It broadly mentions thermal movement, design displacement, route, coefficients and states, but does not explain the roles of parameters such as psi, gammaQ, skewDeg, gammaSat, gammaBulk, surchargeKpa, hasWaterTable, waterTableDepth, phiInferiorDeg, phiSuperiorDeg, nAbutmentsSharing and others. The description adds high-level grouping but not sufficient per-parameter meaning for a 20-parameter tool.

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 states a specific calculation: PD 6694-1 integral abutment earth pressures via the limit-equilibrium route (K*, cl.9.4.3/9.4.4), naming the engine and the four output states. It distinguishes itself from siblings by specifying Route A/A1/A2 versus B/Annex A review and by noting it needs no model, which separates it from model-dependent SSI or write tools.

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 description gives a clear condition for Route A versus Route B / Annex A review, and states that the tool needs no model. It does not explicitly name the SSI or write/remove sibling tools, but the alternative route condition and the model-free scope provide enough context for an agent to select it correctly.

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