suburbs_risks_capital_growth_impactMatched-study capital-growth impact (%/yr) for bushfire, flood, contamination, mine subsidence, aircraft noise and surface acid sulfate, scaled by the share of properties affected.
| 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-hazard capital-growth impact (%/yr) across the suburb's risks.",
- "example": {
- "area_level": "suburb",
- "area_name": "Belmont North",
- "hazards": [
- {
- "affected_pct": 23.62,
- "coefficient_pct_per_year": 0.9,
- "color_class": "neutral",
- "impact": "+0.21%/yr",
- "impact_pct_per_year": 0.2126,
- "key": "bushfire",
- "label": "Bushfire",
- "present": true
- },
- {
- "affected_pct": 100,
- "coefficient_pct_per_year": 0.2,
- "color_class": "neutral",
- "impact": "+0.2%/yr",
- "impact_pct_per_year": 0.2,
- "key": "mine_subsidence",
- "label": "Mine subsidence",
- "present": true
- }
- ],
- "study": "Microburbs matched capital-growth study (DBYD) — treated minus control CAGR",
- "total_properties": 2727
- },
- "properties": {
- "area_level": {
- "const": "suburb",
- "description": "Always 'suburb'.",
- "title": "Area Level",
- "type": "string"
- },
- "area_name": {
- "description": "Canonical ABS SAL suburb name.",
- "title": "Area Name",
- "type": "string"
- },
- "hazards": {
- "description": "One entry per studied hazard.",
- "items": {
- "additionalProperties": true,
- "description": "One hazard's matched-study capital-growth impact for this suburb.",
- "properties": {
- "affected_pct": {
- "description": "Share of the suburb's properties affected (%).",
- "title": "Affected Pct",
- "type": "number"
- },
- "coefficient_pct_per_year": {
- "description": "Matched-study coefficient: treated-minus-control CAGR difference (%/yr) for a fully-affected suburb.",
- "title": "Coefficient Pct Per Year",
- "type": "number"
- },
- "color_class": {
- "anyOf": [
- {
- "enum": [
- "positive",
- "negative",
- "neutral"
- ],
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Report's colour band: |impact| >= 0.3 %/yr is positive/negative, else neutral.",
- "title": "Color Class"
- },
- "impact": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Impact as the report renders it, e.g. '+0.2%/yr'. Null when not shown.",
- "title": "Impact"
- },
- "impact_pct_per_year": {
- "anyOf": [
- {
- "type": "number"
- },
- {
- "type": "null"
- }
- ],
- "description": "Coefficient scaled by the affected share (%/yr). Null when the report shows no impact for this hazard here.",
- "title": "Impact Pct Per Year"
- },
- "key": {
- "description": "Hazard key (bushfire, flood, contamination, mine_subsidence, aircraft_noise, acid_sulfate_surface).",
- "title": "Key",
- "type": "string"
- },
- "label": {
- "description": "Human-readable hazard name.",
- "title": "Label",
- "type": "string"
- },
- "present": {
- "description": "Whether the hazard is material in this suburb (report's own threshold).",
- "title": "Present",
- "type": "boolean"
- }
- },
- "required": [
- "key",
- "label",
- "present",
- "affected_pct",
- "coefficient_pct_per_year"
- ],
- "title": "HazardCgImpact",
- "type": "object"
- },
- "title": "Hazards",
- "type": "array"
- },
- "study": {
- "description": "Provenance of the coefficients.",
- "title": "Study",
- "type": "string"
- },
- "total_properties": {
- "description": "Principal GNAF addresses in the suburb.",
- "title": "Total Properties",
- "type": "integer"
- }
- },
- "required": [
- "area_name",
- "area_level",
- "total_properties",
- "study",
- "hazards"
- ],
- "title": "SuburbRiskCgImpact",
- "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[SuburbRiskCgImpact]",
- "type": "object",
- "x-fastmcp-top-level-schema": "ApiResponse_SuburbRiskCgImpact_"
-}New value: +nullDoes the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds meaningful behavioral context by explaining the output is a matched-study impact metric with specific hazard list and scaling, which is beyond the annotation's generic hints. No contradiction with annotations.
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 one sentence, front-loading the key purpose and listing hazards efficiently. It avoids fluff and is appropriately sized for a simple read-only tool, though it could be slightly more structured with a note about the parameter.
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 with no output schema, the description covers the core output (capital-growth impact per hazard, unit, and scaling). It does not describe the exact return format (e.g., list vs map) or how to interpret values, but given the low complexity and existing annotations, it is largely complete.
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 input schema has a single 'suburb_name' parameter with no description, and schema coverage is 0%. The tool description does not mention or explain the parameter, relying entirely on the name to imply it expects a suburb name. This fails to compensate for the missing schema description, leaving the agent without explicit guidance on what value to provide.
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 the tool returns capital-growth impact (%/yr) per hazard type, listing the specific hazards (bushfire, flood, contamination, etc.) and the scaling by share of properties affected. This is specific and distinguishes it from sibling risk tools that focus on counts, zones, or hazard presence.
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 gives no explicit guidance on when to use this tool versus alternatives like suburbs_risks_all or suburbs_risks_bushfire. Usage context is only implied by the name and description, which is sufficient for an agent to infer it is for capital-growth impact data, but there is no stated when-not or alternative routing.
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.