Hercules property data

Quote an active investor search

quote_active_investor_search

Read-onlyIdempotent

Finds who is actively buying in an area: properties in a zip, city or county owned by investors, grouped by owner when run. By default it looks for owners of 2+ properties who bought in this area in the last 12 months. Options: minPurchasesLast12Months keeps owners who bought at least N properties in the last 12 months. That count covers the owner's whole portfolio, not only this area, so it is the closest available measure of 'bought N+ here'; boughtWithinMonths keeps it to owners who bought here recently. corporateOnly keeps companies and LLCs. cashInvestorOnly keeps properties bought with cash by an absentee investor. outOfStateOnly keeps owners who live in another state. Each property record costs credits, the same as a national property search. Never spends credits: it counts the matches and prices one batch. Always quote first. Then tell the user the credit cost, the batch size and their balance after. Records this workspace already pulled in the last 24 hours are free. For large searches, prefer a smaller batch (limit) or narrower filters, such as a zip instead of a county. One run returns at most 250 records; page with offset. Quotes expire after 10 minutes. Call run_active_investor_search with the quote_id only after the user agrees to the credit cost.

Input Schema

TableJSON Schema

Name	Required	Description
`zip`	No	Five-digit zip code. The narrowest and cheapest place filter.
`city`	No	City name.
`limit`	No	Records to price in this batch (max 250). Leave empty to let the quote pick a safe batch size.
`state`	Yes	Two-letter state code, e.g. TX. Required.
`county`	No	County name, without the word County.
`offset`	No	Skip this many matches. Use it to quote the next page.
`propertyType`	No	SFR single family, MFR multifamily, CONDO, LAND, MOBILE or OTHER.
`corporateOnly`	No	Only companies and LLCs.
`outOfStateOnly`	No	Only owners whose mailing address is in another state.
`cashInvestorOnly`	No	Only properties bought with cash by an absentee investor.
`boughtWithinMonths`	No	Only properties in this area bought in the last N months. Default 12. Null means any time.
`minPropertiesOwned`	No	Only owners with at least this many properties. Default 2.
`minPurchasesLast12Months`	No	Only owners who bought at least this many properties in the last 12 months, counted across their whole portfolio.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`offset`	Yes
`balance`	Yes
`credits`	Yes
`quoteId`	Yes
`runTool`	Yes
`expiresAt`	Yes
`affordable`	Yes
`suggestions`	Yes
`balanceAfter`	Yes
`ownedInBatch`	Yes
`totalMatches`	Yes
`recommendation`	Yes
`recordsInBatch`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 7, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare safety (readOnly, idempotent, non-destructive), but the description discloses the credit-cost model, that the quote never spends credits, that records pulled in the last 24h are free, the 250-record cap, offset paging, and the 10-minute quote expiry — behavioral context the structured fields do not carry.

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

Conciseness4/5

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

Front-loaded with the core purpose and the credit-cost workflow, and every sentence carries actionable content. It is dense and fairly long, but not padded — the length is justified by the credit/expiry/paging constraints.

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

Completeness5/5

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

For a 13-param credit-consuming quote tool with an output schema, the description covers the cost model, safety of quoting, batching, pagination, expiry and the handoff to run_active_investor_search. Nothing an agent needs to call it correctly is missing.

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

Parameters4/5

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

Schema coverage is already 100%, so baseline is 3. The description goes beyond by clarifying semantics the schema cannot: minPurchasesLast12Months counts the owner's whole portfolio rather than only this area, and it explains boughtWithinMonths, corporateOnly, cashInvestorOnly and outOfStateOnly in behavioral terms.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — finds actively-buying investors, defined as properties in a zip/city/county owned by investors, grouped by owner. It implicitly distinguishes itself from quote_national_property_search (investor-focused rather than all properties) and explicitly names run_active_investor_search as the follow-on action.

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

Usage Guidelines5/5

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

Explicit workflow: 'Always quote first,' then report credit cost/batch size/balance, and only call run_active_investor_search with the quote_id after user agreement. It also gives a when-not/narrower guidance: prefer a smaller batch (limit) or narrower filters like a zip instead of a county for large searches.

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

All Hercules property data tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?