find_estaite_submarkets_by_criteria

Description

Filters submarkets by combinations of state, CBSA, rent range, year-over-year growth, and vacancy. Returns matching submarkets with key metrics for the apt 2 BR slice (the default — see Notes below). Use this for “show me submarkets under $1,500 in Texas” or “growing markets in Dallas”.

Inputs

Name	Type	Required	Description
state	string (2-letter)	no	US state code, filters on submarket’s CBSA state.
cbsa_code	string	no	Numeric CBSA code, exact match (e.g. "19100" for Dallas-Fort Worth).
cbsa_name	string	no	Partial CBSA name match (e.g. "Dallas").
min_rent	number	no	Minimum median monthly rent in USD.
max_rent	number	no	Maximum median monthly rent in USD.
min_yoy_growth	number	no	Minimum year-over-year rent growth as whole-percent — e.g. 5 for 5%. (See note below — the underlying field stores values like 5.0, not 0.05.)
max_vacancy	number	no	Maximum vacancy rate as whole-percent — e.g. 8 for 8%.
limit	integer 1–50	no	Max results. Default 25, hard cap 50.

Caution

The MCP server’s input schema description for min_yoy_growth and max_vacancy currently says these should be passed as decimals (0.05 for 5%). That description is wrong — the implementation compares them against the underlying database columns, which store percentages as whole numbers. Pass 5, not 0.05. If you pass 0.05 the filter will be >= 0.05, which matches almost everything since real YoY values are typically in the range -10 to +10.

Response

{
  "attribution": "Data via Estaite Submarket Index",
  "powered_by": "Estaite.com",
  "source_domains": [],
  "property_type": "apt",
  "bedrooms": 2,
  "criteria_applied": { "state": "TX", "max_rent": 1500, "limit": 25 },
  "count": 12,
  "data": [
    {
      "id": 3104,
      "name": "East Riverside",
      "zipcodes": "78741",
      "cbsa": "Austin-Round Rock-San Marcos, TX",
      "state": "TX",
      "as_of": 202603,
      "median_rent": 1420.0,
      "rent_yoy_change": 6.2,
      "vacancy_rate": 7.1,
      "avg_dom": 28,
      "rent_to_income": 31.5
    }
  ]
}

Fields

Field	Type	Description
attribution	string	Data attribution. Becomes "Data provided by …" when responses include licensed customer data.
powered_by	string	Always "Estaite.com".
source_domains	string[]	List of contributing domains/companies (empty when no licensed data is involved).
property_type	string	The slice the comparison ran over — always "apt" in the current release.
bedrooms	number	The bedroom count the comparison ran over — always 2 in the current release.
criteria_applied	object	Echo of all criteria that were honored.
count	number	Number of records returned (≤ limit).
data[].id	number	Submarket id.
data[].name	string	Submarket name.
data[].zipcodes	string	Comma-separated ZIPs aggregated into the submarket.
data[].cbsa	string	CBSA / metro name.
data[].state	string	2-letter state code.
data[].as_of	number	Year-month of the underlying data, format YYYYMM (e.g. 202603).
data[].median_rent	number	Median monthly rent, USD.
data[].rent_yoy_change	number	YoY rent change in whole-percent (e.g. 6.2 = +6.2%).
data[].vacancy_rate	number	Vacancy rate in whole-percent (e.g. 7.1 = 7.1%).
data[].avg_dom	number	Average days on market for the slice.
data[].rent_to_income	number	Rent-to-income ratio in whole-percent (e.g. 31.5 = 31.5% of household income).

Errors

This tool does not raise tool-specific error codes. Invalid combinations simply return count: 0 and an empty data array. Generic upstream failures (database, auth, rate limit) bubble up as the standard MCP error envelope.

Notes

• Always uses apt / 2 BR. The implementation defaults the slice to apartments / 2 bedrooms and currently has no public way to change it. The response echoes property_type and bedrooms for transparency.
• source_domains aggregates across all returned submarkets. If any submarket in the result set is licensed customer data, that domain appears in the array — and the attribution flips to "Data provided by …".
• Sorted by submarket name, alphabetically — not by rent, growth, or any other metric. To rank, see rank_estaite_submarkets.