Skip to main content
Glama

Find places by their rental market

findPlacesByMarket
Read-onlyIdempotent

Rank Canadian or US places by rental market facts (vacancy, rent, rent growth, permits, population). Read-only; signed-in only. Pass country (CA or US; places rank only within one country) and a preset (CA: tight-rental, fast-rent-growth, undersupplied, mli-select-headroom; US: low-rental-vacancy, car-light), filters ({ key, min, max } inclusive, or top/bottom percent), or both; optional region (province or state), sort, limit (default 20, max 50) and offset. An unknown key returns the filterable keys. Returns counts { places, matched, inPlan, excluded, unknown }, matched places with their values and access, and the places missing a filtered value. Report the unknown count: a missing value is not a match and not a fail. truncation.places.nextOffset is the next offset. Each matched place has access: in_plan (the user can screen its lots), available or not_sold (not in the user's plan). Say how many matches are in_plan. Only screen lots in in_plan places. To run a saved filter set, pass setId from listPlaceMarketSets with limit and offset only. unavailableFilters lists stored filters that were skipped; tell the user. Cite every figure with the sources lines (CMHC for CA, ACS for US). Tell the user each filter used, in plain words with units: each result filter has a text field. To find lots, call screenLots with the geoDivisionId of each in_plan place.

Turning a question into filters: pick the country from the place named (Ontario, Texas). Put a province or state in region. Map each condition to the closest key below. "Tight" or "low vacancy" is a max on a vacancy key; "growing" or "rising" is a min on a change key; "above" is min, "below" is max. Percent bounds are numbers: 5 means 5%. Money bounds are in the country's own dollars.

A relative question ("top quarter for rent growth", "lowest 10% vacancy in the province") is a percentile filter: top keeps the highest-valued share of places, bottom the lowest, as a percent (25 = 25%), instead of min and max. It ranks within the request's places, so give a region for "in the province". Each result filter states the cut value it resolved to in text.

Never invent a key. If no key below measures what was asked (for example a comparison to a provincial median), say so, name the nearest key, and use a numeric bound you state. Tell the user every filter you used, in plain words with units, before or with the result: each result filter has a text field for this.

On an UNKNOWN_KEY or CROSS_SCOPE error, read errorDetails and call again in the same turn with a key or region from it.

CA keys: population_density_per_sq_km: Density (people per km²). median_age: Median age (years). median_household_income: Median household income (CAD dollars). owner_occupied_pct: Owner-occupied (%). renter_occupied_pct: Renter-occupied (%). median_home_value: Median home value (CAD dollars). median_gross_rent: Median gross rent (CAD dollars). cmhc_rental_vacancy_rate: Purpose-built rental vacancy (%). cmhc_rental_availability_rate: Purpose-built rental availability (%). cmhc_avg_rent_studio: Avg rent, studio (purpose-built) (CAD dollars). cmhc_avg_rent_1br: Avg rent, 1BR (purpose-built) (CAD dollars). cmhc_avg_rent_2br: Avg rent, 2BR (purpose-built) (CAD dollars). cmhc_avg_rent_3br_plus: Avg rent, 3BR+ (purpose-built) (CAD dollars). cmhc_avg_rent_total: Avg rent, all units (purpose-built) (CAD dollars). cmhc_median_rent_total: Median rent, all units (purpose-built) (CAD dollars). cmhc_avg_rent_built_2000_plus: Avg rent, built 2000 or later (purpose-built) (CAD dollars). cmhc_avg_rent_change_pct: Avg rent change, same units (purpose-built) (%). signal_rent_cagr_5y_pct: Rent change, annualized over 5 years (%). signal_rental_vacancy_trend_3y_pp: Purpose-built rental vacancy change over 3 years (percentage points). signal_new_build_rent_premium_pct: Newer-building rent difference (built 2000 or later vs all units) (%). signal_rental_pipeline_pct: Rental units under construction as a share of purpose-built rental units (%). signal_rental_starts_momentum_pct: Rental starts, last 12 months vs the 12 months before (%). signal_mli_affordability_gap_pct: MLI Select rent difference as a share of average rent (%). signal_population_cagr_census_5y_pct: Population change per year, Census 2016 to 2021 (%). signal_household_income_cagr_census_5y_pct: Median household income change per year, Census 2016 to 2021 (2015 to 2020 incomes, nominal) (%).

US keys: population_density_per_sq_km: Density (people per km²). median_age: Median age (years). acs_households_no_vehicle_pct: Households with no vehicle (%). acs_households_one_vehicle_pct: Households with one vehicle (%). acs_households_two_plus_vehicles_pct: Households with two or more vehicles (%). acs_vehicles_per_household: Vehicles per household (vehicles per household). acs_commute_drove_alone_pct: Commute: drove alone (%). acs_commute_carpool_pct: Commute: carpool (%). acs_commute_transit_pct: Commute: public transit (%). acs_commute_walk_pct: Commute: walked (%). acs_commute_work_from_home_pct: Worked from home (%). median_household_income: Median household income (USD dollars). hud_ami_median_family_income: HUD area median family income (USD dollars). owner_occupied_pct: Owner-occupied (%). renter_occupied_pct: Renter-occupied (%). vacancy_rate: Vacancy rate (%). median_home_value: Median home value (USD dollars). median_gross_rent: Median gross rent (USD dollars). acs_rental_vacancy_rate: ACS rental vacancy rate (all rental units) (%). acs_median_gross_rent_built_2020_plus: ACS median gross rent, built 2020 or later (all rental units) (USD dollars). hud_fmr_efficiency: HUD FMR — efficiency (USD dollars). hud_fmr_one_bedroom: HUD FMR — 1BR (USD dollars). hud_fmr_two_bedroom: HUD FMR — 2BR (USD dollars). hud_fmr_three_bedroom: HUD FMR — 3BR (USD dollars). hud_fmr_four_bedroom: HUD FMR — 4BR (USD dollars). signal_rent_cagr_5y_pct: Rent change, annualized over 5 years (%). signal_rental_vacancy_trend_5y_pp: Rental vacancy change over 5 years (all rental units) (percentage points). signal_rent_premium_built_2020_plus_pct: Newer-building rent difference (built 2020 or later vs all units) (%). signal_multifamily_permits_pct: Units permitted in 5+ unit buildings, 12 months, as a share of renter-occupied units (%). signal_multifamily_permits_momentum_pct: Units permitted in 5+ unit buildings, last 12 months vs the 12 months before (%). signal_lihtc_rent_gap_pct: LIHTC 2-bedroom rent limit difference as a share of median gross rent (%). signal_population_cagr_acs_5y_pct: Population change per year, ACS 2015–2019 to 2020–2024 (%). signal_household_income_cagr_acs_5y_pct: Median household income change per year, ACS 2015–2019 to 2020–2024 (nominal) (%). signal_home_value_cagr_acs_5y_pct: Median home value change per year, ACS 2015–2019 to 2020–2024 (nominal) (%).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "context": "<context>"
    },
    "name": "findPlacesByMarket"
  }
}

Input Schema

NameRequiredDescriptionDefault
sortNoDefaults to the preset sort, else the first filter key
limitNo
setIdNoRun one of your saved filter sets, by id from listPlaceMarketSets. Pass it with limit and offset only.
offsetNoMatched places to skip. Copy truncation.places.nextOffset for the next page.
presetNoA preset id for the country; its filters apply first, then `filters` by key
regionNoProvince or state, as a code (AB) or a name (Alberta)
contextYesA few words on why you are calling this tool, for the server developer's analytics. Describe people and things by role, such as "a customer". Do not quote the user or include names, emails, or other personal details.
countryNoISO country code. Places are filtered and ranked only within this country.
filtersNo
conversation_idNoThe conversation_id this server returned earlier in this conversation, unchanged, including after later user messages. Omit it if you have none. Recorded for the server developer's analytics.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / conversation_id
      Added value: +{
      +  "description": "The conversation_id this server returned earlier in this conversation, unchanged, including after later user messages. Omit it if you have none. Recorded for the server developer's analytics.",
      +  "type": "string"
      +}
  2. Changed2 schema fields changed
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / context / description
      Previous value: -"Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as \"a user\", \"the customer\", or \"an account\". Example: \"Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution.\""New value: +"A few words on why you are calling this tool, for the server developer's analytics. Describe people and things by role, such as \"a customer\". Do not quote the user or include names, emails, or other personal details."
  3. Changed2 schema fields changed
    • addedInput schema / properties / setId
      Added value: +{
      +  "description": "Run one of your saved filter sets, by id from listPlaceMarketSets. Pass it with limit and offset only.",
      +  "format": "uuid",
      +  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      +  "type": "string"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "country",
      -  "context"
      -]New value: +[
      +  "context"
      +]
  4. Changed2 schema fields changed
    • addedInput schema / properties / filters / items / properties / bottom
      Added value: +{
      +  "description": "Percentile band (BUC-4011): keep the lowest-valued share of places with a current value, as a percent. 25 = the lowest 25%. Use instead of min and max.",
      +  "exclusiveMaximum": 100,
      +  "exclusiveMinimum": 0,
      +  "type": "number"
      +}
    • addedInput schema / properties / filters / items / properties / top
      Added value: +{
      +  "description": "Percentile band (BUC-4011): keep the highest-valued share of places with a current value, as a percent. 25 = the highest 25%. Use instead of min and max.",
      +  "exclusiveMaximum": 100,
      +  "exclusiveMinimum": 0,
      +  "type": "number"
      +}
  5. Changed2 schema fields changed
    • changedInput schema / properties / country / description
      Previous value: -"ISO country code. CA has market data today; US follows."New value: +"ISO country code. Places are filtered and ranked only within this country."
    • addedInput schema / properties / offset
      Added value: +{
      +  "default": 0,
      +  "description": "Matched places to skip. Copy truncation.places.nextOffset for the next page.",
      +  "maximum": 10000,
      +  "minimum": 0,
      +  "type": "integer"
      +}
  6. Added

TDQS

A4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description adds real behavior beyond that: sign-in requirement, per-place `access` values (in_plan/available/not_sold), the counts object, unknown-vs-nonmatch semantics, truncation.nextOffset paging, and source citation rules. The remaining gap is that the return shape is described in prose only with no output schema, and per-place value formatting is left implicit.

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

Conciseness3/5

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

The operating instructions are front-loaded and well ordered (purpose, filter mapping, errors, keys), but the text is very long and repeats itself: "tell the user every filter used, in plain words with units, each result filter has a `text` field" appears three times in near-identical form, and citation guidance is restated. The exhaustive key catalog is defensible as discovery support but dominates the definition.

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 10-parameter tool with nested filter objects and no output schema, the description covers return values (counts, matched places, access, missing-value places, truncation) and error recovery nearly completely. Minor shortfall: the meaning of `context` and `conversation_id` analytics fields and the exact matched-place payload shape are left to the schema.

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 80% schema description coverage the baseline is 3, and the description earns credit by enumerating valid presets per country, explaining top/bottom as percentile bands that rank within the request's places, and listing every legal filter key with units. However, that enumerative mass sits outside the tool's own parameter explanation and the interaction between preset filters and explicit filters is only sketched ("apply first, then filters by key").

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 — "Rank Canadian or US places by rental market facts" — and immediately scopes it to country, presets and filters. An agent can distinguish it from siblings like screenLots because the description explicitly assigns lot-screening to screenLots and ranking to this tool.

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?

Gives explicit when-to-use routing (saved set via setId from listPlaceMarketSets, country-specific preset ids, filters, or both) plus how to convert a natural-language question into bounds ("tight" = max on vacancy, "above" = min). It names the alternative tool for the downstream step, states what to do when no key measures the ask, and prescribes recovery on UNKNOWN_KEY/CROSS_SCOPE by re-calling with errorDetails.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.