suburbs_market_stock_on_marketProperties 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, and destructiveHint, so the safety profile is covered. The description adds that results are split by house/unit and include a rank, which is extra behavioral context. However, it does not mention response format, pagination, or any other operational details. Given annotations, a 3 is appropriate – it adds some value but not rich behavioral depth.
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 description is a single, efficient sentence that front-loads the core action and key output characteristics. There is no fluff or redundancy; every word contributes to understanding what the tool does.
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 simple read-only tool with one self-explanatory parameter and no output schema, the description covers the essential purpose. It does not specify return format or data structure details, but given the simplicity and annotations, it is nearly complete. A 4 reflects that it is adequate without being exhaustive.
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?
The schema has zero description coverage for the single parameter suburb_name. The description does not elaborate on the parameter beyond implying it is a suburb, which is obvious from the tool name. Since the description is the only source of parameter meaning and it provides no additional detail, it fails to compensate for the low coverage. A 2 reflects this lack of added semantic value.
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 clearly states the verb (lists) and the resource (properties for sale in a suburb), and it specifies the output split (house/unit) and the inclusion of rank. This distinguishes it from many other suburbs_market_* tools, which focus on different metrics. It is not a tautology and provides concrete meaning beyond the name.
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 description implies use for current listings ('currently listed for sale') but does not explicitly state when to use this tool versus alternatives like suburbs_market_all or suburbs_market_days_on_market. There is no mention of exclusions or specific scenarios. The context is clear enough, but no explicit guidance is given.
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.