Getting Started

What Are These Tools?

BatchData's Property Search MCP tools allow you to search, browse, and analyze property data using natural language queries through AI assistants like Claude. Instead of writing API calls, you simply ask questions like:

"Find all single family homes in Phoenix under $400,000"
"Show me vacant properties with high equity in Miami"
"How many foreclosures are there in Los Angeles County?"

Available Tools

Tool	Purpose	Max Results
`search_properties_count`	Get counts and market metrics	N/A
`search_properties_preview`	Quick 10-property sample	10
`search_properties_page`	Full paginated results	10/page
`comparable_property`	Comparative market analysis	Varies

Cost Considerations

Understanding how MCP property search tools affect billing is crucial for managing costs effectively when using Property Search and Property Lookup operations.

Per-Record Billing: Each property record returned through MCP property search tools incurs the full per-record cost based on your authentication token's provisioned dataset access, regardless of which specific data you request in tool calls.

Dataset Provisioning vs Runtime Selection: Your token is provisioned with access to specific datasets during setup. While MCP tools can specify which datasets to include in responses, billing is based on the token's full provisioned dataset access, not your runtime dataset selection.

Predictable Cost Model: This billing approach enables accurate cost forecasting based on expected property record volumes and token provisioning. Usage reports directly correlate charges to property records retrieved, providing transparency for billing validation and budget management.

Take Parameter Impact: The take parameter in tool calls controls how many property records are returned, directly affecting your total cost. Setting appropriate limits helps control expenses while getting the data you need.

Response Filtering Benefits: Parameters like datasets and customProjection filter response data without reducing per-record costs, but they do provide benefits such as smaller payloads and faster processing.

Cost Control Strategies:

Provision authentication tokens with only datasets needed for your MCP integration use case
Set reasonable take limits in property search tool calls to control the number of records returned
Use sandbox tokens during development and testing to avoid charges
Work with your account manager to optimize token provisioning based on your application's requirements

For detailed billing information and dataset descriptions, see Datasets and Custom Projections.

Tool Selection Guide

Your Goal	Recommended Tool
"How many properties match my criteria?"	`search_properties_count`
"Show me a few examples"	`search_properties_preview`
"Let me browse all results"	`search_properties_page`
"What's this property worth?"	`comparable_property`
"Export data for analysis"	`search_properties_page`

Workflow Patterns

The Count → Preview → Page Flow

This is the recommended workflow for property searches. It uses progressive disclosure to help you refine your search before committing to large result sets.

Step 1: Start with Count

You: "Find all single family homes in Phoenix, AZ priced under $400,000"

AI Response: Found 2,847 properties matching your criteria in Phoenix, AZ. Average Price: $312,500 • Average Price/SqFt: $245 • Price Range: $89,000 - $399,900

Step 2: Preview Results

You: "Show me a preview"

AI Response: Preview (10 of 2,847 properties):

1234 W Camelback Rd, Phoenix, AZ 85015 - $285,000 | 1,450 sqft | 3 bed | 2 bath | Built 1985
5678 N 32nd St, Phoenix, AZ 85018 - $349,900 | 1,890 sqft | 4 bed | 2 bath | Built 1992
9012 E Indian School Rd, Phoenix, AZ 85014 - $275,000 | 1,200 sqft | 3 bed | 1.5 bath | Built 1978

Step 3: Refine Your Search

You: "Filter to only 3+ bedrooms built after 2000"

AI Response: Filtered to 847 properties (down from 2,847). Average Price: $358,200 • Average Price/SqFt: $198

Step 4: Browse Pages

You: "Show me the results"

AI Response: Page 1 of 85 (showing 10 of 847 properties):

123 W Desert Hills Dr, Phoenix, AZ 85045 - $375,000 | 2,100 sqft | 4 bed | 2.5 bath | Built 2005 | Est. Value: $382,000

Step 5: Navigate Pages

"Next page" - Go to the next page
"Go to page 10" - Jump to a specific page
"Show me page 50" - Jump to any page number

Pagination Best Practices

Method	Best For	How to Use
Page-based	Random access, jumping to specific pages	"Go to page 10"
Cursor-based	Sequential iteration, large exports	"Next page"

Page-Based Navigation - Use when you want to jump to a specific page: - "Show me page 5" - "Go to the last page" - "Jump to page 20"

Cursor-Based Navigation - Use for sequential browsing (more efficient): - "Next page" - "Continue" - "Show more"

Filtering & Search Criteria

Location-Based Searches

By City/State: "Find properties in Austin, TX"
By ZIP Code: "Search 90210"
By County: "Properties in Orange County, California"

Property Characteristics

Bedrooms/Bathrooms: "3+ bedroom homes with at least 2 bathrooms"
Square Footage: "Properties between 1,500 and 2,500 square feet"
Year Built: "Homes built after 2000"
Property Type: "Single family homes" / "Condos" / "Multi-family"

Financial Filters

Price Range: "Under $500,000" / "Between $200K and $400K"
Equity: "High equity properties (over 50% equity)"
Listing Status: "Active listings" / "Recently sold" / "Pending sales"

Investor-Focused Filters (Quicklists)

Motivated Sellers: "Preforeclosure properties" • "Properties in notice of default" • "Tax delinquent properties"
Ownership Type: "Absentee owner properties" • "Corporate owned" • "Trust owned"
Investment Opportunities: "High equity with absentee owners" • "Vacant properties" • "Fix and flip candidates"

Combining Filters

"Find 3+ bedroom single family homes in Phoenix under $400,000, built after 1990, with high equity and absentee owners"

Dataset Selection

By default, searches return basic and valuation datasets. You can request additional data:

"Include owner information in the results"
"Also show foreclosure status"
"Add listing details"

Available Datasets: - basic - Address, property ID - valuation - Estimated value, equity - owner - Owner names, occupancy - deed - Transfer history - foreclosure - Foreclosure status - listing - MLS listing info - permit - Building permits - contact - Owner contact info

Common Use Cases

Finding Investment Properties

Wholesale Deals: "Find properties in preforeclosure in Atlanta with at least 30% equity"
Fix and Flip: "Show me properties that sold in the last 6 months that were previously purchased within 12 months"
Rental Properties: "Find 2-4 unit multi-family properties in Cleveland under $200,000"

Comparable Market Analysis

For a Specific Property: "Run comps for 3741 W Evans Dr, Phoenix, AZ 85053"
With Filters: "Find comparables for 123 Main St that sold in the last 6 months within 1 mile"
For Offer Calculation: "What should I offer on 456 Oak Ave based on recent sales?"

The AI will provide: estimated value based on comparables, average price per square foot, and recommended offer ranges for investors vs. retail buyers.

Bulk Data Export

"Export all 847 properties to a CSV file"
"Export addresses, estimated values, and owner names"

Troubleshooting

"Too Many Results" - Narrow your search by adding location specificity (ZIP code instead of city), property characteristic filters, financial filters, or quicklist filters.

"No Results Found" - Broaden your criteria, check spelling of location names, try removing the most restrictive filter, or verify the location exists in our database.

"Results Don't Match Expectations" - Verify filter logic (AND vs. OR for quicklists), check that min/max values are in correct order, confirm property type category matches your intent.

Rate Limits - Wait a few seconds between requests, use cursor-based pagination for large exports, reduce the number of datasets requested.

Tips for Best Results

Start Broad, Then Narrow: Begin with count to understand your market, then add filters progressively.
Use Preview Before Paging: The preview gives you a quick sanity check before committing to browse thousands of results.
Be Specific with Locations: ZIP codes and specific cities work better than broad regional searches.
Combine Quicklists Strategically: Use multiple quicklists to find highly motivated sellers (e.g., "preforeclosure AND high-equity").
Request Only Needed Datasets: Smaller responses are faster and easier to review.