Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@compass-mcp show me recent listings in downtown Austin"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Compass real-estate access as an MCP server for Claude — search listings, fetch property details, photo galleries, price history, and run affordability/mortgage math, all via natural language.
⚠️ Compass does not publish a public consumer API. This server scrapes the same server-rendered HTML compass.com itself ships to your browser, routed through your own signed-in browser tab via the fetchproxy extension. Every request acts on behalf of your existing session — your cookies, your TLS, your JS context — exactly as if you'd clicked it in the browser yourself. Treat this as informal use of Compass's website. Use at your own discretion.
Tool | Purpose | Auth-scoped |
| Search listings by location, price band, beds, home type. Slugifies free-text into Compass's URL routing and extracts the SSR listings array. | |
| Full record for a property by URL or | |
| Full photo gallery — every image in | |
| Full listing-history events (Listed / Sold / Pending / Price Change / Delisted) with date, price, status, and MLS attribution. Returns both this-listing and prior-listing aggregates. | |
| Side-by-side comparison of up to 25 properties with an opt-in aligned summary table. Per-target errors captured per-row. Concurrent fetches. | |
| Local affordability calculator — max purchase price from income + DTI + rates. No network. | |
| Resolve a free-text street address to the canonical Compass URL, | |
| Local PITI calculator — principal+interest, taxes, insurance, HOA, PMI. No network. | |
| Not yet supported — Compass renders /overview/favorites via auth-scoped GraphQL we have not yet identified. Throws a clear "not yet wire" error. | ✓ |
| Not yet supported — same constraint as saved homes. | ✓ |
Related MCP server: NDI-MCP-Server
By using this MCP server, you acknowledge and agree to the following:
1. This server accesses your own Compass session. Every request is dispatched through your own browser tab via the fetchproxy extension — your cookies, your TLS, your session. It does not — and cannot — access anyone else's account.
2. Compass's Terms of Use govern your use of this server, just as they govern your direct use of compass.com. The clauses most relevant here:
You may not automatedly crawl or query the Services for any purpose or by any means (including, without limitation, screen and database scraping, spiders, robots, crawlers and any other automated activity with the purpose of obtaining information from the Services) unless you have received prior express written permission from the applicable Compass Company.
And: "You agree to keep your password confidential, not use others' accounts, nor permit others to use your account."
You are agreeing to those terms — read by the maintainer 2026-05-23 — every time you invoke a tool in this server. Compass's terms prohibit automated crawling without written permission, and IDX listing data is licensed for personal, non-commercial use only.
3. Personal, non-commercial use only. This project is not affiliated with, endorsed by, sponsored by, or in partnership with Compass, Inc. It is a personal automation tool that reads the same server-rendered HTML compass.com itself ships to your browser. Do not use it to bulk-extract listings, redistribute IDX data, train AI models, populate a competing real-estate product, or for any commercial purpose.
4. Stability is not guaranteed. This server reads private inline-script state (global.uc.sharedReactAppProps, window.__INITIAL_DATA__.props.listingRelation.listing) and SSR URL conventions (/homes-for-sale/<slug>/, /homedetails/<slug>/<id>_lid/) that Compass may change without notice. It may break. It may stop working. That's by design — the surface is not theirs to maintain on our behalf.
5. You accept full responsibility for any consequences of using this server in connection with your Compass access — rate limiting, account suspension, IP blocks, AWS WAF challenges, or any enforcement action Compass takes. If Compass objects to your use, stop using this server.
This section is the maintainer's good-faith summary of the terms — it is not legal advice and does not modify or supersede Compass's actual ToU.
Add to .mcp.json:
{
"mcpServers": {
"compass": {
"command": "npx",
"args": ["-y", "compass-mcp"]
}
}
}git clone https://github.com/chrischall/compass-mcp
cd compass-mcp
npm install
npm run build{
"mcpServers": {
"compass": {
"command": "node",
"args": ["/path/to/compass-mcp/dist/bundle.js"]
}
}
}compass-mcp talks to your browser through the fetchproxy extension, which is shared across every fetchproxy-based MCP (zillow-mcp, opentable-mcp, resy-mcp, …). Install it once:
git clone https://github.com/chrischall/fetchproxy
cd fetchproxy
npm ci
npm --workspace=@fetchproxy/extension-chrome run buildThen in Chrome: chrome://extensions → toggle Developer mode → Load unpacked → pick packages/extension-chrome/dist/.
Open compass.com and sign in. That's all the auth this server needs.
┌────────────────┐ stdio ┌──────────────────┐ WS ┌──────────────────┐ fetch() ┌─────────────┐
│ MCP client │◀────────▶│ dist/bundle.js │◀──────▶│ fetchproxy │◀────────────▶│ compass.com │
│ (Claude, etc.) │ │ (Compass MCP) │ :37149 │ extension │ (real TLS, │ (your tab) │
└────────────────┘ └──────────────────┘ │ (separate) │ cookies) └─────────────┘The MCP server runs in Node, but every HTTP call to compass.com is dispatched into your live browser tab through the fetchproxy extension. Each request rides your existing session — TLS fingerprint, cookies, and JS execution context all match the page that's already on screen. No headless browser stand-in, no separate identity, no third-party proxy: just your real browser, acting on its own behalf, with the MCP server picking what to ask for.
Compass's pages are SSR React with no public JSON API — every tool extracts data from inline-script globals (global.uc.sharedReactAppProps on search pages, window.__INITIAL_DATA__.props.listingRelation.listing on homedetails). The client wraps that into the tool surface so callers never have to parse HTML themselves.
npm test # vitest, mocked transport, no network
npm run test:watch
npm run test:coverage
npm run build # tsc --noEmit + esbuild bundle → dist/bundle.js
npm run dev # node dist/bundle.js (after build)MIT
Fetch up to 200 Compass listings in a single call. Returns one structured row per input target (no side-by-side summary table — use compass_compare_properties for that). Each row is either { listing_id_sha, url, property } on success or { listing_id_sha, url, error } on failure — one bad target never fails the whole call. When the failure was a bridge timeout (after one retry) or an unreachable bridge (issue #73), the row also carries { status: "timeout" | "bridge_down", retryable: true } — that is NOT a missing listing, so retry it (a cold bridge usually succeeds on the second call) rather than concluding Compass has no record. Targets accept the same url / listing_id_sha shape as compass_get_property. Calls fan out concurrently. extracted_features is populated per row. The raw description is omitted by default — pass include_description: true to keep it.
| Name | Required | Description | Default |
|---|---|---|---|
| targets | Yes | Up to 200 targets to fetch. For higher counts, batch into multiple calls. | |
| include_description | No | Include the raw `description` on each row. Defaults to `false` — `extracted_features` is always populated. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses batch size limit (200), concurrency, error handling (one bad target doesn't fail whole call), retryable flag, default omission of description, and always-included extracted_features. Adds significant context beyond annotations, no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with main purpose; each sentence adds distinct value (error handling, retry, concurrency, alternative tool). No fluff, efficient paragraph despite covering many aspects.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: purpose, input, output format, error handling, retry logic, default behavior, parallelism, and relation to siblings. Complete for complex bulk fetch tool without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but description adds meaning: explains output format per target, retryable conditions, default value of include_description, and references compass_get_property for target shape. Adds behavioral details not in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Fetch up to 200 Compass listings in a single call' with specific verb and resource. Distinguishes from sibling tools by referencing compass_compare_properties and compass_get_property for shape. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use (for bulk fetch) and when not (for summary table, use compass_compare_properties). Provides retry guidance for timeout/bridge_down errors, and notes targets have same shape as compass_get_property. Clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Solve for the maximum home price you can afford under the standard 28/36 DTI rule. Inputs: monthly income, recurring monthly debts (car/student loans), down payment, interest rate, optional property-tax rate / insurance / HOA / loan term. Output: max home price, binding constraint (front-end vs back-end), and the PITI breakdown at that price. Identical math to zillow-mcp and redfin-mcp. No network — pure local math.
| Name | Required | Description | Default |
|---|---|---|---|
| hoa_monthly | No | ||
| back_end_dti | No | ||
| down_payment | Yes | ||
| front_end_dti | No | ||
| interest_rate | Yes | ||
| monthly_debts | No | ||
| monthly_income | Yes | ||
| loan_term_years | No | ||
| insurance_annual | No | ||
| property_tax_rate | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by explaining the calculation is local (no network), uses the 28/36 rule, and lists the output (max price, binding constraint, PITI). This supplements the readOnlyHint and idempotentHint annotations well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (5 sentences) and front-loaded with purpose, then inputs/outputs, then comparison and behavior. No wasted words; each sentence provides essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core calculation and output but omits default values for DTI ratios (assumed 28/36) and does not handle error conditions. Given no output schema, the output description helps, but missing parameter details reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must document parameters. It lists 8 of 10 parameters (missing front_end_dti and back_end_dti) and doesn't specify units (e.g., interest rate as decimal or percent). This leaves ambiguity for an AI agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool solves for maximum home price under the 28/36 DTI rule, lists inputs and outputs, and distinguishes itself from sibling tools like zillow-mcp and redfin-mcp. It specifies it's a pure local calculation, no network, which sets it apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (wanting to calculate affordability) and mentions it's identical to other MCPs, but does not explicitly exclude alternatives like compass_calculate_mortgage or state when not to use it. However, the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Local-only mortgage payment calculator. Returns a full PITI breakdown (principal + interest, property tax, insurance, HOA, PMI) and total interest over the life of the loan. No network call. Provide either down_payment OR down_payment_percent; defaults to 20%. Property tax can be given as property_tax_annual or property_tax_rate (% of home price). PMI applies automatically when LTV > 80% and pmi_rate is provided.
| Name | Required | Description | Default |
|---|---|---|---|
| pmi_rate | No | Annual %, applied when LTV > 80% | |
| home_price | Yes | ||
| hoa_monthly | No | ||
| down_payment | No | ||
| interest_rate | Yes | Annual %, e.g. 6.5 | |
| loan_term_years | No | Default 30 | |
| insurance_annual | No | ||
| property_tax_rate | No | Annual % of home price | |
| property_tax_annual | No | ||
| down_payment_percent | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavioral details beyond annotations: local-only, no network call, automatic PMI when LTV > 80%, default down payment of 20%.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose and output, no fluff. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains output components (PITI breakdown components, total interest) and key constraints. Does not detail exact output structure or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (40%), but description compensates by explaining key relationships (down_payment vs percent, property tax options, PMI condition). Does not cover all parameters (e.g., hoa_monthly, insurance_annual).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it is a local-only mortgage payment calculator returning PITI breakdown and total interest, with specific verb 'calculate' and resource 'mortgage'. Distinguishes from siblings like compass_calculate_affordability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: local-only, no network call, parameter choices (down_payment OR down_payment_percent). Does not explicitly contrast with siblings or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch 2 or more Compass properties and align their facts side-by-side. Each target may supply url (a full Compass homedetails URL or path) or listing_id_sha alone — sha-only targets fetch /listing//view, which redirects to the homedetails page. Returns the full per-property record per row (with extracted_features populated). Per-target errors are captured per-row — one bad target will not fail the whole call. Calls are concurrent. The raw description is omitted from each row by default — pass include_description: true to keep it. The redundant summary table is also opt-in via include_summary: true — by default only results[] is returned, which already carries every fact.
| Name | Required | Description | Default |
|---|---|---|---|
| targets | Yes | Array of 2–25 properties to compare. (Cap raised from 8 to 25 in #53; for unbounded structured fetch without the summary table, use `compass_bulk_get`.) | |
| include_summary | No | Include the pivoted `summary` table (one row per compared field, one column per listing). Defaults to `false` — `results[].property.*` already carries every fact and the summary was roughly 30% of response weight. Useful only for human-readable rendering. | |
| include_description | No | Include the raw `description` (Compass marketing copy) on each row. Defaults to `false` — `extracted_features` is always populated. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, openWorld, idempotent. Description adds valuable behavioral details: per-target error handling (one bad target doesn't fail all), concurrent calls, default omission of description and summary, and resolution behavior for listing_id_sha.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
While lengthy, the description is well-structured with main purpose first, then parameter details and behavioral notes. Some redundancy exists but is justified by complexity. Could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description fully explains the response structure: full per-property record, extracted_features populated, description and summary opt-in, error handling per row. Complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented. Description adds context: url preferred over listing_id_sha, explanation of sha resolution, and rationale for default false on include_description and include_summary. Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches multiple Compass properties and aligns facts side-by-side. It specifies input options (url or listing_id_sha) and distinguishes from sibling compass_bulk_get for unbounded fetches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool (comparing 2–25 properties) and when to use alternatives (compass_bulk_get for unbounded fetches without summary). Also notes cap raised from 8 to 25.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the listings represented by a Compass agent from their profile page (/agents//). Pass either slug (e.g. "paige-mcguirk") or profile_url (a full https://www.compass.com/agents// URL — both forms are accepted). Returns { agent: {name, slug}, active_listings: [...] }, where each active listing carries the SAME normalized fields as compass_get_property (address, beds/baths, sqft, lot size, price + price-per-sqft, MLS status, the canonical Compass URL + stable pid, extracted_features, etc.).
CLOSED DEALS: the agent's sold/closed deals are opt-in — pass include_closed: true to add a closed_deals array (same normalized shape). Omitted by default to keep the payload lean.
CHAINING: the agent slug is surfaced on each property's listing_agent.profile_slug in compass_get_property results (compass_search_properties results don't carry the listing agent), so you can go property → agent → their other listings. Read-only; safe to call repeatedly.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | Compass agent profile slug — the `<slug>` in /agents/<slug>/ (e.g. "paige-mcguirk"). One of `slug` or `profile_url` is required. | |
| view | No | 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. | |
| profile_url | No | Full Compass agent profile URL (e.g. https://www.compass.com/agents/paige-mcguirk/) or an /agents/<slug>/ path. Accepted as an alternative to `slug`. | |
| include_closed | No | Include the agent's closed/sold deals as a `closed_deals` array. Defaults to `false` to keep the response lean. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint/idempotentHint annotations: it specifies the exact return envelope, explains that active listings carry the same normalized fields as compass_get_property, discloses that closed deals are omitted by default unless include_closed: true, and states it is read-only and safe to call repeatedly. This gives an agent a detailed behavioral model without needing an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly long but well-structured with labeled sections (CLOSED DEALS, CHAINING), front-loaded primary behavior, and no wasted sentences. The only mild redundancy is 'Read-only; safe to call repeatedly,' which duplicates the annotations, but it is brief and harmless.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description provides a thorough return shape, field-level normalization guidance, default behavior, optional parameters, and chaining context. It covers the one-of slug/profile_url requirement in prose, and the schema covers the view parameter in detail. No major operational gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% description coverage for all four parameters, so the baseline is 3. The description adds extra value by clarifying that slug and profile_url are interchangeable alternatives, giving a concrete slug example, and specifying that include_closed appends a closed_deals array with the same normalized shape. This is meaningful but not exhaustive enough to merit a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Fetch the listings represented by a Compass agent from their profile page.' It also gives concrete examples of accepted identifiers ('paige-mcguirk', full URL) and distinguishes the data from what sibling tools return by referencing compass_get_property normalization and compass_search_properties' lack of listing agent info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: when you need an agent's full listing set, optional closed deals, or want to chain property → agent → other listings. It contrasts with compass_search_properties implicitly, but it does not explicitly state when NOT to use this tool versus alternatives like compass_get_property for a single property, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a free-text street address to a Compass listing's canonical URL and identifiers in one call. Walks three rungs: first the structured typeahead POST /api/v3/omnisuggest/autocomplete (the primary rung — Compass's address-suggest API, which routes around the AWS WAF that 403s the SSR free-text path, issues #78/#79), then /homes-for-sale/?q=<address> (the free-text rung) and — when those return no verified match — a slug-based search at /homes-for-sale/<city-state-or-zip>/ (the search-fallback rung, issue #71). Each candidate is verified against the query (case + street-type abbreviation normalization, then whole-token equality, issue #45) before being accepted. Returns { url, listing_id_sha, pid, address, resolved, matched_via } where matched_via is "typeahead", "freetext", or "search_fallback" so callers can see which rung found the match. When no rung matches, returns { resolved: false, error: "no listing matched" } rather than leaking a wrong URL. The url is the stable _pid/ form when Compass provides a navigationPageLink (preferred for trackers/bookmarks — sha URLs go stale on relisting), falling back to the _lid/ form otherwise. Read-only; safe to call repeatedly.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | ZIP code, e.g. "28746" | |
| city | No | e.g. "Lake Lure" | |
| view | No | 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. | |
| state | No | Two-letter state abbreviation, e.g. "NC" | |
| address | Yes | Street address line, e.g. "126 Sleeping Bear Ln". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already declare read-only/idempotent, the description adds substantial behavioral detail: the three-rung fallback strategy, WAF workaround, normalization/verification process, exact response shape including matched_via values, no-match error behavior, and URL-stability preference. This goes far beyond the annotations and gives the agent a precise model of edge cases. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description front-loads the purpose and then proceeds through matching rungs, verification, response, and failure cases in a logical order. It is long but mostly dense; the main deductions are for internal issue references (#78/#79, #71, #45) and WAF details that add context but are not directly actionable for invoking the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully compensates by specifying the return object fields, the possible matched_via values, the failure return shape, and the URL-form preference. It also covers the multi-rung resolution process and read-only safety, so an agent has everything necessary to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline applies; the schema already documents each parameter. The description adds only general matching semantics such as normalization and whole-token equality, not per-parameter guidance or format requirements, so it does not meaningfully raise the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific action — resolving a free-text street address to a Compass listing's canonical URL and identifiers — so the tool's purpose is unmistakable. It clearly distinguishes itself from search/get-property siblings in spirit, though it never names the closest sibling, compass_resolve_addresses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for free-text address resolution and notes it is read-only and safe to call repeatedly, but it does not explicitly state when to prefer this tool over alternatives or when not to use it. The closest sibling, compass_resolve_addresses, is never mentioned, leaving some routing responsibility to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Surface nearby rental listings for a Compass property — useful for evaluating STR (short-term-rental) viability in vacation markets. Lifts the target's city/state/zip from the homedetails page, then searches Compass's type-rental/ filter in the same locality and returns each rental's address, monthly price (in price_formatted), beds/baths, sqft, and the Compass URL. Honest-by-default: when no rentals come back, rentals: [] with the target locality preserved so the caller can decide to widen. Read-only; safe to call repeatedly.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Compass homedetails URL or path of the target property (preferred). | |
| limit | No | Max rental candidates to return. Default 20. | |
| listing_id_sha | No | Compass listing identifier. Sufficient on its own — the slug is resolved internally. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by explaining data extraction ('Lifts the target's city/state/zip'), the honest-empty behavior, and the output fields. It aligns with readOnlyHint and idempotentHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, each sentence provides essential information without redundancy. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers inputs (parameters with defaults), outputs (list of rentals with key fields), and edge cases (empty result behavior). However, it does not define 'nearby' proximity or mention pagination, though the tool appears simple.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds context: explains how `url` is used to extract location, and explicitly states the default for `limit` (20) not in schema. This adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Surface' and the resource 'nearby rental listings for a Compass property', and distinguishes it from siblings by specifying it's for comparable rentals, not general search or property details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use (evaluating STR viability) and describes behavior when no results are returned ('rentals: []' with locality preserved). However, it does not explicitly contrast with sibling tools like compass_search_properties.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full listing history for a Compass property — Listed / Sold / Pending / Price Change / Delisted events with date, price, and MLS attribution. Returns three arrays: events covers this listing's events, history aggregates events from prior listings of the same property, and events_normalized merges both into a shared cross-MCP schema ({date, type, price?, price_change_pct?, source_mls?} with a fixed type enum: Listed | PriceChange | Pending | Contingent | Sold | Withdrawn | Relisted | Delisted). Pass either url (the full Compass homedetails URL or path) or listing_id_sha alone — sha-only calls fetch /listing//view, which redirects to the homedetails page. Note: most of this data is already returned inline on compass_get_property (the events[] / history[] arrays live on the same listing record); call this tool only when you want the merged + normalized timeline. Read-only; safe to call repeatedly.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Compass homedetails URL or path (preferred — no resolver round-trip needed). | |
| listing_id_sha | No | Compass listing identifier. Sufficient on its own — the tool resolves the address slug internally via site search before fetching. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description aligns with annotations (readOnlyHint, idempotentHint). Adds behavioral context: sha-only calls require an internal redirect, and the tool is safe to call repeatedly. No contradiction; annotations already safe, description adds useful detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with the core purpose up front. Every sentence adds value, though slightly verbose (e.g., describing the normalized schema in detail). Could be more concise but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully describes the return structure (three arrays) and the normalized event schema with an enum. It also notes that most data is on compass_get_property, providing complete context for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning: 'url (preferred — no resolver round-trip needed)' and explains that listing_id_sha resolves internally via site search. This helps the agent choose between parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs and resources: 'Full listing history for a Compass property' with event types (Listed/Sold/Pending/Price Change/Delisted). It distinguishes the tool from siblings by noting that most data is on compass_get_property and this tool is for the merged/normalized timeline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call: 'call this tool only when you want the merged + normalized timeline' and when not to: 'most of this data is already returned inline on compass_get_property'. Also explains how to pass parameters (url preferred, listing_id_sha works alone).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a property's full Compass record. Pass either url (a full Compass homedetails URL or path from a compass_search_properties result) or listing_id_sha alone — when only the sha is supplied, the tool fetches /listing//view, which redirects to the canonical /homedetails//_lid/ page. Returns address, neighborhood, beds/baths, sqft, lot size (lot_size_sqft plus the derived lot_size_acres = round(sqft / 43560, 2), null — never 0 — for condos / missing lots), price + price-per-sqft, monthly charges, MLS status, amenities, schools, parcel number, and the canonical Compass URL. Also returns extracted_features (lake_front, hot_tub, basement, furnished, dock, community) keyword-parsed from the description.
DESCRIPTION HANDLING: The raw description (Compass marketing copy) is omitted by default — pass include_description: true to keep it. extracted_features is always populated and usually sufficient.
URL FORMS: Compass exposes two URL shapes for a listing. _lid/ (content-addressed by listing_id_sha) — what this tool fetches and what url returns — is the form to use for reading the current listing record. _pid/ (opaque short ID, in property_url and the surfaced pid field) is stable across re-listings and is the right choice for any long-lived reference (trackers, sheets, bookmarks); sha-based URLs go stale when a property is delisted and relisted. Read-only; safe to call repeatedly.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Compass homedetails URL or path (e.g. /homedetails/162-04-12th-Rd-Queens-NY-11357/2109718971930079225_lid/). One of `url` or `listing_id_sha` is required; pass `url` when you have it (no resolver fetch needed). | |
| listing_id_sha | No | Compass listing identifier (the SHA inside `<sha>_lid`). Sufficient on its own — the tool fetches /listing/<sha>/view, which 302-redirects to the slugged homedetails page (no extra lookup; the fetch follows the redirect). | |
| include_description | No | Include the raw `description` (Compass marketing copy) in the response. Defaults to `false` — `extracted_features` is always populated and usually covers the common needs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses redirect following, omission of raw description by default, derived fields like lot_size_acres and extracted_features, and that url returns the _lid/ form. It agrees with annotations (readOnlyHint, idempotentHint).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but well-structured with clear paragraphs. It could be slightly more concise, but all sentences add value. Front-loaded with core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description thoroughly enumerates return fields (address, beds/baths, sqft, etc.), derived values, and optional inclusion of raw description. It covers behavior for both input methods and URL forms completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions, but the description adds valuable context on URL forms and the difference between sha and pid identifiers. It goes beyond the schema, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch a property's full Compass record.' It uses a specific verb and resource, distinguishing from sibling tools like compass_search_properties (list) and compass_get_by_address (by address).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains two input methods (url vs listing_id_sha) and advises on stability: sha-based URLs go stale, pid is better for long-lived references. It also notes the tool is read-only and safe to call repeatedly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The full photo gallery for a Compass listing — every image in listing.media[]. Each entry returns the original CDN URL plus a thumbnail URL and pixel dimensions. Pass either url (the full Compass homedetails URL or path) or listing_id_sha alone — sha-only calls fetch /listing//view, which redirects to the homedetails page. By default only photos (category 0) are returned; set include_all_categories: true to also include floorplans and other media. Returns { listing_id_sha, count, photos }. Read-only; safe to call repeatedly.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Compass homedetails URL or path (preferred — no resolver round-trip needed). | |
| listing_id_sha | No | Compass listing identifier. Sufficient on its own — the tool resolves the address slug internally via site search before fetching. | |
| include_all_categories | No | Include non-photo media (floorplans, etc.). Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant context beyond annotations: read-only nature, idempotency, redirect behavior for sha-only, and return format. Annotations already indicate safe/read-only, but description enriches with specific behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured, and front-loaded. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without output schema, description explicitly states return shape (`{ listing_id_sha, count, photos }`). Covers default behavior and optional parameter. Sufficient for agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: explains why `url` is preferred (no round-trip), details sha-only behavior and redirect, and clarifies default for `include_all_categories`. Schema coverage is 100%, but description adds valuable context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it retrieves the full photo gallery for a Compass listing, specifying the data source (listing.media[]) and distinguishing it from sibling tools like compass_get_property.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage instructions: pass either `url` or `listing_id_sha`, explains sha-only redirect behavior, and mentions optional `include_all_categories`. Lacks explicit when-not-to-use but is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Not yet supported — Compass renders /overview/favorites via an auth-scoped GraphQL we have not yet identified. Throws a clear error explaining the limitation.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint, openWorldHint), the description discloses that the tool throws a clear error, which is valuable behavioral information for an agent considering invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that convey the limitation and behavior without any wasted words. It is front-loaded with the status.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's unsupported state, the description is functionally complete. However, it lacks differentiation from sibling compass_get_saved_searches and does not explain what 'saved homes' means compared to saved searches, which could help agents decide when to use this tool in the future.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description does not need to add parameter semantics. The schema coverage is 100%, and the description appropriately omits parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's intended purpose (get saved homes) but immediately clarifies it is not yet supported, which accurately informs the agent of its current non-functional state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should not be used ('not yet supported'), but does not explicitly suggest alternative tools like compass_get_saved_searches or compass_search_properties, leaving the agent without guidance on what to use instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Not yet supported — Compass renders saved searches via an auth-scoped GraphQL we have not yet identified. Throws a clear error explaining the limitation.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the tool's behavior: it throws an error. Annotations indicate readOnly, openWorld, idempotent, which are consistent with a read-only stub that fails. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that immediately state the limitation and the error behavior. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a stubbed tool, the description is complete: it explains the limitation and the error. No output schema is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. The description does not need to add parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool is not yet supported and throws an error. This conveys the tool's purpose as a placeholder that provides feedback, which is a valid purpose even if not functional.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the agent should not rely on this tool as it will throw an error. However, it does not explicitly state when to use it or suggest alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the full set of registered sessions plus the current active_session_id. When no sessions are registered, sessions is empty and active_session_id is null.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and openWorldHint=false, but the description adds useful edge-case behavior (empty sessions and null active_session_id) that annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. Front-loaded with main action, followed by edge case. Every sentence adds meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no parameters and no output schema, but the description fully explains the return values and edge cases. No additional information is necessary for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. The description adds value by explaining output fields (sessions array, active_session_id) and their behavior in edge cases, meeting the baseline for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns all registered sessions and the active session ID, using a specific verb and distinct resource. It differentiates from sibling tools like compass_register_session and compass_set_active_session which are mutations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving session context but does not explicitly state when to use or not use this tool versus alternatives. However, sibling tools are clearly separate (registering or setting sessions), making context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Round-trips a small public www.compass.com URL (/robots.txt) through the fetchproxy bridge and returns diagnostics: the bridge's role (host/peer/null), port, version, the extension link (linked / pair pending / not attached / never answered), the elapsed round-trip time, and a plain-English hint distinguishing 'bridge never came up' from 'extension not connected' from 'real www.compass.com-side problem'. Call this when a real tool fails and you want to know which hop broke. Read-only, no auth required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld/idempotent annotations, the description discloses the full set of diagnostic outputs (bridge role, port, version, extension link state, elapsed time, hint) and the failure categories it distinguishes. It also explicitly states 'Read-only, no auth required,' giving agents confidence about side effects and access.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every clause earns its place: the mechanism, the exact diagnostics returned, the failure-mode hint, the invocation condition, and the safety note. It front-loads the core behavior and avoids filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and no output schema, the description compensates fully by enumerating the return fields and their possible values, and by explaining how to interpret the result. An agent has enough information to decide when to call this tool and what the response will tell it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100% because the schema is empty. The description reasonably does not discuss parameters; per the baseline for zero-parameter tools, this is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Round-trips'), a precise resource (public www.compass.com URL through the fetchproxy bridge), and a concrete deliverable (diagnostics). It clearly differentiates itself from sibling property-lookup tools by framing itself as an end-to-end healthcheck rather than a data query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit trigger condition: 'Call this when a real tool fails and you want to know which hop broke.' It does not name sibling alternatives, but the contrast with the domain-specific sibling tools is clear from the diagnostic framing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register (or refresh) an authenticated Compass session keyed by signed-in account identity. Re-registering the same account_identity updates the existing session rather than creating a duplicate. Returns the session_id to use when routing per-tool calls. The first registered session becomes the default active_session_id. Pass mark_active: true to make the newly-registered session active in the same call.
| Name | Required | Description | Default |
|---|---|---|---|
| mark_active | No | When true, immediately make the newly-registered session the active one. | |
| auth_expires_at | No | Optional ISO timestamp at which the session expires. | |
| account_identity | Yes | Caller-supplied identifier for the signed-in account (typically the saved-account email). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint=true, and the description reinforces this by stating 'Re-registering the same account_identity updates the existing session rather than creating a duplicate.' It also discloses that the first registered session becomes the default active_session_id, adding context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no filler, front-loaded with the core action. Every sentence adds value: registration/refresh behavior, idempotency, default active session, and mark_active option.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no output schema, and good annotations, the description covers the return value (session_id), default behavior, and idempotency. It is complete for a registration tool, especially with sibling tools covering other session management aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds operational context for parameters (e.g., 'Pass mark_active: true to make the newly-registered session active') but does not introduce new meaning beyond what the schema descriptions already provide for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Register (or refresh) an authenticated Compass session' using a specific verb and resource. It distinguishes from siblings by explaining the key behavior of re-registering the same account_identity updating the session, which is unique among tools like compass_set_active_session and compass_get_session_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (registering or refreshing a session) and mentions the first session becomes default and the mark_active option. However, it does not explicitly contrast with alternatives like compass_set_active_session for changing the active session, which would strengthen guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve up to 100 street addresses to Compass listing URLs in a single call. Returns one row per input, either { resolved: true, url, listing_id_sha, pid, address, matched_via }, { resolved: false, error, query } for a genuine no-match, or — when the bridge timed out / was unreachable (issue #85) — { resolved: false, status: "timeout" | "bridge_down", retryable: true, error, query }. A status row is NOT a miss: the lookup never completed, so retry it (a cold bridge usually succeeds on the second call) rather than concluding Compass has no listing. Each row walks the same three rungs as compass_get_by_address — first the structured typeahead POST /api/v3/omnisuggest/autocomplete (the primary rung that routes around the AWS WAF, issues #78/#79), then /homes-for-sale/?q=<address> (freetext), then /homes-for-sale/<locality-slug>/ (search_fallback, issue #71) — and verifies candidates against the same whole-token address-match policy (#45). The matched_via field on each resolved row indicates which rung found it. Compass's search degrades into far-away top hits when the local market has no match, and bulk amplifies the corruption surface, so a miss returns resolved: false with no URL rather than leaking the wrong property. Calls fan out concurrently server-side. Read-only; safe to call repeatedly.
| Name | Required | Description | Default |
|---|---|---|---|
| addresses | Yes | Up to 100 address inputs. For higher counts, batch into multiple calls. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, openWorldHint, idempotentHint. The description adds extensive behavioral details: the three search rungs (autocomplete, freetext, fallback), candidate verification policy, error types (no-match, timeout, bridge_down), retryability, and note that bulk amplifies corruption. This enriches the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but well-structured: first sentence gives core purpose, then response shapes, then search algorithm, then error handling, then bulk note. Every sentence adds value for a complex tool. Could be slightly more concise, but it's appropriate for the detail needed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (bulk resolution, multiple response types, matching algorithm, retry logic), the description is highly complete. It covers return value shapes, edge cases (timeout, bridge_down), retry guidance, and match verification. Without an output schema, this is essential and well done.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameters described in schema. The description adds meaning by explaining that the 'addresses' array can hold up to 100 inputs, each with optional zip/city/state and required address. It also details the response structure for each input, going beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resolves up to 100 street addresses to Compass listing URLs. It uses specific verbs ('resolve', 'returns') and resources ('street addresses', 'Compass listing URLs'). The sibling tools list includes compass_get_by_address (single address) and compass_bulk_get, so the description implicitly distinguishes by scale and purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on when to use: for bulk resolution of addresses, up to 100 per call. It explains the three response shapes and the retry behavior for timeouts/bridge_down, which helps the agent decide when to retry. However, it does not explicitly say 'use this instead of compass_get_by_address for multiple addresses' but the context makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | 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. | |
| limit | No | Max 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. | |
| offset | No | Zero-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_max | No | ||
| beds_min | No | ||
| location | Yes | Free-text location: city, ZIP, neighborhood (e.g. "Brooklyn, NY", "94110", "Park Slope") | |
| home_type | No | Restrict to a single property type. | |
| price_max | No | ||
| price_min | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/openWorld annotations, it discloses a concrete pagination defect (#87), exact page capacity, offset/next_offset semantics, URL canonicalization behavior, compact-view field omission, and pid-vs-lid URL stability. This is exactly the behavioral context an agent needs to avoid re-fetching page 1 forever.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but the structure is front-loaded and the detail is mostly load-bearing. A few repetitions (page ~41, issue #87) and a redundant read-only sentence cost it a point, but the density of actionable warnings justifies the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly takes on the burden of explaining return fields, URL variants, pagination limits, workarounds, and image-access options. An agent has everything needed to call it correctly and avoid the pagination trap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema coverage is only 56%, the description compensates with decisive parameter meaning: limit is capped by page capacity, offset is honored only within that page, and price_min/price_max/beds_min/beds_max are framed as banding controls. It also explains view=full's effect on CDN image fields, which the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific action ('Search Compass listings') on a specific resource with location and optional filters, which immediately distinguishes it from listing-detail and mortgage siblings. It further specifies the output content (address, price, beds/baths, URLs), so an agent knows exactly what the tool produces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives strong usage context: it explains the ~41-listing SSR-page cap, tells the agent to use price/beds banding to reach beyond page one, and directs gallery needs to compass_get_property_photos. It does not explicitly enumerate sibling tools to prefer or discard in every case, so it falls just short of a full when-vs-alternatives map.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Switch which registered session subsequent tool calls route through by default. Pass a session_id previously returned by compass_register_session. Tools that accept an explicit session_id parameter override this default per-call.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session id to make active. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint false and idempotentHint true, matching the description of a state-modifying but safe operation. The description provides additional context on routing subsequent calls, which is helpful beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that fully convey the tool's function without wasted words. Information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the essential behavior, interaction with other tools (compass_register_session), and the override mechanism, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with session_id described; the description adds crucial context that it must come from compass_register_session, enhancing the schema's documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Switch', 'route through by default') and resource ('active session'), and distinguishes from sibling tools by explaining that this sets the default while other tools can override with explicit session_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (to set default session) and mentions that tools with explicit session_id override, implying when not to rely on this tool. References compass_register_session as prerequisite, but no explicit when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.14.0compass_get_agent_listings1 field changedInput schema / properties / viewAdded 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"
+}compass_get_by_address1 field changedInput schema / properties / viewAdded 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"
+}compass_search_properties1 field changedInput schema / properties / viewAdded 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"
+}v0.12.1compass_bulk_getcompass_calculate_affordabilitycompass_calculate_mortgagecompass_compare_propertiescompass_get_agent_listingscompass_get_by_addresscompass_get_comparable_rentalscompass_get_price_historycompass_get_propertycompass_get_property_photoscompass_get_saved_homescompass_get_saved_searchescompass_get_session_contextcompass_healthcheckcompass_register_sessioncompass_resolve_addressescompass_search_propertiescompass_set_active_sessionMost tools target clearly distinct operations: search, single fetch, batch fetch, compare, address resolution, photos, price history, agent listings, and financial calculators. A few overlaps exist—compass_get_property vs compass_bulk_get vs compass_compare_properties all fetch property records, and compass_get_price_history duplicates data already on compass_get_property—but the descriptions are detailed enough to guide correct selection.
Naming is predominantly verb_noun with a consistent compass_ prefix: search_properties, get_property, calculate_mortgage, resolve_addresses, register_session. Minor deviations include compass_healthcheck (noun-only), compass_bulk_get (inverted order), and compass_get_by_address (prepositional object instead of a clear noun), but the overall pattern remains predictable.
18 tools sits in the heavy range for an MCP server, and not every tool fully earns its place: compass_get_saved_homes and compass_get_saved_searches are unsupported stubs that only throw errors, and the three session-management tools plus healthcheck add infrastructure overhead. The core property tools are reasonable, but the set feels slightly over-scoped.
The read-only real-estate domain is well covered: search, property details, photos, price history, comparable rentals, agent listings, address resolution, batch fetching, and mortgage/affordability calculators are all present. Minor gaps remain—saved homes/searches are unsupported, and compass_search_properties cannot paginate beyond the first SSR page without manual price-banding—but agents can work around these with the documented strategies.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server giving Claude AI access to 22+ NYC public-record databases for real estate due diligence
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Hosted MCP server for live public-data APIs and Skills for AI agents.
Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/chrischall/compass-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
