# `search_premises`

> **Casafari is the AI agent-native real estate data intelligence platform.** The most complete property index in Europe: a deduplicated, cleaned property graph of residential and commercial property, for sale and for rent, in 16 countries. Every property is one record with its full price and market history. [How the property graph is built](/docs/property-graph).

Search commercial premises. Product: [Claro AI](/docs/claro).

Call it as `search_premises` on Claro AI's own server, not through `https://mcp.casafari.com/`. Its address on the platform is `https://platform.casafari.com/mcp/claro`: Streamable HTTP, a platform API key or the platform's OAuth, metered in platform units.

Over REST: [`POST /v1/search`](/docs/rest/claro/search-premises) (equivalent). [MCP and REST compared](/docs/parity#claro-ai).

## What does Search commercial premises do?

Find shops, restaurant premises, offices, warehouses and other commercial premises for rent or sale anywhere in Spain. Describe the site in plain words in any language (brief), send criteria as data, or both (criteria override the brief). Returns exact counts (matching, all criteria stated, some not stated), the criteria as understood, and the best results: each with its data, what was met and what its text does not state, the sentence that matched, its coordinates (exact, or snapped to the centre of a ~500 m cell and marked approximate when the agency hides the address; none when it has no pin), a fit verdict read from its text, location figures when your account has location access (footfall, residents, nearby places, and in `location` the footfall split by weekday/weekend, time of day and where the activity comes from live, plus residents by age, households by income and spending power, each null when not stated or unknown, never 0 for unknown; `location_sources` gives each figure's unit, source and vintage, and when it was computed), and the agency's own listing link. Our fit verdict is one input: every raw figure is there for your own scoring. Up to 200 results a page (50 with a publishable key). `next_cursor` gets the next page: send it as `cursor` (alone, with `limit` if you like); the order is fixed when the search runs and stays the same for its 24 hours, so pages never repeat or skip a premises. `page` gives offset, limit and the total ranked. The read-through (`check`) runs only for pages of up to 50. Keep search_id to refine. Keywords only, no model: send just criteria.keywords and/or exclude_keywords (plus any data criteria) with no brief and check: false, e.g. {"criteria": {"operation": "rent", "cities": ["madrid"], "keywords": [["salida de humos", "sortida de fums"], ["esquina", "chaflán"]], "exclude_keywords": ["se traspasa"]}, "check": false}; each keyword group met carries the sentence that matched (evidence) and the phrase it holds (matched).

## Which parameters does search_premises take?

- `brief` (string, optional): The site brief in plain words, e.g. "burger restaurant, corner unit 120-250 m², smoke outlet, busy street, Madrid, rent under 8,000 a month".
- `criteria` (object, optional): Criteria as data. Hard criteria (operation, cities, types, price, area) exclude properties outside them; the rest exclude only properties that state the opposite, and each result says which were met and which the property does not state.
  - `operation` (string, optional) Values: `rent`, `sale`, `either`.
  - `cities` (string[], optional): Spanish towns or cities by name or slug ("valencia", "Palma"). Leave out for all of Spain.
  - `provinces` (string[], optional): Provinces; a property must be in one of them. Values: `a-coruna`, `alava`, `albacete`, `alicante`, `almeria`, `asturias`, `avila`, `badajoz`, `barcelona`, `burgos`, `caceres`, `cadiz`, `cantabria`, `castellon`, `ceuta`, `ciudad-real`, `cordoba`, `cuenca`, `girona`, `granada`, `guadalajara`, `guipuzcoa`, `huelva`, `huesca`, `islas-baleares`, `jaen`, `la-rioja`, `las-palmas`, `leon`, `lleida`, `lugo`, `madrid`, `malaga`, `melilla`, `murcia`, `navarra`, `ourense`, `palencia`, `pontevedra`, `salamanca`, `santa-cruz-de-tenerife`, `segovia`, `sevilla`, `soria`, `tarragona`, `teruel`, `toledo`, `valencia`, `valladolid`, `vizcaya`, `zamora`, `zaragoza`.
  - `districts` (string[], optional): Named districts or neighbourhoods in the cities (Centro, Malasaña, Chamberí, Eixample, Gràcia, Poblenou...). A property outside them is out; one that does not state its district stays, marked not stated.
  - `types` (string[], optional) Values: `hotel`, `retail`, `warehouse`, `industrial`, `office`, `other_commercial`.
  - `area_min` (number, optional)
  - `area_max` (number, optional)
  - `price_min` (number, optional): EUR: a month for rent, the total for a sale; applies to each operation without its own rent_/sale_ limit.
  - `price_max` (number, optional)
  - `rent_price_min` (number, optional): EUR a month; compared only with rents.
  - `rent_price_max` (number, optional): EUR a month; compared only with rents. With sale_price_max, operation "either" keeps a property whose rent or sale price fits its own limit.
  - `sale_price_min` (number, optional): EUR total; compared only with sale prices.
  - `sale_price_max` (number, optional)
  - `price_m2_min` (number, optional): EUR per m² of the property's area (a month for rent); a property with no stated area is "not stated".
  - `price_m2_max` (number, optional)
  - `rent_price_m2_min` (number, optional)
  - `rent_price_m2_max` (number, optional)
  - `sale_price_m2_min` (number, optional)
  - `sale_price_m2_max` (number, optional)
  - `street_level` (boolean, optional)
  - `frontage_min_m` (number, optional): Facade length (fachada) in metres.
  - `frontage_max_m` (number, optional)
  - `floors_min` (number, optional): Number of floors (plantas) the premises has.
  - `floors_max` (number, optional)
  - `ceiling_min_m` (number, optional)
  - `smoke_extraction` (boolean, optional)
  - `corner` (boolean, optional)
  - `shop_window` (boolean, optional)
  - `open_plan` (boolean, optional)
  - `step_free` (boolean, optional)
  - `loading_access` (boolean, optional)
  - `licence` (string, optional) Values: `food_service`, `retail`, `office`, `gym`, `none`.
  - `licence_activities` (string[], optional): Activities its licence sentence must name, in Spanish or Catalan: cafetería, panadería, restaurante...
  - `transfer_price_min` (number, optional): Transfer fee (traspaso) in EUR; met when its stated range overlaps.
  - `transfer_price_max` (number, optional)
  - `business_transfer` (boolean, optional): true: only business transfers (traspasos); false: none.
  - `business_types` (string[], optional): Uses its text says it suits, in English: restaurant, cafe, gym...
  - `keywords` (string[][], optional): Groups of phrases; a property meets a group when its text holds any phrase. Write phrases as Spanish agencies do.
  - `exclude_keywords` (string[], optional): Leave out properties whose text holds any of these.
  - `footfall_min` (number, optional): Minimum footfall index within a 5-minute walk (an index of pedestrian activity that compares places; not a head count). Needs location data access.
  - `pop_walk10_min` (number, optional): Residents within a 10-minute walk. Needs location data access.
  - `pop_drive10_min` (number, optional): Residents within a 10-minute drive. Needs location data access.
  - `transit_min` (number, optional): Stations and stops within a 5-minute walk. Needs location data access.
  - `competitors_max` (object[], optional): At most this many places of a kind within a 5-minute walk (gyms: 10). Needs location data access.
    - `kind` (string, required) Values: `restaurants`, `fast_food`, `cafes`, `shops`, `supermarkets`, `gyms`.
    - `max` (number, required)
  - `own_stores_away_m` (number, optional): No store from your own list (upload it with PUT /v1/stores) within this many metres of the premises, straight-line, 1-1,000. Needs an exact pin.
  - `competitors_near_max` (object[], optional): At most `max` businesses of a segment (or of the named `chains`) within `within_m` straight-line metres (1-1,000), from Overture Maps places. A property with an approximate pin gets no verdict.
    - `segment` (string, required) Values: `gym`, `burger`, `fast_food`, `coffee`, `bakery`, `pharmacy`, `supermarket`, `fashion`, `pizza`.
    - `within_m` (number, required)
    - `max` (number, required)
    - `chains` (string[], optional): Only these brands count (rivals or your own), e.g. Burger King, Basic-Fit. Matched on Overture brand and name.
  - `spending_per_resident_min` (number, optional): Spending power a resident a year (EUR) within a 10-minute walk. Needs location data access.
  - `high_income_share_min` (number, optional): % of households within a 10-minute walk with net income above 40,162 EUR a year. Needs location data access.
  - `age_shares_min` (object[], optional): Minimum % of residents within a 10-minute walk in an age band. Needs location data access.
    - `band` (string, required) Values: `0_14`, `15_29`, `30_44`, `45_59`, `60p`.
    - `min_pct` (number, required)
  - `meaning` (string, optional): A wish no field holds, in any language; ranks results, never filters.
  - `sort` (string, optional): supply_gap ranks where residents per similar place is highest (residents within a 10-minute walk / (places within gap_radius_m, 600 m by default, + 1)); needs gap_segment or one competitors_near_max segment. Needs location data access; unscored properties go last. Values: `best`, `price_asc`, `price_desc`, `area_desc`, `footfall_desc`, `supply_gap`.
  - `gap_segment` (string, optional): The business kind the supply_gap sort counts. Values: `gym`, `burger`, `fast_food`, `coffee`, `bakery`, `pharmacy`, `supermarket`, `fashion`, `pizza`.
  - `gap_radius_m` (integer, optional): Radius in metres in which the supply_gap sort counts similar places: 600 (default) or 300 (about a 5-minute walk). Only with sort supply_gap. Values: `300`, `600`.
- `limit` (integer, optional): Results a page, up to 200; above 50 check is off. 1–200; default 10.
- `cursor` (string, optional): next_cursor from an earlier answer: returns that search's next page, same criteria and order. Send without brief, criteria or change.
- `check` (boolean, optional): Read the top results' text against the brief (adds a few seconds). Off above 50 results a page and on later pages. default true.
- `insights` (boolean, optional): Add `insights`, charts as data over every match, each with a one-sentence answer, its count, scope, source and date: per criterion how many matches meet it, leave it unsaid or contradict it (and how many would state everything without it); with one price limit, what it reaches among premises of this kind and place before the limit, else what the matches ask per m²; and where the matches are by district or town. Asking prices; each unit counted once. default false.

## How do I call search_premises?

Required arguments only, with placeholder values; see the parameters above for real ones.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_premises",
    "arguments": {
      "brief": "…"
    }
  }
}
```

## Related pages

- [Refine a search (refine_search)](/docs/claro/refine_search)
- [Get one premises (get_premises)](/docs/claro/get_premises)
- [Compare premises (compare_premises)](/docs/claro/compare_premises)
- [What premises ask in a place (market_snapshot)](/docs/claro/market_snapshot)
- [Claro AI: all its MCP tools and REST operations](/docs/claro)
- [Connect Claro to an MCP client](/docs/claro/connect)