new.estate

Search listings

search_listings

Read-onlyIdempotent

Use this when the user is looking for a property to buy or rent — a home, apartment, plot or commercial space — or asks what is on offer in a place, in a price range or of a given size. Searches real-estate listings published on new.estate in many countries and returns matching listings with price, area, location and the URL of each listing page. The accepted property type and country values are listed by get_catalog. The listing URL is the page to cite for each result. Do not use for publishing a listing; get_publishing_info covers that.

Input Schema

Name	Required	Description	Default
`sort`	No	Result order; default is the portal's own order. Sorting by price puts listings that do not disclose a price last.	default
`limit`	No
`rooms`	No	Room counts to include; 6 means six or more.
`shelf`	No	Limit to standard or to premium (prestige) listings.
`cursor`	No	nextCursor of the previous page.
`locale`	No	Language of names, titles, descriptions and listing URLs, e.g. en-US, pl-PL, de-DE.	en-US
`country`	No	ISO 3166-1 alpha-2 country code, upper case, e.g. PL, ES.
`maxArea`	No
`minArea`	No
`areaUnit`	No	Unit of minArea/maxArea: square metres (m) or square feet (ft).	m
`currency`	No	ISO 4217 code of minPrice/maxPrice. Required with a price bound; listings in other currencies are compared after conversion. Listings that do not disclose a price (auction or tender) are left out of any search with a price bound.
`features`	No	Only listings that have every feature given.
`latitude`	No
`location`	No	Free-text place: city, district or street. Matched against the listing address, ignoring case and diacritics.
`maxPrice`	No
`minPrice`	No
`radiusKm`	No	Search radius in kilometres around latitude/longitude. All three must be given together.
`longitude`	No
`propertyTypes`	No	Property type values from the catalog (e.g. APARTMENT, HOUSE, PLOT). A base type also matches its variants.
`transactionType`	No	Sale or rent.
`publishedWithinDays`	No	Only listings first published in the last 7 or 30 days.

Output Schema

Name	Required	Description
`source`	Yes
`listings`	Yes
`nextCursor`	Yes
`totalCount`	Yes	Number of matching listings; given on the first page only.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 24, 2026

changedInput schema / properties / locale / enum

Previous value: -[
-  "en-US",
-  "en-GB",
-  "en-AU",
-  "en-CA",
-  "en-IE",
-  "en-NZ",
-  "pl-PL",
-  "cs-CZ",
-  "sk-SK",
-  "hr-HR",
-  "sr-RS",
-  "sl-SI",
-  "bg-BG",
-  "fr-FR",
-  "fr-CH",
-  "fr-BE",
-  "fr-CA",
-  "de-DE",
-  "de-AT",
-  "de-CH",
-  "es-ES",
-  "es-MX",
-  "es-AR",
-  "es-CO",
-  "es-CL",
-  "it-IT",
-  "ro-RO",
-  "nl-NL",
-  "nl-BE",
-  "sv-SE",
-  "da-DK",
-  "nb-NO",
-  "fi-FI",
-  "hu-HU",
-  "el-GR",
-  "lt-LT",
-  "lv-LV",
-  "et-EE",
-  "uk-UA",
-  "pt-PT",
-  "pt-BR"
-]New value: +[
+  "en-US",
+  "en-GB",
+  "en-AU",
+  "en-CA",
+  "en-IE",
+  "en-NZ",
+  "pl-PL",
+  "cs-CZ",
+  "sk-SK",
+  "hr-HR",
+  "sr-RS",
+  "sl-SI",
+  "bg-BG",
+  "fr-FR",
+  "fr-CH",
+  "fr-BE",
+  "fr-CA",
+  "de-DE",
+  "de-AT",
+  "de-CH",
+  "es-ES",
+  "es-MX",
+  "es-AR",
+  "es-CO",
+  "es-CL",
+  "it-IT",
+  "ro-RO",
+  "nl-NL",
+  "nl-BE",
+  "sv-SE",
+  "da-DK",
+  "nb-NO",
+  "is-IS",
+  "fi-FI",
+  "hu-HU",
+  "el-GR",
+  "lt-LT",
+  "lv-LV",
+  "et-EE",
+  "uk-UA",
+  "pt-PT",
+  "pt-BR"
+]

Changed2 schema fields changedOct 18, 2026

addedOutput schema / properties / listings / items / properties / promoted

Added value: +{
+  "description": "True when the advertiser paid to move the listing up the default order (a bump); the listing page marks it the same way.",
+  "type": "boolean"
+}

changedOutput schema / properties / listings / items / required

Previous value: -[
-  "id",
-  "url",
-  "title",
-  "transactionType",
-  "propertyType",
-  "shelf",
-  "price",
-  "priceHidden",
-  "pricePerAreaUnit",
-  "area",
-  "rooms",
-  "bedrooms",
-  "floor",
-  "totalFloors",
-  "location",
-  "availability",
-  "image",
-  "publishedAt",
-  "project",
-  "openHouse",
-  "source"
-]New value: +[
+  "id",
+  "url",
+  "title",
+  "transactionType",
+  "propertyType",
+  "shelf",
+  "price",
+  "priceHidden",
+  "pricePerAreaUnit",
+  "area",
+  "rooms",
+  "bedrooms",
+  "floor",
+  "totalFloors",
+  "location",
+  "availability",
+  "image",
+  "publishedAt",
+  "promoted",
+  "project",
+  "openHouse",
+  "source"
+]

First observedOct 18, 2026

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds value by stating the returned fields (price, area, location, URL) and the citation requirement for the listing URL. It does not discuss pagination behavior or result-cap semantics, though the cursor parameter is documented in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, front-loaded with the trigger before scope, catalog pointer, citation note and exclusion. Slightly redundant in that the URL is mentioned in the return-fields sentence and again as a citation instruction, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 21-parameter search with full annotations and an output schema, the description covers intent, scope, value sources, and the sibling boundary. Remaining gaps (pagination flow, result cap of 24, sort ordering) are already documented in the schema, so nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 21 parameters at 67% schema description coverage, the schema does most of the work, including enum and unit semantics. The description only gestures at filters ('in a price range or of a given size', 'in a place') and defers accepted values to get_catalog, adding little parameter-level meaning beyond the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Searches real-estate listings published on new.estate') plus the user intents it serves (buy/rent, home/apartment/plot/commercial). It also distinguishes itself from siblings by naming get_catalog for valid values and get_publishing_info as the wrong tool for publishing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Opens with an explicit trigger condition ('Use this when the user is looking for...') and closes with a negative case plus the correct alternative ('Do not use for publishing a listing; get_publishing_info covers that'). An agent can route between this, get_listing, find_similar_listings and get_publishing_info without inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All new.estate tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?