{ "openapi": "3.1.0", "info": { "title": "Casafari MCP tools", "version": "1.0.0", "description": "The tools of the Casafari MCP server (https://mcp.casafari.com/) that these docs cover, as OpenAPI. Call them over MCP (tools/call), not as HTTP paths: the paths only give each tool a place in the document." }, "servers": [ { "url": "https://mcp.casafari.com/" } ], "tags": [ { "name": "Gateway" }, { "name": "Comparables & Valuation" }, { "name": "Area Insights" }, { "name": "AgentGraph AI" } ], "paths": { "/tools/list_servers": { "post": { "operationId": "list_servers", "summary": "List Servers", "description": "List the tool groups available to you. Each entry is {namespace, title, description, instructions} as the\ngroup's server describes itself; tools in a group are named '_'. Call this before using a\ngroup for the first time: the instructions say how to use its tools (for example, which one to start with).", "tags": [ "Gateway" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "properties": { "result": { "items": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": "object" }, "type": "array" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } } } } }, "x-mcp-tool": { "name": "list_servers", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/gateway/list_servers" } } }, "/tools/comps_get-comparables": { "post": { "operationId": "comps_get-comparables", "summary": "Get Comparables", "description": "# Tool: get-comparables\n\n## Description\nRetrieves **comparable real estate properties** and **AI-powered market valuations** using the Casafari Comparables Engine.\n\nThe tool analyzes:\n- **Active listings** – current market offerings\n- **Historical transactions** – past sales and rentals\n- **Verified DVF data** – official property transfer records\n\nReturns:\n- **Matched comparable properties** ranked by relevance\n- **Aggregated market statistics** (median prices, DOM, listing velocity)\n- **Estimated price ranges**: fair market value, quick-sale price, premium pricing\n\n## Primary Use Cases\n| Use Case | Description |\n|----------|-------------|\n| **Property Valuation** | Price a listing based on real market data |\n| **Comp Analysis** | Find similar properties for BPO/CMA reports |\n| **Market Research** | Analyze local trends, absorption rates, pricing dynamics |\n| **Investment Modeling** | Assess fair value vs. asking price spreads |\n| **Historical Trends** | Track price evolution using sold_or_rented_after filter |\n\n## Key Capabilities\n\n### Advanced Filtering\n- **Property attributes**: type, bedrooms, bathrooms, size, condition\n- **Structural features**: floor level, orientation, views, parking, storage\n- **Quality markers**: construction year, energy rating, renovation status\n- **Characteristic logic**: must-have / nice-to-have / exclude lists\n- **Temporal filters**: sold/rented after specific date\n\n### Spatial Precision\nUses a **circle boundary** (target point + radius in kilometers) or a **closed polygon** of geo-points to ensure all comparables reflect the same micro-market conditions. The target point accepts coordinates, an address, or a Spanish cadastral reference.\n\n### Output Intelligence\n- **Property-level data**: individual comp details with photos, descriptions, pricing history\n- **Registry data**: DVF records (dvf_results) and notarial transactions (transactional_data)\n- **Market-level stats**: aggregated insights (median $/sqm, average DOM, inventory levels)\n- **Valuation estimates**: algorithmic price recommendations based on comp set\n\n## Pro Tips\n- Use tight radius (0.5-1 km) for urban areas, wider (2-5 km) for rural\n- Combine sold_or_rented_after with recent date for \"hot market\" analysis\n- Leverage characteristic filters to match unique property features (e.g., sea views, penthouse, ground floor)\n- Check both active listings AND sold comps for complete market picture\n\n---\n\n**Powered by Casafari's proprietary matching algorithm** – trained on millions of European property transactions.", "tags": [ "Comparables & Valuation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comparables_count": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum number of comparable properties in results." }, "location_boundary": { "type": "object", "properties": { "polygon": { "type": "array", "items": { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude." }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude." } }, "required": [ "latitude", "longitude" ], "additionalProperties": false }, "minItems": 4, "description": "Closed polygon of geo-points to search within. First and last points must match." }, "circle": { "type": "object", "properties": { "distance": { "type": "number", "minimum": 0.05, "maximum": 50, "description": "Maximum distance in kilometers from the requested `target_point` to the properties. Default value: 5." }, "target_point": { "type": "object", "properties": { "coordinates": { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude." }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude." } }, "required": [ "latitude", "longitude" ], "additionalProperties": false, "description": "Target point coordinates to search around." }, "address": { "type": "string", "description": "Address of the property to define the point to search around." }, "cadastral_reference": { "type": "object", "properties": { "country_code": { "type": "string", "enum": [ "ES" ], "description": "Country code following the ISO 3166-1 alpha-2 rules." }, "cadastral_reference": { "type": "string", "description": "Cadastral reference of the estate." }, "province": { "type": "string", "description": "Name of the estate's province." }, "municipality": { "type": "string", "description": "Name of the estate's municipality." } }, "required": [ "country_code", "cadastral_reference" ], "additionalProperties": false, "description": "Cadastral reference of the property to define the point to search around. For now available only for Spain." } }, "additionalProperties": false, "description": "Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided." } }, "required": [ "target_point" ], "additionalProperties": false, "description": "Circle boundary to search within." } }, "additionalProperties": false, "description": "Location to search within. Can be defined as a polygon of geo-points or a circle with a given target point and a distance. Only one value should be provided." }, "sold_or_rented_after": { "type": [ "string", "null" ], "description": "Properties sold/rented since this date (in the format `YYYY-MM-DD`) will be considered as possible comparables. Default value: 9 months ago, counting from today. If `null` is passed, only active properties will be considered." }, "operation": { "type": "string", "enum": [ "sale", "rent" ], "description": "Operation type." }, "comparables_types": { "type": "array", "items": { "type": "string", "enum": [ "apartment", "studio", "duplex", "penthouse", "dachgeschosswohnung", "etagenwohnung", "erdgeschosswohnung", "country_house", "house", "palace", "townhouse", "villa", "country_estate", "chalet", "bungalow", "family_house", "reihenhaus", "reihenendhaus", "reihenmittelhaus", "einfamilienhaus", "zweifamilienhaus", "landwirtschaftliche_betriebe", "retail", "office", "industrial", "warehouse", "hotel", "other_commercial", "restaurant", "werkstatt", "plot", "urban_plot", "rural_plot", "room", "other", "garage", "parking", "apartment_building", "office_building", "mix_use_building" ] }, "description": "Country availability per type is available at the GET /api/v1/references/types endpoint. Property types by type groups: apartment: erdgeschosswohnung, etagenwohnung, dachgeschosswohnung, duplex, studio, penthouse, apartment house: villa, reihenhaus, palace, country_estate, family_house (DEPRECATED), zweifamilienhaus, reihenmittelhaus, reihenendhaus, landwirtschaftliche_betriebe, country_house, townhouse, chalet, bungalow, einfamilienhaus, house room: room building: mix_use_building, office_building, apartment_building investment: restaurant, other_commercial, warehouse, office, industrial, werkstatt, hotel, retail plot: plot (DEPRECATED), rural_plot, urban_plot other: garage, other, parking Note that you can select multiple types only from one property type group." }, "min_price": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "The minimum price filter for comparables result. Default value: 0." }, "max_price": { "type": "integer", "minimum": 1, "maximum": 2147483647, "description": "The maximum price filter for comparables result." }, "condition": { "type": "string", "enum": [ "used", "ruin", "very-good", "new", "other" ], "description": "Property condition, as returned by the GET /api/v1/references/conditions endpoint." }, "bedrooms": { "type": "integer", "minimum": 0, "maximum": 15000, "description": "Number of bedrooms (cannot be used together with `rooms`)." }, "rooms": { "type": "integer", "minimum": 0, "maximum": 15000, "description": "Number of rooms (cannot be used together with `bedrooms`)." }, "bathrooms": { "type": "integer", "minimum": 1, "maximum": 15000, "description": "Number of bathrooms." }, "construction_year": { "type": "integer", "minimum": 1, "maximum": 3000, "description": "Desired construction year." }, "total_area": { "type": "integer", "minimum": 5, "maximum": 10000000, "description": "Desired total area, square meters. This field is required for `hotel`, `industrial`, `office`, `other_commercial`, `restaurant`, `retail`, `warehouse`, `werkstatt` property types if `target_point.cadastral_reference` is not provided." }, "plot_area": { "type": "integer", "minimum": 20, "maximum": 10000000, "description": "Desired plot area, square meters. This field is required for `rural_plot` and `urban_plot` property types if `target_point.cadastral_reference` is not provided." }, "floors": { "type": "array", "items": { "type": "string", "enum": [ "no_floor", "ground", "middle", "top" ] }, "description": "List of floor types." }, "floor_number": { "type": "array", "items": { "type": "integer", "minimum": -250, "maximum": 250 }, "description": "Desired list of floor numbers. Negative values indicate underground floors (e.g. basements). Minimum value is -250. Maximum value is 250." }, "orientation": { "type": "string", "enum": [ "exterior", "interior" ], "description": "Property view orientation." }, "views": { "type": "array", "items": { "type": "string", "enum": [ "water", "landscape", "city", "golf", "park" ] }, "description": "List of views from the property." }, "directions": { "type": "array", "items": { "type": "string", "enum": [ "north", "south", "east", "west" ] }, "description": "List of cardinal directions the property faces." }, "characteristics": { "type": "object", "properties": { "must_have": { "type": "array", "items": { "type": "string", "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ] }, "description": "Include only properties that have all these characteristics." }, "nice_to_have": { "type": "array", "items": { "type": "string", "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ] }, "description": "Include properties that have any of these characteristics." }, "exclude": { "type": "array", "items": { "type": "string", "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ] }, "description": "Exclude properties that contain any of these characteristics." } }, "additionalProperties": false, "description": "Property characteristics." }, "energy_ratings": { "type": "array", "items": { "type": "string", "enum": [ "Unknown", "A+", "A", "B", "C", "D", "E", "F", "G", "H" ] }, "description": "List of energy ratings." }, "days_on_market_from": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Minimum days on market value." }, "days_on_market_to": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Maximum days on market value." }, "with_agencies": { "type": "array", "items": { "type": "string" }, "description": "Return properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint." }, "without_agencies": { "type": "array", "items": { "type": "string" }, "description": "Exclude properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint." }, "exclude_outliers": { "type": "boolean", "description": "Exclude properties that are significantly underpriced or overpriced compared to similar properties. Default value: true." } }, "required": [ "comparables_count", "location_boundary", "operation", "comparables_types" ] } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "property_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "ID of the property." }, "property_url": { "type": [ "string", "null" ], "description": "URL of the property in the CASAFARI website." }, "primary_listing_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Primary listing (ad) ID of the property which is defined after the matching into property." }, "type": { "anyOf": [ { "type": "string", "enum": [ "apartment", "studio", "duplex", "penthouse", "dachgeschosswohnung", "etagenwohnung", "erdgeschosswohnung", "country_house", "house", "palace", "townhouse", "villa", "country_estate", "chalet", "bungalow", "family_house", "reihenhaus", "reihenendhaus", "reihenmittelhaus", "einfamilienhaus", "zweifamilienhaus", "landwirtschaftliche_betriebe", "retail", "office", "industrial", "warehouse", "hotel", "other_commercial", "restaurant", "werkstatt", "plot", "urban_plot", "rural_plot", "room", "other", "garage", "parking", "apartment_building", "office_building", "mix_use_building" ] }, { "type": "null" } ], "description": "Property type, as returned by the GET /api/v1/references/types endpoint." }, "type_group": { "anyOf": [ { "type": "string", "enum": [ "apartment", "house", "investment", "plot", "other" ] }, { "type": "null" } ], "description": "Property type group, as returned by the GET /api/v1/references/types endpoint." }, "coordinates": { "anyOf": [ { "type": "object", "properties": { "latitude": { "type": [ "number", "null" ], "description": "Latitude." }, "longitude": { "type": [ "number", "null" ], "description": "Longitude." } }, "required": [ "latitude", "longitude" ], "additionalProperties": true }, { "type": "null" } ], "description": "Property coordinates." }, "location": { "anyOf": [ { "type": "object", "properties": { "location_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Location ID, as returned by the POST /api/v1/references/locations endpoint." }, "name": { "type": [ "string", "null" ], "description": "Location name." }, "administrative_level": { "type": [ "string", "null" ], "description": "Location administrative level." }, "zip_codes": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The location zip codes." } }, "required": [ "location_id", "name", "administrative_level" ], "additionalProperties": true }, { "type": "null" } ], "description": "Information about property location." }, "locations_structure": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "location_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Location ID, as returned by the POST /api/v1/references/locations endpoint." }, "name": { "type": [ "string", "null" ], "description": "Location name." }, "administrative_level": { "type": [ "string", "null" ], "description": "Location administrative level." }, "zip_codes": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The location zip codes." } }, "required": [ "location_id", "name", "administrative_level" ], "additionalProperties": true } }, { "type": "null" } ], "description": "Information about all the parent locations (including property location) up to the country." }, "address": { "type": [ "string", "null" ], "description": "Property address." }, "zip_code": { "type": [ "string", "null" ], "description": "The location zip code." }, "distance": { "type": [ "number", "null" ], "description": "Distance in kilometers from target point to the property. Not calculated for search by polygon." }, "construction_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Construction year." }, "total_area": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total area." }, "living_area": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Living area." }, "plot_area": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Plot area." }, "terrace_area": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Terrace area." }, "bedrooms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of bedrooms." }, "rooms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of rooms." }, "bathrooms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of bathrooms." }, "floor_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Exact floor number. Negative values indicate underground floors (e.g. basements)." }, "condition": { "anyOf": [ { "type": "string", "enum": [ "used", "ruin", "very-good", "new", "other" ] }, { "type": "null" } ], "description": "Property condition, as returned by the GET /api/v1/references/conditions endpoint." }, "features": { "anyOf": [ { "type": "object", "properties": { "floor": { "anyOf": [ { "type": "string", "enum": [ "no_floor", "ground", "middle", "top" ] }, { "type": "null" } ], "description": "Floor type." }, "orientation": { "anyOf": [ { "type": "string", "enum": [ "exterior", "interior" ] }, { "type": "null" } ], "description": "Property view orientation." }, "view": { "anyOf": [ { "type": "string", "enum": [ "water", "landscape", "city", "golf", "park" ] }, { "type": "null" } ], "description": "View from the property. This field is deprecated and will be removed in the next major update. Please, use `views` field instead." }, "views": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "water", "landscape", "city", "golf", "park" ] } }, { "type": "null" } ], "description": "List of views from the property." }, "direction": { "anyOf": [ { "type": "string", "enum": [ "north", "south", "east", "west" ] }, { "type": "null" } ], "description": "Cardinal direction the property faces. This field is deprecated and will be removed in the next major update. Please, use `directions` field instead." }, "directions": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "north", "south", "east", "west" ] } }, { "type": "null" } ], "description": "List of cardinal directions the property faces." }, "characteristics": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ] } }, { "type": "null" } ], "description": "Property characteristics." } }, "required": [ "floor", "orientation", "view", "views", "direction", "directions", "characteristics" ], "additionalProperties": true }, { "type": "null" } ], "description": "Property features, as returned by the GET /api/v1/references/features endpoint." }, "operations": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "sale", "rent" ] } }, { "type": "null" } ], "description": "Operation types for which property is available." }, "sale_status": { "anyOf": [ { "type": "string", "enum": [ "active", "reserved", "hold", "sold", "none" ] }, { "type": "null" } ], "description": "Sale status." }, "sale_currency": { "type": [ "string", "null" ], "description": "Sale price currency code." }, "sale_price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Sale price, in the currency of the listings (specified by the `sale_currency` field)." }, "sale_price_base": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Sale price, in Euros." }, "sale_price_per_sqm": { "type": [ "number", "null" ], "description": "Sale price per square meter, in the currency of the listings (specified by the `sale_currency` field)." }, "sale_price_per_sqm_base": { "type": [ "number", "null" ], "description": "Sale price per square meter, in Euros." }, "rent_status": { "anyOf": [ { "type": "string", "enum": [ "active", "reserved", "hold", "rented", "none" ] }, { "type": "null" } ], "description": "Rent status." }, "rent_currency": { "type": [ "string", "null" ], "description": "Rent price currency code." }, "rent_price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Rent price, in the currency of the listings (specified by the `rent_currency` field)." }, "rent_price_base": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Rent price, in Euros." }, "rent_price_per_sqm": { "type": [ "number", "null" ], "description": "Rent price per square meter, in the currency of the listings (specified by the `rent_currency` field)." }, "rent_price_per_sqm_base": { "type": [ "number", "null" ], "description": "Rent price per square meter, in Euros." }, "rent_period": { "anyOf": [ { "type": "string", "enum": [ "day", "week", "fortnight", "month", "year", "none" ] }, { "type": "null" } ], "description": "Rent period." }, "title": { "type": [ "string", "null" ], "description": "Property title." }, "description": { "type": [ "string", "null" ], "description": "Property description." }, "thumbnails": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "List of the thumbnail image URLs." }, "pictures": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "List of the original picture image URLs." }, "gross_yield": { "type": [ "number", "null" ], "description": "Gross yield in percentage." }, "sold_at": { "type": [ "string", "null" ], "description": "Date when the property was sold." }, "rented_at": { "type": [ "string", "null" ], "description": "Date when the property was rented." }, "total_sale_price_change": { "type": [ "number", "null" ], "description": "Total sale price change in percents." }, "total_rent_price_change": { "type": [ "number", "null" ], "description": "Total rent price change in percents." }, "last_sale_price_reduction": { "type": [ "number", "null" ], "description": "Last sale price reduction in percents." }, "last_rent_price_reduction": { "type": [ "number", "null" ], "description": "Last rent price reduction in percents." }, "sale_price_last_change": { "anyOf": [ { "type": "object", "properties": { "change_date": { "type": [ "string", "null" ], "description": "Date of the change." }, "old_value": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Value before change." }, "new_value": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Value after change." } }, "required": [ "change_date", "old_value", "new_value" ], "additionalProperties": true }, { "type": "null" } ], "description": "Information about the last change of sale price." }, "rent_price_last_change": { "anyOf": [ { "type": "object", "properties": { "change_date": { "type": [ "string", "null" ], "description": "Date of the change." }, "old_value": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Value before change." }, "new_value": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Value after change." } }, "required": [ "change_date", "old_value", "new_value" ], "additionalProperties": true }, { "type": "null" } ], "description": "Information about the last change of rent price." }, "sale_time_on_market": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Information about the property last activity on the sales market." }, "rent_time_on_market": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Information about the property last activity on the rental market." }, "sale_active_listings_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of active listings for this property on the sales market." }, "rent_active_listings_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of active listings for this property on the rental market." }, "similarity_score": { "type": [ "number", "null" ], "description": "Similarity score of the property. Value between 0 and 1. Indicates how property parameters are close to the requested ones." }, "listing_urls": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Listing urls of the comparable." }, "is_outlier": { "type": [ "boolean", "null" ], "description": "Whether the property is considered an outlier based on its price. Default value: false." }, "is_private_property": { "type": [ "boolean", "null" ], "description": "Whether the property is listed by a private individual, as opposed to an agent or a professional." }, "energy_certificate": { "type": [ "string", "null" ], "description": "Energy certificate classification that attests to the energy efficiency of a property. This field is deprecated and will be removed in the next major update. Please, use `energy_rating` field instead." }, "energy_rating": { "type": [ "string", "null" ], "description": "Energy rating that attests to the energy efficiency of a property." }, "ref_numbers": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "List of reference numbers from listings." } }, "required": [ "property_id", "primary_listing_id", "type", "type_group", "coordinates", "location", "locations_structure", "address", "zip_code", "construction_year", "total_area", "living_area", "plot_area", "terrace_area", "bedrooms", "rooms", "bathrooms", "floor_number", "condition", "features", "operations", "sale_status", "sale_currency", "sale_price", "sale_price_base", "sale_price_per_sqm", "sale_price_per_sqm_base", "rent_status", "rent_currency", "rent_price", "rent_price_base", "rent_price_per_sqm", "rent_price_per_sqm_base", "rent_period", "title", "description", "gross_yield", "sold_at", "rented_at", "total_sale_price_change", "total_rent_price_change", "last_sale_price_reduction", "last_rent_price_reduction", "sale_price_last_change", "rent_price_last_change", "listing_urls", "is_private_property", "ref_numbers" ], "additionalProperties": true }, "description": "Array of found comparable properties." }, "dvf_results": { "type": "array", "items": { "type": "object", "properties": { "dvf_reference": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Reference ID of the DVF property." }, "coordinates": { "anyOf": [ { "type": "object", "properties": { "lat": { "type": [ "number", "null" ], "description": "Latitude." }, "lon": { "type": [ "number", "null" ], "description": "Longitude." } }, "required": [ "lat", "lon" ], "additionalProperties": true }, { "type": "null" } ], "description": "DVF property coordinates." }, "distance": { "type": [ "number", "null" ], "description": "Distance in kilometers from target point to DVF the property. Not calculated for search by polygon." }, "type": { "anyOf": [ { "type": "string", "enum": [ "apartment", "studio", "duplex", "penthouse", "dachgeschosswohnung", "etagenwohnung", "erdgeschosswohnung", "country_house", "house", "palace", "townhouse", "villa", "country_estate", "chalet", "bungalow", "family_house", "reihenhaus", "reihenendhaus", "reihenmittelhaus", "einfamilienhaus", "zweifamilienhaus", "landwirtschaftliche_betriebe", "retail", "office", "industrial", "warehouse", "hotel", "other_commercial", "restaurant", "werkstatt", "plot", "urban_plot", "rural_plot", "room", "other", "garage", "parking", "apartment_building", "office_building", "mix_use_building" ] }, { "type": "null" } ], "description": "Property type, as returned by the GET /api/v1/references/types endpoint." }, "type_group": { "anyOf": [ { "type": "string", "enum": [ "apartment", "house", "investment", "plot", "other" ] }, { "type": "null" } ], "description": "Property type group, as returned by the GET /api/v1/references/types endpoint." }, "sale_price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Sale price, in the original currency." }, "sale_price_base": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Sale price, in Euros." }, "sale_price_psqm": { "type": [ "number", "null" ], "description": "Sale price per square meter, in the original currency. Default value: 0." }, "sale_price_psqm_base": { "type": [ "number", "null" ], "description": "Sale price per square meter, in Euros. Default value: 0." }, "sold_at": { "type": [ "string", "null" ], "description": "Date when the property was sold." }, "total_area": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total area." }, "plot_area": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Plot area." }, "rooms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of rooms." }, "bedrooms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of bedrooms." }, "address": { "type": [ "string", "null" ], "description": "Property address." }, "location": { "anyOf": [ { "type": "object", "properties": { "location_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Location ID, as returned by the POST /api/v1/references/locations endpoint." }, "name": { "type": [ "string", "null" ], "description": "Location name." }, "administrative_level": { "type": [ "string", "null" ], "description": "Location administrative level." }, "zip_codes": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The location zip codes." } }, "required": [ "location_id", "name", "administrative_level" ], "additionalProperties": true }, { "type": "null" } ], "description": "Information about DVF property location." }, "locations_structure": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "location_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Location ID, as returned by the POST /api/v1/references/locations endpoint." }, "name": { "type": [ "string", "null" ], "description": "Location name." }, "administrative_level": { "type": [ "string", "null" ], "description": "Location administrative level." }, "zip_codes": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The location zip codes." } }, "required": [ "location_id", "name", "administrative_level" ], "additionalProperties": true } }, { "type": "null" } ], "description": "Information about all the parent locations (including DVF property location) up to the country." }, "sale_status": { "anyOf": [ { "type": "string", "enum": [ "active", "reserved", "hold", "sold", "none" ] }, { "type": "null" } ], "description": "Sale status." }, "thumbnails": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "List of the thumbnail image URLs." } }, "required": [ "dvf_reference", "coordinates", "type", "type_group", "sale_price", "sale_price_base", "total_area", "plot_area", "rooms", "bedrooms", "address", "location", "locations_structure" ], "additionalProperties": true }, "description": "Array of found DVF data (Request for geolocated property values)." }, "transactional_data": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "reference": { "type": [ "string", "null" ] }, "cadastral_reference": { "type": [ "string", "null" ] }, "rooms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "bedrooms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "bathrooms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "coordinates": { "anyOf": [ { "type": "object", "properties": { "lat": { "type": [ "number", "null" ], "description": "Latitude." }, "lon": { "type": [ "number", "null" ], "description": "Longitude." } }, "required": [ "lat", "lon" ], "additionalProperties": true }, { "type": "null" } ] }, "total_area": { "type": [ "number", "null" ] }, "plot_area": { "type": [ "number", "null" ] }, "address": { "type": [ "string", "null" ] }, "source_typology": { "type": [ "string", "null" ] }, "source_annexes": { "type": [ "string", "null" ], "description": "Additional raw source data (if present), describing annexes (such as parking, storage, etc) included in the transaction price." }, "type": { "anyOf": [ { "type": "string", "enum": [ "apartment", "studio", "duplex", "penthouse", "dachgeschosswohnung", "etagenwohnung", "erdgeschosswohnung", "country_house", "house", "palace", "townhouse", "villa", "country_estate", "chalet", "bungalow", "family_house", "reihenhaus", "reihenendhaus", "reihenmittelhaus", "einfamilienhaus", "zweifamilienhaus", "landwirtschaftliche_betriebe", "retail", "office", "industrial", "warehouse", "hotel", "other_commercial", "restaurant", "werkstatt", "plot", "urban_plot", "rural_plot", "room", "other", "garage", "parking", "apartment_building", "office_building", "mix_use_building" ] }, { "type": "null" } ] }, "type_group": { "type": [ "string", "null" ] }, "sold_at": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ], "description": "Price currency code." }, "price": { "type": [ "number", "null" ] }, "price_per_sqm": { "type": [ "number", "null" ] }, "with_mortgage": { "type": [ "boolean", "null" ], "description": "Flag indicating whether the transaction was financed with a mortgage." }, "distance": { "type": [ "number", "null" ], "description": "Distance in kilometers from target point to the property. Not calculated for search by polygon." }, "location_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "construction_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "object", "properties": { "location_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Location ID, as returned by the POST /api/v1/references/locations endpoint." }, "name": { "type": [ "string", "null" ], "description": "Location name." }, "administrative_level": { "type": [ "string", "null" ], "description": "Location administrative level." }, "zip_codes": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The location zip codes." } }, "required": [ "location_id", "name", "administrative_level" ], "additionalProperties": true }, { "type": "null" } ] }, "locations_structure": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "location_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Location ID, as returned by the POST /api/v1/references/locations endpoint." }, "name": { "type": [ "string", "null" ], "description": "Location name." }, "administrative_level": { "type": [ "string", "null" ], "description": "Location administrative level." }, "zip_codes": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The location zip codes." } }, "required": [ "location_id", "name", "administrative_level" ], "additionalProperties": true } }, { "type": "null" } ] }, "image_url": { "type": [ "string", "null" ] }, "country_code": { "anyOf": [ { "type": "string", "enum": [ "FR", "IT", "PT", "ES" ] }, { "type": "null" } ] } }, "required": [ "id", "reference", "cadastral_reference", "rooms", "bedrooms", "bathrooms", "coordinates", "total_area", "plot_area", "address", "source_typology", "source_annexes", "type", "type_group", "sold_at", "currency", "price", "price_per_sqm", "with_mortgage", "location_id", "construction_year", "location", "locations_structure", "image_url", "country_code" ], "additionalProperties": true } }, { "type": "null" } ] }, "statistics": { "anyOf": [ { "type": "object", "properties": { "average_price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Average price." }, "average_price_per_sqm": { "type": [ "number", "null" ], "description": "Average price per square meter." }, "average_time_on_the_market": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Average number of days on the market." }, "average_listings_per_property": { "type": [ "number", "null" ], "description": "Average number of listings per property." }, "sold_or_rented_in_last_six_months": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of properties that were sold or rented during the last 6 months in the requested location." } }, "required": [ "average_price", "average_price_per_sqm", "average_time_on_the_market", "average_listings_per_property", "sold_or_rented_in_last_six_months" ], "additionalProperties": true }, { "type": "null" } ], "description": "Statistics information for the found comparables (for `operation` defined in the request)." }, "estimated_prices": { "anyOf": [ { "type": "object", "properties": { "fast_sell_price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Fast sell price." }, "fair_market_price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Fair market price." }, "out_of_market_price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Out of market price." }, "fast_sell_price_per_sqm": { "type": [ "number", "null" ], "description": "Fast sell price per square meter." }, "fair_market_price_per_sqm": { "type": [ "number", "null" ], "description": "Fair market price per square meter." }, "out_of_market_price_per_sqm": { "type": [ "number", "null" ], "description": "Out of market price per square meter." } }, "required": [ "fast_sell_price", "fair_market_price", "out_of_market_price", "fast_sell_price_per_sqm", "fair_market_price_per_sqm", "out_of_market_price_per_sqm" ], "additionalProperties": true }, { "type": "null" } ], "description": "Estimated prices calculated based on the found comparables (for `operation` defined in the request)." }, "casafari_link": { "type": [ "string", "null" ], "description": "Link to Comparative Market Analysis page." }, "valuation_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Persistent valuation ID used to generate Smart Link or a PDF. Expires in a year." } }, "required": [ "results", "statistics", "estimated_prices", "casafari_link" ], "additionalProperties": true } } } } }, "x-mcp-tool": { "name": "comps_get-comparables", "annotations": { "readOnlyHint": true }, "docs": "https://platform.casafari.com/docs/comparables-valuation/get-comparables" } } }, "/tools/ma_get_current_datetime": { "post": { "operationId": "ma_get_current_datetime", "summary": "Get Current Datetime", "description": "# Tool: `get_current_datetime`\n\n## Description\nReturns the current system date and time.\n\n## Returns\n```json\n{\n \"current_datetime\": \"2025-10-06T12:45:00.000000\"\n}\n```\n\n| Key | Type | Description |\n|------|------|-------------|\n| `current_datetime` | `str` | Local system date and time in ISO format. |\n\n## Example Usage\n```python\nresult = await call_tool(\"get_current_datetime\")\nprint(result[\"current_datetime\"])\n```", "tags": [ "Area Insights" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } } }, "responses": { "200": { "description": "Tool result" } }, "x-mcp-tool": { "name": "ma_get_current_datetime", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/area-insights/get_current_datetime" } } }, "/tools/ma_get_time_series_data": { "post": { "operationId": "ma_get_time_series_data", "summary": "Get Time Series Data", "description": "# Tool: `get_time_series_data`\n\n## Description\nRetrieve **time series data** for the real estate market.\nEach data point in the series represents an aggregated metric (`data_point`) for a specific period,\ndefined by the chosen `date_interval` and property filters.\n\nThis tool provides consistent, interval-based historical data for various real estate indicators.\n\n## Use Cases\nRetrieve historical market information, such as:\n- Average property prices.\n- Average price per square meter.\n- Number of properties sold or rented over time.\n- Number of newly listed properties.\n- Number of properties available on the market.\n- Number of price increases or decreases for listings.\n\n## Parameters\n| Name | Type | Required | Description |\n|------|------|-----------|--------------|\n| `request_data` | `MCPTimeSeriesRequestSchema` | Yes | Defines filters, time interval, and data metric (`data_point`) for aggregation. |\n\n### Filter highlights\n- `data_point`: defines **which metric** to retrieve (e.g. price, listings, sold count, etc.).\n- `date_interval`: defines **the frequency** of data points in the response (`WEEK`, `MONTH`, `QUARTER`, `YEAR`).\n- `custom_location_boundary`: spatial boundary (circle or list of location IDs).\n- `type_group`: group of property types to analyze.\n- `business_type`: `\"sale\"` or `\"rent\"`.\n- `exclude_outliers`: optionally exclude statistical outliers from the results.\n- optional property filters: price range, area, bedrooms, bathrooms, etc.\n\n## Important Notes\n- If you need to compare different property types, send **separate requests** for each type group.\n- For broader analyses, prefer using `AVERAGE_PRICE_PER_SQM` over total price.\n- You can reuse the same filters with different `data_point` values to analyze multiple aspects of the market\n(e.g. compare new listings vs. sold properties).\n- Use the `exclude_outliers` flag to remove extreme values and improve analytical accuracy.\n\n## Returns\n```json\n[\n {\n \"date_start\": \"2024-01-01\",\n \"value\": 4350.5\n }\n]", "tags": [ "Area Insights" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "request_data": { "description": "One analytical segment defining a specific filter or location boundary.\nAlias (name) is generated automatically on the server based on the location definition.", "properties": { "type_group": { "description": "Estate type group.", "enum": [ "apartment", "house" ], "type": "string" }, "business_type": { "enum": [ "sale", "rent" ], "type": "string", "description": "Operation type for which the property is available." }, "price_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "price_per_sqm_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "rooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "bedrooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "bathrooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "total_area_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "plot_area_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "construction_year_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 3000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 3000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "characteristics": { "anyOf": [ { "properties": { "must_have": { "description": "Include only properties that have all these characteristics.", "items": { "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ], "type": "string" }, "type": "array" }, "exclude": { "description": "Exclude properties that contain any of these characteristics.", "items": { "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ], "type": "string" }, "type": "array" } }, "type": "object" }, { "type": "null" } ], "default": null }, "conditions": { "default": null, "description": "Property conditions, as returned by the [GET /api/v1/references/conditions](/#operation/) endpoint.", "items": { "enum": [ "used", "ruin", "very-good", "new", "other" ], "type": "string" }, "minItems": 1, "type": "array" }, "private": { "default": null, "description": "Whether the property is listed by a private individual, as opposed to an agent or a professional.", "type": "boolean" }, "bank": { "default": null, "description": "Whether the property is owned by the bank.", "type": "boolean" }, "auction": { "default": false, "description": "Whether the property is the subject of an auction.", "type": "boolean" }, "exclude_outliers": { "default": true, "description": "Exclude properties that are significantly underpriced or overpriced compared to similar properties.", "type": "boolean" }, "alias": { "description": "Alias (name) of the segment that was analyzed.", "type": "string" }, "custom_location_boundary": { "properties": { "location_ids": { "default": null, "description": "List of location IDs.", "items": { "maximum": 2147483647, "minimum": 1, "type": "integer" }, "maxItems": 10, "minItems": 1, "type": "array" }, "circle": { "properties": { "distance": { "description": "Maximum distance in meters from the requested `target_point` to the properties.", "maximum": 50000, "minimum": 50, "type": "integer" }, "target_point": { "properties": { "latitude": { "maximum": 90, "minimum": -90, "type": "number" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number" } }, "required": [ "latitude", "longitude" ], "type": "object", "description": "Target point coordinates to search around." } }, "required": [ "distance", "target_point" ], "type": "object", "default": null, "description": "Circle boundary to search within." } }, "type": "object", "description": "Geographic boundary definition (circle, or location ID list)." }, "data_point": { "enum": [ "avg_price", "avg_price_psqm", "available_on_market", "new", "sold_or_rented", "price_up", "price_down" ], "type": "string", "description": "Specifies the type of real estate data to retrieve for a given period." }, "date_interval": { "enum": [ "week", "month", "quarter", "year" ], "type": "string", "description": "Defines the time interval for aggregating data points. Determines the frequency at which data is reported in the response." }, "date_range": { "properties": { "min": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date in the format `YYYY-MM-DD`. If the specified date is not Monday - the closest previous Monday will be selected." }, "max": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date in the format `YYYY-MM-DD`. If the specified date is not Sunday - the closest previous Sunday will be selected." } }, "required": [ "min" ], "type": "object" } }, "required": [ "type_group", "business_type", "alias", "custom_location_boundary", "data_point", "date_interval", "date_range" ], "type": "object" } }, "required": [ "request_data" ], "type": "object" } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "properties": { "result": { "items": { "properties": { "date_start": { "description": "The starting date of the period associated with the passed `date_interval` field value. The format follows `YYYY-MM-DD`.", "format": "date", "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The numerical value corresponding to the passed `data_point` field value for the given `date_start`." } }, "required": [ "date_start", "value" ], "type": "object" }, "type": "array" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } } } } }, "x-mcp-tool": { "name": "ma_get_time_series_data", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/area-insights/get_time_series_data" } } }, "/tools/ma_get_time_series_operations": { "post": { "operationId": "ma_get_time_series_operations", "summary": "Get Time Series Operations", "description": "# Tool: `get_time_series_operations`\n\n## Description\nPerforms analytical **time-series operations** (e.g., `mean`, `delta_pct`, `CAGR`, `cv`, `std`, etc.)\nfor a **single geographic or analytical segment** using real-estate historical data.\n\nThis tool enables focused analysis of **real estate market dynamics** over time —\nsuch as prices, listings, or sales — within one defined location or subset.\n\n## Purpose\nDesigned for analytical scenarios such as:\n- Tracking how property prices evolve in a specific area.\n- Measuring growth trends (e.g., CAGR, percentage deltas).\n- Evaluating volatility using standard deviation or coefficient of variation.\n- Studying local market activity over a given period.\n\n## Input (`request_data`)\nExpects an instance of `MCPTimeSeriesOperationsRequestSchema`, which includes:\n- **`segment`** → a single `MCPTimeSeriesRequestSchema` object defining the geographic or analytical subset.\n- **`operations`** → list of time-series operations (`TimeSeriesOperationEnum`) to compute.\n\n`MCPTimeSeriesRequestSchema` includes:\n- `custom_location_boundary`: spatial boundary (circle or list of location IDs).\n- `data_point`: metric to analyze (e.g. `AVERAGE_PRICE_PER_SQM`, `SOLD_COUNT`, `NEW_LISTED_COUNT`).\n- `date_interval`: aggregation interval (`WEEK`, `MONTH`, `QUARTER`, or `YEAR`).\n- `date_range`: start and end of the analysis period.\n- Optional property filters (price, area, rooms, construction year, etc.).\n- `exclude_outliers`: whether to exclude statistical outliers.\n\n> **Analytical consistency rule:**\nThe analytical context (data_point, date_interval, business_type, etc.) must remain\nconsistent within the request. The `segment` may only redefine `custom_location_boundary`\nand `alias` relative to the base filter.\n\n## Operations\nSupported operations from `TimeSeriesOperationEnum` include:\n- `mean` — average value across the time range.\n- `delta_pct` — percentage change between the first and last data points.\n- `cagr` — compound annual growth rate.\n- `std` — standard deviation.\n- `cv` — coefficient of variation.\n- (plus others defined in the enum).\n\n## LLM Behavior\n- On success → returns a **single analytical result** (`MCPTimeSeriesUnitResponseSchema`)\n containing computed metrics for the requested segment.\n- On error → raises a `ToolError` with an error message.\n\n## Example Success Response\n```json\n {\n \"alias\": \"Madrid Center\",\n \"date_start\": \"2020-01-01\",\n \"date_end\": \"2024-01-01\",\n \"date_interval\": \"MONTH\",\n \"total_of_data_points\": 48,\n \"results\": [\n {\"operation\": \"mean\", \"value\": 3200.5},\n {\"operation\": \"delta_pct\", \"value\": 12.4},\n {\"operation\": \"cagr\", \"value\": 0.032}\n ]\n }\n```\n\n## Example Error Response\n```\nToolError: No data found for the specified segment.\n```\n\n## Example Use Cases\n- Analyze **average price per m²** in a specific city or district.\n- Measure **sales growth** over several years.\n- Evaluate **rental market volatility**.\n- Assess **seasonal dynamics** of listings or sales activity.\n\n## Summary\n`get_time_series_operations` retrieves **aggregated real-estate time-series data**\nfor a defined location or segment and computes selected analytical operations.\nIt provides a structured, quantitative summary of market trends and changes\nfor a single region or subset.", "tags": [ "Area Insights" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "request_data": { "description": "Schema for MCP time-series analytical requests.\n\n### Concept\nThis schema defines *what* to analyze (via `filter`), *where* to analyze (via `segment`),\nand *which operations* to compute (via `operations`).\n\n- The `filter` contains **shared analytical parameters** defining the general query context.\n- The `segment` represents a **specific analytical subset** (e.g., a district, city, or region),\n which inherits all values from `filter` but can override a few (e.g., location boundary).\n\nThis logic ensures a consistent analytical context while allowing\na single location-specific override — suitable for focused analytical requests\nwhere only one boundary or subset is being analyzed.", "properties": { "segment": { "description": "Analytical segment representing a boundary or subset of data. Inherits all fields from `filter` but may redefine location-specific ones (such as `custom_location_boundary` or `alias`).", "properties": { "type_group": { "description": "Estate type group.", "enum": [ "apartment", "house" ], "type": "string" }, "business_type": { "enum": [ "sale", "rent" ], "type": "string", "description": "Operation type for which the property is available." }, "price_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "price_per_sqm_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "rooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "bedrooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "bathrooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "total_area_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "plot_area_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "construction_year_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 3000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 3000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "characteristics": { "anyOf": [ { "properties": { "must_have": { "description": "Include only properties that have all these characteristics.", "items": { "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ], "type": "string" }, "type": "array" }, "exclude": { "description": "Exclude properties that contain any of these characteristics.", "items": { "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ], "type": "string" }, "type": "array" } }, "type": "object" }, { "type": "null" } ], "default": null }, "conditions": { "default": null, "description": "Property conditions, as returned by the [GET /api/v1/references/conditions](/#operation/) endpoint.", "items": { "enum": [ "used", "ruin", "very-good", "new", "other" ], "type": "string" }, "minItems": 1, "type": "array" }, "private": { "default": null, "description": "Whether the property is listed by a private individual, as opposed to an agent or a professional.", "type": "boolean" }, "bank": { "default": null, "description": "Whether the property is owned by the bank.", "type": "boolean" }, "auction": { "default": false, "description": "Whether the property is the subject of an auction.", "type": "boolean" }, "exclude_outliers": { "default": true, "description": "Exclude properties that are significantly underpriced or overpriced compared to similar properties.", "type": "boolean" }, "alias": { "description": "Alias (name) of the segment that was analyzed.", "type": "string" }, "custom_location_boundary": { "properties": { "location_ids": { "default": null, "description": "List of location IDs.", "items": { "maximum": 2147483647, "minimum": 1, "type": "integer" }, "maxItems": 10, "minItems": 1, "type": "array" }, "circle": { "properties": { "distance": { "description": "Maximum distance in meters from the requested `target_point` to the properties.", "maximum": 50000, "minimum": 50, "type": "integer" }, "target_point": { "properties": { "latitude": { "maximum": 90, "minimum": -90, "type": "number" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number" } }, "required": [ "latitude", "longitude" ], "type": "object", "description": "Target point coordinates to search around." } }, "required": [ "distance", "target_point" ], "type": "object", "default": null, "description": "Circle boundary to search within." } }, "type": "object", "description": "Geographic boundary definition (circle, or location ID list)." }, "data_point": { "enum": [ "avg_price", "avg_price_psqm", "available_on_market", "new", "sold_or_rented", "price_up", "price_down" ], "type": "string", "description": "Specifies the type of real estate data to retrieve for a given period." }, "date_interval": { "enum": [ "week", "month", "quarter", "year" ], "type": "string", "description": "Defines the time interval for aggregating data points. Determines the frequency at which data is reported in the response." }, "date_range": { "properties": { "min": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date in the format `YYYY-MM-DD`. If the specified date is not Monday - the closest previous Monday will be selected." }, "max": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date in the format `YYYY-MM-DD`. If the specified date is not Sunday - the closest previous Sunday will be selected." } }, "required": [ "min" ], "type": "object" } }, "required": [ "type_group", "business_type", "alias", "custom_location_boundary", "data_point", "date_interval", "date_range" ], "type": "object" }, "operations": { "default": null, "description": "List of analytical operations to compute (e.g. `mean`, `cagr`, `delta_pct`). If omitted, a default minimal set is applied.", "items": { "enum": [ "mean", "median", "std", "var", "min", "max", "sum", "count", "delta_abs", "delta_pct", "cagr", "mom_last", "yoy_last", "slope_per_period", "trend_strength", "cv", "inc_steps", "dec_steps", "flat_steps", "p10", "q1", "p90", "p95", "iqr", "outlier_ratio", "zscore_max", "movavg_last_3", "movavg_last_6", "movavg_last_12" ], "type": "string" }, "type": "array" } }, "required": [ "segment" ], "type": "object" } }, "required": [ "request_data" ], "type": "object" } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "description": "Response schema for a single segment (location boundary)\nprocessed within the time-series operations batch.", "properties": { "alias": { "description": "Alias (name) of the segment that was analyzed.", "type": "string" }, "date_start": { "description": "Start date of the analyzed period.", "format": "date", "type": "string" }, "date_end": { "description": "End date of the analyzed period.", "format": "date", "type": "string" }, "date_interval": { "enum": [ "week", "month", "quarter", "year" ], "type": "string", "description": "Frequency of the analyzed period." }, "total_of_data_points": { "description": "Number of data points included in the analyzed period.", "type": "integer" }, "results": { "anyOf": [ { "items": { "description": "Computed result for one analytical operation.", "properties": { "operation": { "enum": [ "mean", "median", "std", "var", "min", "max", "sum", "count", "delta_abs", "delta_pct", "cagr", "mom_last", "yoy_last", "slope_per_period", "trend_strength", "cv", "inc_steps", "dec_steps", "flat_steps", "p10", "q1", "p90", "p95", "iqr", "outlier_ratio", "zscore_max", "movavg_last_3", "movavg_last_6", "movavg_last_12" ], "type": "string", "description": "Operation type applied to the time series (e.g., mean, cagr, delta_pct, cv)." }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Computed numeric value. None if insufficient data for the operation." } }, "required": [ "operation", "value" ], "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "List of computed results for each analytical operation." } }, "required": [ "alias", "date_start", "date_end", "date_interval", "total_of_data_points", "results" ], "type": "object" } } } } }, "x-mcp-tool": { "name": "ma_get_time_series_operations", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/area-insights/get_time_series_operations" } } }, "/tools/ma_get_price_distribution": { "post": { "operationId": "ma_get_price_distribution", "summary": "Get Price Distribution", "description": "# Tool: `get_price_distribution`\n\n## Description\nReturns a **distribution of property prices** based on the provided filters.\nEach record represents a price interval and the number of properties within that interval.\n\n## Parameters\n| Name | Type | Required | Description |\n|------|------|-----------|--------------|\n| `request_data` | `MCPPriceDistributionRequestSchema` | Yes | Configuration for price distribution filtering. |\n\n### Filter highlights\n- `type_group`: group of estate types (e.g., apartment, house)\n- `business_type`: `\"sale\"` or `\"rent\"`\n- `price_range`: numeric price range filter\n- `exclude_outliers`: optional flag to exclude statistical outliers\n\n## Returns\n```json\n[\n {\n \"lower_bound\": 100000,\n \"upper_bound\": 150000,\n \"properties_count\": 42,\n \"is_mean\": false\n }\n]\n```\n\n| Field | Type | Description |\n|--------|------|-------------|\n| `lower_bound` | `int` | Lower price boundary |\n| `upper_bound` | `int` | Upper price boundary |\n| `properties_count` | `int` | Number of properties in the range |\n| `is_mean` | `bool` | Indicates whether the range includes the mean price |\n\n## Example Request\n```json\n{\n \"custom_location_boundary\": {\n \"circle\": {\n \"target_point\": {\"latitude\": 48.8566, \"longitude\": 2.3522},\n \"distance\": 10000\n }\n },\n \"type_group\": \"apartment\",\n \"business_type\": \"sale\",\n \"price_range\": {\"min\": 100000, \"max\": 500000},\n \"exclude_outliers\": true\n}\n```", "tags": [ "Area Insights" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "request_data": { "properties": { "type_group": { "description": "Estate type group.", "enum": [ "apartment", "house" ], "type": "string" }, "business_type": { "enum": [ "sale", "rent" ], "type": "string", "description": "Operation type for which the property is available." }, "price_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "price_per_sqm_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "rooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "bedrooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "bathrooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "total_area_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "plot_area_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "construction_year_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 3000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 3000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "characteristics": { "anyOf": [ { "properties": { "must_have": { "description": "Include only properties that have all these characteristics.", "items": { "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ], "type": "string" }, "type": "array" }, "exclude": { "description": "Exclude properties that contain any of these characteristics.", "items": { "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ], "type": "string" }, "type": "array" } }, "type": "object" }, { "type": "null" } ], "default": null }, "conditions": { "default": null, "description": "Property conditions, as returned by the [GET /api/v1/references/conditions](/#operation/) endpoint.", "items": { "enum": [ "used", "ruin", "very-good", "new", "other" ], "type": "string" }, "minItems": 1, "type": "array" }, "private": { "default": null, "description": "Whether the property is listed by a private individual, as opposed to an agent or a professional.", "type": "boolean" }, "bank": { "default": null, "description": "Whether the property is owned by the bank.", "type": "boolean" }, "auction": { "default": false, "description": "Whether the property is the subject of an auction.", "type": "boolean" }, "exclude_outliers": { "default": true, "description": "Exclude properties that are significantly underpriced or overpriced compared to similar properties.", "type": "boolean" }, "custom_location_boundary": { "properties": { "location_ids": { "default": null, "description": "List of location IDs.", "items": { "maximum": 2147483647, "minimum": 1, "type": "integer" }, "maxItems": 10, "minItems": 1, "type": "array" }, "circle": { "properties": { "distance": { "description": "Maximum distance in meters from the requested `target_point` to the properties.", "maximum": 50000, "minimum": 50, "type": "integer" }, "target_point": { "properties": { "latitude": { "maximum": 90, "minimum": -90, "type": "number" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number" } }, "required": [ "latitude", "longitude" ], "type": "object", "description": "Target point coordinates to search around." } }, "required": [ "distance", "target_point" ], "type": "object", "default": null, "description": "Circle boundary to search within." } }, "type": "object" } }, "required": [ "type_group", "business_type", "custom_location_boundary" ], "type": "object" } }, "required": [ "request_data" ], "type": "object" } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "properties": { "result": { "items": { "properties": { "lower_bound": { "description": "The lower price bound of the distribution unit.", "type": "integer" }, "upper_bound": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The upper price bound of the distribution unit." }, "properties_count": { "description": "The number of properties that participated in the distribution.", "type": "integer" }, "is_mean": { "description": "Indicates whether the mean value is within this distribution unit.", "type": "boolean" } }, "required": [ "lower_bound", "upper_bound", "properties_count", "is_mean" ], "type": "object" }, "type": "array" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } } } } }, "x-mcp-tool": { "name": "ma_get_price_distribution", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/area-insights/get_price_distribution" } } }, "/tools/ma_get_bedrooms_distribution": { "post": { "operationId": "ma_get_bedrooms_distribution", "summary": "Get Bedrooms Distribution", "description": "# Tool: `get_bedrooms_distribution`\n\n## Description\nReturns a **distribution of properties grouped by the number of bedrooms**.\nEach record includes total listings count, average price, and average price per square meter.\n\n## Business Context\nUseful for analyzing pricing differences and market concentration\nbased on bedroom count — ideal for residential market segmentation.\n\n## Parameters\n| Name | Type | Required | Description |\n|------|------|-----------|--------------|\n| `request_data` | `MCPBedroomsDistributionRequestSchema` | Yes | Filter configuration for bedroom-based distribution. |\n\n### Filter highlights\n- `type_group`: property type group (e.g., apartment, house)\n- `business_type`: `\"sale\"` or `\"rent\"`\n- `custom_location_boundary`: geographical boundary filter\n- `bedrooms_range`: range of bedroom counts\n- `exclude_outliers`: optional flag to remove statistical outliers\n\n## Returns\n```json\n[\n {\n \"bedrooms\": \"2\",\n \"properties_count\": 324,\n \"average_price\": 245000.0,\n \"average_price_per_sqm\": 5200.0\n }\n]\n```\n\n| Field | Type | Description |\n|--------|------|-------------|\n| `bedrooms` | `str` | Bedroom count label |\n| `properties_count` | `int` | Number of properties |\n| `average_price` | `float` | Average property price |\n| `average_price_per_sqm` | `float` | Average price per square meter |\n\n## Example Request\n```json\n{\n \"custom_location_boundary\": {\n \"circle\": {\n \"target_point\": {\"latitude\": 48.8566, \"longitude\": 2.3522},\n \"distance\": 10000\n }\n },\n \"type_group\": \"apartment\",\n \"business_type\": \"sale\",\n \"bedrooms_range\": {\"min\": 1, \"max\": 4},\n \"exclude_outliers\": true\n}\n```", "tags": [ "Area Insights" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "request_data": { "properties": { "type_group": { "description": "Estate type group.", "enum": [ "apartment", "house" ], "type": "string" }, "business_type": { "enum": [ "sale", "rent" ], "type": "string", "description": "Operation type for which the property is available." }, "price_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "price_per_sqm_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "rooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "bedrooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 10, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 10, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "bathrooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "total_area_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "plot_area_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "construction_year_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 3000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 3000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "characteristics": { "anyOf": [ { "properties": { "must_have": { "description": "Include only properties that have all these characteristics.", "items": { "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ], "type": "string" }, "type": "array" }, "exclude": { "description": "Exclude properties that contain any of these characteristics.", "items": { "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ], "type": "string" }, "type": "array" } }, "type": "object" }, { "type": "null" } ], "default": null }, "conditions": { "default": null, "description": "Property conditions, as returned by the [GET /api/v1/references/conditions](/#operation/) endpoint.", "items": { "enum": [ "used", "ruin", "very-good", "new", "other" ], "type": "string" }, "minItems": 1, "type": "array" }, "private": { "default": null, "description": "Whether the property is listed by a private individual, as opposed to an agent or a professional.", "type": "boolean" }, "bank": { "default": null, "description": "Whether the property is owned by the bank.", "type": "boolean" }, "auction": { "default": false, "description": "Whether the property is the subject of an auction.", "type": "boolean" }, "exclude_outliers": { "default": true, "description": "Exclude properties that are significantly underpriced or overpriced compared to similar properties.", "type": "boolean" }, "custom_location_boundary": { "properties": { "location_ids": { "default": null, "description": "List of location IDs.", "items": { "maximum": 2147483647, "minimum": 1, "type": "integer" }, "maxItems": 10, "minItems": 1, "type": "array" }, "circle": { "properties": { "distance": { "description": "Maximum distance in meters from the requested `target_point` to the properties.", "maximum": 50000, "minimum": 50, "type": "integer" }, "target_point": { "properties": { "latitude": { "maximum": 90, "minimum": -90, "type": "number" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number" } }, "required": [ "latitude", "longitude" ], "type": "object", "description": "Target point coordinates to search around." } }, "required": [ "distance", "target_point" ], "type": "object", "default": null, "description": "Circle boundary to search within." } }, "type": "object" } }, "required": [ "type_group", "business_type", "custom_location_boundary" ], "type": "object" } }, "required": [ "request_data" ], "type": "object" } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "properties": { "result": { "items": { "properties": { "bedrooms": { "description": "The number of bedrooms in the properties that participated in the distribution.", "type": "string" }, "properties_count": { "description": "The number of properties that participated in the distribution.", "type": "integer" }, "average_price": { "description": "Average price of properties with a specific number of bedrooms.", "type": "number" }, "average_price_per_sqm": { "description": "Average price per square meter of properties with a specific number of bedrooms.", "type": "number" } }, "required": [ "bedrooms", "properties_count", "average_price", "average_price_per_sqm" ], "type": "object" }, "type": "array" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } } } } }, "x-mcp-tool": { "name": "ma_get_bedrooms_distribution", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/area-insights/get_bedrooms_distribution" } } }, "/tools/ma_get_time_on_market_distribution": { "post": { "operationId": "ma_get_time_on_market_distribution", "summary": "Get Time on Market Distribution", "description": "# Tool: `get_time_on_market_distribution`\n\n## Description\nReturns a **distribution of properties by their time on the market**, grouped by price intervals.\nEach record contains average listing duration and property count.\n\n## Business Context\nUseful for evaluating **market liquidity** and **demand efficiency**,\nidentifying price segments where listings sell faster or remain longer.\n\n## Parameters\n| Name | Type | Required | Description |\n|------|------|-----------|--------------|\n| `request_data` | `MCPTimeOnMarketDistributionRequestSchema` | Yes | Defines filters for listing duration analysis. |\n\n### Filter highlights\n- `type_group`: property type group\n- `business_type`: `\"sale\"` or `\"rent\"`\n- `price_range`: price interval boundaries\n- `date_range`: date range for the active listing period\n- `exclude_outliers`: optional flag to exclude statistical outliers\n\n## Returns\n```json\n[\n {\n \"lower_bound\": 100000,\n \"upper_bound\": 199999,\n \"days_on_market\": 45,\n \"months_on_market\": 1.5,\n \"properties_count\": 120\n }\n]\n```\n\n| Field | Type | Description |\n|---------------|-------|------------|\n| `lower_bound` | `int` | Lower price limit |\n| `upper_bound` | `int` | Upper price limit |\n| `days_on_market` | `int` | Average number of active days |\n| `months_on_market` | `float` | Average duration in months |\n| `properties_count` | `int` | Number of listings in the group |\n\n## Example Request\n```json\n{\n \"custom_location_boundary\": {\n \"circle\": {\n \"target_point\": {\"latitude\": 41.3851, \"longitude\": 2.1734},\n \"distance\": 20000\n }\n },\n \"type_group\": \"apartment\",\n \"business_type\": \"sale\",\n \"price_range\": {\"min\": 100000, \"max\": 1000000},\n \"date_range\": {\"min\": \"2024-01-01\", \"max\": \"2024-12-31\"},\n \"exclude_outliers\": true\n}\n```", "tags": [ "Area Insights" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "request_data": { "properties": { "type_group": { "description": "Estate type group.", "enum": [ "apartment", "house" ], "type": "string" }, "business_type": { "enum": [ "sale", "rent" ], "type": "string", "description": "Operation type for which the property is available." }, "price_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "price_per_sqm_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "rooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "bedrooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "bathrooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "total_area_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "plot_area_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "construction_year_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 3000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 3000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "characteristics": { "anyOf": [ { "properties": { "must_have": { "description": "Include only properties that have all these characteristics.", "items": { "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ], "type": "string" }, "type": "array" }, "exclude": { "description": "Exclude properties that contain any of these characteristics.", "items": { "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ], "type": "string" }, "type": "array" } }, "type": "object" }, { "type": "null" } ], "default": null }, "conditions": { "default": null, "description": "Property conditions, as returned by the [GET /api/v1/references/conditions](/#operation/) endpoint.", "items": { "enum": [ "used", "ruin", "very-good", "new", "other" ], "type": "string" }, "minItems": 1, "type": "array" }, "private": { "default": null, "description": "Whether the property is listed by a private individual, as opposed to an agent or a professional.", "type": "boolean" }, "bank": { "default": null, "description": "Whether the property is owned by the bank.", "type": "boolean" }, "auction": { "default": false, "description": "Whether the property is the subject of an auction.", "type": "boolean" }, "exclude_outliers": { "default": true, "description": "Exclude properties that are significantly underpriced or overpriced compared to similar properties.", "type": "boolean" }, "custom_location_boundary": { "properties": { "location_ids": { "default": null, "description": "List of location IDs.", "items": { "maximum": 2147483647, "minimum": 1, "type": "integer" }, "maxItems": 10, "minItems": 1, "type": "array" }, "circle": { "properties": { "distance": { "description": "Maximum distance in meters from the requested `target_point` to the properties.", "maximum": 50000, "minimum": 50, "type": "integer" }, "target_point": { "properties": { "latitude": { "maximum": 90, "minimum": -90, "type": "number" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number" } }, "required": [ "latitude", "longitude" ], "type": "object", "description": "Target point coordinates to search around." } }, "required": [ "distance", "target_point" ], "type": "object", "default": null, "description": "Circle boundary to search within." } }, "type": "object" }, "date_range": { "properties": { "min": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date in the format `YYYY-MM-DD`." }, "max": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date in the format `YYYY-MM-DD`." } }, "required": [ "min" ], "type": "object", "default": null, "description": "Filter properties based on the start date of their last active period on the market." } }, "required": [ "type_group", "business_type", "custom_location_boundary" ], "type": "object" } }, "required": [ "request_data" ], "type": "object" } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "properties": { "result": { "items": { "properties": { "lower_bound": { "description": "The lower price bound of the distribution unit.", "type": "integer" }, "upper_bound": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The upper price bound of the distribution unit." }, "days_on_market": { "description": "The average days on the market.", "type": "integer" }, "months_on_market": { "description": "The average months on the market.", "type": "number" }, "properties_count": { "description": "The number of properties that participated in the distribution.", "type": "integer" } }, "required": [ "lower_bound", "upper_bound", "days_on_market", "months_on_market", "properties_count" ], "type": "object" }, "type": "array" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } } } } }, "x-mcp-tool": { "name": "ma_get_time_on_market_distribution", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/area-insights/get_time_on_market_distribution" } } }, "/tools/ma_get_heatmap": { "post": { "operationId": "ma_get_heatmap", "summary": "Get Heatmap", "description": "# Tool: `get_heatmap`\n\n## Description\nGenerate an **area insights heatmap** showing property distribution and price dynamics\nacross geographic areas.\n\nThis tool aggregates **active real estate listings** for the child locations of the given `location_id`\n(e.g., districts of a city), returning the selected `data_point` metric for each of them.\nIt supports a wide range of property filters, including estate type, price range,\nconstruction year, and location hierarchy.\n\n## Use Cases\nRetrieve geographic insights for real estate analytics:\n- Visualize market activity intensity across a city or region.\n- Identify hotspots of high property density or high average price.\n- Compare neighborhoods based on average price per sqm.\n- Analyze supply distribution and property trends over time.\n- Combine with time-series data to understand historical evolution by area.\n\n## Parameters\n| Name | Type | Required | Description |\n|------|------|-----------|--------------|\n| `request_data` | `MCPHeatMapRequestSchema` | Yes | Defines filters, metrics, and date range for heatmap generation. |\n\n## Important Notes\n- Only **ACTIVE** listings are included.\n- The tool automatically resolves **child locations** (e.g., neighborhoods within a city).\n- If no matching data is found, a `ToolError` will be raised.\n- Use returned data for **map visualization** or **spatial analytics dashboards**.\n\n## Returns\n```json\n[\n {\n \"location_id\": 12345,\n \"location_name\": \"Lisbon\",\n \"value\": 5200.5\n }\n]\n```\nEach item represents one geographic unit with aggregated metric value.", "tags": [ "Area Insights" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "request_data": { "properties": { "type_group": { "description": "Estate type group.", "enum": [ "apartment", "house" ], "type": "string" }, "business_type": { "enum": [ "sale", "rent" ], "type": "string", "description": "Operation type for which the property is available." }, "price_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "price_per_sqm_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 2147483647, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "rooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "bedrooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "bathrooms_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 15000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "total_area_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "plot_area_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 1000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "construction_year_range": { "anyOf": [ { "properties": { "min": { "anyOf": [ { "maximum": 3000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null }, "max": { "anyOf": [ { "maximum": 3000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null } }, "type": "object" }, { "type": "null" } ], "default": null }, "characteristics": { "anyOf": [ { "properties": { "must_have": { "description": "Include only properties that have all these characteristics.", "items": { "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ], "type": "string" }, "type": "array" }, "exclude": { "description": "Exclude properties that contain any of these characteristics.", "items": { "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ], "type": "string" }, "type": "array" } }, "type": "object" }, { "type": "null" } ], "default": null }, "conditions": { "default": null, "description": "Property conditions, as returned by the [GET /api/v1/references/conditions](/#operation/) endpoint.", "items": { "enum": [ "used", "ruin", "very-good", "new", "other" ], "type": "string" }, "minItems": 1, "type": "array" }, "private": { "default": null, "description": "Whether the property is listed by a private individual, as opposed to an agent or a professional.", "type": "boolean" }, "bank": { "default": null, "description": "Whether the property is owned by the bank.", "type": "boolean" }, "auction": { "default": false, "description": "Whether the property is the subject of an auction.", "type": "boolean" }, "exclude_outliers": { "default": true, "description": "Exclude properties that are significantly underpriced or overpriced compared to similar properties.", "type": "boolean" }, "location_id": { "maximum": 2147483647, "minimum": 1, "type": "integer" }, "data_point": { "enum": [ "avg_price", "avg_price_psqm", "available_on_market", "new", "sold_or_rented", "price_up", "price_down" ], "type": "string", "description": "Specifies the type of real estate data to retrieve for a given period." }, "date_range": { "properties": { "min": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date in the format `YYYY-MM-DD`. If the specified date is not Monday - the closest previous Monday will be selected" }, "max": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date in the format `YYYY-MM-DD`. If the specified date is not Sunday - the closest previous Sunday will be selected" } }, "required": [ "min" ], "type": "object" } }, "required": [ "type_group", "business_type", "location_id", "data_point", "date_range" ], "type": "object" } }, "required": [ "request_data" ], "type": "object" } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "properties": { "result": { "items": { "properties": { "location_id": { "type": "integer" }, "location_name": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "location_id", "location_name", "value" ], "type": "object" }, "type": "array" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } } } } }, "x-mcp-tool": { "name": "ma_get_heatmap", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/area-insights/get_heatmap" } } }, "/tools/ma_get_location_typeahead": { "post": { "operationId": "ma_get_location_typeahead", "summary": "Get Location Typeahead", "description": "Retrieve typeahead suggestions for a given location name.\n\nUse case:\n Retrieve typeahead suggestions to get location_id for different requests.\n\nImportant notes:\n- If there is more than one location with the same name, and it's not clear which one is correct - specify more\ninformation / symbols in the request.\n- The `location_name` should be a valid location name in English.", "tags": [ "Area Insights" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "location_name": { "type": "string" } }, "required": [ "location_name" ], "type": "object" } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "properties": { "result": { "items": { "properties": { "location_id": { "type": "integer" }, "name": { "type": "string" }, "matched_name": { "type": "string" }, "administrative_level": { "type": "string" }, "breadcrumbs": { "items": { "properties": { "location_id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "location_id", "name" ], "type": "object" }, "type": "array" } }, "required": [ "location_id", "name", "matched_name", "administrative_level", "breadcrumbs" ], "type": "object" }, "type": "array" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } } } } }, "x-mcp-tool": { "name": "ma_get_location_typeahead", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/area-insights/get_location_typeahead" } } }, "/tools/agentgraph_find_location": { "post": { "operationId": "agentgraph_find_location", "summary": "Find a German location", "description": "Finds German cities, districts and states by name and returns their location ids, kinds and parent areas. Use it when a name is ambiguous (several \"Neustadt\") or to pick a district within a city.", "tags": [ "AgentGraph AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 2 }, "limit": { "type": "integer", "minimum": 1, "maximum": 20, "default": 8 } } } } } }, "responses": { "200": { "description": "Tool result" } }, "x-mcp-tool": { "name": "agentgraph_find_location", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/agentgraph/find_location" } } }, "/tools/agentgraph_list_profiles": { "post": { "operationId": "agentgraph_list_profiles", "summary": "Partner profiles", "description": "Lists the partner profiles the screens match against, with each one's exact rules, priority and what the listing data cannot show.", "tags": [ "AgentGraph AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } }, "responses": { "200": { "description": "Tool result" } }, "x-mcp-tool": { "name": "agentgraph_list_profiles", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/agentgraph/list_profiles" } } }, "/tools/agentgraph_screen_agencies": { "post": { "operationId": "agentgraph_screen_agencies", "summary": "Screen agencies in an area", "description": "Ranks the real estate agencies active in a German area against partner profiles: franchise offices losing momentum and growing independent agencies (solo brokers and small teams of about 2-10). Each result has its figures (active homes, new homes per quarter, momentum, exits and days on market, price cuts, postcodes), the profile signals it meets and misses, its team, and contacts. Use this to find agencies worth partnering with.", "tags": [ "AgentGraph AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "location": { "description": "A German city, district or state by name (\"München\", \"Hamburg-Altona\", \"Bayern\") or a location id from find_location. A 5-digit value is read as a postcode.", "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "zipcodes": { "type": "array", "items": { "type": "string", "pattern": "^\\d{5}$" }, "maxItems": 200, "description": "Limit to these postcodes (with or without a location)." }, "profile": { "description": "Profiles to match: franchise_office_losing_momentum, growing_independent; \"all\" (default) for any of them, or \"none\" to rank every broker by volume using filters only.", "oneOf": [ { "type": "string", "enum": [ "franchise_office_losing_momentum", "growing_independent", "all", "none" ] }, { "type": "array", "items": { "type": "string", "enum": [ "franchise_office_losing_momentum", "growing_independent" ] } } ] }, "operation": { "type": "string", "enum": [ "sale", "rent" ], "default": "sale", "description": "Sales listings (default) or rentals." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "filters": { "type": "object", "description": "Optional thresholds applied on top of the profiles (or alone with profile \"none\"). Percent values are whole numbers.", "additionalProperties": false, "properties": { "min_active_homes": { "type": "integer", "minimum": 0 }, "max_active_homes": { "type": "integer", "minimum": 0 }, "min_exits_last_12m": { "type": "integer", "minimum": 0 }, "min_momentum_pct": { "type": "number" }, "max_momentum_pct": { "type": "number" }, "min_median_days_on_market": { "type": "integer", "minimum": 0 }, "max_median_days_on_market": { "type": "integer", "minimum": 0 }, "min_price_cut_share_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "max_postcodes": { "type": "integer", "minimum": 1 }, "min_top_postcode_share_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "brand_kinds": { "type": "array", "items": { "type": "string", "enum": [ "independent", "franchise", "bank_network", "digital_brokerage" ] } }, "exclude_brands": { "type": "array", "items": { "type": "string" } }, "min_team_size": { "type": "integer", "minimum": 0, "description": "Agencies only: named people on its listings." }, "max_team_size": { "type": "integer", "minimum": 0, "description": "Agencies only." } } }, "client_brand": { "type": "string", "description": "Your own network's name, if you are one. Its offices and agents are not offered as matches from \"another network's franchise\"." } } } } } }, "responses": { "200": { "description": "Tool result" } }, "x-mcp-tool": { "name": "agentgraph_screen_agencies", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/agentgraph/screen_agencies" } } }, "/tools/agentgraph_screen_agents": { "post": { "operationId": "agentgraph_screen_agents", "summary": "Screen agents in an area", "description": "Ranks the individual agents named on listings in a German area against partner profiles: top agents in a small area, top performers with a capped territory, agents in traditional offices, and brokers in an early phase. Each result has the agent's own figures, agency, signals met and missed, career history where known, and contacts. Only listings that name an agent count (most agency websites name them, portals less often).", "tags": [ "AgentGraph AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "location": { "description": "A German city, district or state by name (\"München\", \"Hamburg-Altona\", \"Bayern\") or a location id from find_location. A 5-digit value is read as a postcode.", "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "zipcodes": { "type": "array", "items": { "type": "string", "pattern": "^\\d{5}$" }, "maxItems": 200, "description": "Limit to these postcodes (with or without a location)." }, "profile": { "description": "Profiles to match: top_performer_capped_territory, top_agent_small_area, agent_traditional_office, early_phase_broker; \"all\" (default) for any of them, or \"none\" to rank every broker by volume using filters only.", "oneOf": [ { "type": "string", "enum": [ "top_performer_capped_territory", "top_agent_small_area", "agent_traditional_office", "early_phase_broker", "all", "none" ] }, { "type": "array", "items": { "type": "string", "enum": [ "top_performer_capped_territory", "top_agent_small_area", "agent_traditional_office", "early_phase_broker" ] } } ] }, "operation": { "type": "string", "enum": [ "sale", "rent" ], "default": "sale", "description": "Sales listings (default) or rentals." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "filters": { "type": "object", "description": "Optional thresholds applied on top of the profiles (or alone with profile \"none\"). Percent values are whole numbers.", "additionalProperties": false, "properties": { "min_active_homes": { "type": "integer", "minimum": 0 }, "max_active_homes": { "type": "integer", "minimum": 0 }, "min_exits_last_12m": { "type": "integer", "minimum": 0 }, "min_momentum_pct": { "type": "number" }, "max_momentum_pct": { "type": "number" }, "min_median_days_on_market": { "type": "integer", "minimum": 0 }, "max_median_days_on_market": { "type": "integer", "minimum": 0 }, "min_price_cut_share_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "max_postcodes": { "type": "integer", "minimum": 1 }, "min_top_postcode_share_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "brand_kinds": { "type": "array", "items": { "type": "string", "enum": [ "independent", "franchise", "bank_network", "digital_brokerage" ] } }, "exclude_brands": { "type": "array", "items": { "type": "string" } }, "min_team_size": { "type": "integer", "minimum": 0, "description": "Agencies only: named people on its listings." }, "max_team_size": { "type": "integer", "minimum": 0, "description": "Agencies only." } } }, "client_brand": { "type": "string", "description": "Your own network's name, if you are one. Its offices and agents are not offered as matches from \"another network's franchise\"." } } } } } }, "responses": { "200": { "description": "Tool result" } }, "x-mcp-tool": { "name": "agentgraph_screen_agents", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/agentgraph/screen_agents" } } }, "/tools/agentgraph_agency_profile": { "post": { "operationId": "agentgraph_agency_profile", "summary": "Agency in full", "description": "One agency's figures, quarter by quarter, its team (named agents on its listings), its places, contacts, and every partner profile it matches, benchmarked against its main city (or the area you give). Pass an id from screen_agencies, or a name.", "tags": [ "AgentGraph AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The id a screen returned (c:... or k:...)." }, "name": { "type": "string", "description": "The agency's name when no id is known." }, "location": { "description": "A German city, district or state by name (\"München\", \"Hamburg-Altona\", \"Bayern\") or a location id from find_location. A 5-digit value is read as a postcode.", "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "zipcodes": { "type": "array", "items": { "type": "string", "pattern": "^\\d{5}$" }, "maxItems": 200, "description": "Limit to these postcodes (with or without a location)." }, "operation": { "type": "string", "enum": [ "sale", "rent" ], "default": "sale", "description": "Sales listings (default) or rentals." }, "client_brand": { "type": "string", "description": "Your own network's name, if you are one. Its offices and agents are not offered as matches from \"another network's franchise\"." } } } } } }, "responses": { "200": { "description": "Tool result" } }, "x-mcp-tool": { "name": "agentgraph_agency_profile", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/agentgraph/agency_profile" } } }, "/tools/agentgraph_agent_profile": { "post": { "operationId": "agentgraph_agent_profile", "summary": "Agent in full", "description": "One agent's own figures, quarter by quarter, their agency, career across agencies (where Casafari's directory has it), contacts, and every partner profile they match, benchmarked against their main city (or the area you give). Pass an id from screen_agents, or a name with their agency.", "tags": [ "AgentGraph AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The id a screen returned (a:... or p:...)." }, "name": { "type": "string", "description": "The agent's name when no id is known." }, "company": { "type": "string", "description": "Their agency, to tell two people of the same name apart." }, "location": { "description": "A German city, district or state by name (\"München\", \"Hamburg-Altona\", \"Bayern\") or a location id from find_location. A 5-digit value is read as a postcode.", "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "zipcodes": { "type": "array", "items": { "type": "string", "pattern": "^\\d{5}$" }, "maxItems": 200, "description": "Limit to these postcodes (with or without a location)." }, "operation": { "type": "string", "enum": [ "sale", "rent" ], "default": "sale", "description": "Sales listings (default) or rentals." }, "client_brand": { "type": "string", "description": "Your own network's name, if you are one. Its offices and agents are not offered as matches from \"another network's franchise\"." } } } } } }, "responses": { "200": { "description": "Tool result" } }, "x-mcp-tool": { "name": "agentgraph_agent_profile", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/agentgraph/agent_profile" } } }, "/tools/agentgraph_partner_brief": { "post": { "operationId": "agentgraph_partner_brief", "summary": "Partner brief", "description": "A one-page brief on one agency or agent for the person who will approach them: key figures against the area, the partner signals they meet, listing quality (photos, descriptions, sole-agent mandates, price cuts, own website vs portals), team or career, a map of their active listings, two or three talking points, and how they may lawfully be approached in Germany. Returns the brief and brief_url, a printable page valid for 7 days (share it only inside your organisation). Pass an id from a screen and the area to compare against.", "tags": [ "AgentGraph AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "description": "An id from screen_agencies, screen_agents or a profile (c:, k:, a: or p:)." }, "location": { "description": "A German city, district or state by name (\"München\", \"Hamburg-Altona\", \"Bayern\") or a location id from find_location. A 5-digit value is read as a postcode.", "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "zipcodes": { "type": "array", "items": { "type": "string", "pattern": "^\\d{5}$" }, "maxItems": 200, "description": "Limit to these postcodes (with or without a location)." }, "operation": { "type": "string", "enum": [ "sale", "rent" ], "default": "sale", "description": "Sales listings (default) or rentals." }, "client_brand": { "type": "string", "description": "Your own network's name, if you are one. Its offices and agents are not offered as matches from \"another network's franchise\"." } } } } } }, "responses": { "200": { "description": "Tool result" } }, "x-mcp-tool": { "name": "agentgraph_partner_brief", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/agentgraph/partner_brief" } } }, "/tools/agentgraph_territory_map": { "post": { "operationId": "agentgraph_territory_map", "summary": "Territory map", "description": "One row per district or municipality of a German region (state, district or city): active homes, exits in 12 months, number of brokers, exits and active homes per broker, the share held by franchise networks and by independents, your own network's share, the top networks, a centre point for drawing a map, and an opportunity score. Use it to decide where to open or grow next; then screen_agencies or screen_agents in the best areas.", "tags": [ "AgentGraph AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "location" ], "properties": { "location": { "description": "A German city, district or state by name (\"München\", \"Hamburg-Altona\", \"Bayern\") or a location id from find_location. A 5-digit value is read as a postcode.", "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "operation": { "type": "string", "enum": [ "sale", "rent" ], "default": "sale", "description": "Sales listings (default) or rentals." }, "client_brand": { "type": "string", "description": "Your own network's name, if you are one. Its offices and agents are not offered as matches from \"another network's franchise\"." } } } } } }, "responses": { "200": { "description": "Tool result" } }, "x-mcp-tool": { "name": "agentgraph_territory_map", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/agentgraph/territory_map" } } }, "/tools/agentgraph_save_to_watchlist": { "post": { "operationId": "agentgraph_save_to_watchlist", "summary": "Save to watchlist", "description": "Saves agencies or agents (ids from a screen) to your organisation's shared watchlist, each measured in the area you give. AgentGraph AI re-measures the list every day and records changes: priority or profile changes, momentum turning against the area, more price cuts, slower exits, stock falling, an agent listing under a new agency, or no new listings for 60 days. Up to 200 entries.", "tags": [ "AgentGraph AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Ids from screen_agencies, screen_agents or a profile." }, "location": { "description": "A German city, district or state by name (\"München\", \"Hamburg-Altona\", \"Bayern\") or a location id from find_location. A 5-digit value is read as a postcode.", "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "zipcodes": { "type": "array", "items": { "type": "string", "pattern": "^\\d{5}$" }, "maxItems": 200, "description": "Limit to these postcodes (with or without a location)." }, "operation": { "type": "string", "enum": [ "sale", "rent" ], "default": "sale", "description": "Sales listings (default) or rentals." }, "label": { "type": "string", "maxLength": 60, "description": "An optional note shown with the entry, e.g. 'Q4 outreach'." }, "client_brand": { "type": "string", "description": "Your own network's name, if you are one. Its offices and agents are not offered as matches from \"another network's franchise\"." } } } } } }, "responses": { "200": { "description": "Tool result" } }, "x-mcp-tool": { "name": "agentgraph_save_to_watchlist", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/agentgraph/save_to_watchlist" } } }, "/tools/agentgraph_remove_from_watchlist": { "post": { "operationId": "agentgraph_remove_from_watchlist", "summary": "Remove from watchlist", "description": "Removes entries from your organisation's watchlist by id.", "tags": [ "AgentGraph AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 } } } } } }, "responses": { "200": { "description": "Tool result" } }, "x-mcp-tool": { "name": "agentgraph_remove_from_watchlist", "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/agentgraph/remove_from_watchlist" } } }, "/tools/agentgraph_watchlist": { "post": { "operationId": "agentgraph_watchlist", "summary": "Watchlist", "description": "Your organisation's watched agencies and agents, with their area, latest priority, active homes and momentum against the area.", "tags": [ "AgentGraph AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } }, "responses": { "200": { "description": "Tool result" } }, "x-mcp-tool": { "name": "agentgraph_watchlist", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/agentgraph/watchlist" } } }, "/tools/agentgraph_watchlist_changes": { "post": { "operationId": "agentgraph_watchlist_changes", "summary": "What changed", "description": "Changes on your watchlist since a date (default: the last 7 days), most important first within each day: priority and profile changes, momentum turning, price cuts, slower exits, falling or growing stock, agents moving agency, going quiet. refresh: true re-measures now instead of waiting for the daily run (slower).", "tags": [ "AgentGraph AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "since": { "type": "string", "description": "YYYY-MM-DD" }, "refresh": { "type": "boolean", "default": false }, "min_importance": { "type": "string", "enum": [ "high", "medium", "low" ], "default": "low" } } } } } }, "responses": { "200": { "description": "Tool result" } }, "x-mcp-tool": { "name": "agentgraph_watchlist_changes", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/agentgraph/watchlist_changes" } } }, "/tools/agentgraph_area_benchmark": { "post": { "operationId": "agentgraph_area_benchmark", "summary": "Area benchmark", "description": "What normal looks like for brokers in a German area: percentiles of active homes, exits, days on market, price cuts and momentum, how the market splits between independents, franchises, banks and online brokerages, and the biggest networks there.", "tags": [ "AgentGraph AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "location": { "description": "A German city, district or state by name (\"München\", \"Hamburg-Altona\", \"Bayern\") or a location id from find_location. A 5-digit value is read as a postcode.", "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "zipcodes": { "type": "array", "items": { "type": "string", "pattern": "^\\d{5}$" }, "maxItems": 200, "description": "Limit to these postcodes (with or without a location)." }, "unit": { "type": "string", "enum": [ "agency", "agent" ], "default": "agency" }, "operation": { "type": "string", "enum": [ "sale", "rent" ], "default": "sale", "description": "Sales listings (default) or rentals." } } } } } }, "responses": { "200": { "description": "Tool result" } }, "x-mcp-tool": { "name": "agentgraph_area_benchmark", "annotations": { "readOnlyHint": true, "openWorldHint": false }, "docs": "https://platform.casafari.com/docs/agentgraph/area_benchmark" } } } } }