Skip to main content
Glama
Sign In

Microburbs Australian Property Data

by au.com.microburbs
OverviewDiscussionsAdmin

List suburbs

suburbs_list
Read-onlyIdempotent

List Australian suburbs (SALs). Always returns {suburb, state} per row so SAL-name collisions across states are unambiguous.

With no filter you get 1000 suburbs at a time, alphabetically — page with offset (1000, 2000, …) for the rest. Pass any of the filters to narrow: state / lga / sa4 / sa3 / postcode / q (name search). Filters combine (AND). Flat cost regardless of how many rows come back.

Name search (q) is typo-tolerant. It tries an exact match, then substring, then a fuzzy near-miss, and returns match (exact / contains / fuzzy) and score on every row so you can see which happened.

Always tell the user which suburb you resolved to, and its state, before quoting numbers for it. A fuzzy match is a suggestion, not a confirmation — rokeby is one letter from Kokeby in Western Australia and Rokeby exists in both Tasmania and Victoria. If more than one candidate is plausible, ask rather than pick.

When q is combined with state, the state is a preference, not a filter: in-state candidates rank first, but a suburb of that name in another state is still returned rather than hidden, so a near-miss becomes "Seaview is in Victoria, not Tasmania" instead of "no data". Every other filter stays a strict AND.

Free.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "suburbs_list"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoSuburb-name search. Matches exactly, then by substring, then by fuzzy near-miss so a typo still resolves ('devenport' -> Devonport). Each row comes back with `match` and `score` saying how it was found.
lgaNoFilter by Local Government Area name.
sa3NoFilter by SA3 name.
sa4NoFilter by SA4 name.
stateNoFilter by state / territory (e.g. NSW, VIC, 'New South Wales').
offsetNoRow offset for the unfiltered list, which comes 1000 suburbs at a time: pass 1000, 2000, … for the next pages (a page shorter than 1000 is the last). Ignored with `q`.
postcodeNoFilter by 4-digit postcode (POA).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / offset
      Added value: +{
+  "default": 0,
+  "description": "Row offset for the unfiltered list, which comes 1000 suburbs at a time: pass 1000, 2000, … for the next pages (a page shorter than 1000 is the last). Ignored with `q`.",
+  "minimum": 0,
+  "type": "integer"
+}
  2. Changed1 schema field changed
    • changedOutput 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": [
-        {
-          "items": {
-            "description": "One row in the suburb directory — minimum to disambiguate SAL\nnames that collide across states (e.g. 'Springfield' in NSW + QLD).",
-            "example": {
-              "state": "New South Wales",
-              "suburb": "Belmont North"
-            },
-            "properties": {
-              "match": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "description": "How this row matched the `q` you sent — `exact`, `contains`, or `fuzzy` (a near-miss recovered from a likely typo). Only present when `q` was supplied. **Anything other than `exact` is a suggestion, not a confirmation: tell the user which suburb and state you used before you quote numbers for it.** A `fuzzy` row in a different state from the one the user named is very often the wrong place.",
-                "title": "Match"
-              },
-              "score": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "description": "Match confidence 0-1 (1.0 = exact). Only present when `q` was supplied. Use it to decide between asking the user and proceeding — not as a licence to pick silently.",
-                "title": "Score"
-              },
-              "state": {
-                "description": "State / Territory.",
-                "title": "State",
-                "type": "string"
-              },
-              "suburb": {
-                "description": "Suburb (SAL) name.",
-                "title": "Suburb",
-                "type": "string"
-              }
-            },
-            "required": [
-              "suburb",
-              "state"
-            ],
-            "title": "SuburbListItem",
-            "type": "object"
-          },
-          "type": "array"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "description": "The endpoint's payload, or `null` when Microburbs has no value.",
-      "title": "Data"
-    },
-    "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[list[SuburbListItem]]",
-  "type": "object",
-  "x-fastmcp-top-level-schema": "ApiResponse_list_SuburbListItem__"
-}New value: +null
  3. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: it discloses the 1000-row page size, that cost is flat regardless of row count, that `offset` is ignored when `q` is present, and the three-stage exact/substring/fuzzy matching with `match` and `score` returned per row. The subtle rule that `state` degrades to a preference (not a filter) when combined with `q` is exactly the kind of non-obvious behavior an agent could otherwise misread as a bug.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and return shape, then pagination, then the fuzzy-match caveat, then the `q`+`state` exception — a sensible order. The heavy bolding and the worked Rokeby/Kokeby/Seaview examples are somewhat verbose, but each illustrates a failure mode that would otherwise cause a wrong answer.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing returns and does so — row shape, the `match`/`score` fields, and page-size semantics. Combined with 100% schema coverage, an agent has everything needed to call this correctly and interpret the response.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema does not: `state` behaves as a ranking preference under `q` while all other filters remain strict AND, and `offset` is inert with `q`. That changes how an agent interprets results rather than merely restating field names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'List Australian suburbs (SALs)' — and immediately defines the return shape (`{suburb, state}`), so an agent knows this is a reference/lookup tool rather than an analytics one. It does not name the closest siblings (`geocode_suburb`, `suburbs_finder_search`), so the boundary with those must be inferred.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to-use guidance: unfiltered calls page 1000 at a time via `offset`, filters narrow and combine with AND, and `q` triggers fuzzy resolution. It also prescribes downstream behavior ('tell the user which suburb you resolved to… ask rather than pick'), which is unusually actionable. It stops short of explicitly saying when to prefer `geocode_suburb` or `suburbs_finder_search` instead.

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

All Microburbs Australian Property Data toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources