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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered; the description adds genuinely new behavioral facts beyond that: 20¢ per call pricing, nearest-first ordering, inclusion of blocks across suburb lines, and the provenance taxonomy (measured, measured_wider_area, estimate, not_recorded) with the meaning of each. Return shape is described but no pagination or result-cap behavior is mentioned.

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 lead question frames intent immediately, followed by scope, response shape, and pricing in a sensible order, with bold emphasis on the core question and cost. Some sentences (the provenance enumeration) are dense but each carries substantive information; the title's parenthetical is redundant with the body but minor.

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?

With no output schema, the description does the necessary work of describing the response envelope (a mesh_blocks array, nearest first, with mb_code, distance_m, population, dwellings) and the per-field provenance annotation. Pricing and cross-sibling division of labour are also covered, so an agent can call this correctly without further information.

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?

There is a single required parameter with 0% schema description coverage, so the description carries the full burden. It implies gnaf_id identifies a property and even embeds it in the URL template /properties/{gnaf_id}/context/mesh-blocks, but never states the identifier's expected format or how to obtain one.

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 names a specific verb-and-resource pairing (per-mesh-block environment metrics: greenness, vegetation change, noise score, solar installations) and bounds it explicitly to blocks within 1,000 m of the property keyed by gnaf_id. It further distinguishes itself from properties_context_mesh_blocks by stating that geometry comes from that other endpoint and this tool returns values only.

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 gives a clear usage context (asking 'is it green and quiet?' for a specific property) and an explicit division of labour with /properties/{gnaf_id}/context/mesh-blocks for polygons. It stops short of naming when to prefer suburb-level or postcode-level alternatives, so no explicit exclusions are stated.

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