suburbs_demographics_ancestry_mapThe dominant ancestry (and its share) in each of the suburb's microburbs, plus suburb-level ancestry shares. Pilot coverage.
| 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 dominant ancestry (pilot-coverage dataset).",
- "example": {
- "microburbs": [
- {
- "dominant_ancestry": "Anglo-Australian",
- "mb": "10694860000",
- "persons": 118,
- "share_pct": 62.1,
- "street": "Edinburgh Rd"
- }
- ],
- "n_microburbs": 37,
- "suburb": "Castlecrag",
- "suburb_ancestry_shares": [
- {
- "ancestry": "Anglo-Australian",
- "pct": 58.4
- },
- {
- "ancestry": "Chinese",
- "pct": 12.9
- }
- ]
- },
- "properties": {
- "microburbs": {
- "description": "Dominant ancestry per microburb.",
- "items": {
- "additionalProperties": true,
- "description": "One microburb's dominant ancestry.",
- "properties": {
- "dominant_ancestry": {
- "description": "Largest ancestry bucket.",
- "title": "Dominant Ancestry",
- "type": "string"
- },
- "mb": {
- "description": "ABS mesh-block code.",
- "title": "Mb",
- "type": "string"
- },
- "persons": {
- "anyOf": [
- {
- "type": "integer"
- },
- {
- "type": "null"
- }
- ],
- "description": "Total persons in the MB.",
- "title": "Persons"
- },
- "share_pct": {
- "description": "Dominant bucket's share of ancestry responses (%).",
- "title": "Share Pct",
- "type": "number"
- },
- "street": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Modal street name in the MB.",
- "title": "Street"
- }
- },
- "required": [
- "mb",
- "dominant_ancestry",
- "share_pct"
- ],
- "title": "AncestryMb",
- "type": "object"
- },
- "title": "Microburbs",
- "type": "array"
- },
- "n_microburbs": {
- "description": "Microburbs with ancestry data.",
- "title": "N Microburbs",
- "type": "integer"
- },
- "suburb": {
- "description": "Canonical SAL name.",
- "title": "Suburb",
- "type": "string"
- },
- "suburb_ancestry_shares": {
- "description": "Suburb-level ancestry shares, descending.",
- "items": {
- "additionalProperties": true,
- "description": "Suburb-level ancestry share.",
- "properties": {
- "ancestry": {
- "description": "Ancestry bucket name.",
- "title": "Ancestry",
- "type": "string"
- },
- "pct": {
- "description": "Share of all ancestry responses (%).",
- "title": "Pct",
- "type": "number"
- }
- },
- "required": [
- "ancestry",
- "pct"
- ],
- "title": "AncestryShare",
- "type": "object"
- },
- "title": "Suburb Ancestry Shares",
- "type": "array"
- }
- },
- "required": [
- "suburb",
- "n_microburbs",
- "microburbs",
- "suburb_ancestry_shares"
- ],
- "title": "SuburbAncestryMap",
- "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[SuburbAncestryMap]",
- "type": "object",
- "x-fastmcp-top-level-schema": "ApiResponse_SuburbAncestryMap_"
-}New value: +nullDoes the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation read-only, idempotent, and non-destructive, so the safety burden is covered. The description adds only a vague 'Pilot coverage' caveat and does not clarify what happens for unsupported suburbs or how 'dominant' is determined.
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?
One clean sentence front-loads the core output and ends with a caveat. It contains no filler and does not redundantly restate the title or annotations.
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?
Because there is no output schema, the description appropriately names the main return values: dominant ancestry per microburb and suburb-level shares. It could be more complete by spelling out the share format and the scope of 'Pilot coverage,' but for a simple one-parameter read-only tool the description is largely sufficient.
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 single required parameter, suburb_name, is self-explanatory, and the description clarifies that it identifies the suburb whose microburbs are being examined. This compensates for the 0% schema description coverage, even though no format or exact-match requirements are stated.
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 precise output: the dominant ancestry and its share per microburb, plus suburb-level ancestry shares. The title reinforces the resource, and the 'map' framing distinguishes it from related ancestry/list siblings such as suburbs_ethnicity_ancestry.
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 tool is for per-microburb ancestry mapping, but it does not explicitly name alternatives or state when not to use it. The 'Pilot coverage' note hints at limited availability but is too vague to help an agent route between this and similar demographics/ethnicity tools.
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.