suburbs_demographics_unemploymentLabour-force-weighted unemployment rate for the suburb against the pinned national median, plus the per-microburb shares behind it.
| 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": "Suburb unemployment rate vs the national median, plus per-mesh-block.",
- "example": {
- "basis": "labour_force",
- "growth_impact": {
- "band": "Mid unemployment",
- "pct_per_year": 0
- },
- "microburbs": [
- {
- "mb": "10664530000",
- "street": "Marquis St",
- "unemployment_pct": 3.1
- }
- ],
- "n_microburbs": 71,
- "national_median_pct": 5.2,
- "suburb": "Belmont North",
- "unemployment_pct": 4.2,
- "vs_national": "below"
- },
- "properties": {
- "basis": {
- "description": "Denominator behind unemployment_pct — 'labour_force' (unemployed / labour force, the reported figure) or 'population_share' (suburb census fallback when the mesh-block downscale has no coverage).",
- "enum": [
- "labour_force",
- "population_share"
- ],
- "title": "Basis",
- "type": "string"
- },
- "growth_impact": {
- "additionalProperties": true,
- "description": "The capital-growth difference historically associated with suburbs in this unemployment band. An association from past research, not a forecast — see the field's own description.",
- "properties": {
- "band": {
- "description": "Plain-language name of the band the suburb landed in, suitable for display alongside the figure — e.g. 'Middle 90%', 'High unemployment', 'Low private-school share'. The wording differs per indicator; treat it as a label, not a shared enum.",
- "title": "Band",
- "type": "string"
- },
- "pct_per_year": {
- "description": "The growth difference historically associated with this band, in percentage points per year on a percent scale — `-3.8` means 3.8 percentage points a year worse, `0.5` means half a point a year better, and `0.0` (the common case, for suburbs in the middle band) means no association either way. A relative difference, not a growth rate in its own right.",
- "title": "Pct Per Year",
- "type": "number"
- }
- },
- "required": [
- "pct_per_year",
- "band"
- ],
- "title": "GrowthImpact",
- "type": "object"
- },
- "microburbs": {
- "description": "Per-mesh-block unemployment shares (sparse cells dropped).",
- "items": {
- "additionalProperties": true,
- "description": "One mesh block's unemployment share.",
- "properties": {
- "mb": {
- "description": "ABS mesh-block code.",
- "title": "Mb",
- "type": "string"
- },
- "street": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Modal street name in the mesh block.",
- "title": "Street"
- },
- "unemployment_pct": {
- "anyOf": [
- {
- "type": "number"
- },
- {
- "type": "null"
- }
- ],
- "description": "Downscaled unemployment share for the mesh block.",
- "title": "Unemployment Pct"
- }
- },
- "required": [
- "mb"
- ],
- "title": "UnemploymentMicroburb",
- "type": "object"
- },
- "title": "Microburbs",
- "type": "array"
- },
- "n_microburbs": {
- "description": "Mesh blocks in the microburbs list.",
- "title": "N Microburbs",
- "type": "integer"
- },
- "national_median_pct": {
- "description": "The Australia-wide unemployment rate to compare `unemployment_pct` against, as a percentage — a fixed 2021 Census benchmark, so it is the same constant in every response and does not move between suburbs or over time. Despite 'median' in the name it is a national aggregate rate, not the median of suburb rates.",
- "title": "National Median Pct",
- "type": "number"
- },
- "suburb": {
- "description": "Canonical SAL name.",
- "title": "Suburb",
- "type": "string"
- },
- "unemployment_pct": {
- "description": "Suburb unemployment rate as a percentage.",
- "title": "Unemployment Pct",
- "type": "number"
- },
- "vs_national": {
- "description": "Whether this suburb's unemployment sits 'below' or 'above' the national benchmark — the shorthand answer to 'is this good or bad'. Below is the favourable direction here. A suburb exactly equal to the benchmark is reported as 'above'.",
- "enum": [
- "below",
- "above"
- ],
- "title": "Vs National",
- "type": "string"
- }
- },
- "required": [
- "suburb",
- "unemployment_pct",
- "basis",
- "national_median_pct",
- "vs_national",
- "growth_impact",
- "n_microburbs",
- "microburbs"
- ],
- "title": "Unemployment",
- "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[Unemployment]",
- "type": "object",
- "x-fastmcp-top-level-schema": "ApiResponse_Unemployment_"
-}New value: +nullDoes the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the metric being labour-force-weighted and the comparison to a pinned national median, plus per-microburb shares. It doesn't disclose return format, pagination, or data source limitations, but for a read-only stats tool this is acceptable.
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 sentence that packs in the metric, the comparison baseline, and the breakdown structure. It's front-loaded with the key metric and doesn't waste words. Minor deduction for the slightly awkward line break and the term 'microburb' which may need definition.
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 one-parameter read-only tool, the description covers the core purpose and the output's conceptual content (rate vs median, per-microburb shares). However, it doesn't explain what 'microburb' means, how the national median is pinned, or what the response structure looks like. Given no output schema, a bit more detail on return values would help.
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%, so the description must compensate for the single parameter suburb_name. The description implies the parameter is the suburb to query, but it doesn't explicitly state the expected format (e.g., full name vs. short name) or provide examples. With only one parameter, the baseline is 4, but the lack of any parameter guidance reduces it to 3.
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 states a specific metric (labour-force-weighted unemployment rate) and the resource (suburb), and mentions the comparison to a pinned national median. It distinguishes itself from other suburbs_demographics_* tools by focusing on unemployment, though it doesn't explicitly name a sibling alternative.
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 usage for retrieving unemployment data for a suburb, and the context of comparing against a national median is clear. However, it doesn't explicitly state when to use this tool versus other demographics tools (e.g., suburbs_demographics_income or suburbs_demographics_all), nor does it mention any exclusions or prerequisites.
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.