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

Annotations already establish that this is a safe, idempotent read; the description goes well beyond them. It discloses per-call cost (5¢), flags twice that values are modelled estimates, pins the data window and freshness (monthly Nov 2024–Oct 2026, current to 2026-10-01), and explains exactly which suburbs are excluded from scoring. Those are precisely the behavioral traits an agent cannot see in annotations.

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 core definition, then labeled Coverage and Price sections, so the agent gets the essentials first. The coverage paragraph is dense with parenthetical counts but each clause carries real information about result availability. Minor density is the only deduction.

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 saying what a result contains (a 0-100 score plus the four components) and points to `/v1/datasets/suburb-hotness` for the field list and method. The delegation of exact field semantics to an external path is the only gap, and the `fields` enum in the schema largely covers it.

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 100%, so the schema already documents suburb_name formats, from/to formats, and the full comma-separated field list. The description's mention of 'the four parts behind the latest score' loosely corresponds to the momentum/volume/rent component fields but never names them or maps them to the `fields` parameter. With the schema doing the heavy lifting, baseline 3 applies.

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 resource and measure: a modelled 0-100 score of how hot each suburb's house and unit market is relative to the rest of its state, monthly over 24 months, plus the four component parts. That is far more precise than the title and lets an agent distinguish it from sibling price/growth tools. It stops short of explicitly naming which sibling to use for raw price growth instead, so it is not a 5.

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 concrete eligibility conditions — suburbs need at least 10 sales of that type in the latest 3 months, and states need at least 30 qualifying suburbs — so an agent knows when results will be empty. It also states coverage counts (about 4,300 house / 1,700 unit suburbs) to set expectations. No explicit 'use X instead when Y' routing is provided, so no 5.

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