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

Annotations already establish readOnly/idempotent/non-destructive/closed-world, so the description isn't needed for safety, and it instead adds genuinely new behavioral context: the provenance vocabulary (measured, measured_wider_area, estimate, not_recorded), the warning that SA1/postcode values are repeated across every block in the area, and the pairing of each value with a `how` explanation. It does not mention response size, block counts, or what happens for a suburb with no listings, so it stops short of a 5.

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 bold question front-loads the purpose, followed by signal content, then output shape, then provenance semantics — a logical order with no filler sentences. The markdown/bold formatting and the long provenance sentence make it denser than necessary, but every block carries information the agent needs.

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 work of describing the return: a `mesh_blocks` array keyed by mb_code with population and dwellings, per-value provenance and `how`, plus the explicit exclusion of geometries. The remaining gap is input-side — the suburb parameter's expected format and disambiguation — plus no sense of result volume.

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 0% for the single required parameter, so the description carries the burden — it establishes that the input is a suburb and that results span all mesh blocks within it. However, it never states the expected form (suburb name vs. code), case/ambiguity handling, or how to resolve a suburb first (e.g. geocode_suburb / suburbs_list), so meaning beyond the key name is thin.

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 the resource precisely (per-mesh-block condition/renovation signals derived from listing text) and the scope (all blocks in one suburb), and enumerates the signal families — renovated, updated kitchens/bathrooms, renovation potential, original features, air conditioning, listing counts. It does not explicitly differentiate against close siblings such as suburbs_mesh_blocks_building or suburbs_mesh_blocks_signals, so the agent must infer the boundary from content.

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?

Usage is implied by the 'What condition are the homes in?' framing and the 'by suburb' scope, and it usefully tells the agent that geometry is not returned here and must come from /shapes/mesh-blocks. There is no explicit when-to-use/when-not-to-use statement and no routing to an alternative sibling for a different granularity, which leaves selection against the many mesh-block tools to inference.

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