Release Date: January 7, 2026 Affected Tools: search_properties_count, search_properties_preview, search_properties_page, comparable_property

Overview

We're excited to announce the release of three new Property Search MCP tools that enable powerful property searching capabilities through natural language interactions. These tools provide a progressive disclosure pattern that prevents context overflow while giving you full access to BatchData's comprehensive property database.

Additionally, the existing comparable_property tool has been updated with improved pagination and response size optimizations.

New Tools Summary

1. search_properties_count

Purpose: Get total count and aggregate metrics for properties matching your search criteria.

Attribute	Value
Max Results	N/A (counts only)
Use Case	Scope assessment before detailed searches

When to Use: - Starting a new property search to understand result size - Validating filters before requesting detailed data - Getting market metrics (average price, price per sqft)

Example Request:

{
  "property_city": "Phoenix",
  "property_state": "AZ",
  "property_type_category": "Single Family Residential",
  "max_estimated_value": 400000,
  "min_bedrooms": 3
}

Example Response:

{
  "totalCount": 2847,
  "aggregatedMetrics": {
    "averagePrice": 312500,
    "averagePricePerSqft": 245,
    "priceRangeMin": 89000,
    "priceRangeMax": 399900
  }
}

2. search_properties_preview

Purpose: Get a quick sample of the first 10 properties matching your criteria.

Attribute	Value
Max Results	10
Use Case	Quick sampling before full pagination

When to Use: - Previewing search results before committing to detailed browsing - Validating that search criteria return expected property types - Quick spot-checking of data quality

Example Request:

{
  "property_city": "Phoenix",
  "property_state": "AZ",
  "property_type_category": "Single Family Residential",
  "max_estimated_value": 400000,
  "min_bedrooms": 3
}

Example Response:

{
  "totalCount": 2847,
  "properties": [
    {
      "address": {
        "street": "1234 W Camelback Rd",
        "city": "Phoenix",
        "state": "AZ",
        "zip": "85015"
      },
      "valuation": {
        "estimatedValue": 285000
      },
      "building": {
        "bedroomCount": 3,
        "bathroomCount": 2,
        "totalBuildingAreaSquareFeet": 1450,
        "yearBuilt": 1985
      }
    }
    // ... up to 10 properties
  ]
}

3. search_properties_page

Purpose: Paginated access to detailed property results with full dataset support.

Attribute	Value
Page Size	10 properties per page
Pagination	Offset-based (page) or cursor-based (page_cursor)
Use Case	Detailed browsing and data export

When to Use: - Browsing detailed property information page by page - Exporting property data for analysis - Building property lists for outreach campaigns

Pagination Options:

Page-based (offset): Use page parameter (1-indexed)
Cursor-based: Use page_cursor from previous response for efficient sequential iteration

Example Request (Page-based):

{
  "property_city": "Phoenix",
  "property_state": "AZ",
  "property_type_category": "Single Family Residential",
  "max_estimated_value": 400000,
  "min_bedrooms": 3,
  "page": 1,
  "datasets": [
    "basic",
    "valuation",
    "owner"
  ]
}

Example Request (Cursor-based):

{
  "property_city": "Phoenix",
  "property_state": "AZ",
  "page_cursor": "eyJza2lwIjoyNSwic2Vzc2lvbklkIjoiYWJjMTIzIn0="
}

Example Response:

{
  "totalCount": 2847,
  "currentPage": 1,
  "totalPages": 285,
  "nextCursor": "eyJza2lwIjoxMCwic2Vzc2lvbklkIjoiYWJjMTIzIn0=",
  "properties": [
    {
      "id": "prop_123456",
      "address": {
        "street": "1234 W Camelback Rd",
        "city": "Phoenix",
        "state": "AZ",
        "zip": "85015"
      },
      "valuation": {
        "estimatedValue": 285000,
        "priceRangeMin": 270000,
        "priceRangeMax": 300000
      },
      "owner": {
        "names": ["John Smith"],
        "ownerOccupied": true
      },
      "building": {
        "bedroomCount": 3,
        "bathroomCount": 2,
        "totalBuildingAreaSquareFeet": 1450,
        "yearBuilt": 1985
      }
    }
    // ... up to 10 properties per page
  ]
}

Comparable Property Update

The comparable_property tool has been updated with pagination support and response size optimizations.

What Changed

Pagination Support: Large comparable result sets are now paginated to prevent context overflow
Response Size Optimization: Default projections limit response to essential fields
Aggregated Metrics: New aggregatedMetrics object provides calculated values

New Response Format

{
  "subjectProperty": {
    "address": {
      "street": "3741 W Evans Dr",
      "city": "Phoenix",
      "state": "AZ",
      "zip": "85053"
    },
    "building": {
      "bedroomCount": 3,
      "bathroomCount": 2,
      "totalBuildingAreaSquareFeet": 1650
    }
  },
  "aggregatedMetrics": {
    "estimatedValue": 385000,
    "averagePrice": 372500,
    "averagePricePerSqft": 226,
    "comparableCount": 15
  },
  "comparables": [
    {
      "address": {
        "street": "3825 W Butler Dr",
        "city": "Phoenix",
        "state": "AZ",
        "zip": "85051"
      },
      "sale": {
        "lastSale": {
          "price": 365000,
          "saleDate": "2024-11-15"
        }
      },
      "building": {
        "bedroomCount": 3,
        "bathroomCount": 2,
        "totalBuildingAreaSquareFeet": 1580
      }
    }
    // ... additional comparables
  ]
}

Guidance for Offer Calculations

Use the aggregatedMetrics.estimatedValue for calculating offer prices:

Buyer Type	Recommended Multiplier
Investment/Wholesale	70-80% of estimatedValue
Retail Buyers	90-95% of estimatedValue

Always validate using averagePricePerSqft and adjust for property condition and market trends.

Datasets Parameter

All property search tools support the datasets parameter to control which data sections are returned.

Important Billing Information: While the datasets parameter provides control over response content, it's important to understand that billing for Property Search and Property Lookup operations is based on your authentication token's provisioned dataset access rather than the datasets you specify at runtime.

Billing Model Rationale: This token-based per-record billing approach ensures predictable cost estimation and transparent usage tracking. You can accurately forecast API expenses based on expected property record volumes, and usage reports provide direct correlation between charges and property records retrieved for straightforward billing validation.

Each property record returned from Property Search and Property Lookup endpoints incurs the full per-record rate for all datasets your token is provisioned to access, regardless of which datasets you request in the API call. The datasets parameter filters which data categories are included in the response but does not affect per-record billing costs.

Cost Control: To optimize costs, ensure your authentication token is provisioned only with datasets needed for your application. Contact your account manager to adjust dataset provisioning based on your specific requirements.

Performance Benefits: Using the datasets parameter to limit response content provides performance benefits such as reduced response payload size and faster processing, even though billing remains constant based on token provisioning.

For comprehensive billing information, see Introduction to the Property Search API.

Available Datasets

Dataset	Description
`basic`	Core property identifiers, address, basic characteristics
`core`	Extended core property data (mutually exclusive with basic)
`valuation`	Property valuation and equity estimates
`owner`	Property owner information
`deed`	Deed history and transfer records
`contact`	Owner contact information
`demographic`	Neighborhood demographic data
`foreclosure`	Foreclosure status and history
`listing`	MLS listing information
`mortgageliens`	Mortgage and lien records
`permit`	Building permit records
`quicklist`	Quicklist categorization flags
`general`	General property classification

Default Datasets

search_properties_page: basic, valuation
comparable_property: basic, core, general, valuation

Example with Custom Datasets

{
  "property_city": "Phoenix",
  "property_state": "AZ",
  "datasets": [
    "basic",
    "valuation",
    "owner",
    "foreclosure"
  ]
}

Full Search Criteria

All property search tools support a comprehensive set of filter parameters:

Location Filters

property_city, property_state, property_zip
property_county, property_county_fips

Property Characteristics

property_type_category, property_type_detail
min_bedrooms, max_bedrooms
min_bathrooms, max_bathrooms
min_sqft, max_sqft, min_living_sqft, max_living_sqft
min_lot_size_sqft, max_lot_size_sqft
min_year_built, max_year_built
min_stories, max_stories

Valuation Filters

min_estimated_value, max_estimated_value
min_equity_percent, max_equity_percent
min_ltv, max_ltv

Sale History

min_last_sale_date, max_last_sale_date
min_last_sale_price, max_last_sale_price

Listing Filters

listing_status (Active, Pending, Sold, Expired, Canceled)
min_list_price, max_list_price
min_days_on_market, max_days_on_market

Owner Filters

owner_occupied
min_owner_age, max_owner_age
min_length_of_residence_years, max_length_of_residence_years

Quicklist Filters

quicklist (single filter)
quicklists (AND logic - must match ALL)
or_quicklists (OR logic - match ANY)

Available Quicklists: - absentee-owner, high-equity, low-equity, free-and-clear - preforeclosure, notice-of-default, notice-of-sale, active-auction - active-listing, pending-listing, recently-sold - senior-owner, vacant, corporate-owned, trust-owned - tired-landlord, fix-and-flip, cash-buyer - And many more...

Migration Notes

For Existing comparable_property Users

Response Structure Change: Results are now wrapped in an object with subjectProperty, aggregatedMetrics, and comparables arrays
Use aggregatedMetrics: The new estimatedValue in aggregatedMetrics is the recommended value for offer calculations
Pagination: Large result sets may be paginated - check for nextCursor in responses