properties_schools_rankingSchools within ~5km of the property, ranked by NAPLAN / socioeconomic score.
Price: 100¢ per call.
| Name | Required | Description | Default |
|---|---|---|---|
| gnaf_id | 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": [
- {
- "items": {
- "additionalProperties": true,
- "description": "One school within ~5km, ranked by NAPLAN + socio-economic percentiles.",
- "example": {
- "attendance_rate": 0.89,
- "distance_m": 612,
- "id": 42002,
- "name": "Belmont North Public School",
- "naplan_label": "Top 40%",
- "naplan_rank": 0.63,
- "school_level_type": "Primary",
- "sector": "public",
- "socioeconomic_label": "Bottom 20%",
- "socioeconomic_rank": 0.17
- },
- "properties": {
- "attendance_rate": {
- "anyOf": [
- {
- "type": "number"
- },
- {
- "type": "null"
- }
- ],
- "description": "Mean attendance rate (0–1).",
- "title": "Attendance Rate"
- },
- "distance_m": {
- "anyOf": [
- {
- "type": "integer"
- },
- {
- "type": "null"
- }
- ],
- "description": "Distance from the property in metres.",
- "title": "Distance M"
- },
- "id": {
- "anyOf": [
- {
- "type": "integer"
- },
- {
- "type": "null"
- }
- ],
- "description": "School identifier (MySchool ID).",
- "title": "Id"
- },
- "name": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "School name.",
- "title": "Name"
- },
- "naplan_label": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Human-readable NAPLAN band — 'Top 5%', 'Top 40%', etc.",
- "title": "Naplan Label"
- },
- "naplan_rank": {
- "anyOf": [
- {
- "type": "number"
- },
- {
- "type": "null"
- }
- ],
- "description": "NAPLAN rank percentile (0–1, higher = better).",
- "title": "Naplan Rank"
- },
- "school_level_type": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Primary / Secondary / Combined.",
- "title": "School Level Type"
- },
- "sector": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "public / private.",
- "title": "Sector"
- },
- "socioeconomic_label": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Human-readable affluence band.",
- "title": "Socioeconomic Label"
- },
- "socioeconomic_rank": {
- "anyOf": [
- {
- "type": "number"
- },
- {
- "type": "null"
- }
- ],
- "description": "Socio-economic rank percentile (0–1, higher = more advantaged).",
- "title": "Socioeconomic Rank"
- }
- },
- "title": "SchoolRanking",
- "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[SchoolRanking]]",
- "type": "object",
- "x-fastmcp-top-level-schema": "ApiResponse_list_SchoolRanking__"
-}New value: +nullDoes the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety information. However, it does add useful context about the data being ranked by NAPLAN/socioeconomic score, which is not inferred from the name alone. It does not disclose potential variability in the number of schools returned or any limits, which could be relevant for an agent.
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 concise with two sentences, and the key purpose is front-loaded. The pricing note is a separate line, which is clear but could be considered extraneous for functional description, yet it is important for decision-making. The structure is efficient and avoids redundancy.
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?
Given the tool's simplicity (one parameter, no output schema), the description is fairly complete, but it lacks details on the output format, such as whether it returns a list of school names, scores, or both. The ranking methodology is mentioned but not elaborated, which may be acceptable for a simple tool, but an agent might need more to fully utilize the result.
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 parameter gnaf_id is not explained in the schema. The description also does not explicitly explain what gnaf_id is or how to obtain it, placing the burden on the agent to infer from naming conventions. Since there is only one parameter, the description should at least clarify its role, but it does not add meaning beyond the parameter name.
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 that it returns schools within ~5km of the property ranked by NAPLAN/socioeconomic score, which distinguishes it from broader school tools like properties_schools_all and properties_schools_nearby. It uses a specific verb 'ranked' and a clear resource, making the purpose easy to understand. However, it could be more explicit about how it differs from nearby schools or catchment tools.
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 when a ranking of nearby schools by performance is needed, but it does not provide explicit guidance on when to use this tool versus alternatives like properties_schools_nearby or suburbs_schools_catchment. There is no mention of exclusions or specific scenarios, so the guidance is only implicit based on the description's focus on ranking.
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.