| name | market-study |
| description | Generate an institutional-grade market study PDF with price performance, supply-demand, and investor metrics |
| user-invocable | true |
| argument-hint | [market name] |
| allowed-tools | Read, Grep, Glob, Bash, Write, Edit, WebFetch |
Market Study
Generates a comprehensive market study PDF for a target real estate market using Parcl Labs MCP data. Produces institutional-grade analysis with quarterly KPI matrices, supply-demand charts, and investor metrics.
Target market: $ARGUMENTS (e.g., "Hamptons", "Miami Beach", "Aspen")
Audience: Ultra-high-net-worth clients, luxury agents, and institutional investors.
Tool Mapping
All tools are invoked through the Parcl Labs MCP server.
| Step | Tool | Purpose |
|---|
| Resolve market | search_locations | Convert market name → parcl_id(s). Search metro, key ZIPs, cities. |
| Sale prices | sale_price_index | Price per sq ft over time |
| Rental prices | rental_price_index | Rental price trends |
| Gross yield | rental_gross_yield | Gross rental yields |
| New listing supply | for_sale_new_listings_rolling_counts | Rolling counts of new for-sale listings |
| Sales & listing counts | market_metrics_housing_event_counts | Total sales, new listings, rentals |
| Housing stock | market_metrics_housing_stock | Total housing stock |
| Investor acquisitions | housing_event_counts | Investor acquisitions vs dispositions |
| Ownership breakdown | housing_stock_ownership | Ownership breakdown by type |
| Net investor activity | purchase_to_sale_ratio | Purchase-to-sale ratio (apply 3-month rolling average) |
| Portfolio operator activity | portfolio_sf_housing_event_counts | SFR portfolio operator transactions |
| Portfolio ownership | portfolio_sf_housing_stock_ownership | Portfolio ownership share |
| All-cash share | market_metrics_all_cash | All-cash transaction percentage |
| Motivated seller scores | motivated_seller_index | Motivated seller scores by submarket |
| Listing-level seller data | motivated_seller_properties | Individual listings with price cut data |
| Property events (KPI matrices) | property_events | Full listing lifecycle for session reconstruction |
| Benchmarks | search_locations + above tools | Same metrics for parent MSA, state, USA |
For detailed tool notes, scope warnings, and the complete KPI matrix session reconstruction methodology, see reference/analytical-framework.md.
Execution Steps
- Resolve geography. Use
search_locations for metro area, then key ZIP codes and cities. Also resolve parent MSA, state, and USA aggregate for benchmarking.
- Preview all datasets. Call each data tool with
preview=True to check credit costs and record counts.
- Download datasets. Call each data tool with
preview=False for presigned CSV URLs (expire in 1 hour).
- Retrieve CSVs. Download each CSV via presigned URLs.
- Generate PDF. Produce the full report following the structure below.
PDF Structure
- Cover Page: Market name, date, Parcl Labs branding. Disclaimer about data sources.
- Executive Summary: Current price level/YoY, supply-demand gap, price cut rate vs 41% national benchmark, market classification, top risk and opportunity.
- Price Performance: Sale price index chart with submarket lines + metro benchmark. Submarket price table.
- Key Market Indicators: Institutional KPI matrices:
- All Properties matrix (QoQ and YoY comparisons)
- Single Family matrix
- Luxury segment matrix (top 10% by price)
- Listing distribution by price tier
- Supply-Demand Dynamics: KPI boxes, divergence chart (Jan 2023 onward), gap interpretation.
- Seller Behavior & Motivated Sellers: Bubble chart (X=DOM, Y=cut rate, size=listings, color=MSI label), operational metrics table.
- All-Cash Transactions: Share over time, flows into investor section.
- Investor Activity: Acquisitions vs dispositions, purchase-to-sale ratio, ownership chart.
- Portfolio Operator Activity: SFR operator trends, institutional presence.
- Market Outlook: Forward-looking synthesis.
- Appendix: Data dictionary, methodology, attribution.
Display Names
Never display raw parcl_id values in user-facing output. Always resolve to human-readable names:
- ZIP parcl_ids to actual ZIP codes and town names (e.g.,
5452730 to "East Hampton (11937)")
- MSA parcl_ids to metro area names (e.g.,
2900417 to "Tampa-St. Petersburg-Clearwater, FL")
- Investor IDs to standardized names from
search_investors
Note: some MCP endpoints return IDs as floats with .0 suffix (e.g., 5452730.0). Strip the .0 before any lookup or display.
Narrative Style
Follow the Parcl Labs Annual Housing Report voice:
- State the finding first, then support with specific numbers
- Use precise figures, not hedging language
- Compare to benchmarks: national averages, prior year, historical norms
- Flag inflection points and divergences between metrics
Anti-AI writing rules (mandatory):
- No significance inflation ("significant," "crucial," "vital," "notably")
- No promotional language ("impressive," "remarkable," "robust")
- No copula hedging ("stands at," "sits at," "comes in at")
- No -ing analysis starters ("Highlighting...", "Underscoring...")
- No rule-of-three lists. Vary structure
- No em dashes in narrative prose (use commas, parentheses, periods)
- No bold inline headers in body text
- Vary sentence length. Mix short and long
- Use contractions where natural
- Every paragraph has a clear takeaway
Visualization Principles
- Every chart title states the takeaway, not just the metric
- Horizontal text always; never rotate axis labels
- Direct-label lines/bars instead of legends when possible
- Source attribution on every chart ("Source: Parcl Labs")
- Colorblind-friendly palettes
- No 3D or pie charts
