Skip to main content
Glama
chrischall

compass-mcp

by chrischall
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Search Compass listings

compass_search_properties
Read-onlyIdempotent

Search Compass listings by city, ZIP, or neighborhood and filter by price, beds, and home type to retrieve details like address, price, beds, baths, and square footage.

Instructions

Search Compass listings by location (city, ZIP, neighborhood) and optional filters. Resolves free-text via slugification into Compass's URL routing, then fetches the SSR search-results page and extracts the embedded listings array. Compass server-renders ~41 listings into that page (its num), and total_items reports the full market count. PAGINATION (issue #87): Compass no longer paginates the SSR search via any URL — /page-N/, ?page=N, and ?start=N all canonicalize back to page 1 and return the identical listings, so only the first SSR page (~41 listings) is reachable through this primitive. offset is honored WITHIN that page, and next_offset is emitted only when more listings remain within it — it is never a false cursor that re-fetches page 1. TO REACH BEYOND THE FIRST PAGE, narrow with price_min / price_max / beds_min/beds_max to bucket the result set into <~41-listing bands (price-banding), then search each band. Returns each matching listing's address, price, beds/baths, sqft, lat/lng, the Compass homedetails URL (_lid/ form, content-addressed by listing_id_sha), and the stable _pid/ URL via property_url and the surfaced pid field. The per-listing primary_photo_url / primary_thumbnail_url are omitted in the default compact view (they are Compass CDN URLs a model cannot see); pass view: "full" to get them, or compass_get_property_photos for the whole gallery. USE pid/_pid/ FOR LONG-LIVED REFERENCES (trackers, sheets, bookmarks) — sha-based _lid/ URLs change when a property is delisted and relisted. Use the sha-based URL to fetch the current listing record. Read-only; safe to call repeatedly.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
viewNoResponse shape: "compact" (default) drops fields the response already carries elsewhere; "full" returns every field this server understands. compact strips image/avatar URLs from the response; "full" returns Compass's payload untouched. No field projection: this server has no verified record of which Compass fields matter, and inventing one would risk dropping a field a caller needs.
limitNoMax listings to return (default 40). Only the first SSR page (~41 listings) is reachable (#87), so a limit above that is capped by the page; use price/beds banding to reach more.
offsetNoZero-based offset into the reachable first SSR page. Honored only within that page (#87); use the `next_offset` value from a previous response to continue within it. An offset at or beyond the page returns no results — narrow with price/beds bands to reach more. Default 0.
beds_maxNo
beds_minNo
locationYesFree-text location: city, ZIP, neighborhood (e.g. "Brooklyn, NY", "94110", "Park Slope")
home_typeNoRestrict to a single property type.
price_maxNo
price_minNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.0.0
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  2. Changed1 schema field changedv0.14.0
    • addedInput schema / properties / view
      Added value: +{
+  "description": "Response shape: \"compact\" (default) drops fields the response already carries elsewhere; \"full\" returns every field this server understands. compact strips image/avatar URLs from the response; \"full\" returns Compass's payload untouched. No field projection: this server has no verified record of which Compass fields matter, and inventing one would risk dropping a field a caller needs.",
+  "enum": [
+    "compact",
+    "full"
+  ],
+  "type": "string"
+}
  3. First observedv0.12.1

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses the ~41-listing SSR page ceiling, #87 pagination canonicalization, offset/next_offset semantics, stable pid vs sha-based URL behavior, and photo URL omission in compact view. This is deep behavioral context an agent needs to avoid false cursor loops and stale references.

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

Conciseness5/5

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

The description is long but every sentence earns its place: purpose is front-loaded, then critical caveats are grouped into PAGINATION, banding, return-field, and URL-stability sections. There is no filler or repetition beyond a harmless closing read-only note.

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

Completeness5/5

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

Given no output schema and a complex search with pagination and URL nuances, the description enumerates the returned fields (address, price, beds/baths, sqft, lat/lng, _lid/ and _pid/ URLs, pid) and explains the total_items/num context. An agent has enough to call it correctly and interpret results.

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

Parameters5/5

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

With only 56% schema coverage, the description compensates by explaining view modes ('compact' strips image URLs), limit/offset caveats tied to #87, and the price/beds banding strategy for params that have bare schema entries. It adds actionable meaning beyond what the schema alone provides.

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?

The opening sentence delivers a specific verb and resource: 'Search Compass listings by location (city, ZIP, neighborhood) and optional filters.' It goes on to describe the retrieval mechanism and return payload, so an agent can distinguish this search primitive from single-property siblings like compass_get_property or compass_get_by_address.

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

Usage Guidelines4/5

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

The description gives strong operational guidance: narrow with price/beds bands to reach beyond the first SSR page, use next_offset to continue within a page, and pass view:'full' or switch to compass_get_property_photos for images. It stops short of explicitly ruling out when not to use search in favor of property-detail tools, though the names and returned URL guidance make the distinction mostly clear.

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

Deploy Server

Other Tools