# `refine_search`

> **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).

Refine a search. Product: [Claro AI](/docs/claro).

Call it as `refine_search` 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/refine`](/docs/rest/claro/refine-search) (equivalent). [MCP and REST compared](/docs/parity#claro-ai).

## What does Refine a search do?

Change part of an earlier search in plain words ("bigger, at least 200 m²", "Barcelona too", "drop the corner") and run it again, as a new search with its own search_id and pages. Uses the search_id from search_premises; searches are kept 24 hours. Results as search_premises gives them, location figures with `location_sources`. 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.

## Which parameters does refine_search take?

- `search_id` (string, required)
- `change` (string, optional): What to change, in plain words. Required unless cursor is sent.
- `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) 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 refine_search?

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

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

## Related pages

- [Search commercial premises (search_premises)](/docs/claro/search_premises)
- [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)