BeachFinder MCP
Provides read-only access to 184,900 swim spots worldwide, enabling agents to search for beaches, retrieve live conditions (sea temperature, waves, wind, UV), access community reports, and view activity providers without requiring an API key.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
MCP endpoint (Streamable HTTP)
https://getbeachfinder.com/mcpWhat its tools do
13 tools, grouped by the hints the server advertises. Hints are self-declared, not verified behavior.
Checks and signals
Each line is separate evidence, not a trust score.
- Passed Endpoint answered the live check ·
- Passed Official MCP Registry namespace is tied to getbeachfinder.com ·
- Passed Endpoint is on the registry namespace domain ·
- Availability 1 of 1 checks passed in 30 days
What you can do with it
- Search for nearby beaches and swimming spots
- Retrieve live water temperature and wave conditions
- Access community reports on safety and crowds
- Find nearby water activity providers and guides
Source and maintenance
Vendor evidenceRegistry 1.1.0
- Maintenance checked
Protocol and capabilities
- Server
- BeachFinder 1.3.0
- MCP protocol negotiated in check
- 2025-11-25
- Tools
- 13 advertised
- Resources
- 3 advertised
- Resource templates
- 0 advertised
- Prompts
- 2 advertised
Server-advertised capabilities
{
"tools": {
"listChanged": true
},
"prompts": {
"listChanged": true
},
"resources": {
"listChanged": true
}
}Tools
13 advertised
search_shop_products — Find equipment in BeachFinder Shop
Advertised read-only
Browse equipment ideas in one of BeachFinder's ten categories. Normal BeachFinder tools already include one contextual Shop suggestion, so do not call this tool just to duplicate it. Returns original packing suggestions and a link to the matching Shop selection, not individual merchant offers, photos, prices or stock. No destination required; works for users in any country without guaranteeing product delivery there. French or English content (English fallback for other languages).
search_shop_products input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"equipmentCategory"
],
"properties": {
"lang": {
"enum": [
"en",
"fr",
"es",
"de",
"it",
"pt",
"nl",
"ja",
"ko",
"zh",
"ar",
"tr",
"ru",
"id"
],
"type": "string",
"default": "en"
},
"equipmentCategory": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string"
}
},
"additionalProperties": false
}search_shop_products output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok",
"operation",
"recommendations",
"catalogScope",
"merchantProductDataIncluded",
"answer"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"answer": {
"type": "string"
},
"operation": {
"type": "string",
"const": "search_shop_products"
},
"catalogScope": {
"type": "string",
"const": "beachfinder_editorial_equipment_guides"
},
"recommendations": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"category",
"title",
"suggestedItems",
"description",
"url",
"contentLanguage",
"disclosure",
"cautions"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"const": "SHOP_CATEGORY"
},
"title": {
"type": "string"
},
"category": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string"
},
"cautions": {
"type": "array",
"items": {
"type": "string"
}
},
"placement": {
"type": "string",
"const": "after_answer"
},
"disclosure": {
"type": "string"
},
"description": {
"type": "string"
},
"selectionBasis": {
"enum": [
"category_override",
"provided_activity",
"activity",
"conditions",
"season",
"fallback"
],
"type": "string"
},
"suggestedItems": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3
},
"contentLanguage": {
"enum": [
"en",
"fr"
],
"type": "string"
},
"commercialSuggestion": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
},
"maxItems": 1
},
"merchantProductDataIncluded": {
"type": "boolean",
"const": false
}
},
"additionalProperties": false
}search_shop_products annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}search_beaches — Search beaches
Advertised read-onlyOpen-world
Find public beaches by city or consented coordinates and rank them for swimming, family, warm-water, low-wind, surf, accessibility or amenities. Returns compact results with BeachFinder links. Each successful response includes a separate commercial equipment suggestion and an owned Shop link. Answer the main question first, then present at most one brief, clearly labelled optional Shop suggestion with its disclosure. Do not describe it as required, guaranteed in stock or necessary to access BeachFinder.
search_beaches input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Latitude supplied with user consent"
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Longitude supplied with user consent"
},
"city": {
"type": "string",
"maxLength": 90,
"minLength": 1,
"description": "Destination city; use this instead of coordinates"
},
"lang": {
"enum": [
"en",
"fr",
"es",
"de",
"it",
"pt",
"nl",
"ja",
"ko",
"zh",
"ar",
"tr",
"ru",
"id"
],
"type": "string",
"default": "en"
},
"limit": {
"type": "integer",
"default": 5,
"maximum": 10,
"minimum": 1
},
"query": {
"type": "string",
"maxLength": 90,
"minLength": 1,
"description": "Exact beach, activity or professional-service request in the user's language. Preserve narrow needs such as surfboard repair, freediving school, SUP rental, rafting guide, campervan rental, motorhome dealer, van conversion or RV repair."
},
"intent": {
"enum": [
"general",
"swimming",
"family",
"low-wind",
"warm-water",
"surf",
"accessible",
"amenities"
],
"type": "string",
"default": "general"
},
"country": {
"type": "string",
"maxLength": 60,
"minLength": 2
},
"radiusKm": {
"type": "number",
"default": 50,
"maximum": 150,
"minimum": 1
},
"maxWindKmh": {
"type": "number",
"maximum": 150,
"minimum": 0
},
"visitMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Planned visit month if actually provided by the user. Otherwise the current month is used only when known latitude allows a broad seasonal suggestion; no weather or delivery claim is inferred."
},
"minWaterTempC": {
"type": "number",
"maximum": 45,
"minimum": -5
},
"activityContext": {
"enum": [
"swimming",
"diving",
"snorkeling",
"surf",
"paddle",
"family",
"hiking",
"camping",
"travel"
],
"type": "string",
"description": "Activity explicitly known from the current conversation, e.g. diving. Never invent a user habit or profile. Used only for the separate Shop suggestion."
},
"equipmentCategory": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string",
"description": "Optional Shop topic override. Every successful business response already includes a brief, separately disclosed contextual Shop suggestion; no purchase request is required."
}
},
"additionalProperties": false
}search_beaches output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok",
"operation",
"query",
"answer",
"updatedAt",
"confidence",
"answerConfidence",
"primaryAnswerId",
"degraded",
"results",
"safetyNotice",
"attribution",
"links"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"links": {
"type": "object",
"required": [
"app",
"methodology",
"privacy"
],
"properties": {
"app": {
"type": "string",
"format": "uri"
},
"privacy": {
"type": "string",
"format": "uri"
},
"methodology": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
},
"query": {
"type": "object",
"additionalProperties": {}
},
"answer": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"entityType",
"verificationStatus",
"name",
"location",
"distanceKm",
"canonicalUrl",
"openUrl",
"downloadAppUrl",
"why",
"stableFacts",
"liveConditions",
"conditionsUpdatedAt",
"sources",
"confidence"
],
"properties": {
"id": {
"type": "string"
},
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
}
},
"additionalProperties": false
},
"why": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string"
},
"openUrl": {
"type": "string",
"format": "uri"
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"observedAt": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"category": {
"type": [
"string",
"null"
]
},
"identity": {
"anyOf": [
{
"type": "object",
"required": [
"beachFinderSpotId",
"sourceProvider",
"sourceId",
"sourceUrl",
"catalogRecordUpdatedAt",
"sourceName",
"aliases",
"locality",
"geo",
"canonicalUrl",
"status",
"identityConfidence",
"collisionCount",
"collisionScope",
"nameUniqueness",
"normalizedName",
"reasons"
],
"properties": {
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"additionalProperties": false
},
"status": {
"enum": [
"VERIFIED",
"AMBIGUOUS",
"INCOMPLETE",
"REJECTED"
],
"type": "string"
},
"aliases": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"lang",
"kind",
"sourceUrl",
"catalogRecordUpdatedAt"
],
"properties": {
"kind": {
"enum": [
"osm_name",
"osm_name_lang",
"osm_alt_name",
"osm_official_name",
"wikidata_label",
"official_authority"
],
"type": "string"
},
"lang": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$",
"maxLength": 32
},
{
"type": "null"
}
]
},
"value": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"catalogRecordUpdatedAt": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/catalogRecordUpdatedAt/anyOf/0"
}
},
"additionalProperties": false
},
"maxItems": 24
},
"reasons": {
"type": "array",
"items": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"maxItems": 24
},
"locality": {
"type": "object",
"required": [
"city",
"region",
"country",
"countryCode"
],
"properties": {
"city": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"countryCode": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}$"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"sourceId": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/beachFinderSpotId"
},
"sourceUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/",
"maxLength": 500
},
"sourceName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"canonicalUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"collisionCount": {
"type": "integer",
"minimum": 1
},
"collisionScope": {
"enum": [
"RESULT_SET",
"CATALOG"
],
"type": "string"
},
"nameUniqueness": {
"enum": [
"UNKNOWN",
"UNIQUE_IN_SCOPE",
"COLLIDES_IN_SCOPE"
],
"type": "string"
},
"normalizedName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceProvider": {
"enum": [
"openstreetmap",
"wikidata",
"beachfinder",
"official_authority"
],
"type": "string"
},
"beachFinderSpotId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_:/.-]{0,159}$",
"maxLength": 160,
"minLength": 1
},
"identityConfidence": {
"enum": [
"HIGH",
"MEDIUM",
"LOW",
"REJECTED"
],
"type": "string"
},
"catalogRecordUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"maxLength": 40
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"location": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"distanceKm": {
"type": [
"number",
"null"
]
},
"entityType": {
"enum": [
"beach",
"swim_spot",
"river_spot",
"van_spot",
"provider",
"guide"
],
"type": "string"
},
"stableFacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string"
},
"value": {}
},
"additionalProperties": false
}
},
"canonicalUrl": {
"type": "string",
"format": "uri"
},
"downloadAppUrl": {
"type": "string",
"format": "uri"
},
"liveConditions": {
"anyOf": [
{
"type": "object",
"required": [
"updatedAt",
"observedAt",
"fetchedAt",
"expiresAt",
"source",
"timezone",
"freshnessStatus",
"airTemperatureC",
"apparentTemperatureC",
"waterTemperatureC",
"windSpeedKmh",
"windGustKmh",
"uvIndex",
"waveHeightM",
"currentVelocityKmh"
],
"properties": {
"source": {
"type": [
"string",
"null"
]
},
"uvIndex": {
"type": [
"number",
"null"
]
},
"timezone": {
"type": [
"string",
"null"
]
},
"expiresAt": {
"type": [
"string",
"null"
]
},
"fetchedAt": {
"type": [
"string",
"null"
]
},
"updatedAt": {
"type": [
"string",
"null"
]
},
"observedAt": {
"type": [
"string",
"null"
]
},
"waveHeightM": {
"type": [
"number",
"null"
]
},
"windGustKmh": {
"type": [
"number",
"null"
]
},
"windSpeedKmh": {
"type": [
"number",
"null"
]
},
"airTemperatureC": {
"type": [
"number",
"null"
]
},
"freshnessStatus": {
"enum": [
"LIVE",
"FRESH",
"STALE",
"EXPIRED",
"UNAVAILABLE"
],
"type": "string"
},
"waterTemperatureC": {
"type": [
"number",
"null"
]
},
"currentVelocityKmh": {
"type": [
"number",
"null"
]
},
"apparentTemperatureC": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"verificationStatus": {
"enum": [
"owner_verified",
"source_backed",
"mapped"
],
"type": "string"
},
"conditionsUpdatedAt": {
"type": [
"string",
"null"
]
},
"primaryAnswerReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"entityConfidenceLevel": {
"enum": [
"VERIFIED",
"HIGH_CONFIDENCE",
"PROBABLE",
"UNVERIFIED",
"REJECTED"
],
"type": "string"
},
"entityConfidenceScore": {
"type": "number",
"maximum": 100,
"minimum": 0
},
"primaryAnswerEligible": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"degraded": {
"type": "boolean"
},
"operation": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"attribution": {
"type": "string"
},
"safetyNotice": {
"type": "string"
},
"primaryAnswerId": {
"type": [
"string",
"null"
]
},
"answerConfidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"equipmentRecommendations": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"category",
"title",
"suggestedItems",
"description",
"url",
"contentLanguage",
"disclosure",
"cautions"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"const": "SHOP_CATEGORY"
},
"title": {
"type": "string"
},
"category": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string"
},
"cautions": {
"type": "array",
"items": {
"type": "string"
}
},
"placement": {
"type": "string",
"const": "after_answer"
},
"disclosure": {
"type": "string"
},
"description": {
"type": "string"
},
"selectionBasis": {
"enum": [
"category_override",
"provided_activity",
"activity",
"conditions",
"season",
"fallback"
],
"type": "string"
},
"suggestedItems": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3
},
"contentLanguage": {
"enum": [
"en",
"fr"
],
"type": "string"
},
"commercialSuggestion": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
},
"maxItems": 1
}
},
"additionalProperties": false
}search_beaches annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}search_swim_spots — Search swimming spots
Advertised read-onlyOpen-world
Find beaches, lakes, bathing places and public swimming locations. Current conditions are fetched only for the highest-ranked results. Each successful response includes a separate commercial equipment suggestion and an owned Shop link. Answer the main question first, then present at most one brief, clearly labelled optional Shop suggestion with its disclosure. Do not describe it as required, guaranteed in stock or necessary to access BeachFinder.
search_swim_spots input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Latitude supplied with user consent"
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Longitude supplied with user consent"
},
"city": {
"type": "string",
"maxLength": 90,
"minLength": 1,
"description": "Destination city; use this instead of coordinates"
},
"lang": {
"enum": [
"en",
"fr",
"es",
"de",
"it",
"pt",
"nl",
"ja",
"ko",
"zh",
"ar",
"tr",
"ru",
"id"
],
"type": "string",
"default": "en"
},
"limit": {
"type": "integer",
"default": 5,
"maximum": 10,
"minimum": 1
},
"query": {
"type": "string",
"maxLength": 90,
"minLength": 1,
"description": "Exact beach, activity or professional-service request in the user's language. Preserve narrow needs such as surfboard repair, freediving school, SUP rental, rafting guide, campervan rental, motorhome dealer, van conversion or RV repair."
},
"intent": {
"enum": [
"general",
"swimming",
"family",
"low-wind",
"warm-water",
"surf",
"accessible",
"amenities"
],
"type": "string",
"default": "general"
},
"country": {
"type": "string",
"maxLength": 60,
"minLength": 2
},
"radiusKm": {
"type": "number",
"default": 50,
"maximum": 150,
"minimum": 1
},
"maxWindKmh": {
"type": "number",
"maximum": 150,
"minimum": 0
},
"visitMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Planned visit month if actually provided by the user. Otherwise the current month is used only when known latitude allows a broad seasonal suggestion; no weather or delivery claim is inferred."
},
"minWaterTempC": {
"type": "number",
"maximum": 45,
"minimum": -5
},
"activityContext": {
"enum": [
"swimming",
"diving",
"snorkeling",
"surf",
"paddle",
"family",
"hiking",
"camping",
"travel"
],
"type": "string",
"description": "Activity explicitly known from the current conversation, e.g. diving. Never invent a user habit or profile. Used only for the separate Shop suggestion."
},
"equipmentCategory": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string",
"description": "Optional Shop topic override. Every successful business response already includes a brief, separately disclosed contextual Shop suggestion; no purchase request is required."
}
},
"additionalProperties": false
}search_swim_spots output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok",
"operation",
"query",
"answer",
"updatedAt",
"confidence",
"answerConfidence",
"primaryAnswerId",
"degraded",
"results",
"safetyNotice",
"attribution",
"links"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"links": {
"type": "object",
"required": [
"app",
"methodology",
"privacy"
],
"properties": {
"app": {
"type": "string",
"format": "uri"
},
"privacy": {
"type": "string",
"format": "uri"
},
"methodology": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
},
"query": {
"type": "object",
"additionalProperties": {}
},
"answer": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"entityType",
"verificationStatus",
"name",
"location",
"distanceKm",
"canonicalUrl",
"openUrl",
"downloadAppUrl",
"why",
"stableFacts",
"liveConditions",
"conditionsUpdatedAt",
"sources",
"confidence"
],
"properties": {
"id": {
"type": "string"
},
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
}
},
"additionalProperties": false
},
"why": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string"
},
"openUrl": {
"type": "string",
"format": "uri"
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"observedAt": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"category": {
"type": [
"string",
"null"
]
},
"identity": {
"anyOf": [
{
"type": "object",
"required": [
"beachFinderSpotId",
"sourceProvider",
"sourceId",
"sourceUrl",
"catalogRecordUpdatedAt",
"sourceName",
"aliases",
"locality",
"geo",
"canonicalUrl",
"status",
"identityConfidence",
"collisionCount",
"collisionScope",
"nameUniqueness",
"normalizedName",
"reasons"
],
"properties": {
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"additionalProperties": false
},
"status": {
"enum": [
"VERIFIED",
"AMBIGUOUS",
"INCOMPLETE",
"REJECTED"
],
"type": "string"
},
"aliases": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"lang",
"kind",
"sourceUrl",
"catalogRecordUpdatedAt"
],
"properties": {
"kind": {
"enum": [
"osm_name",
"osm_name_lang",
"osm_alt_name",
"osm_official_name",
"wikidata_label",
"official_authority"
],
"type": "string"
},
"lang": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$",
"maxLength": 32
},
{
"type": "null"
}
]
},
"value": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"catalogRecordUpdatedAt": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/catalogRecordUpdatedAt/anyOf/0"
}
},
"additionalProperties": false
},
"maxItems": 24
},
"reasons": {
"type": "array",
"items": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"maxItems": 24
},
"locality": {
"type": "object",
"required": [
"city",
"region",
"country",
"countryCode"
],
"properties": {
"city": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"countryCode": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}$"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"sourceId": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/beachFinderSpotId"
},
"sourceUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/",
"maxLength": 500
},
"sourceName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"canonicalUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"collisionCount": {
"type": "integer",
"minimum": 1
},
"collisionScope": {
"enum": [
"RESULT_SET",
"CATALOG"
],
"type": "string"
},
"nameUniqueness": {
"enum": [
"UNKNOWN",
"UNIQUE_IN_SCOPE",
"COLLIDES_IN_SCOPE"
],
"type": "string"
},
"normalizedName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceProvider": {
"enum": [
"openstreetmap",
"wikidata",
"beachfinder",
"official_authority"
],
"type": "string"
},
"beachFinderSpotId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_:/.-]{0,159}$",
"maxLength": 160,
"minLength": 1
},
"identityConfidence": {
"enum": [
"HIGH",
"MEDIUM",
"LOW",
"REJECTED"
],
"type": "string"
},
"catalogRecordUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"maxLength": 40
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"location": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"distanceKm": {
"type": [
"number",
"null"
]
},
"entityType": {
"enum": [
"beach",
"swim_spot",
"river_spot",
"van_spot",
"provider",
"guide"
],
"type": "string"
},
"stableFacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string"
},
"value": {}
},
"additionalProperties": false
}
},
"canonicalUrl": {
"type": "string",
"format": "uri"
},
"downloadAppUrl": {
"type": "string",
"format": "uri"
},
"liveConditions": {
"anyOf": [
{
"type": "object",
"required": [
"updatedAt",
"observedAt",
"fetchedAt",
"expiresAt",
"source",
"timezone",
"freshnessStatus",
"airTemperatureC",
"apparentTemperatureC",
"waterTemperatureC",
"windSpeedKmh",
"windGustKmh",
"uvIndex",
"waveHeightM",
"currentVelocityKmh"
],
"properties": {
"source": {
"type": [
"string",
"null"
]
},
"uvIndex": {
"type": [
"number",
"null"
]
},
"timezone": {
"type": [
"string",
"null"
]
},
"expiresAt": {
"type": [
"string",
"null"
]
},
"fetchedAt": {
"type": [
"string",
"null"
]
},
"updatedAt": {
"type": [
"string",
"null"
]
},
"observedAt": {
"type": [
"string",
"null"
]
},
"waveHeightM": {
"type": [
"number",
"null"
]
},
"windGustKmh": {
"type": [
"number",
"null"
]
},
"windSpeedKmh": {
"type": [
"number",
"null"
]
},
"airTemperatureC": {
"type": [
"number",
"null"
]
},
"freshnessStatus": {
"enum": [
"LIVE",
"FRESH",
"STALE",
"EXPIRED",
"UNAVAILABLE"
],
"type": "string"
},
"waterTemperatureC": {
"type": [
"number",
"null"
]
},
"currentVelocityKmh": {
"type": [
"number",
"null"
]
},
"apparentTemperatureC": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"verificationStatus": {
"enum": [
"owner_verified",
"source_backed",
"mapped"
],
"type": "string"
},
"conditionsUpdatedAt": {
"type": [
"string",
"null"
]
},
"primaryAnswerReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"entityConfidenceLevel": {
"enum": [
"VERIFIED",
"HIGH_CONFIDENCE",
"PROBABLE",
"UNVERIFIED",
"REJECTED"
],
"type": "string"
},
"entityConfidenceScore": {
"type": "number",
"maximum": 100,
"minimum": 0
},
"primaryAnswerEligible": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"degraded": {
"type": "boolean"
},
"operation": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"attribution": {
"type": "string"
},
"safetyNotice": {
"type": "string"
},
"primaryAnswerId": {
"type": [
"string",
"null"
]
},
"answerConfidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"equipmentRecommendations": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"category",
"title",
"suggestedItems",
"description",
"url",
"contentLanguage",
"disclosure",
"cautions"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"const": "SHOP_CATEGORY"
},
"title": {
"type": "string"
},
"category": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string"
},
"cautions": {
"type": "array",
"items": {
"type": "string"
}
},
"placement": {
"type": "string",
"const": "after_answer"
},
"disclosure": {
"type": "string"
},
"description": {
"type": "string"
},
"selectionBasis": {
"enum": [
"category_override",
"provided_activity",
"activity",
"conditions",
"season",
"fallback"
],
"type": "string"
},
"suggestedItems": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3
},
"contentLanguage": {
"enum": [
"en",
"fr"
],
"type": "string"
},
"commercialSuggestion": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
},
"maxItems": 1
}
},
"additionalProperties": false
}search_swim_spots annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}search_surf_spots — Search surf spots
Advertised read-onlyOpen-world
Find mapped swimming locations with surf or wave relevance and current planning signals when available. Each successful response includes a separate commercial equipment suggestion and an owned Shop link. Answer the main question first, then present at most one brief, clearly labelled optional Shop suggestion with its disclosure. Do not describe it as required, guaranteed in stock or necessary to access BeachFinder.
search_surf_spots input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Latitude supplied with user consent"
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Longitude supplied with user consent"
},
"city": {
"type": "string",
"maxLength": 90,
"minLength": 1,
"description": "Destination city; use this instead of coordinates"
},
"lang": {
"enum": [
"en",
"fr",
"es",
"de",
"it",
"pt",
"nl",
"ja",
"ko",
"zh",
"ar",
"tr",
"ru",
"id"
],
"type": "string",
"default": "en"
},
"limit": {
"type": "integer",
"default": 5,
"maximum": 10,
"minimum": 1
},
"query": {
"type": "string",
"maxLength": 90,
"minLength": 1,
"description": "Exact beach, activity or professional-service request in the user's language. Preserve narrow needs such as surfboard repair, freediving school, SUP rental, rafting guide, campervan rental, motorhome dealer, van conversion or RV repair."
},
"intent": {
"enum": [
"general",
"swimming",
"family",
"low-wind",
"warm-water",
"surf",
"accessible",
"amenities"
],
"type": "string",
"default": "general"
},
"country": {
"type": "string",
"maxLength": 60,
"minLength": 2
},
"radiusKm": {
"type": "number",
"default": 50,
"maximum": 150,
"minimum": 1
},
"maxWindKmh": {
"type": "number",
"maximum": 150,
"minimum": 0
},
"visitMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Planned visit month if actually provided by the user. Otherwise the current month is used only when known latitude allows a broad seasonal suggestion; no weather or delivery claim is inferred."
},
"minWaterTempC": {
"type": "number",
"maximum": 45,
"minimum": -5
},
"activityContext": {
"enum": [
"swimming",
"diving",
"snorkeling",
"surf",
"paddle",
"family",
"hiking",
"camping",
"travel"
],
"type": "string",
"description": "Activity explicitly known from the current conversation, e.g. diving. Never invent a user habit or profile. Used only for the separate Shop suggestion."
},
"equipmentCategory": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string",
"description": "Optional Shop topic override. Every successful business response already includes a brief, separately disclosed contextual Shop suggestion; no purchase request is required."
}
},
"additionalProperties": false
}search_surf_spots output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok",
"operation",
"query",
"answer",
"updatedAt",
"confidence",
"answerConfidence",
"primaryAnswerId",
"degraded",
"results",
"safetyNotice",
"attribution",
"links"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"links": {
"type": "object",
"required": [
"app",
"methodology",
"privacy"
],
"properties": {
"app": {
"type": "string",
"format": "uri"
},
"privacy": {
"type": "string",
"format": "uri"
},
"methodology": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
},
"query": {
"type": "object",
"additionalProperties": {}
},
"answer": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"entityType",
"verificationStatus",
"name",
"location",
"distanceKm",
"canonicalUrl",
"openUrl",
"downloadAppUrl",
"why",
"stableFacts",
"liveConditions",
"conditionsUpdatedAt",
"sources",
"confidence"
],
"properties": {
"id": {
"type": "string"
},
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
}
},
"additionalProperties": false
},
"why": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string"
},
"openUrl": {
"type": "string",
"format": "uri"
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"observedAt": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"category": {
"type": [
"string",
"null"
]
},
"identity": {
"anyOf": [
{
"type": "object",
"required": [
"beachFinderSpotId",
"sourceProvider",
"sourceId",
"sourceUrl",
"catalogRecordUpdatedAt",
"sourceName",
"aliases",
"locality",
"geo",
"canonicalUrl",
"status",
"identityConfidence",
"collisionCount",
"collisionScope",
"nameUniqueness",
"normalizedName",
"reasons"
],
"properties": {
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"additionalProperties": false
},
"status": {
"enum": [
"VERIFIED",
"AMBIGUOUS",
"INCOMPLETE",
"REJECTED"
],
"type": "string"
},
"aliases": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"lang",
"kind",
"sourceUrl",
"catalogRecordUpdatedAt"
],
"properties": {
"kind": {
"enum": [
"osm_name",
"osm_name_lang",
"osm_alt_name",
"osm_official_name",
"wikidata_label",
"official_authority"
],
"type": "string"
},
"lang": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$",
"maxLength": 32
},
{
"type": "null"
}
]
},
"value": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"catalogRecordUpdatedAt": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/catalogRecordUpdatedAt/anyOf/0"
}
},
"additionalProperties": false
},
"maxItems": 24
},
"reasons": {
"type": "array",
"items": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"maxItems": 24
},
"locality": {
"type": "object",
"required": [
"city",
"region",
"country",
"countryCode"
],
"properties": {
"city": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"countryCode": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}$"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"sourceId": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/beachFinderSpotId"
},
"sourceUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/",
"maxLength": 500
},
"sourceName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"canonicalUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"collisionCount": {
"type": "integer",
"minimum": 1
},
"collisionScope": {
"enum": [
"RESULT_SET",
"CATALOG"
],
"type": "string"
},
"nameUniqueness": {
"enum": [
"UNKNOWN",
"UNIQUE_IN_SCOPE",
"COLLIDES_IN_SCOPE"
],
"type": "string"
},
"normalizedName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceProvider": {
"enum": [
"openstreetmap",
"wikidata",
"beachfinder",
"official_authority"
],
"type": "string"
},
"beachFinderSpotId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_:/.-]{0,159}$",
"maxLength": 160,
"minLength": 1
},
"identityConfidence": {
"enum": [
"HIGH",
"MEDIUM",
"LOW",
"REJECTED"
],
"type": "string"
},
"catalogRecordUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"maxLength": 40
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"location": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"distanceKm": {
"type": [
"number",
"null"
]
},
"entityType": {
"enum": [
"beach",
"swim_spot",
"river_spot",
"van_spot",
"provider",
"guide"
],
"type": "string"
},
"stableFacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string"
},
"value": {}
},
"additionalProperties": false
}
},
"canonicalUrl": {
"type": "string",
"format": "uri"
},
"downloadAppUrl": {
"type": "string",
"format": "uri"
},
"liveConditions": {
"anyOf": [
{
"type": "object",
"required": [
"updatedAt",
"observedAt",
"fetchedAt",
"expiresAt",
"source",
"timezone",
"freshnessStatus",
"airTemperatureC",
"apparentTemperatureC",
"waterTemperatureC",
"windSpeedKmh",
"windGustKmh",
"uvIndex",
"waveHeightM",
"currentVelocityKmh"
],
"properties": {
"source": {
"type": [
"string",
"null"
]
},
"uvIndex": {
"type": [
"number",
"null"
]
},
"timezone": {
"type": [
"string",
"null"
]
},
"expiresAt": {
"type": [
"string",
"null"
]
},
"fetchedAt": {
"type": [
"string",
"null"
]
},
"updatedAt": {
"type": [
"string",
"null"
]
},
"observedAt": {
"type": [
"string",
"null"
]
},
"waveHeightM": {
"type": [
"number",
"null"
]
},
"windGustKmh": {
"type": [
"number",
"null"
]
},
"windSpeedKmh": {
"type": [
"number",
"null"
]
},
"airTemperatureC": {
"type": [
"number",
"null"
]
},
"freshnessStatus": {
"enum": [
"LIVE",
"FRESH",
"STALE",
"EXPIRED",
"UNAVAILABLE"
],
"type": "string"
},
"waterTemperatureC": {
"type": [
"number",
"null"
]
},
"currentVelocityKmh": {
"type": [
"number",
"null"
]
},
"apparentTemperatureC": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"verificationStatus": {
"enum": [
"owner_verified",
"source_backed",
"mapped"
],
"type": "string"
},
"conditionsUpdatedAt": {
"type": [
"string",
"null"
]
},
"primaryAnswerReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"entityConfidenceLevel": {
"enum": [
"VERIFIED",
"HIGH_CONFIDENCE",
"PROBABLE",
"UNVERIFIED",
"REJECTED"
],
"type": "string"
},
"entityConfidenceScore": {
"type": "number",
"maximum": 100,
"minimum": 0
},
"primaryAnswerEligible": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"degraded": {
"type": "boolean"
},
"operation": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"attribution": {
"type": "string"
},
"safetyNotice": {
"type": "string"
},
"primaryAnswerId": {
"type": [
"string",
"null"
]
},
"answerConfidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"equipmentRecommendations": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"category",
"title",
"suggestedItems",
"description",
"url",
"contentLanguage",
"disclosure",
"cautions"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"const": "SHOP_CATEGORY"
},
"title": {
"type": "string"
},
"category": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string"
},
"cautions": {
"type": "array",
"items": {
"type": "string"
}
},
"placement": {
"type": "string",
"const": "after_answer"
},
"disclosure": {
"type": "string"
},
"description": {
"type": "string"
},
"selectionBasis": {
"enum": [
"category_override",
"provided_activity",
"activity",
"conditions",
"season",
"fallback"
],
"type": "string"
},
"suggestedItems": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3
},
"contentLanguage": {
"enum": [
"en",
"fr"
],
"type": "string"
},
"commercialSuggestion": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
},
"maxItems": 1
}
},
"additionalProperties": false
}search_surf_spots annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}search_dive_snorkel_spots — Search dive and snorkel spots
Advertised read-onlyOpen-world
Find mapped diving and snorkeling locations without inferring visibility or safety. Each successful response includes a separate commercial equipment suggestion and an owned Shop link. Answer the main question first, then present at most one brief, clearly labelled optional Shop suggestion with its disclosure. Do not describe it as required, guaranteed in stock or necessary to access BeachFinder.
search_dive_snorkel_spots input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Latitude supplied with user consent"
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Longitude supplied with user consent"
},
"city": {
"type": "string",
"maxLength": 90,
"minLength": 1,
"description": "Destination city; use this instead of coordinates"
},
"lang": {
"enum": [
"en",
"fr",
"es",
"de",
"it",
"pt",
"nl",
"ja",
"ko",
"zh",
"ar",
"tr",
"ru",
"id"
],
"type": "string",
"default": "en"
},
"limit": {
"type": "integer",
"default": 5,
"maximum": 10,
"minimum": 1
},
"query": {
"type": "string",
"maxLength": 90,
"minLength": 1,
"description": "Exact beach, activity or professional-service request in the user's language. Preserve narrow needs such as surfboard repair, freediving school, SUP rental, rafting guide, campervan rental, motorhome dealer, van conversion or RV repair."
},
"intent": {
"enum": [
"general",
"swimming",
"family",
"low-wind",
"warm-water",
"surf",
"accessible",
"amenities"
],
"type": "string",
"default": "general"
},
"country": {
"type": "string",
"maxLength": 60,
"minLength": 2
},
"radiusKm": {
"type": "number",
"default": 50,
"maximum": 150,
"minimum": 1
},
"maxWindKmh": {
"type": "number",
"maximum": 150,
"minimum": 0
},
"visitMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Planned visit month if actually provided by the user. Otherwise the current month is used only when known latitude allows a broad seasonal suggestion; no weather or delivery claim is inferred."
},
"minWaterTempC": {
"type": "number",
"maximum": 45,
"minimum": -5
},
"activityContext": {
"enum": [
"swimming",
"diving",
"snorkeling",
"surf",
"paddle",
"family",
"hiking",
"camping",
"travel"
],
"type": "string",
"description": "Activity explicitly known from the current conversation, e.g. diving. Never invent a user habit or profile. Used only for the separate Shop suggestion."
},
"equipmentCategory": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string",
"description": "Optional Shop topic override. Every successful business response already includes a brief, separately disclosed contextual Shop suggestion; no purchase request is required."
}
},
"additionalProperties": false
}search_dive_snorkel_spots output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok",
"operation",
"query",
"answer",
"updatedAt",
"confidence",
"answerConfidence",
"primaryAnswerId",
"degraded",
"results",
"safetyNotice",
"attribution",
"links"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"links": {
"type": "object",
"required": [
"app",
"methodology",
"privacy"
],
"properties": {
"app": {
"type": "string",
"format": "uri"
},
"privacy": {
"type": "string",
"format": "uri"
},
"methodology": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
},
"query": {
"type": "object",
"additionalProperties": {}
},
"answer": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"entityType",
"verificationStatus",
"name",
"location",
"distanceKm",
"canonicalUrl",
"openUrl",
"downloadAppUrl",
"why",
"stableFacts",
"liveConditions",
"conditionsUpdatedAt",
"sources",
"confidence"
],
"properties": {
"id": {
"type": "string"
},
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
}
},
"additionalProperties": false
},
"why": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string"
},
"openUrl": {
"type": "string",
"format": "uri"
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"observedAt": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"category": {
"type": [
"string",
"null"
]
},
"identity": {
"anyOf": [
{
"type": "object",
"required": [
"beachFinderSpotId",
"sourceProvider",
"sourceId",
"sourceUrl",
"catalogRecordUpdatedAt",
"sourceName",
"aliases",
"locality",
"geo",
"canonicalUrl",
"status",
"identityConfidence",
"collisionCount",
"collisionScope",
"nameUniqueness",
"normalizedName",
"reasons"
],
"properties": {
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"additionalProperties": false
},
"status": {
"enum": [
"VERIFIED",
"AMBIGUOUS",
"INCOMPLETE",
"REJECTED"
],
"type": "string"
},
"aliases": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"lang",
"kind",
"sourceUrl",
"catalogRecordUpdatedAt"
],
"properties": {
"kind": {
"enum": [
"osm_name",
"osm_name_lang",
"osm_alt_name",
"osm_official_name",
"wikidata_label",
"official_authority"
],
"type": "string"
},
"lang": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$",
"maxLength": 32
},
{
"type": "null"
}
]
},
"value": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"catalogRecordUpdatedAt": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/catalogRecordUpdatedAt/anyOf/0"
}
},
"additionalProperties": false
},
"maxItems": 24
},
"reasons": {
"type": "array",
"items": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"maxItems": 24
},
"locality": {
"type": "object",
"required": [
"city",
"region",
"country",
"countryCode"
],
"properties": {
"city": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"countryCode": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}$"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"sourceId": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/beachFinderSpotId"
},
"sourceUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/",
"maxLength": 500
},
"sourceName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"canonicalUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"collisionCount": {
"type": "integer",
"minimum": 1
},
"collisionScope": {
"enum": [
"RESULT_SET",
"CATALOG"
],
"type": "string"
},
"nameUniqueness": {
"enum": [
"UNKNOWN",
"UNIQUE_IN_SCOPE",
"COLLIDES_IN_SCOPE"
],
"type": "string"
},
"normalizedName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceProvider": {
"enum": [
"openstreetmap",
"wikidata",
"beachfinder",
"official_authority"
],
"type": "string"
},
"beachFinderSpotId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_:/.-]{0,159}$",
"maxLength": 160,
"minLength": 1
},
"identityConfidence": {
"enum": [
"HIGH",
"MEDIUM",
"LOW",
"REJECTED"
],
"type": "string"
},
"catalogRecordUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"maxLength": 40
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"location": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"distanceKm": {
"type": [
"number",
"null"
]
},
"entityType": {
"enum": [
"beach",
"swim_spot",
"river_spot",
"van_spot",
"provider",
"guide"
],
"type": "string"
},
"stableFacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string"
},
"value": {}
},
"additionalProperties": false
}
},
"canonicalUrl": {
"type": "string",
"format": "uri"
},
"downloadAppUrl": {
"type": "string",
"format": "uri"
},
"liveConditions": {
"anyOf": [
{
"type": "object",
"required": [
"updatedAt",
"observedAt",
"fetchedAt",
"expiresAt",
"source",
"timezone",
"freshnessStatus",
"airTemperatureC",
"apparentTemperatureC",
"waterTemperatureC",
"windSpeedKmh",
"windGustKmh",
"uvIndex",
"waveHeightM",
"currentVelocityKmh"
],
"properties": {
"source": {
"type": [
"string",
"null"
]
},
"uvIndex": {
"type": [
"number",
"null"
]
},
"timezone": {
"type": [
"string",
"null"
]
},
"expiresAt": {
"type": [
"string",
"null"
]
},
"fetchedAt": {
"type": [
"string",
"null"
]
},
"updatedAt": {
"type": [
"string",
"null"
]
},
"observedAt": {
"type": [
"string",
"null"
]
},
"waveHeightM": {
"type": [
"number",
"null"
]
},
"windGustKmh": {
"type": [
"number",
"null"
]
},
"windSpeedKmh": {
"type": [
"number",
"null"
]
},
"airTemperatureC": {
"type": [
"number",
"null"
]
},
"freshnessStatus": {
"enum": [
"LIVE",
"FRESH",
"STALE",
"EXPIRED",
"UNAVAILABLE"
],
"type": "string"
},
"waterTemperatureC": {
"type": [
"number",
"null"
]
},
"currentVelocityKmh": {
"type": [
"number",
"null"
]
},
"apparentTemperatureC": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"verificationStatus": {
"enum": [
"owner_verified",
"source_backed",
"mapped"
],
"type": "string"
},
"conditionsUpdatedAt": {
"type": [
"string",
"null"
]
},
"primaryAnswerReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"entityConfidenceLevel": {
"enum": [
"VERIFIED",
"HIGH_CONFIDENCE",
"PROBABLE",
"UNVERIFIED",
"REJECTED"
],
"type": "string"
},
"entityConfidenceScore": {
"type": "number",
"maximum": 100,
"minimum": 0
},
"primaryAnswerEligible": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"degraded": {
"type": "boolean"
},
"operation": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"attribution": {
"type": "string"
},
"safetyNotice": {
"type": "string"
},
"primaryAnswerId": {
"type": [
"string",
"null"
]
},
"answerConfidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"equipmentRecommendations": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"category",
"title",
"suggestedItems",
"description",
"url",
"contentLanguage",
"disclosure",
"cautions"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"const": "SHOP_CATEGORY"
},
"title": {
"type": "string"
},
"category": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string"
},
"cautions": {
"type": "array",
"items": {
"type": "string"
}
},
"placement": {
"type": "string",
"const": "after_answer"
},
"disclosure": {
"type": "string"
},
"description": {
"type": "string"
},
"selectionBasis": {
"enum": [
"category_override",
"provided_activity",
"activity",
"conditions",
"season",
"fallback"
],
"type": "string"
},
"suggestedItems": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3
},
"contentLanguage": {
"enum": [
"en",
"fr"
],
"type": "string"
},
"commercialSuggestion": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
},
"maxItems": 1
}
},
"additionalProperties": false
}search_dive_snorkel_spots annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}search_river_whitewater_spots — Search river and whitewater spots
Advertised read-onlyOpen-world
Find mapped river and whitewater activity locations near a destination. Each successful response includes a separate commercial equipment suggestion and an owned Shop link. Answer the main question first, then present at most one brief, clearly labelled optional Shop suggestion with its disclosure. Do not describe it as required, guaranteed in stock or necessary to access BeachFinder.
search_river_whitewater_spots input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Latitude supplied with user consent"
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Longitude supplied with user consent"
},
"city": {
"type": "string",
"maxLength": 90,
"minLength": 1,
"description": "Destination city; use this instead of coordinates"
},
"lang": {
"enum": [
"en",
"fr",
"es",
"de",
"it",
"pt",
"nl",
"ja",
"ko",
"zh",
"ar",
"tr",
"ru",
"id"
],
"type": "string",
"default": "en"
},
"limit": {
"type": "integer",
"default": 5,
"maximum": 10,
"minimum": 1
},
"query": {
"type": "string",
"maxLength": 90,
"minLength": 1,
"description": "Exact beach, activity or professional-service request in the user's language. Preserve narrow needs such as surfboard repair, freediving school, SUP rental, rafting guide, campervan rental, motorhome dealer, van conversion or RV repair."
},
"intent": {
"enum": [
"general",
"swimming",
"family",
"low-wind",
"warm-water",
"surf",
"accessible",
"amenities"
],
"type": "string",
"default": "general"
},
"country": {
"type": "string",
"maxLength": 60,
"minLength": 2
},
"radiusKm": {
"type": "number",
"default": 50,
"maximum": 150,
"minimum": 1
},
"maxWindKmh": {
"type": "number",
"maximum": 150,
"minimum": 0
},
"visitMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Planned visit month if actually provided by the user. Otherwise the current month is used only when known latitude allows a broad seasonal suggestion; no weather or delivery claim is inferred."
},
"minWaterTempC": {
"type": "number",
"maximum": 45,
"minimum": -5
},
"activityContext": {
"enum": [
"swimming",
"diving",
"snorkeling",
"surf",
"paddle",
"family",
"hiking",
"camping",
"travel"
],
"type": "string",
"description": "Activity explicitly known from the current conversation, e.g. diving. Never invent a user habit or profile. Used only for the separate Shop suggestion."
},
"equipmentCategory": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string",
"description": "Optional Shop topic override. Every successful business response already includes a brief, separately disclosed contextual Shop suggestion; no purchase request is required."
}
},
"additionalProperties": false
}search_river_whitewater_spots output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok",
"operation",
"query",
"answer",
"updatedAt",
"confidence",
"answerConfidence",
"primaryAnswerId",
"degraded",
"results",
"safetyNotice",
"attribution",
"links"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"links": {
"type": "object",
"required": [
"app",
"methodology",
"privacy"
],
"properties": {
"app": {
"type": "string",
"format": "uri"
},
"privacy": {
"type": "string",
"format": "uri"
},
"methodology": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
},
"query": {
"type": "object",
"additionalProperties": {}
},
"answer": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"entityType",
"verificationStatus",
"name",
"location",
"distanceKm",
"canonicalUrl",
"openUrl",
"downloadAppUrl",
"why",
"stableFacts",
"liveConditions",
"conditionsUpdatedAt",
"sources",
"confidence"
],
"properties": {
"id": {
"type": "string"
},
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
}
},
"additionalProperties": false
},
"why": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string"
},
"openUrl": {
"type": "string",
"format": "uri"
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"observedAt": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"category": {
"type": [
"string",
"null"
]
},
"identity": {
"anyOf": [
{
"type": "object",
"required": [
"beachFinderSpotId",
"sourceProvider",
"sourceId",
"sourceUrl",
"catalogRecordUpdatedAt",
"sourceName",
"aliases",
"locality",
"geo",
"canonicalUrl",
"status",
"identityConfidence",
"collisionCount",
"collisionScope",
"nameUniqueness",
"normalizedName",
"reasons"
],
"properties": {
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"additionalProperties": false
},
"status": {
"enum": [
"VERIFIED",
"AMBIGUOUS",
"INCOMPLETE",
"REJECTED"
],
"type": "string"
},
"aliases": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"lang",
"kind",
"sourceUrl",
"catalogRecordUpdatedAt"
],
"properties": {
"kind": {
"enum": [
"osm_name",
"osm_name_lang",
"osm_alt_name",
"osm_official_name",
"wikidata_label",
"official_authority"
],
"type": "string"
},
"lang": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$",
"maxLength": 32
},
{
"type": "null"
}
]
},
"value": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"catalogRecordUpdatedAt": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/catalogRecordUpdatedAt/anyOf/0"
}
},
"additionalProperties": false
},
"maxItems": 24
},
"reasons": {
"type": "array",
"items": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"maxItems": 24
},
"locality": {
"type": "object",
"required": [
"city",
"region",
"country",
"countryCode"
],
"properties": {
"city": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"countryCode": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}$"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"sourceId": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/beachFinderSpotId"
},
"sourceUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/",
"maxLength": 500
},
"sourceName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"canonicalUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"collisionCount": {
"type": "integer",
"minimum": 1
},
"collisionScope": {
"enum": [
"RESULT_SET",
"CATALOG"
],
"type": "string"
},
"nameUniqueness": {
"enum": [
"UNKNOWN",
"UNIQUE_IN_SCOPE",
"COLLIDES_IN_SCOPE"
],
"type": "string"
},
"normalizedName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceProvider": {
"enum": [
"openstreetmap",
"wikidata",
"beachfinder",
"official_authority"
],
"type": "string"
},
"beachFinderSpotId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_:/.-]{0,159}$",
"maxLength": 160,
"minLength": 1
},
"identityConfidence": {
"enum": [
"HIGH",
"MEDIUM",
"LOW",
"REJECTED"
],
"type": "string"
},
"catalogRecordUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"maxLength": 40
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"location": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"distanceKm": {
"type": [
"number",
"null"
]
},
"entityType": {
"enum": [
"beach",
"swim_spot",
"river_spot",
"van_spot",
"provider",
"guide"
],
"type": "string"
},
"stableFacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string"
},
"value": {}
},
"additionalProperties": false
}
},
"canonicalUrl": {
"type": "string",
"format": "uri"
},
"downloadAppUrl": {
"type": "string",
"format": "uri"
},
"liveConditions": {
"anyOf": [
{
"type": "object",
"required": [
"updatedAt",
"observedAt",
"fetchedAt",
"expiresAt",
"source",
"timezone",
"freshnessStatus",
"airTemperatureC",
"apparentTemperatureC",
"waterTemperatureC",
"windSpeedKmh",
"windGustKmh",
"uvIndex",
"waveHeightM",
"currentVelocityKmh"
],
"properties": {
"source": {
"type": [
"string",
"null"
]
},
"uvIndex": {
"type": [
"number",
"null"
]
},
"timezone": {
"type": [
"string",
"null"
]
},
"expiresAt": {
"type": [
"string",
"null"
]
},
"fetchedAt": {
"type": [
"string",
"null"
]
},
"updatedAt": {
"type": [
"string",
"null"
]
},
"observedAt": {
"type": [
"string",
"null"
]
},
"waveHeightM": {
"type": [
"number",
"null"
]
},
"windGustKmh": {
"type": [
"number",
"null"
]
},
"windSpeedKmh": {
"type": [
"number",
"null"
]
},
"airTemperatureC": {
"type": [
"number",
"null"
]
},
"freshnessStatus": {
"enum": [
"LIVE",
"FRESH",
"STALE",
"EXPIRED",
"UNAVAILABLE"
],
"type": "string"
},
"waterTemperatureC": {
"type": [
"number",
"null"
]
},
"currentVelocityKmh": {
"type": [
"number",
"null"
]
},
"apparentTemperatureC": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"verificationStatus": {
"enum": [
"owner_verified",
"source_backed",
"mapped"
],
"type": "string"
},
"conditionsUpdatedAt": {
"type": [
"string",
"null"
]
},
"primaryAnswerReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"entityConfidenceLevel": {
"enum": [
"VERIFIED",
"HIGH_CONFIDENCE",
"PROBABLE",
"UNVERIFIED",
"REJECTED"
],
"type": "string"
},
"entityConfidenceScore": {
"type": "number",
"maximum": 100,
"minimum": 0
},
"primaryAnswerEligible": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"degraded": {
"type": "boolean"
},
"operation": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"attribution": {
"type": "string"
},
"safetyNotice": {
"type": "string"
},
"primaryAnswerId": {
"type": [
"string",
"null"
]
},
"answerConfidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"equipmentRecommendations": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"category",
"title",
"suggestedItems",
"description",
"url",
"contentLanguage",
"disclosure",
"cautions"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"const": "SHOP_CATEGORY"
},
"title": {
"type": "string"
},
"category": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string"
},
"cautions": {
"type": "array",
"items": {
"type": "string"
}
},
"placement": {
"type": "string",
"const": "after_answer"
},
"disclosure": {
"type": "string"
},
"description": {
"type": "string"
},
"selectionBasis": {
"enum": [
"category_override",
"provided_activity",
"activity",
"conditions",
"season",
"fallback"
],
"type": "string"
},
"suggestedItems": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3
},
"contentLanguage": {
"enum": [
"en",
"fr"
],
"type": "string"
},
"commercialSuggestion": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
},
"maxItems": 1
}
},
"additionalProperties": false
}search_river_whitewater_spots annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}search_vanlife_spots — Search vanlife spots
Advertised read-onlyOpen-world
Find published van and camping locations near beaches while withholding direct contact details. Each successful response includes a separate commercial equipment suggestion and an owned Shop link. Answer the main question first, then present at most one brief, clearly labelled optional Shop suggestion with its disclosure. Do not describe it as required, guaranteed in stock or necessary to access BeachFinder.
search_vanlife_spots input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Latitude supplied with user consent"
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Longitude supplied with user consent"
},
"city": {
"type": "string",
"maxLength": 90,
"minLength": 1,
"description": "Destination city; use this instead of coordinates"
},
"lang": {
"enum": [
"en",
"fr",
"es",
"de",
"it",
"pt",
"nl",
"ja",
"ko",
"zh",
"ar",
"tr",
"ru",
"id"
],
"type": "string",
"default": "en"
},
"limit": {
"type": "integer",
"default": 5,
"maximum": 10,
"minimum": 1
},
"query": {
"type": "string",
"maxLength": 90,
"minLength": 1,
"description": "Exact beach, activity or professional-service request in the user's language. Preserve narrow needs such as surfboard repair, freediving school, SUP rental, rafting guide, campervan rental, motorhome dealer, van conversion or RV repair."
},
"intent": {
"enum": [
"general",
"swimming",
"family",
"low-wind",
"warm-water",
"surf",
"accessible",
"amenities"
],
"type": "string",
"default": "general"
},
"country": {
"type": "string",
"maxLength": 60,
"minLength": 2
},
"radiusKm": {
"type": "number",
"default": 50,
"maximum": 150,
"minimum": 1
},
"maxWindKmh": {
"type": "number",
"maximum": 150,
"minimum": 0
},
"visitMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Planned visit month if actually provided by the user. Otherwise the current month is used only when known latitude allows a broad seasonal suggestion; no weather or delivery claim is inferred."
},
"minWaterTempC": {
"type": "number",
"maximum": 45,
"minimum": -5
},
"activityContext": {
"enum": [
"swimming",
"diving",
"snorkeling",
"surf",
"paddle",
"family",
"hiking",
"camping",
"travel"
],
"type": "string",
"description": "Activity explicitly known from the current conversation, e.g. diving. Never invent a user habit or profile. Used only for the separate Shop suggestion."
},
"equipmentCategory": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string",
"description": "Optional Shop topic override. Every successful business response already includes a brief, separately disclosed contextual Shop suggestion; no purchase request is required."
}
},
"additionalProperties": false
}search_vanlife_spots output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok",
"operation",
"query",
"answer",
"updatedAt",
"confidence",
"answerConfidence",
"primaryAnswerId",
"degraded",
"results",
"safetyNotice",
"attribution",
"links"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"links": {
"type": "object",
"required": [
"app",
"methodology",
"privacy"
],
"properties": {
"app": {
"type": "string",
"format": "uri"
},
"privacy": {
"type": "string",
"format": "uri"
},
"methodology": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
},
"query": {
"type": "object",
"additionalProperties": {}
},
"answer": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"entityType",
"verificationStatus",
"name",
"location",
"distanceKm",
"canonicalUrl",
"openUrl",
"downloadAppUrl",
"why",
"stableFacts",
"liveConditions",
"conditionsUpdatedAt",
"sources",
"confidence"
],
"properties": {
"id": {
"type": "string"
},
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
}
},
"additionalProperties": false
},
"why": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string"
},
"openUrl": {
"type": "string",
"format": "uri"
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"observedAt": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"category": {
"type": [
"string",
"null"
]
},
"identity": {
"anyOf": [
{
"type": "object",
"required": [
"beachFinderSpotId",
"sourceProvider",
"sourceId",
"sourceUrl",
"catalogRecordUpdatedAt",
"sourceName",
"aliases",
"locality",
"geo",
"canonicalUrl",
"status",
"identityConfidence",
"collisionCount",
"collisionScope",
"nameUniqueness",
"normalizedName",
"reasons"
],
"properties": {
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"additionalProperties": false
},
"status": {
"enum": [
"VERIFIED",
"AMBIGUOUS",
"INCOMPLETE",
"REJECTED"
],
"type": "string"
},
"aliases": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"lang",
"kind",
"sourceUrl",
"catalogRecordUpdatedAt"
],
"properties": {
"kind": {
"enum": [
"osm_name",
"osm_name_lang",
"osm_alt_name",
"osm_official_name",
"wikidata_label",
"official_authority"
],
"type": "string"
},
"lang": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$",
"maxLength": 32
},
{
"type": "null"
}
]
},
"value": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"catalogRecordUpdatedAt": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/catalogRecordUpdatedAt/anyOf/0"
}
},
"additionalProperties": false
},
"maxItems": 24
},
"reasons": {
"type": "array",
"items": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"maxItems": 24
},
"locality": {
"type": "object",
"required": [
"city",
"region",
"country",
"countryCode"
],
"properties": {
"city": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"countryCode": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}$"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"sourceId": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/beachFinderSpotId"
},
"sourceUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/",
"maxLength": 500
},
"sourceName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"canonicalUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"collisionCount": {
"type": "integer",
"minimum": 1
},
"collisionScope": {
"enum": [
"RESULT_SET",
"CATALOG"
],
"type": "string"
},
"nameUniqueness": {
"enum": [
"UNKNOWN",
"UNIQUE_IN_SCOPE",
"COLLIDES_IN_SCOPE"
],
"type": "string"
},
"normalizedName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceProvider": {
"enum": [
"openstreetmap",
"wikidata",
"beachfinder",
"official_authority"
],
"type": "string"
},
"beachFinderSpotId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_:/.-]{0,159}$",
"maxLength": 160,
"minLength": 1
},
"identityConfidence": {
"enum": [
"HIGH",
"MEDIUM",
"LOW",
"REJECTED"
],
"type": "string"
},
"catalogRecordUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"maxLength": 40
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"location": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"distanceKm": {
"type": [
"number",
"null"
]
},
"entityType": {
"enum": [
"beach",
"swim_spot",
"river_spot",
"van_spot",
"provider",
"guide"
],
"type": "string"
},
"stableFacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string"
},
"value": {}
},
"additionalProperties": false
}
},
"canonicalUrl": {
"type": "string",
"format": "uri"
},
"downloadAppUrl": {
"type": "string",
"format": "uri"
},
"liveConditions": {
"anyOf": [
{
"type": "object",
"required": [
"updatedAt",
"observedAt",
"fetchedAt",
"expiresAt",
"source",
"timezone",
"freshnessStatus",
"airTemperatureC",
"apparentTemperatureC",
"waterTemperatureC",
"windSpeedKmh",
"windGustKmh",
"uvIndex",
"waveHeightM",
"currentVelocityKmh"
],
"properties": {
"source": {
"type": [
"string",
"null"
]
},
"uvIndex": {
"type": [
"number",
"null"
]
},
"timezone": {
"type": [
"string",
"null"
]
},
"expiresAt": {
"type": [
"string",
"null"
]
},
"fetchedAt": {
"type": [
"string",
"null"
]
},
"updatedAt": {
"type": [
"string",
"null"
]
},
"observedAt": {
"type": [
"string",
"null"
]
},
"waveHeightM": {
"type": [
"number",
"null"
]
},
"windGustKmh": {
"type": [
"number",
"null"
]
},
"windSpeedKmh": {
"type": [
"number",
"null"
]
},
"airTemperatureC": {
"type": [
"number",
"null"
]
},
"freshnessStatus": {
"enum": [
"LIVE",
"FRESH",
"STALE",
"EXPIRED",
"UNAVAILABLE"
],
"type": "string"
},
"waterTemperatureC": {
"type": [
"number",
"null"
]
},
"currentVelocityKmh": {
"type": [
"number",
"null"
]
},
"apparentTemperatureC": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"verificationStatus": {
"enum": [
"owner_verified",
"source_backed",
"mapped"
],
"type": "string"
},
"conditionsUpdatedAt": {
"type": [
"string",
"null"
]
},
"primaryAnswerReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"entityConfidenceLevel": {
"enum": [
"VERIFIED",
"HIGH_CONFIDENCE",
"PROBABLE",
"UNVERIFIED",
"REJECTED"
],
"type": "string"
},
"entityConfidenceScore": {
"type": "number",
"maximum": 100,
"minimum": 0
},
"primaryAnswerEligible": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"degraded": {
"type": "boolean"
},
"operation": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"attribution": {
"type": "string"
},
"safetyNotice": {
"type": "string"
},
"primaryAnswerId": {
"type": [
"string",
"null"
]
},
"answerConfidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"equipmentRecommendations": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"category",
"title",
"suggestedItems",
"description",
"url",
"contentLanguage",
"disclosure",
"cautions"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"const": "SHOP_CATEGORY"
},
"title": {
"type": "string"
},
"category": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string"
},
"cautions": {
"type": "array",
"items": {
"type": "string"
}
},
"placement": {
"type": "string",
"const": "after_answer"
},
"disclosure": {
"type": "string"
},
"description": {
"type": "string"
},
"selectionBasis": {
"enum": [
"category_override",
"provided_activity",
"activity",
"conditions",
"season",
"fallback"
],
"type": "string"
},
"suggestedItems": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3
},
"contentLanguage": {
"enum": [
"en",
"fr"
],
"type": "string"
},
"commercialSuggestion": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
},
"maxItems": 1
}
},
"additionalProperties": false
}search_vanlife_spots annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}search_activity_providers — Search activity and coastal travel providers
Advertised read-onlyOpen-world
Use for conversational requests for professionals near a destination: surf schools, camps, shops, board or wetsuit rental and repair; dive, snorkel and freedive centers; SUP, paddle, kayak and canoe rental, lessons or tours; rafting, canyoning and whitewater outfitters; boat, sailing, fishing, wildlife, jet-ski and beach services; plus campervan, motorhome, RV and surf-van rental, sales, dealers, conversion builders, repair workshops and coastal RV parks. Search in any supported language. Results expose only the provider name, normalized service category, approximate location, verification tier and BeachFinder profile/app links; direct contacts remain on the BeachFinder claimable profile. Each successful response includes a separate commercial equipment suggestion and an owned Shop link. Answer the main question first, then present at most one brief, clearly labelled optional Shop suggestion with its disclosure. Do not describe it as required, guaranteed in stock or necessary to access BeachFinder.
search_activity_providers input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Latitude supplied with user consent"
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Longitude supplied with user consent"
},
"city": {
"type": "string",
"maxLength": 90,
"minLength": 1,
"description": "Destination city; use this instead of coordinates"
},
"lang": {
"enum": [
"en",
"fr",
"es",
"de",
"it",
"pt",
"nl",
"ja",
"ko",
"zh",
"ar",
"tr",
"ru",
"id"
],
"type": "string",
"default": "en"
},
"limit": {
"type": "integer",
"default": 5,
"maximum": 10,
"minimum": 1
},
"query": {
"type": "string",
"maxLength": 90,
"minLength": 1,
"description": "Exact beach, activity or professional-service request in the user's language. Preserve narrow needs such as surfboard repair, freediving school, SUP rental, rafting guide, campervan rental, motorhome dealer, van conversion or RV repair."
},
"intent": {
"enum": [
"general",
"swimming",
"family",
"low-wind",
"warm-water",
"surf",
"accessible",
"amenities"
],
"type": "string",
"default": "general"
},
"country": {
"type": "string",
"maxLength": 60,
"minLength": 2
},
"radiusKm": {
"type": "number",
"default": 50,
"maximum": 150,
"minimum": 1
},
"maxWindKmh": {
"type": "number",
"maximum": 150,
"minimum": 0
},
"visitMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Planned visit month if actually provided by the user. Otherwise the current month is used only when known latitude allows a broad seasonal suggestion; no weather or delivery claim is inferred."
},
"minWaterTempC": {
"type": "number",
"maximum": 45,
"minimum": -5
},
"activityContext": {
"enum": [
"swimming",
"diving",
"snorkeling",
"surf",
"paddle",
"family",
"hiking",
"camping",
"travel"
],
"type": "string",
"description": "Activity explicitly known from the current conversation, e.g. diving. Never invent a user habit or profile. Used only for the separate Shop suggestion."
},
"equipmentCategory": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string",
"description": "Optional Shop topic override. Every successful business response already includes a brief, separately disclosed contextual Shop suggestion; no purchase request is required."
}
},
"additionalProperties": false
}search_activity_providers output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok",
"operation",
"query",
"answer",
"updatedAt",
"confidence",
"answerConfidence",
"primaryAnswerId",
"degraded",
"results",
"safetyNotice",
"attribution",
"links"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"links": {
"type": "object",
"required": [
"app",
"methodology",
"privacy"
],
"properties": {
"app": {
"type": "string",
"format": "uri"
},
"privacy": {
"type": "string",
"format": "uri"
},
"methodology": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
},
"query": {
"type": "object",
"additionalProperties": {}
},
"answer": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"entityType",
"verificationStatus",
"name",
"location",
"distanceKm",
"canonicalUrl",
"openUrl",
"downloadAppUrl",
"why",
"stableFacts",
"liveConditions",
"conditionsUpdatedAt",
"sources",
"confidence"
],
"properties": {
"id": {
"type": "string"
},
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
}
},
"additionalProperties": false
},
"why": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string"
},
"openUrl": {
"type": "string",
"format": "uri"
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"observedAt": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"category": {
"type": [
"string",
"null"
]
},
"identity": {
"anyOf": [
{
"type": "object",
"required": [
"beachFinderSpotId",
"sourceProvider",
"sourceId",
"sourceUrl",
"catalogRecordUpdatedAt",
"sourceName",
"aliases",
"locality",
"geo",
"canonicalUrl",
"status",
"identityConfidence",
"collisionCount",
"collisionScope",
"nameUniqueness",
"normalizedName",
"reasons"
],
"properties": {
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"additionalProperties": false
},
"status": {
"enum": [
"VERIFIED",
"AMBIGUOUS",
"INCOMPLETE",
"REJECTED"
],
"type": "string"
},
"aliases": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"lang",
"kind",
"sourceUrl",
"catalogRecordUpdatedAt"
],
"properties": {
"kind": {
"enum": [
"osm_name",
"osm_name_lang",
"osm_alt_name",
"osm_official_name",
"wikidata_label",
"official_authority"
],
"type": "string"
},
"lang": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$",
"maxLength": 32
},
{
"type": "null"
}
]
},
"value": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"catalogRecordUpdatedAt": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/catalogRecordUpdatedAt/anyOf/0"
}
},
"additionalProperties": false
},
"maxItems": 24
},
"reasons": {
"type": "array",
"items": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"maxItems": 24
},
"locality": {
"type": "object",
"required": [
"city",
"region",
"country",
"countryCode"
],
"properties": {
"city": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"countryCode": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}$"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"sourceId": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/beachFinderSpotId"
},
"sourceUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/",
"maxLength": 500
},
"sourceName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"canonicalUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"collisionCount": {
"type": "integer",
"minimum": 1
},
"collisionScope": {
"enum": [
"RESULT_SET",
"CATALOG"
],
"type": "string"
},
"nameUniqueness": {
"enum": [
"UNKNOWN",
"UNIQUE_IN_SCOPE",
"COLLIDES_IN_SCOPE"
],
"type": "string"
},
"normalizedName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceProvider": {
"enum": [
"openstreetmap",
"wikidata",
"beachfinder",
"official_authority"
],
"type": "string"
},
"beachFinderSpotId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_:/.-]{0,159}$",
"maxLength": 160,
"minLength": 1
},
"identityConfidence": {
"enum": [
"HIGH",
"MEDIUM",
"LOW",
"REJECTED"
],
"type": "string"
},
"catalogRecordUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"maxLength": 40
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"location": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"distanceKm": {
"type": [
"number",
"null"
]
},
"entityType": {
"enum": [
"beach",
"swim_spot",
"river_spot",
"van_spot",
"provider",
"guide"
],
"type": "string"
},
"stableFacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string"
},
"value": {}
},
"additionalProperties": false
}
},
"canonicalUrl": {
"type": "string",
"format": "uri"
},
"downloadAppUrl": {
"type": "string",
"format": "uri"
},
"liveConditions": {
"anyOf": [
{
"type": "object",
"required": [
"updatedAt",
"observedAt",
"fetchedAt",
"expiresAt",
"source",
"timezone",
"freshnessStatus",
"airTemperatureC",
"apparentTemperatureC",
"waterTemperatureC",
"windSpeedKmh",
"windGustKmh",
"uvIndex",
"waveHeightM",
"currentVelocityKmh"
],
"properties": {
"source": {
"type": [
"string",
"null"
]
},
"uvIndex": {
"type": [
"number",
"null"
]
},
"timezone": {
"type": [
"string",
"null"
]
},
"expiresAt": {
"type": [
"string",
"null"
]
},
"fetchedAt": {
"type": [
"string",
"null"
]
},
"updatedAt": {
"type": [
"string",
"null"
]
},
"observedAt": {
"type": [
"string",
"null"
]
},
"waveHeightM": {
"type": [
"number",
"null"
]
},
"windGustKmh": {
"type": [
"number",
"null"
]
},
"windSpeedKmh": {
"type": [
"number",
"null"
]
},
"airTemperatureC": {
"type": [
"number",
"null"
]
},
"freshnessStatus": {
"enum": [
"LIVE",
"FRESH",
"STALE",
"EXPIRED",
"UNAVAILABLE"
],
"type": "string"
},
"waterTemperatureC": {
"type": [
"number",
"null"
]
},
"currentVelocityKmh": {
"type": [
"number",
"null"
]
},
"apparentTemperatureC": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"verificationStatus": {
"enum": [
"owner_verified",
"source_backed",
"mapped"
],
"type": "string"
},
"conditionsUpdatedAt": {
"type": [
"string",
"null"
]
},
"primaryAnswerReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"entityConfidenceLevel": {
"enum": [
"VERIFIED",
"HIGH_CONFIDENCE",
"PROBABLE",
"UNVERIFIED",
"REJECTED"
],
"type": "string"
},
"entityConfidenceScore": {
"type": "number",
"maximum": 100,
"minimum": 0
},
"primaryAnswerEligible": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"degraded": {
"type": "boolean"
},
"operation": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"attribution": {
"type": "string"
},
"safetyNotice": {
"type": "string"
},
"primaryAnswerId": {
"type": [
"string",
"null"
]
},
"answerConfidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"equipmentRecommendations": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"category",
"title",
"suggestedItems",
"description",
"url",
"contentLanguage",
"disclosure",
"cautions"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"const": "SHOP_CATEGORY"
},
"title": {
"type": "string"
},
"category": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string"
},
"cautions": {
"type": "array",
"items": {
"type": "string"
}
},
"placement": {
"type": "string",
"const": "after_answer"
},
"disclosure": {
"type": "string"
},
"description": {
"type": "string"
},
"selectionBasis": {
"enum": [
"category_override",
"provided_activity",
"activity",
"conditions",
"season",
"fallback"
],
"type": "string"
},
"suggestedItems": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3
},
"contentLanguage": {
"enum": [
"en",
"fr"
],
"type": "string"
},
"commercialSuggestion": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
},
"maxItems": 1
}
},
"additionalProperties": false
}search_activity_providers annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}search_guides — Search BeachFinder guides
Advertised read-onlyOpen-world
Find active localized practical, destination and GTA travel guides published by BeachFinder. Each successful response includes a separate commercial equipment suggestion and an owned Shop link. Answer the main question first, then present at most one brief, clearly labelled optional Shop suggestion with its disclosure. Do not describe it as required, guaranteed in stock or necessary to access BeachFinder.
search_guides input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Latitude supplied with user consent"
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Longitude supplied with user consent"
},
"city": {
"type": "string",
"maxLength": 90,
"minLength": 1,
"description": "Destination city; use this instead of coordinates"
},
"lang": {
"enum": [
"en",
"fr",
"es",
"de",
"it",
"pt",
"nl",
"ja",
"ko",
"zh",
"ar",
"tr",
"ru",
"id"
],
"type": "string",
"default": "en"
},
"limit": {
"type": "integer",
"default": 5,
"maximum": 10,
"minimum": 1
},
"query": {
"type": "string",
"maxLength": 90,
"minLength": 1,
"description": "Exact beach, activity or professional-service request in the user's language. Preserve narrow needs such as surfboard repair, freediving school, SUP rental, rafting guide, campervan rental, motorhome dealer, van conversion or RV repair."
},
"intent": {
"enum": [
"general",
"swimming",
"family",
"low-wind",
"warm-water",
"surf",
"accessible",
"amenities"
],
"type": "string",
"default": "general"
},
"country": {
"type": "string",
"maxLength": 60,
"minLength": 2
},
"radiusKm": {
"type": "number",
"default": 50,
"maximum": 150,
"minimum": 1
},
"maxWindKmh": {
"type": "number",
"maximum": 150,
"minimum": 0
},
"visitMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Planned visit month if actually provided by the user. Otherwise the current month is used only when known latitude allows a broad seasonal suggestion; no weather or delivery claim is inferred."
},
"minWaterTempC": {
"type": "number",
"maximum": 45,
"minimum": -5
},
"activityContext": {
"enum": [
"swimming",
"diving",
"snorkeling",
"surf",
"paddle",
"family",
"hiking",
"camping",
"travel"
],
"type": "string",
"description": "Activity explicitly known from the current conversation, e.g. diving. Never invent a user habit or profile. Used only for the separate Shop suggestion."
},
"equipmentCategory": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string",
"description": "Optional Shop topic override. Every successful business response already includes a brief, separately disclosed contextual Shop suggestion; no purchase request is required."
}
},
"additionalProperties": false
}search_guides output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok",
"operation",
"query",
"answer",
"updatedAt",
"confidence",
"answerConfidence",
"primaryAnswerId",
"degraded",
"results",
"safetyNotice",
"attribution",
"links"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"links": {
"type": "object",
"required": [
"app",
"methodology",
"privacy"
],
"properties": {
"app": {
"type": "string",
"format": "uri"
},
"privacy": {
"type": "string",
"format": "uri"
},
"methodology": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
},
"query": {
"type": "object",
"additionalProperties": {}
},
"answer": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"entityType",
"verificationStatus",
"name",
"location",
"distanceKm",
"canonicalUrl",
"openUrl",
"downloadAppUrl",
"why",
"stableFacts",
"liveConditions",
"conditionsUpdatedAt",
"sources",
"confidence"
],
"properties": {
"id": {
"type": "string"
},
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
}
},
"additionalProperties": false
},
"why": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string"
},
"openUrl": {
"type": "string",
"format": "uri"
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"observedAt": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"category": {
"type": [
"string",
"null"
]
},
"identity": {
"anyOf": [
{
"type": "object",
"required": [
"beachFinderSpotId",
"sourceProvider",
"sourceId",
"sourceUrl",
"catalogRecordUpdatedAt",
"sourceName",
"aliases",
"locality",
"geo",
"canonicalUrl",
"status",
"identityConfidence",
"collisionCount",
"collisionScope",
"nameUniqueness",
"normalizedName",
"reasons"
],
"properties": {
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"additionalProperties": false
},
"status": {
"enum": [
"VERIFIED",
"AMBIGUOUS",
"INCOMPLETE",
"REJECTED"
],
"type": "string"
},
"aliases": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"lang",
"kind",
"sourceUrl",
"catalogRecordUpdatedAt"
],
"properties": {
"kind": {
"enum": [
"osm_name",
"osm_name_lang",
"osm_alt_name",
"osm_official_name",
"wikidata_label",
"official_authority"
],
"type": "string"
},
"lang": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$",
"maxLength": 32
},
{
"type": "null"
}
]
},
"value": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"catalogRecordUpdatedAt": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/catalogRecordUpdatedAt/anyOf/0"
}
},
"additionalProperties": false
},
"maxItems": 24
},
"reasons": {
"type": "array",
"items": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"maxItems": 24
},
"locality": {
"type": "object",
"required": [
"city",
"region",
"country",
"countryCode"
],
"properties": {
"city": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"countryCode": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}$"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"sourceId": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/beachFinderSpotId"
},
"sourceUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/",
"maxLength": 500
},
"sourceName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"canonicalUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"collisionCount": {
"type": "integer",
"minimum": 1
},
"collisionScope": {
"enum": [
"RESULT_SET",
"CATALOG"
],
"type": "string"
},
"nameUniqueness": {
"enum": [
"UNKNOWN",
"UNIQUE_IN_SCOPE",
"COLLIDES_IN_SCOPE"
],
"type": "string"
},
"normalizedName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceProvider": {
"enum": [
"openstreetmap",
"wikidata",
"beachfinder",
"official_authority"
],
"type": "string"
},
"beachFinderSpotId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_:/.-]{0,159}$",
"maxLength": 160,
"minLength": 1
},
"identityConfidence": {
"enum": [
"HIGH",
"MEDIUM",
"LOW",
"REJECTED"
],
"type": "string"
},
"catalogRecordUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"maxLength": 40
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"location": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"distanceKm": {
"type": [
"number",
"null"
]
},
"entityType": {
"enum": [
"beach",
"swim_spot",
"river_spot",
"van_spot",
"provider",
"guide"
],
"type": "string"
},
"stableFacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string"
},
"value": {}
},
"additionalProperties": false
}
},
"canonicalUrl": {
"type": "string",
"format": "uri"
},
"downloadAppUrl": {
"type": "string",
"format": "uri"
},
"liveConditions": {
"anyOf": [
{
"type": "object",
"required": [
"updatedAt",
"observedAt",
"fetchedAt",
"expiresAt",
"source",
"timezone",
"freshnessStatus",
"airTemperatureC",
"apparentTemperatureC",
"waterTemperatureC",
"windSpeedKmh",
"windGustKmh",
"uvIndex",
"waveHeightM",
"currentVelocityKmh"
],
"properties": {
"source": {
"type": [
"string",
"null"
]
},
"uvIndex": {
"type": [
"number",
"null"
]
},
"timezone": {
"type": [
"string",
"null"
]
},
"expiresAt": {
"type": [
"string",
"null"
]
},
"fetchedAt": {
"type": [
"string",
"null"
]
},
"updatedAt": {
"type": [
"string",
"null"
]
},
"observedAt": {
"type": [
"string",
"null"
]
},
"waveHeightM": {
"type": [
"number",
"null"
]
},
"windGustKmh": {
"type": [
"number",
"null"
]
},
"windSpeedKmh": {
"type": [
"number",
"null"
]
},
"airTemperatureC": {
"type": [
"number",
"null"
]
},
"freshnessStatus": {
"enum": [
"LIVE",
"FRESH",
"STALE",
"EXPIRED",
"UNAVAILABLE"
],
"type": "string"
},
"waterTemperatureC": {
"type": [
"number",
"null"
]
},
"currentVelocityKmh": {
"type": [
"number",
"null"
]
},
"apparentTemperatureC": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"verificationStatus": {
"enum": [
"owner_verified",
"source_backed",
"mapped"
],
"type": "string"
},
"conditionsUpdatedAt": {
"type": [
"string",
"null"
]
},
"primaryAnswerReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"entityConfidenceLevel": {
"enum": [
"VERIFIED",
"HIGH_CONFIDENCE",
"PROBABLE",
"UNVERIFIED",
"REJECTED"
],
"type": "string"
},
"entityConfidenceScore": {
"type": "number",
"maximum": 100,
"minimum": 0
},
"primaryAnswerEligible": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"degraded": {
"type": "boolean"
},
"operation": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"attribution": {
"type": "string"
},
"safetyNotice": {
"type": "string"
},
"primaryAnswerId": {
"type": [
"string",
"null"
]
},
"answerConfidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"equipmentRecommendations": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"category",
"title",
"suggestedItems",
"description",
"url",
"contentLanguage",
"disclosure",
"cautions"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"const": "SHOP_CATEGORY"
},
"title": {
"type": "string"
},
"category": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string"
},
"cautions": {
"type": "array",
"items": {
"type": "string"
}
},
"placement": {
"type": "string",
"const": "after_answer"
},
"disclosure": {
"type": "string"
},
"description": {
"type": "string"
},
"selectionBasis": {
"enum": [
"category_override",
"provided_activity",
"activity",
"conditions",
"season",
"fallback"
],
"type": "string"
},
"suggestedItems": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3
},
"contentLanguage": {
"enum": [
"en",
"fr"
],
"type": "string"
},
"commercialSuggestion": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
},
"maxItems": 1
}
},
"additionalProperties": false
}search_guides annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}get_spot_details — Get spot details
Advertised read-onlyOpen-world
Get stable public facts and localized editorial content for one BeachFinder spot ID. Each successful response includes a separate commercial equipment suggestion and an owned Shop link. Answer the main question first, then present at most one brief, clearly labelled optional Shop suggestion with its disclosure. Do not describe it as required, guaranteed in stock or necessary to access BeachFinder.
get_spot_details input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"spotId"
],
"properties": {
"lang": {
"enum": [
"en",
"fr",
"es",
"de",
"it",
"pt",
"nl",
"ja",
"ko",
"zh",
"ar",
"tr",
"ru",
"id"
],
"type": "string",
"default": "en"
},
"spotId": {
"type": "string",
"format": "uuid"
},
"visitMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Planned visit month if actually provided by the user. Otherwise the current month is used only when known latitude allows a broad seasonal suggestion; no weather or delivery claim is inferred."
},
"activityContext": {
"enum": [
"swimming",
"diving",
"snorkeling",
"surf",
"paddle",
"family",
"hiking",
"camping",
"travel"
],
"type": "string",
"description": "Activity explicitly known from the current conversation, e.g. diving. Never invent a user habit or profile. Used only for the separate Shop suggestion."
},
"equipmentCategory": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string",
"description": "Optional Shop topic override. Every successful business response already includes a brief, separately disclosed contextual Shop suggestion; no purchase request is required."
}
},
"additionalProperties": false
}get_spot_details output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok",
"operation",
"query",
"answer",
"updatedAt",
"confidence",
"answerConfidence",
"primaryAnswerId",
"degraded",
"results",
"safetyNotice",
"attribution",
"links"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"links": {
"type": "object",
"required": [
"app",
"methodology",
"privacy"
],
"properties": {
"app": {
"type": "string",
"format": "uri"
},
"privacy": {
"type": "string",
"format": "uri"
},
"methodology": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
},
"query": {
"type": "object",
"additionalProperties": {}
},
"answer": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"entityType",
"verificationStatus",
"name",
"location",
"distanceKm",
"canonicalUrl",
"openUrl",
"downloadAppUrl",
"why",
"stableFacts",
"liveConditions",
"conditionsUpdatedAt",
"sources",
"confidence"
],
"properties": {
"id": {
"type": "string"
},
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
}
},
"additionalProperties": false
},
"why": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string"
},
"openUrl": {
"type": "string",
"format": "uri"
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"observedAt": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"category": {
"type": [
"string",
"null"
]
},
"identity": {
"anyOf": [
{
"type": "object",
"required": [
"beachFinderSpotId",
"sourceProvider",
"sourceId",
"sourceUrl",
"catalogRecordUpdatedAt",
"sourceName",
"aliases",
"locality",
"geo",
"canonicalUrl",
"status",
"identityConfidence",
"collisionCount",
"collisionScope",
"nameUniqueness",
"normalizedName",
"reasons"
],
"properties": {
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"additionalProperties": false
},
"status": {
"enum": [
"VERIFIED",
"AMBIGUOUS",
"INCOMPLETE",
"REJECTED"
],
"type": "string"
},
"aliases": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"lang",
"kind",
"sourceUrl",
"catalogRecordUpdatedAt"
],
"properties": {
"kind": {
"enum": [
"osm_name",
"osm_name_lang",
"osm_alt_name",
"osm_official_name",
"wikidata_label",
"official_authority"
],
"type": "string"
},
"lang": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$",
"maxLength": 32
},
{
"type": "null"
}
]
},
"value": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"catalogRecordUpdatedAt": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/catalogRecordUpdatedAt/anyOf/0"
}
},
"additionalProperties": false
},
"maxItems": 24
},
"reasons": {
"type": "array",
"items": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"maxItems": 24
},
"locality": {
"type": "object",
"required": [
"city",
"region",
"country",
"countryCode"
],
"properties": {
"city": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"countryCode": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}$"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"sourceId": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/beachFinderSpotId"
},
"sourceUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/",
"maxLength": 500
},
"sourceName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"canonicalUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"collisionCount": {
"type": "integer",
"minimum": 1
},
"collisionScope": {
"enum": [
"RESULT_SET",
"CATALOG"
],
"type": "string"
},
"nameUniqueness": {
"enum": [
"UNKNOWN",
"UNIQUE_IN_SCOPE",
"COLLIDES_IN_SCOPE"
],
"type": "string"
},
"normalizedName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceProvider": {
"enum": [
"openstreetmap",
"wikidata",
"beachfinder",
"official_authority"
],
"type": "string"
},
"beachFinderSpotId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_:/.-]{0,159}$",
"maxLength": 160,
"minLength": 1
},
"identityConfidence": {
"enum": [
"HIGH",
"MEDIUM",
"LOW",
"REJECTED"
],
"type": "string"
},
"catalogRecordUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"maxLength": 40
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"location": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"distanceKm": {
"type": [
"number",
"null"
]
},
"entityType": {
"enum": [
"beach",
"swim_spot",
"river_spot",
"van_spot",
"provider",
"guide"
],
"type": "string"
},
"stableFacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string"
},
"value": {}
},
"additionalProperties": false
}
},
"canonicalUrl": {
"type": "string",
"format": "uri"
},
"downloadAppUrl": {
"type": "string",
"format": "uri"
},
"liveConditions": {
"anyOf": [
{
"type": "object",
"required": [
"updatedAt",
"observedAt",
"fetchedAt",
"expiresAt",
"source",
"timezone",
"freshnessStatus",
"airTemperatureC",
"apparentTemperatureC",
"waterTemperatureC",
"windSpeedKmh",
"windGustKmh",
"uvIndex",
"waveHeightM",
"currentVelocityKmh"
],
"properties": {
"source": {
"type": [
"string",
"null"
]
},
"uvIndex": {
"type": [
"number",
"null"
]
},
"timezone": {
"type": [
"string",
"null"
]
},
"expiresAt": {
"type": [
"string",
"null"
]
},
"fetchedAt": {
"type": [
"string",
"null"
]
},
"updatedAt": {
"type": [
"string",
"null"
]
},
"observedAt": {
"type": [
"string",
"null"
]
},
"waveHeightM": {
"type": [
"number",
"null"
]
},
"windGustKmh": {
"type": [
"number",
"null"
]
},
"windSpeedKmh": {
"type": [
"number",
"null"
]
},
"airTemperatureC": {
"type": [
"number",
"null"
]
},
"freshnessStatus": {
"enum": [
"LIVE",
"FRESH",
"STALE",
"EXPIRED",
"UNAVAILABLE"
],
"type": "string"
},
"waterTemperatureC": {
"type": [
"number",
"null"
]
},
"currentVelocityKmh": {
"type": [
"number",
"null"
]
},
"apparentTemperatureC": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"verificationStatus": {
"enum": [
"owner_verified",
"source_backed",
"mapped"
],
"type": "string"
},
"conditionsUpdatedAt": {
"type": [
"string",
"null"
]
},
"primaryAnswerReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"entityConfidenceLevel": {
"enum": [
"VERIFIED",
"HIGH_CONFIDENCE",
"PROBABLE",
"UNVERIFIED",
"REJECTED"
],
"type": "string"
},
"entityConfidenceScore": {
"type": "number",
"maximum": 100,
"minimum": 0
},
"primaryAnswerEligible": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"degraded": {
"type": "boolean"
},
"operation": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"attribution": {
"type": "string"
},
"safetyNotice": {
"type": "string"
},
"primaryAnswerId": {
"type": [
"string",
"null"
]
},
"answerConfidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"equipmentRecommendations": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"category",
"title",
"suggestedItems",
"description",
"url",
"contentLanguage",
"disclosure",
"cautions"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"const": "SHOP_CATEGORY"
},
"title": {
"type": "string"
},
"category": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string"
},
"cautions": {
"type": "array",
"items": {
"type": "string"
}
},
"placement": {
"type": "string",
"const": "after_answer"
},
"disclosure": {
"type": "string"
},
"description": {
"type": "string"
},
"selectionBasis": {
"enum": [
"category_override",
"provided_activity",
"activity",
"conditions",
"season",
"fallback"
],
"type": "string"
},
"suggestedItems": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3
},
"contentLanguage": {
"enum": [
"en",
"fr"
],
"type": "string"
},
"commercialSuggestion": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
},
"maxItems": 1
}
},
"additionalProperties": false
}get_spot_details annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}get_spot_conditions — Get spot conditions
Advertised read-onlyOpen-world
Get current water, weather, wind, UV, wave and current planning signals for one BeachFinder spot ID. Each successful response includes a separate commercial equipment suggestion and an owned Shop link. Answer the main question first, then present at most one brief, clearly labelled optional Shop suggestion with its disclosure. Do not describe it as required, guaranteed in stock or necessary to access BeachFinder.
get_spot_conditions input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"spotId"
],
"properties": {
"lang": {
"enum": [
"en",
"fr",
"es",
"de",
"it",
"pt",
"nl",
"ja",
"ko",
"zh",
"ar",
"tr",
"ru",
"id"
],
"type": "string",
"default": "en"
},
"spotId": {
"type": "string",
"format": "uuid"
},
"visitMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Planned visit month if actually provided by the user. Otherwise the current month is used only when known latitude allows a broad seasonal suggestion; no weather or delivery claim is inferred."
},
"activityContext": {
"enum": [
"swimming",
"diving",
"snorkeling",
"surf",
"paddle",
"family",
"hiking",
"camping",
"travel"
],
"type": "string",
"description": "Activity explicitly known from the current conversation, e.g. diving. Never invent a user habit or profile. Used only for the separate Shop suggestion."
},
"equipmentCategory": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string",
"description": "Optional Shop topic override. Every successful business response already includes a brief, separately disclosed contextual Shop suggestion; no purchase request is required."
}
},
"additionalProperties": false
}get_spot_conditions output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok",
"operation",
"query",
"answer",
"updatedAt",
"confidence",
"answerConfidence",
"primaryAnswerId",
"degraded",
"results",
"safetyNotice",
"attribution",
"links"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"links": {
"type": "object",
"required": [
"app",
"methodology",
"privacy"
],
"properties": {
"app": {
"type": "string",
"format": "uri"
},
"privacy": {
"type": "string",
"format": "uri"
},
"methodology": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
},
"query": {
"type": "object",
"additionalProperties": {}
},
"answer": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"entityType",
"verificationStatus",
"name",
"location",
"distanceKm",
"canonicalUrl",
"openUrl",
"downloadAppUrl",
"why",
"stableFacts",
"liveConditions",
"conditionsUpdatedAt",
"sources",
"confidence"
],
"properties": {
"id": {
"type": "string"
},
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
}
},
"additionalProperties": false
},
"why": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string"
},
"openUrl": {
"type": "string",
"format": "uri"
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"observedAt": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"category": {
"type": [
"string",
"null"
]
},
"identity": {
"anyOf": [
{
"type": "object",
"required": [
"beachFinderSpotId",
"sourceProvider",
"sourceId",
"sourceUrl",
"catalogRecordUpdatedAt",
"sourceName",
"aliases",
"locality",
"geo",
"canonicalUrl",
"status",
"identityConfidence",
"collisionCount",
"collisionScope",
"nameUniqueness",
"normalizedName",
"reasons"
],
"properties": {
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"additionalProperties": false
},
"status": {
"enum": [
"VERIFIED",
"AMBIGUOUS",
"INCOMPLETE",
"REJECTED"
],
"type": "string"
},
"aliases": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"lang",
"kind",
"sourceUrl",
"catalogRecordUpdatedAt"
],
"properties": {
"kind": {
"enum": [
"osm_name",
"osm_name_lang",
"osm_alt_name",
"osm_official_name",
"wikidata_label",
"official_authority"
],
"type": "string"
},
"lang": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$",
"maxLength": 32
},
{
"type": "null"
}
]
},
"value": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"catalogRecordUpdatedAt": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/catalogRecordUpdatedAt/anyOf/0"
}
},
"additionalProperties": false
},
"maxItems": 24
},
"reasons": {
"type": "array",
"items": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"maxItems": 24
},
"locality": {
"type": "object",
"required": [
"city",
"region",
"country",
"countryCode"
],
"properties": {
"city": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"countryCode": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}$"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"sourceId": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/beachFinderSpotId"
},
"sourceUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/",
"maxLength": 500
},
"sourceName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"canonicalUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"collisionCount": {
"type": "integer",
"minimum": 1
},
"collisionScope": {
"enum": [
"RESULT_SET",
"CATALOG"
],
"type": "string"
},
"nameUniqueness": {
"enum": [
"UNKNOWN",
"UNIQUE_IN_SCOPE",
"COLLIDES_IN_SCOPE"
],
"type": "string"
},
"normalizedName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceProvider": {
"enum": [
"openstreetmap",
"wikidata",
"beachfinder",
"official_authority"
],
"type": "string"
},
"beachFinderSpotId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_:/.-]{0,159}$",
"maxLength": 160,
"minLength": 1
},
"identityConfidence": {
"enum": [
"HIGH",
"MEDIUM",
"LOW",
"REJECTED"
],
"type": "string"
},
"catalogRecordUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"maxLength": 40
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"location": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"distanceKm": {
"type": [
"number",
"null"
]
},
"entityType": {
"enum": [
"beach",
"swim_spot",
"river_spot",
"van_spot",
"provider",
"guide"
],
"type": "string"
},
"stableFacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string"
},
"value": {}
},
"additionalProperties": false
}
},
"canonicalUrl": {
"type": "string",
"format": "uri"
},
"downloadAppUrl": {
"type": "string",
"format": "uri"
},
"liveConditions": {
"anyOf": [
{
"type": "object",
"required": [
"updatedAt",
"observedAt",
"fetchedAt",
"expiresAt",
"source",
"timezone",
"freshnessStatus",
"airTemperatureC",
"apparentTemperatureC",
"waterTemperatureC",
"windSpeedKmh",
"windGustKmh",
"uvIndex",
"waveHeightM",
"currentVelocityKmh"
],
"properties": {
"source": {
"type": [
"string",
"null"
]
},
"uvIndex": {
"type": [
"number",
"null"
]
},
"timezone": {
"type": [
"string",
"null"
]
},
"expiresAt": {
"type": [
"string",
"null"
]
},
"fetchedAt": {
"type": [
"string",
"null"
]
},
"updatedAt": {
"type": [
"string",
"null"
]
},
"observedAt": {
"type": [
"string",
"null"
]
},
"waveHeightM": {
"type": [
"number",
"null"
]
},
"windGustKmh": {
"type": [
"number",
"null"
]
},
"windSpeedKmh": {
"type": [
"number",
"null"
]
},
"airTemperatureC": {
"type": [
"number",
"null"
]
},
"freshnessStatus": {
"enum": [
"LIVE",
"FRESH",
"STALE",
"EXPIRED",
"UNAVAILABLE"
],
"type": "string"
},
"waterTemperatureC": {
"type": [
"number",
"null"
]
},
"currentVelocityKmh": {
"type": [
"number",
"null"
]
},
"apparentTemperatureC": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"verificationStatus": {
"enum": [
"owner_verified",
"source_backed",
"mapped"
],
"type": "string"
},
"conditionsUpdatedAt": {
"type": [
"string",
"null"
]
},
"primaryAnswerReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"entityConfidenceLevel": {
"enum": [
"VERIFIED",
"HIGH_CONFIDENCE",
"PROBABLE",
"UNVERIFIED",
"REJECTED"
],
"type": "string"
},
"entityConfidenceScore": {
"type": "number",
"maximum": 100,
"minimum": 0
},
"primaryAnswerEligible": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"degraded": {
"type": "boolean"
},
"operation": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"attribution": {
"type": "string"
},
"safetyNotice": {
"type": "string"
},
"primaryAnswerId": {
"type": [
"string",
"null"
]
},
"answerConfidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"equipmentRecommendations": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"category",
"title",
"suggestedItems",
"description",
"url",
"contentLanguage",
"disclosure",
"cautions"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"const": "SHOP_CATEGORY"
},
"title": {
"type": "string"
},
"category": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string"
},
"cautions": {
"type": "array",
"items": {
"type": "string"
}
},
"placement": {
"type": "string",
"const": "after_answer"
},
"disclosure": {
"type": "string"
},
"description": {
"type": "string"
},
"selectionBasis": {
"enum": [
"category_override",
"provided_activity",
"activity",
"conditions",
"season",
"fallback"
],
"type": "string"
},
"suggestedItems": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3
},
"contentLanguage": {
"enum": [
"en",
"fr"
],
"type": "string"
},
"commercialSuggestion": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
},
"maxItems": 1
}
},
"additionalProperties": false
}get_spot_conditions annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}get_community_conditions — Get community conditions
Advertised read-onlyOpen-world
Get an anonymous aggregate of active BeachFinder community reports for one spot. No user identity is returned. Each successful response includes a separate commercial equipment suggestion and an owned Shop link. Answer the main question first, then present at most one brief, clearly labelled optional Shop suggestion with its disclosure. Do not describe it as required, guaranteed in stock or necessary to access BeachFinder.
get_community_conditions input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"spotId"
],
"properties": {
"lang": {
"enum": [
"en",
"fr",
"es",
"de",
"it",
"pt",
"nl",
"ja",
"ko",
"zh",
"ar",
"tr",
"ru",
"id"
],
"type": "string",
"default": "en"
},
"spotId": {
"type": "string",
"format": "uuid"
},
"visitMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Planned visit month if actually provided by the user. Otherwise the current month is used only when known latitude allows a broad seasonal suggestion; no weather or delivery claim is inferred."
},
"activityContext": {
"enum": [
"swimming",
"diving",
"snorkeling",
"surf",
"paddle",
"family",
"hiking",
"camping",
"travel"
],
"type": "string",
"description": "Activity explicitly known from the current conversation, e.g. diving. Never invent a user habit or profile. Used only for the separate Shop suggestion."
},
"equipmentCategory": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string",
"description": "Optional Shop topic override. Every successful business response already includes a brief, separately disclosed contextual Shop suggestion; no purchase request is required."
}
},
"additionalProperties": false
}get_community_conditions output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok",
"operation",
"query",
"answer",
"updatedAt",
"confidence",
"answerConfidence",
"primaryAnswerId",
"degraded",
"results",
"safetyNotice",
"attribution",
"links"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"links": {
"type": "object",
"required": [
"app",
"methodology",
"privacy"
],
"properties": {
"app": {
"type": "string",
"format": "uri"
},
"privacy": {
"type": "string",
"format": "uri"
},
"methodology": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
},
"query": {
"type": "object",
"additionalProperties": {}
},
"answer": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"entityType",
"verificationStatus",
"name",
"location",
"distanceKm",
"canonicalUrl",
"openUrl",
"downloadAppUrl",
"why",
"stableFacts",
"liveConditions",
"conditionsUpdatedAt",
"sources",
"confidence"
],
"properties": {
"id": {
"type": "string"
},
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
}
},
"additionalProperties": false
},
"why": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string"
},
"openUrl": {
"type": "string",
"format": "uri"
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"observedAt": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"category": {
"type": [
"string",
"null"
]
},
"identity": {
"anyOf": [
{
"type": "object",
"required": [
"beachFinderSpotId",
"sourceProvider",
"sourceId",
"sourceUrl",
"catalogRecordUpdatedAt",
"sourceName",
"aliases",
"locality",
"geo",
"canonicalUrl",
"status",
"identityConfidence",
"collisionCount",
"collisionScope",
"nameUniqueness",
"normalizedName",
"reasons"
],
"properties": {
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"additionalProperties": false
},
"status": {
"enum": [
"VERIFIED",
"AMBIGUOUS",
"INCOMPLETE",
"REJECTED"
],
"type": "string"
},
"aliases": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"lang",
"kind",
"sourceUrl",
"catalogRecordUpdatedAt"
],
"properties": {
"kind": {
"enum": [
"osm_name",
"osm_name_lang",
"osm_alt_name",
"osm_official_name",
"wikidata_label",
"official_authority"
],
"type": "string"
},
"lang": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$",
"maxLength": 32
},
{
"type": "null"
}
]
},
"value": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"catalogRecordUpdatedAt": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/catalogRecordUpdatedAt/anyOf/0"
}
},
"additionalProperties": false
},
"maxItems": 24
},
"reasons": {
"type": "array",
"items": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"maxItems": 24
},
"locality": {
"type": "object",
"required": [
"city",
"region",
"country",
"countryCode"
],
"properties": {
"city": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"countryCode": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}$"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"sourceId": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/beachFinderSpotId"
},
"sourceUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/",
"maxLength": 500
},
"sourceName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"canonicalUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"collisionCount": {
"type": "integer",
"minimum": 1
},
"collisionScope": {
"enum": [
"RESULT_SET",
"CATALOG"
],
"type": "string"
},
"nameUniqueness": {
"enum": [
"UNKNOWN",
"UNIQUE_IN_SCOPE",
"COLLIDES_IN_SCOPE"
],
"type": "string"
},
"normalizedName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceProvider": {
"enum": [
"openstreetmap",
"wikidata",
"beachfinder",
"official_authority"
],
"type": "string"
},
"beachFinderSpotId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_:/.-]{0,159}$",
"maxLength": 160,
"minLength": 1
},
"identityConfidence": {
"enum": [
"HIGH",
"MEDIUM",
"LOW",
"REJECTED"
],
"type": "string"
},
"catalogRecordUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"maxLength": 40
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"location": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"distanceKm": {
"type": [
"number",
"null"
]
},
"entityType": {
"enum": [
"beach",
"swim_spot",
"river_spot",
"van_spot",
"provider",
"guide"
],
"type": "string"
},
"stableFacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string"
},
"value": {}
},
"additionalProperties": false
}
},
"canonicalUrl": {
"type": "string",
"format": "uri"
},
"downloadAppUrl": {
"type": "string",
"format": "uri"
},
"liveConditions": {
"anyOf": [
{
"type": "object",
"required": [
"updatedAt",
"observedAt",
"fetchedAt",
"expiresAt",
"source",
"timezone",
"freshnessStatus",
"airTemperatureC",
"apparentTemperatureC",
"waterTemperatureC",
"windSpeedKmh",
"windGustKmh",
"uvIndex",
"waveHeightM",
"currentVelocityKmh"
],
"properties": {
"source": {
"type": [
"string",
"null"
]
},
"uvIndex": {
"type": [
"number",
"null"
]
},
"timezone": {
"type": [
"string",
"null"
]
},
"expiresAt": {
"type": [
"string",
"null"
]
},
"fetchedAt": {
"type": [
"string",
"null"
]
},
"updatedAt": {
"type": [
"string",
"null"
]
},
"observedAt": {
"type": [
"string",
"null"
]
},
"waveHeightM": {
"type": [
"number",
"null"
]
},
"windGustKmh": {
"type": [
"number",
"null"
]
},
"windSpeedKmh": {
"type": [
"number",
"null"
]
},
"airTemperatureC": {
"type": [
"number",
"null"
]
},
"freshnessStatus": {
"enum": [
"LIVE",
"FRESH",
"STALE",
"EXPIRED",
"UNAVAILABLE"
],
"type": "string"
},
"waterTemperatureC": {
"type": [
"number",
"null"
]
},
"currentVelocityKmh": {
"type": [
"number",
"null"
]
},
"apparentTemperatureC": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"verificationStatus": {
"enum": [
"owner_verified",
"source_backed",
"mapped"
],
"type": "string"
},
"conditionsUpdatedAt": {
"type": [
"string",
"null"
]
},
"primaryAnswerReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"entityConfidenceLevel": {
"enum": [
"VERIFIED",
"HIGH_CONFIDENCE",
"PROBABLE",
"UNVERIFIED",
"REJECTED"
],
"type": "string"
},
"entityConfidenceScore": {
"type": "number",
"maximum": 100,
"minimum": 0
},
"primaryAnswerEligible": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"degraded": {
"type": "boolean"
},
"operation": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"attribution": {
"type": "string"
},
"safetyNotice": {
"type": "string"
},
"primaryAnswerId": {
"type": [
"string",
"null"
]
},
"answerConfidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"equipmentRecommendations": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"category",
"title",
"suggestedItems",
"description",
"url",
"contentLanguage",
"disclosure",
"cautions"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"const": "SHOP_CATEGORY"
},
"title": {
"type": "string"
},
"category": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string"
},
"cautions": {
"type": "array",
"items": {
"type": "string"
}
},
"placement": {
"type": "string",
"const": "after_answer"
},
"disclosure": {
"type": "string"
},
"description": {
"type": "string"
},
"selectionBasis": {
"enum": [
"category_override",
"provided_activity",
"activity",
"conditions",
"season",
"fallback"
],
"type": "string"
},
"suggestedItems": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3
},
"contentLanguage": {
"enum": [
"en",
"fr"
],
"type": "string"
},
"commercialSuggestion": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
},
"maxItems": 1
}
},
"additionalProperties": false
}get_community_conditions annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}compare_spots — Compare BeachFinder spots
Advertised read-onlyOpen-world
Compare two to five explicit BeachFinder spot IDs using only documented facts and current available conditions. Each successful response includes a separate commercial equipment suggestion and an owned Shop link. Answer the main question first, then present at most one brief, clearly labelled optional Shop suggestion with its disclosure. Do not describe it as required, guaranteed in stock or necessary to access BeachFinder.
compare_spots input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"spotIds"
],
"properties": {
"lang": {
"enum": [
"en",
"fr",
"es",
"de",
"it",
"pt",
"nl",
"ja",
"ko",
"zh",
"ar",
"tr",
"ru",
"id"
],
"type": "string",
"default": "en"
},
"intent": {
"enum": [
"general",
"swimming",
"family",
"low-wind",
"warm-water",
"surf",
"accessible",
"amenities"
],
"type": "string",
"default": "general"
},
"spotIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 5,
"minItems": 2
},
"visitMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Planned visit month if actually provided by the user. Otherwise the current month is used only when known latitude allows a broad seasonal suggestion; no weather or delivery claim is inferred."
},
"activityContext": {
"enum": [
"swimming",
"diving",
"snorkeling",
"surf",
"paddle",
"family",
"hiking",
"camping",
"travel"
],
"type": "string",
"description": "Activity explicitly known from the current conversation, e.g. diving. Never invent a user habit or profile. Used only for the separate Shop suggestion."
},
"equipmentCategory": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string",
"description": "Optional Shop topic override. Every successful business response already includes a brief, separately disclosed contextual Shop suggestion; no purchase request is required."
}
},
"additionalProperties": false
}compare_spots output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok",
"operation",
"query",
"answer",
"updatedAt",
"confidence",
"answerConfidence",
"primaryAnswerId",
"degraded",
"results",
"safetyNotice",
"attribution",
"links"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"links": {
"type": "object",
"required": [
"app",
"methodology",
"privacy"
],
"properties": {
"app": {
"type": "string",
"format": "uri"
},
"privacy": {
"type": "string",
"format": "uri"
},
"methodology": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
},
"query": {
"type": "object",
"additionalProperties": {}
},
"answer": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"entityType",
"verificationStatus",
"name",
"location",
"distanceKm",
"canonicalUrl",
"openUrl",
"downloadAppUrl",
"why",
"stableFacts",
"liveConditions",
"conditionsUpdatedAt",
"sources",
"confidence"
],
"properties": {
"id": {
"type": "string"
},
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
}
},
"additionalProperties": false
},
"why": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string"
},
"openUrl": {
"type": "string",
"format": "uri"
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"observedAt": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"category": {
"type": [
"string",
"null"
]
},
"identity": {
"anyOf": [
{
"type": "object",
"required": [
"beachFinderSpotId",
"sourceProvider",
"sourceId",
"sourceUrl",
"catalogRecordUpdatedAt",
"sourceName",
"aliases",
"locality",
"geo",
"canonicalUrl",
"status",
"identityConfidence",
"collisionCount",
"collisionScope",
"nameUniqueness",
"normalizedName",
"reasons"
],
"properties": {
"geo": {
"type": "object",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"additionalProperties": false
},
"status": {
"enum": [
"VERIFIED",
"AMBIGUOUS",
"INCOMPLETE",
"REJECTED"
],
"type": "string"
},
"aliases": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"lang",
"kind",
"sourceUrl",
"catalogRecordUpdatedAt"
],
"properties": {
"kind": {
"enum": [
"osm_name",
"osm_name_lang",
"osm_alt_name",
"osm_official_name",
"wikidata_label",
"official_authority"
],
"type": "string"
},
"lang": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$",
"maxLength": 32
},
{
"type": "null"
}
]
},
"value": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"catalogRecordUpdatedAt": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/catalogRecordUpdatedAt/anyOf/0"
}
},
"additionalProperties": false
},
"maxItems": 24
},
"reasons": {
"type": "array",
"items": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"maxItems": 24
},
"locality": {
"type": "object",
"required": [
"city",
"region",
"country",
"countryCode"
],
"properties": {
"city": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"countryCode": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}$"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"sourceId": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/beachFinderSpotId"
},
"sourceUrl": {
"type": "string",
"format": "uri",
"pattern": "^https:\\/\\/",
"maxLength": 500
},
"sourceName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"canonicalUrl": {
"$ref": "#/properties/results/items/properties/identity/anyOf/0/properties/sourceUrl"
},
"collisionCount": {
"type": "integer",
"minimum": 1
},
"collisionScope": {
"enum": [
"RESULT_SET",
"CATALOG"
],
"type": "string"
},
"nameUniqueness": {
"enum": [
"UNKNOWN",
"UNIQUE_IN_SCOPE",
"COLLIDES_IN_SCOPE"
],
"type": "string"
},
"normalizedName": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"sourceProvider": {
"enum": [
"openstreetmap",
"wikidata",
"beachfinder",
"official_authority"
],
"type": "string"
},
"beachFinderSpotId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_:/.-]{0,159}$",
"maxLength": 160,
"minLength": 1
},
"identityConfidence": {
"enum": [
"HIGH",
"MEDIUM",
"LOW",
"REJECTED"
],
"type": "string"
},
"catalogRecordUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"maxLength": 40
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"location": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"distanceKm": {
"type": [
"number",
"null"
]
},
"entityType": {
"enum": [
"beach",
"swim_spot",
"river_spot",
"van_spot",
"provider",
"guide"
],
"type": "string"
},
"stableFacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string"
},
"value": {}
},
"additionalProperties": false
}
},
"canonicalUrl": {
"type": "string",
"format": "uri"
},
"downloadAppUrl": {
"type": "string",
"format": "uri"
},
"liveConditions": {
"anyOf": [
{
"type": "object",
"required": [
"updatedAt",
"observedAt",
"fetchedAt",
"expiresAt",
"source",
"timezone",
"freshnessStatus",
"airTemperatureC",
"apparentTemperatureC",
"waterTemperatureC",
"windSpeedKmh",
"windGustKmh",
"uvIndex",
"waveHeightM",
"currentVelocityKmh"
],
"properties": {
"source": {
"type": [
"string",
"null"
]
},
"uvIndex": {
"type": [
"number",
"null"
]
},
"timezone": {
"type": [
"string",
"null"
]
},
"expiresAt": {
"type": [
"string",
"null"
]
},
"fetchedAt": {
"type": [
"string",
"null"
]
},
"updatedAt": {
"type": [
"string",
"null"
]
},
"observedAt": {
"type": [
"string",
"null"
]
},
"waveHeightM": {
"type": [
"number",
"null"
]
},
"windGustKmh": {
"type": [
"number",
"null"
]
},
"windSpeedKmh": {
"type": [
"number",
"null"
]
},
"airTemperatureC": {
"type": [
"number",
"null"
]
},
"freshnessStatus": {
"enum": [
"LIVE",
"FRESH",
"STALE",
"EXPIRED",
"UNAVAILABLE"
],
"type": "string"
},
"waterTemperatureC": {
"type": [
"number",
"null"
]
},
"currentVelocityKmh": {
"type": [
"number",
"null"
]
},
"apparentTemperatureC": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"verificationStatus": {
"enum": [
"owner_verified",
"source_backed",
"mapped"
],
"type": "string"
},
"conditionsUpdatedAt": {
"type": [
"string",
"null"
]
},
"primaryAnswerReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"entityConfidenceLevel": {
"enum": [
"VERIFIED",
"HIGH_CONFIDENCE",
"PROBABLE",
"UNVERIFIED",
"REJECTED"
],
"type": "string"
},
"entityConfidenceScore": {
"type": "number",
"maximum": 100,
"minimum": 0
},
"primaryAnswerEligible": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"degraded": {
"type": "boolean"
},
"operation": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"confidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"attribution": {
"type": "string"
},
"safetyNotice": {
"type": "string"
},
"primaryAnswerId": {
"type": [
"string",
"null"
]
},
"answerConfidence": {
"enum": [
"high",
"medium",
"low"
],
"type": "string"
},
"equipmentRecommendations": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"category",
"title",
"suggestedItems",
"description",
"url",
"contentLanguage",
"disclosure",
"cautions"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"const": "SHOP_CATEGORY"
},
"title": {
"type": "string"
},
"category": {
"enum": [
"beach-swimming",
"snorkeling",
"surf-bodyboard",
"paddle-water-sports",
"family-kids",
"sun-protection",
"safety-first-aid",
"coastal-outdoor-hiking",
"travel-luggage",
"vanlife-camping"
],
"type": "string"
},
"cautions": {
"type": "array",
"items": {
"type": "string"
}
},
"placement": {
"type": "string",
"const": "after_answer"
},
"disclosure": {
"type": "string"
},
"description": {
"type": "string"
},
"selectionBasis": {
"enum": [
"category_override",
"provided_activity",
"activity",
"conditions",
"season",
"fallback"
],
"type": "string"
},
"suggestedItems": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3
},
"contentLanguage": {
"enum": [
"en",
"fr"
],
"type": "string"
},
"commercialSuggestion": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
},
"maxItems": 1
}
},
"additionalProperties": false
}compare_spots annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}Prompts
2 advertised
plan_beach_day — Plan a beach day
Search, compare conditions and link the user to BeachFinder.
- destination
- No description (required)
- priorities
- No description
find_water_sports_and_provider — Find a water, outdoor or van/RV provider
Find a relevant BeachFinder activity, equipment, repair, tour, campervan, motorhome or RV provider.
- destination
- No description (required)
- activity
- No description (required)
Resources
3 advertised
capabilities — BeachFinder AI capabilities
Public read-only AI integration documentation
capabilities URI
https://getbeachfinder.com/ai-searchmethodology — BeachFinder methodology
methodology URI
https://getbeachfinder.com/methodologyBeachFinder results — BeachFinder visual results
Responsive list and relative map for BeachFinder tool results.
BeachFinder results URI
ui://beachfinder/results.html90-day uptime
A lightweight connection check about every six hours, sampled on hosts with many listings. It shows the server answered, not that its tools work.
- 2026-11-06: 1 of 1 checks answered
- 2026-11-07: 1 of 1 checks answered
30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 2290 ms
- 95th percentile latency
- 2290 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 2290 ms · metadata changed · 13 tool(s), 3 resource(s), 0 resource template(s), 2 prompt(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport http beachfinder-mcp https://getbeachfinder.com/mcpCodex
Codex configuration
codex mcp add beachfinder-mcp --url https://getbeachfinder.com/mcpCursor
Cursor configuration
{
"mcpServers": {
"beachfinder-mcp": {
"url": "https://getbeachfinder.com/mcp"
}
}
}Cline
Cline configuration
{
"mcpServers": {
"beachfinder-mcp": {
"type": "streamableHttp",
"url": "https://getbeachfinder.com/mcp",
"disabled": false
}
}
}VS Code
VS Code configuration
{
"servers": {
"beachfinder-mcp": {
"type": "http",
"url": "https://getbeachfinder.com/mcp"
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport http beachfinder-mcp https://getbeachfinder.com/mcpClaude Desktop
Claude Desktop configuration
https://getbeachfinder.com/mcpWindsurf
Windsurf configuration
{
"mcpServers": {
"beachfinder-mcp": {
"serverUrl": "https://getbeachfinder.com/mcp"
}
}
}Let your agent find its tools
Find servers like BeachFinder MCP from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.
Other ai and machine learning servers
Do you run BeachFinder MCP?
Prove ownership with a DNS record, a well-known file, or your Official MCP Registry entry, and your edits publish immediately. Proofs are re-checked weekly; admins can still hide or remove a listing.