{
  "descriptorVersion": "1.0.0",
  "name": "search_car_parks",
  "title": "Hong Kong car park vacancy search",
  "description": "Search operator-reported private car park vacancies from Hong Kong's official one-stop parking feed (DATA.GOV.HK). Replaces this page's search text, district, sort and filter controls with the given arguments and shows the same results on screen. Queries public data already loaded in the page (no new data fetch per call); never uses or returns the visitor's location or distances. Results include official report times, freshness and source attribution. Calculation or source matching runs in this page; arguments and results are not uploaded to Agoodeal servers or to Google Analytics, and the result is returned only to the calling agent. Non-sensitive usage metadata (tool name, outcome, execution mode, error code, duration; predefined source IDs for source matching) is reported through the site’s existing Google Analytics 4.",
  "execution": {
    "environment": "browser",
    "interface": "WebMCP imperative API: document.modelContext.registerTool (experimental)",
    "pageUrls": [
      "https://www.agoodeal.com/tools/car-park-vacancy/",
      "https://www.agoodeal.com/tools/car-park-vacancy/central-and-western/",
      "https://www.agoodeal.com/tools/car-park-vacancy/wan-chai/",
      "https://www.agoodeal.com/tools/car-park-vacancy/eastern/",
      "https://www.agoodeal.com/tools/car-park-vacancy/southern/",
      "https://www.agoodeal.com/tools/car-park-vacancy/yau-tsim-mong/",
      "https://www.agoodeal.com/tools/car-park-vacancy/sham-shui-po/",
      "https://www.agoodeal.com/tools/car-park-vacancy/kowloon-city/",
      "https://www.agoodeal.com/tools/car-park-vacancy/wong-tai-sin/",
      "https://www.agoodeal.com/tools/car-park-vacancy/kwun-tong/",
      "https://www.agoodeal.com/tools/car-park-vacancy/tsuen-wan/",
      "https://www.agoodeal.com/tools/car-park-vacancy/tuen-mun/",
      "https://www.agoodeal.com/tools/car-park-vacancy/yuen-long/",
      "https://www.agoodeal.com/tools/car-park-vacancy/north/",
      "https://www.agoodeal.com/tools/car-park-vacancy/tai-po/",
      "https://www.agoodeal.com/tools/car-park-vacancy/sai-kung/",
      "https://www.agoodeal.com/tools/car-park-vacancy/sha-tin/",
      "https://www.agoodeal.com/tools/car-park-vacancy/kwai-tsing/",
      "https://www.agoodeal.com/tools/car-park-vacancy/islands/"
    ],
    "requirement": "Open one of pageUrls in a browser that exposes document.modelContext. As of October 2026 this is experimental: Chrome 149+ with chrome://flags/#enable-webmcp-testing, or an origin trial that Agoodeal has not joined. Without it the page works normally for people and no tool is registered.",
    "serverEndpoint": null,
    "argumentsEncoding": "JSON object (some browser versions require callers to pass it as a JSON string).",
    "returns": "A JSON string matching outputSchema."
  },
  "annotations": {
    "readOnlyHint": false,
    "untrustedContentHint": true,
    "consequentialHint": false
  },
  "annotationNotes": "readOnlyHint is false because the tool changes the visible filters and results on the page. It submits, stores and purchases nothing. Source text is third-party data.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "maxLength": 40,
        "description": "Optional text matched against car park name, address and sub-district (Traditional Chinese works best, e.g. 觀塘)."
      },
      "district": {
        "type": "string",
        "enum": [
          "中西區",
          "灣仔區",
          "東區",
          "南區",
          "油尖旺區",
          "深水埗區",
          "九龍城區",
          "黃大仙區",
          "觀塘區",
          "荃灣區",
          "屯門區",
          "元朗區",
          "北區",
          "大埔區",
          "西貢區",
          "沙田區",
          "葵青區",
          "離島區"
        ],
        "description": "Optional official district name. Omit for all districts on this page."
      },
      "onlyAvailable": {
        "type": "boolean",
        "default": true,
        "description": "When true, keep only reports that currently count as available: not full, closed, unknown, or older than 60 minutes."
      },
      "requireEvCharger": {
        "type": "boolean",
        "default": false,
        "description": "When true, keep only car parks whose source lists EV charging facilities."
      },
      "sort": {
        "type": "string",
        "enum": [
          "vacancy",
          "price",
          "name"
        ],
        "default": "vacancy",
        "description": "vacancy = most reported spaces first; price = lowest listed hourly-equivalent rate first; name = Chinese name order."
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 20,
        "default": 10,
        "description": "Maximum number of car parks returned."
      }
    },
    "additionalProperties": false
  },
  "outputSchema": {
    "oneOf": [
      {
        "type": "object",
        "required": [
          "ok",
          "tool",
          "uiInputsReplaced",
          "arguments",
          "evaluatedAt",
          "matchedCount",
          "returnedCount",
          "feed",
          "carparks",
          "source",
          "notes"
        ],
        "properties": {
          "ok": {
            "const": true
          },
          "tool": {
            "const": "search_car_parks"
          },
          "uiInputsReplaced": {
            "const": true
          },
          "arguments": {
            "type": "object"
          },
          "evaluatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Browser clock instant used for ages and availability."
          },
          "pageScope": {
            "type": "string"
          },
          "matchedCount": {
            "type": "integer"
          },
          "returnedCount": {
            "type": "integer"
          },
          "excludedSourceFlaggedClosed": {
            "type": "integer"
          },
          "feed": {
            "type": "object",
            "required": [
              "fetchedAt",
              "newestReliableReportAt",
              "staleNow"
            ],
            "properties": {
              "fetchedAt": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "newestReliableReportAt": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "staleNow": {
                "type": "boolean"
              },
              "staleMeaning": {
                "type": "string"
              },
              "freshnessMinutes": {
                "type": "object"
              }
            }
          },
          "carparks": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "object",
              "required": [
                "id",
                "name",
                "district",
                "availability",
                "countsAsAvailable",
                "vacancy",
                "vacancyStatus",
                "reportedAt",
                "reportedAtIso",
                "reportAgeMinutes",
                "freshness",
                "hourlyPriceFrom",
                "hasEvCharger"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "district": {
                  "type": "string"
                },
                "subDistrict": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "address": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "availability": {
                  "enum": [
                    "available",
                    "flag",
                    "outdated",
                    "full",
                    "closed",
                    "unknown"
                  ]
                },
                "availabilityLabel": {
                  "type": "string"
                },
                "countsAsAvailable": {
                  "type": "boolean"
                },
                "vacancy": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Exact reported count; null when not a count. null is never zero."
                },
                "vacancyType": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "vacancyStatus": {
                  "enum": [
                    "available",
                    "full",
                    "closed",
                    "unknown"
                  ]
                },
                "sourceOpeningStatus": {
                  "enum": [
                    "open",
                    "closed",
                    "unknown",
                    "conflict"
                  ]
                },
                "reportedAt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Official report time as published (Hong Kong local time)."
                },
                "reportedAtIso": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "reportAgeMinutes": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "freshness": {
                  "enum": [
                    "current",
                    "older",
                    "outdated",
                    "unknown"
                  ]
                },
                "hourlyPriceFrom": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "HKD hourly equivalent of the lowest listed rate; not a guaranteed charge."
                },
                "priceBasis": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "hasEvCharger": {
                  "type": "boolean"
                },
                "heightLimitMetres": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "note": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "additionalProperties": false
            }
          },
          "source": {
            "type": "object"
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      {
        "type": "object",
        "required": [
          "ok",
          "error"
        ],
        "properties": {
          "ok": {
            "const": false
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "enum": [
                  "invalid_json",
                  "invalid_argument",
                  "district_outside_page",
                  "district_not_in_current_data",
                  "data_unavailable",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              },
              "field": {
                "type": "string"
              },
              "maximumAchievableDays": {
                "type": "integer"
              }
            }
          }
        }
      }
    ]
  },
  "privacy": "No location, coordinates or distances are accepted or returned, even if the visitor has shared location with the page. Nothing is stored or logged by the tool. Calculation or source matching runs in this page; arguments and results are not uploaded to Agoodeal servers or to Google Analytics, and the result is returned only to the calling agent. Non-sensitive usage metadata (tool name, outcome, execution mode, error code, duration; predefined source IDs for source matching) is reported through the site’s existing Google Analytics 4.",
  "dataSource": {
    "name": "Parking Vacancy Data (One-Stop Version)",
    "publisher": "Digital Policy Office (DATA.GOV.HK)",
    "datasetUrl": "https://data.gov.hk/en-data/dataset/hk-dpo-datagovhk1-carpark-info-vacancy",
    "termsUrl": "https://data.gov.hk/en/terms-and-conditions",
    "httpContract": "https://www.agoodeal.com/schemas/carparks-v1.schema.json"
  }
}