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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes beyond them: it discloses that the £/m² benchmark leg returns `not_available` until a tender benchmark is loaded, that no rate is invented, that nothing is a modelled number, and that an invalid region raises an error enumerating loaded values. That is real behavioral disclosure about sentinels, errors, and provenance.

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 purpose, then the output legs, then the estimate mechanics, then the caveat. It is dense but almost every clause carries distinct, actionable information; the three short trailing sentences (not_available behavior, UK only, free) are each independently useful.

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?

An output schema exists, so return structure needn't be restated, and annotations cover safety. The description supplies the operative semantics, error/sentinel behavior, and rate provenance. The only real gap is the unexplained `basis` enum, which an agent would have to guess at.

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 schema description coverage at 0%, the description must carry the load, and it does for five of six parameters: sector (index selection), region (enum values plus error behavior), gia_m2, rate_gbp_m2 (BCIS or in-house base rate), and rate_period ("the series' own format, e.g. 2024Q1"). The `basis` parameter (tender/output enum) is never mentioned, leaving one documented enum unexplained.

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 opening clause states a specific verb+resource ("Build cost for a scheme") and enumerates the outputs: sector cost index with 1- and 5-year movement, regional factor, on-cost percentages, and a rate-derived estimate. This is clearly distinguishable from narrower siblings like cost_index or valuation_estimate, which an agent can infer without opening a 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?

It conveys context (UK only, free) and the conditional that triggers the estimate leg ("given gia_m2 and rate_gbp_m2 ..."), which is genuinely useful. However, it never names when to prefer this over cost_index, site_appraisal, or valuation_estimate, so sibling routing is left to inference.

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