suburbs_demographics_cohortsHow the suburb ranks inside its SA4 region and against its touching neighbours on renter share, welfare dependency, overseas-born parents and public housing.
| 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": "SA4-cohort percentile ranks + neighbour comparisons for four\ndemographic metrics (renters, welfare, overseas-born, public housing).",
- "example": {
- "metrics": [
- {
- "field": "mib_perc_renters",
- "label": "Renter share",
- "neighbours": {
- "dramatic": {
- "delta_pct": 258,
- "suburb": "Windale",
- "value_pct": 39.4
- },
- "highest_in_group": false,
- "lowest_in_group": false,
- "n": 7
- },
- "sa4": {
- "delta_pct": 34,
- "n": 135,
- "percentile": 34,
- "position": "bottom"
- },
- "value_pct": 11
- }
- ],
- "n_neighbours": 7,
- "sa4": {
- "cohort_size": 148,
- "name": "Newcastle and Lake Macquarie"
- },
- "suburb": "Belmont North"
- },
- "properties": {
- "metrics": {
- "description": "Per-metric comparisons.",
- "items": {
- "additionalProperties": true,
- "description": "One ranked metric with its SA4 + neighbour comparisons.",
- "properties": {
- "field": {
- "description": "suburb_finder field code.",
- "title": "Field",
- "type": "string"
- },
- "label": {
- "description": "Human metric name.",
- "title": "Label",
- "type": "string"
- },
- "neighbours": {
- "anyOf": [
- {
- "additionalProperties": true,
- "description": "Touching-suburb comparison for one metric.",
- "properties": {
- "dramatic": {
- "anyOf": [
- {
- "additionalProperties": true,
- "description": "Largest-delta neighbouring suburb (|delta| >= 25%).",
- "properties": {
- "delta_pct": {
- "description": "Percent difference vs the subject (signed).",
- "title": "Delta Pct",
- "type": "integer"
- },
- "suburb": {
- "description": "Neighbouring SAL name.",
- "title": "Suburb",
- "type": "string"
- },
- "value_pct": {
- "anyOf": [
- {
- "type": "number"
- },
- {
- "type": "null"
- }
- ],
- "description": "Neighbour's value (%).",
- "title": "Value Pct"
- }
- },
- "required": [
- "suburb",
- "delta_pct"
- ],
- "title": "DramaticNeighbour",
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "description": "Largest-delta neighbour (only when mixed)."
- },
- "highest_in_group": {
- "description": "True when every neighbour is at or below the suburb.",
- "title": "Highest In Group",
- "type": "boolean"
- },
- "lowest_in_group": {
- "description": "True when every neighbour is at or above the suburb.",
- "title": "Lowest In Group",
- "type": "boolean"
- },
- "n": {
- "description": "Touching suburbs with a value.",
- "title": "N",
- "type": "integer"
- }
- },
- "required": [
- "n",
- "lowest_in_group",
- "highest_in_group"
- ],
- "title": "CohortNeighbours",
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "description": "Touching-suburb comparison."
- },
- "sa4": {
- "anyOf": [
- {
- "additionalProperties": true,
- "description": "SA4-cohort percentile position for one metric.",
- "properties": {
- "delta_pct": {
- "description": "Distance from the tail — 6 reads as 'Top 6%'.",
- "title": "Delta Pct",
- "type": "integer"
- },
- "n": {
- "description": "SA4 cohort suburbs with a value.",
- "title": "N",
- "type": "integer"
- },
- "percentile": {
- "description": "Share of SA4 cohort strictly below the suburb (0-100).",
- "title": "Percentile",
- "type": "integer"
- },
- "position": {
- "description": "Which tail the suburb sits in.",
- "enum": [
- "top",
- "bottom"
- ],
- "title": "Position",
- "type": "string"
- }
- },
- "required": [
- "percentile",
- "position",
- "delta_pct",
- "n"
- ],
- "title": "CohortSa4Rank",
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "description": "SA4 percentile rank."
- },
- "value_pct": {
- "anyOf": [
- {
- "type": "number"
- },
- {
- "type": "null"
- }
- ],
- "description": "The suburb's value (%).",
- "title": "Value Pct"
- }
- },
- "required": [
- "field",
- "label"
- ],
- "title": "CohortMetric",
- "type": "object"
- },
- "title": "Metrics",
- "type": "array"
- },
- "n_neighbours": {
- "description": "Touching suburbs in the cohort.",
- "title": "N Neighbours",
- "type": "integer"
- },
- "sa4": {
- "anyOf": [
- {
- "additionalProperties": true,
- "description": "The suburb's SA4 cohort.",
- "properties": {
- "cohort_size": {
- "anyOf": [
- {
- "type": "integer"
- },
- {
- "type": "null"
- }
- ],
- "description": "Suburbs in the SA4 cohort.",
- "title": "Cohort Size"
- },
- "name": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "SA4 region name.",
- "title": "Name"
- }
- },
- "title": "CohortSa4",
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "description": "SA4 cohort metadata."
- },
- "suburb": {
- "description": "Canonical SAL name.",
- "title": "Suburb",
- "type": "string"
- }
- },
- "required": [
- "suburb",
- "n_neighbours",
- "metrics"
- ],
- "title": "SuburbCohorts",
- "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[SuburbCohorts]",
- "type": "object",
- "x-fastmcp-top-level-schema": "ApiResponse_SuburbCohorts_"
-}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 useful context about comparison scope and metrics, but does not disclose return format, rank ordering, or how ranks are computed. It adds some value beyond annotations but not extensive behavioral detail.
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 compact sentence with no filler. It front-loads the core action ('How the suburb ranks') and immediately specifies the comparison groups and metrics. Every word contributes to understanding the tool's purpose.
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, the description is mostly adequate: it tells the agent what suburb to pass and what question the tool answers. However, without an output schema, the description does not explain what the returned ranking data looks like, which is a notable completeness gap.
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% and the description only implicitly references 'the suburb' without explaining the expected format of suburb_name. It does not provide examples, case-sensitivity guidance, or clarity on what forms of suburb names are accepted. The single string parameter is simple, but the description does not compensate for the missing schema-level documentation.
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 what the tool does: it ranks a suburb within its SA4 region and against touching neighbours on four specific metrics (renter share, welfare dependency, overseas-born parents, public housing). This distinguishes it from the many other demographics sibling tools. It lacks an imperative verb like 'Get' or 'Returns', but the purpose is still explicit.
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 provides enough context to infer when to use the tool: when a suburb's cohort-related ranking relative to its region or neighbours is needed. However, it gives no explicit when-not-to-use guidance or references to alternative sibling tools, which would be valuable given the large sibling list.
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.