suburbs_market_yield_mapGross rental yield for every microburb (mesh block) in the suburb —
weekly rent x 52 over median price — with both inputs returned so the
number is checkable, plus the best- and worst-yielding pockets. Values
only; polygons come from /shapes/mesh-blocks.
| 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": "Per-microburb gross rental yield — the report's `yield` overlay.",
- "example": {
- "as_of": "2026-08-16",
- "definition": "Gross rental yield for the mesh block: modelled median weekly house rent x 52, divided by the modelled median house price, as a percentage. Same definition as the suburb-wide yield at /market/yield-pct (which reports it as a decimal); gross, so before rates, strata, management or vacancy. Microburbs missing either the rent or the price are absent, not zero.",
- "highest": {
- "gross_yield_pct": 6.65,
- "mb": "10439020000",
- "median_price": 892000,
- "street": "Floraville",
- "weekly_rent": 1140
- },
- "lowest": {
- "gross_yield_pct": 1.85,
- "mb": "10434330000",
- "median_price": 1600000,
- "street": "Arlington",
- "weekly_rent": 570
- },
- "metric": "gross_rental_yield_house",
- "microburbs": [
- {
- "gross_yield_pct": 6.65,
- "mb": "10439020000",
- "median_price": 892000,
- "street": "Floraville",
- "weekly_rent": 1140
- }
- ],
- "n_microburbs": 58,
- "suburb": "Belmont North",
- "unit": "percent"
- },
- "properties": {
- "as_of": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Date of the surfaces (YYYY-MM-DD).",
- "title": "As Of"
- },
- "definition": {
- "description": "How the figure is derived.",
- "title": "Definition",
- "type": "string"
- },
- "highest": {
- "anyOf": [
- {
- "additionalProperties": true,
- "description": "Gross rental yield for one microburb, with both inputs.",
- "properties": {
- "gross_yield_pct": {
- "description": "Annual rent as a share of price for this microburb — `weekly_rent × 52 ÷ median_price` — expressed as a percent to 2 dp: `6.65` means 6.65%. The suburb-wide `/market/yield-pct` endpoint reports this same metric as a decimal (0.0665), so the two differ by a factor of 100 by design — check which one you are reading. Gross: before rates, strata, management, insurance or vacancy, so a real net return will be materially lower.",
- "title": "Gross Yield Pct",
- "type": "number"
- },
- "mb": {
- "description": "ABS 2021 mesh-block code.",
- "title": "Mb",
- "type": "string"
- },
- "median_price": {
- "description": "The price side of the yield calculation: modelled median house price for the microburb, in AUD. Houses only, matching `weekly_rent`, so the two divide cleanly.",
- "title": "Median Price",
- "type": "integer"
- },
- "street": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Modal street name for the mesh block, title-cased.",
- "title": "Street"
- },
- "weekly_rent": {
- "description": "The rent side of the yield calculation: modelled median weekly advertised house rent for the microburb, in AUD. Advertised, not contracted, and houses only. Returned so the yield is checkable without a second call.",
- "title": "Weekly Rent",
- "type": "integer"
- }
- },
- "required": [
- "mb",
- "gross_yield_pct",
- "weekly_rent",
- "median_price"
- ],
- "title": "YieldMb",
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "description": "Highest-yielding microburb. None when there is no spread."
- },
- "lowest": {
- "anyOf": [
- {
- "additionalProperties": true,
- "description": "Gross rental yield for one microburb, with both inputs.",
- "properties": {
- "gross_yield_pct": {
- "description": "Annual rent as a share of price for this microburb — `weekly_rent × 52 ÷ median_price` — expressed as a percent to 2 dp: `6.65` means 6.65%. The suburb-wide `/market/yield-pct` endpoint reports this same metric as a decimal (0.0665), so the two differ by a factor of 100 by design — check which one you are reading. Gross: before rates, strata, management, insurance or vacancy, so a real net return will be materially lower.",
- "title": "Gross Yield Pct",
- "type": "number"
- },
- "mb": {
- "description": "ABS 2021 mesh-block code.",
- "title": "Mb",
- "type": "string"
- },
- "median_price": {
- "description": "The price side of the yield calculation: modelled median house price for the microburb, in AUD. Houses only, matching `weekly_rent`, so the two divide cleanly.",
- "title": "Median Price",
- "type": "integer"
- },
- "street": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Modal street name for the mesh block, title-cased.",
- "title": "Street"
- },
- "weekly_rent": {
- "description": "The rent side of the yield calculation: modelled median weekly advertised house rent for the microburb, in AUD. Advertised, not contracted, and houses only. Returned so the yield is checkable without a second call.",
- "title": "Weekly Rent",
- "type": "integer"
- }
- },
- "required": [
- "mb",
- "gross_yield_pct",
- "weekly_rent",
- "median_price"
- ],
- "title": "YieldMb",
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "description": "Lowest-yielding microburb. None when there is no spread."
- },
- "metric": {
- "description": "Always 'gross_rental_yield_house'.",
- "title": "Metric",
- "type": "string"
- },
- "microburbs": {
- "description": "Per-microburb yields, highest first.",
- "items": {
- "additionalProperties": true,
- "description": "Gross rental yield for one microburb, with both inputs.",
- "properties": {
- "gross_yield_pct": {
- "description": "Annual rent as a share of price for this microburb — `weekly_rent × 52 ÷ median_price` — expressed as a percent to 2 dp: `6.65` means 6.65%. The suburb-wide `/market/yield-pct` endpoint reports this same metric as a decimal (0.0665), so the two differ by a factor of 100 by design — check which one you are reading. Gross: before rates, strata, management, insurance or vacancy, so a real net return will be materially lower.",
- "title": "Gross Yield Pct",
- "type": "number"
- },
- "mb": {
- "description": "ABS 2021 mesh-block code.",
- "title": "Mb",
- "type": "string"
- },
- "median_price": {
- "description": "The price side of the yield calculation: modelled median house price for the microburb, in AUD. Houses only, matching `weekly_rent`, so the two divide cleanly.",
- "title": "Median Price",
- "type": "integer"
- },
- "street": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Modal street name for the mesh block, title-cased.",
- "title": "Street"
- },
- "weekly_rent": {
- "description": "The rent side of the yield calculation: modelled median weekly advertised house rent for the microburb, in AUD. Advertised, not contracted, and houses only. Returned so the yield is checkable without a second call.",
- "title": "Weekly Rent",
- "type": "integer"
- }
- },
- "required": [
- "mb",
- "gross_yield_pct",
- "weekly_rent",
- "median_price"
- ],
- "title": "YieldMb",
- "type": "object"
- },
- "title": "Microburbs",
- "type": "array"
- },
- "n_microburbs": {
- "description": "Microburbs with both a rent and a price.",
- "title": "N Microburbs",
- "type": "integer"
- },
- "suburb": {
- "description": "Canonical SAL name.",
- "title": "Suburb",
- "type": "string"
- },
- "unit": {
- "description": "Always 'percent' — note /market/yield-pct reports the same metric as a decimal.",
- "title": "Unit",
- "type": "string"
- }
- },
- "required": [
- "suburb",
- "metric",
- "unit",
- "definition",
- "n_microburbs",
- "microburbs"
- ],
- "title": "SuburbYieldMap",
- "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[SuburbYieldMap]",
- "type": "object",
- "x-fastmcp-top-level-schema": "ApiResponse_SuburbYieldMap_"
-}New value: +nullDoes the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds genuinely useful behavior: it discloses the calculation, says both rental and price inputs are returned so the yield is checkable, and clarifies that the response contains values only, not polygons.
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 compact sentences front-load the metric and formula, then add a meaningful boundary about values vs polygons. Every sentence earns its place with no filler.
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 one-parameter read-only tool with no output schema, the description fully covers what is computed, how, what is returned for auditability, the best/worst-pockets extra, and the split from shape endpoints. Nothing critical is missing.
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 only parameter, suburb_name, is self-explanatory, and the phrase 'in the suburb' loosely ties it to the output. However, schema description coverage is 0%, and the description does not explicitly document the parameter, its format, or any constraints, leaving the agent to infer the only input.
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 precisely states that the tool returns gross rental yield per microburb in a suburb and gives the formula, so an agent knows exactly what is computed. The clause 'Values only; polygons come from /shapes/mesh-blocks' distinguishes it from shape-returning tools.
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 this is the tool for mesh-block-level yield values and points geometry requests elsewhere, but it never names sibling tools such as suburbs_market_yield_pct or states when to prefer one over the other. The routing guidance is limited to one exclusion rather than a full usage policy.
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.