suburbs_market_stock_on_marketShown in the suburb report as the 'Stock on Market' card in the Overview section.
Properties currently listed for sale in the suburb, split house/unit, with the suburb's rank among its peers.
| Name | Required | Description | Default |
|---|---|---|---|
| suburb_name | Yes |
Changes observed during successful MCP inspections.
Output schema / (root)Previous value: -{
- "properties": {
- "available": {
- "anyOf": [
- {
- "type": "boolean"
- },
- {
- "type": "null"
- }
- ],
- "description": "`false` on no-data responses. Omitted on success — branch on `data !== null` if you want a single discriminator.",
- "title": "Available"
- },
- "data": {
- "anyOf": [
- {
- "additionalProperties": true,
- "description": "Properties currently listed for sale in the suburb.",
- "example": {
- "area_level": "suburb",
- "area_name": "Belmont North",
- "areas": 131,
- "as_of": "2026-08-09",
- "house": 20,
- "rank": 30,
- "stock_on_market": 21,
- "unit": 1
- },
- "properties": {
- "area_level": {
- "description": "Always 'suburb' for these endpoints.",
- "title": "Area Level",
- "type": "string"
- },
- "area_name": {
- "description": "Suburb (SAL) name.",
- "title": "Area Name",
- "type": "string"
- },
- "areas": {
- "anyOf": [
- {
- "type": "integer"
- },
- {
- "type": "null"
- }
- ],
- "description": "Size of the peer group the rank is out of.",
- "title": "Areas"
- },
- "as_of": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Date of the observation (YYYY-MM-DD).",
- "title": "As Of"
- },
- "house": {
- "anyOf": [
- {
- "type": "number"
- },
- {
- "type": "null"
- }
- ],
- "description": "Houses listed for sale.",
- "title": "House"
- },
- "rank": {
- "anyOf": [
- {
- "type": "integer"
- },
- {
- "type": "null"
- }
- ],
- "description": "Position among peer suburbs (1 = most stock).",
- "title": "Rank"
- },
- "stock_on_market": {
- "description": "Total properties listed for sale.",
- "title": "Stock On Market",
- "type": "number"
- },
- "unit": {
- "anyOf": [
- {
- "type": "number"
- },
- {
- "type": "null"
- }
- ],
- "description": "Units listed for sale.",
- "title": "Unit"
- }
- },
- "required": [
- "area_name",
- "area_level",
- "stock_on_market"
- ],
- "title": "StockOnMarket",
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "description": "The endpoint's payload, or `null` when Microburbs has no value."
- },
- "message": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Human-readable explanation. Omitted on success.",
- "title": "Message"
- },
- "reason": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Machine-readable slug naming the no-data condition (e.g. `no_avm_for_GANSW704074813`). Stable per endpoint. Omitted on success.",
- "title": "Reason"
- }
- },
- "title": "ApiResponse[StockOnMarket]",
- "type": "object",
- "x-fastmcp-top-level-schema": "ApiResponse_StockOnMarket_"
-}New value: +nullDoes the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds substantive content context (currently listed stock, house/unit split, peer ranking) but says nothing about freshness/as-of date, response shape details, or whether the rank is national/state/peer-group scoped.
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?
Two tight sentences with no filler. The report-card placement sentence leads, which is the least actionable information; putting the data definition first would front-load better.
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 single-parameter read-only metric with no output schema, the description is close to sufficient: it tells the caller what is counted, how it is segmented, and that a rank is included, so the return content is largely predictable. The remaining gap is the undocumented suburb_name format.
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 0% for the single suburb_name parameter, so the description carries the full burden and does not meet it. It never states the expected name format, whether state/postcode disambiguation is needed, or that names can be resolved via geocode_suburb or suburbs_list.
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?
States a specific metric and scope: properties currently listed for sale in a suburb, split house/unit, plus the suburb's rank among peers. That is well beyond a restatement of the name. It stops short of distinguishing itself from closely overlapping siblings such as suburbs_listings_for_sale or suburbs_market_months_of_supply.
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 'Shown in the suburb report as the Stock on Market card' framing implies where this metric belongs, but there is no explicit when-to-use rule and no named alternative for when a caller wants raw listings versus this summary. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.