Hercules property data

Search NYC property signals

search_nyc_signals

Read-onlyIdempotent

Lists NYC lots that carry one or more property signals: reasons a deal can happen, such as a loan coming due, an old mortgage not refinanced, a long-time owner, an absentee or company owner, a foreclosure case, the tax lien sale list, open code violations, a vacate order, unused air rights, a teardown lot or a rezoning. Use it for asks like these, with these keys: loans coming due or maturing: loan_maturing; old mortgage, not refinanced: aging_mortgage; long holds or long-time owners: long_hold; likely or motivated sellers: long_hold, absentee_owner, serial_seller, value_below_loan; tired landlords or distressed owners: code_violations, hpd_litigation, tax_lien, vacate_order; underwater or over-leveraged: value_below_loan; free and clear, no mortgage: no_recorded_debt; development sites or air rights: underbuilt, teardown, vacant_land, assemblage; new construction or rezonings: new_building_permit, rezoning_filed, entitled_not_built; recent sales or active buyers: just_sold, serial_buyer. Narrow by boroughs, ZIP codes, neighborhoods (ntas) and building types. Each row gives the BBL, address, owner of record and every signal on the lot with its date. Signals marked likely are estimates; say likely when you repeat them. The result also counts lots per signal in the area. Never spends credits. On any paid plan the first 25 rows each day are free; other workspaces pay for every row. Rows already pulled are free again. Past the free rows, rows cost 1 credit per row, and this tool returns them as a quote: tell the user the credit cost and ask before calling run_nyc_signals_search with the quote_id. No contacts in the result: use unlock_nyc_property_report and then unlock_nyc_owner_contacts on a BBL for the owner's phones and emails. Up to 50 rows per call (default 25), newest signal first; page with offset.

Input Schema

Name	Required	Description	Default
`ntas`	No	2020 neighborhood codes from find_nyc_area, for example BK0102 Williamsburg. Use them whenever the person names a neighborhood.
`zips`	No	NYC ZIP codes. Boroughs, ZIPs and ntas combine as any of them.
`limit`	No
`match`	No	any keeps lots with at least one of the signals; all keeps lots with every one.	any
`offset`	No
`signals`	Yes	One or more signal keys: long_hold, absentee_owner, entity_owner, portfolio_owner, just_sold, serial_buyer, serial_seller, recorded_mortgage, no_recorded_debt, aging_mortgage, value_below_loan, foreclosure_filed, auction_scheduled, tax_lien, code_violations, vacate_order, fire_vacate, hpd_litigation, vacant_storefront, underbuilt, vacant_land, teardown, land_just_bought, assemblage, rezoning_filed, new_building_permit, new_co, entitled_not_built, loan_maturing, io_balloon, weak_coverage, occupancy_down, noi_down, dscr_below_1, loan_modified, maturity_extended, servicer_advancing, special_servicing, delinquent, ll97_covered, ll97_fine_2024, ll97_fine_2030, evictions, facade_unsafe, j51_ending, 421a_ending, low_inspection_grade, lihtc_year15, subsidy_expiring, oz_year10.
`boroughs`	No	Whole NYC boroughs. All five when omitted.
`asset_classes`	No	Building types, for example multifamily_walkup, multifamily_elevator, mixed_use, office, retail, one_two_family, condo, coop.

Output Schema

Name	Required	Description	Default
`rows`	Yes
`quote`	Yes
`counts`	Yes
`offset`	Yes
`notYetBuilt`	Yes
`totalMatches`	Yes
`creditsCharged`	Yes
`freeRowsPerDay`	Yes
`freeRowsUsedToday`	Yes
`possibleIsEstimate`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 21, 2026

changedInput schema / properties / signals / description

Previous value: -"One or more signal keys: long_hold, absentee_owner, entity_owner, portfolio_owner, just_sold, serial_buyer, serial_seller, recorded_mortgage, no_recorded_debt, aging_mortgage, value_below_loan, foreclosure_filed, tax_lien, code_violations, vacate_order, fire_vacate, hpd_litigation, vacant_storefront, underbuilt, vacant_land, teardown, land_just_bought, assemblage, rezoning_filed, new_building_permit, new_co, entitled_not_built, loan_maturing, io_balloon, weak_coverage, occupancy_down, noi_down, dscr_below_1, loan_modified, maturity_extended, servicer_advancing, special_servicing, delinquent, ll97_covered, ll97_fine_2024, ll97_fine_2030, evictions, facade_unsafe, j51_ending, 421a_ending, low_inspection_grade, lihtc_year15, subsidy_expiring, oz_year10."New value: +"One or more signal keys: long_hold, absentee_owner, entity_owner, portfolio_owner, just_sold, serial_buyer, serial_seller, recorded_mortgage, no_recorded_debt, aging_mortgage, value_below_loan, foreclosure_filed, auction_scheduled, tax_lien, code_violations, vacate_order, fire_vacate, hpd_litigation, vacant_storefront, underbuilt, vacant_land, teardown, land_just_bought, assemblage, rezoning_filed, new_building_permit, new_co, entitled_not_built, loan_maturing, io_balloon, weak_coverage, occupancy_down, noi_down, dscr_below_1, loan_modified, maturity_extended, servicer_advancing, special_servicing, delinquent, ll97_covered, ll97_fine_2024, ll97_fine_2030, evictions, facade_unsafe, j51_ending, 421a_ending, low_inspection_grade, lihtc_year15, subsidy_expiring, oz_year10."

changedInput schema / properties / signals / items / enum

Previous value: -[
-  "long_hold",
-  "absentee_owner",
-  "entity_owner",
-  "portfolio_owner",
-  "just_sold",
-  "serial_buyer",
-  "serial_seller",
-  "recorded_mortgage",
-  "no_recorded_debt",
-  "aging_mortgage",
-  "value_below_loan",
-  "foreclosure_filed",
-  "tax_lien",
-  "code_violations",
-  "vacate_order",
-  "fire_vacate",
-  "hpd_litigation",
-  "vacant_storefront",
-  "underbuilt",
-  "vacant_land",
-  "teardown",
-  "land_just_bought",
-  "assemblage",
-  "rezoning_filed",
-  "new_building_permit",
-  "new_co",
-  "entitled_not_built",
-  "loan_maturing",
-  "io_balloon",
-  "weak_coverage",
-  "occupancy_down",
-  "noi_down",
-  "dscr_below_1",
-  "loan_modified",
-  "maturity_extended",
-  "servicer_advancing",
-  "special_servicing",
-  "delinquent",
-  "ll97_covered",
-  "ll97_fine_2024",
-  "ll97_fine_2030",
-  "evictions",
-  "facade_unsafe",
-  "j51_ending",
-  "421a_ending",
-  "low_inspection_grade",
-  "lihtc_year15",
-  "subsidy_expiring",
-  "oz_year10"
-]New value: +[
+  "long_hold",
+  "absentee_owner",
+  "entity_owner",
+  "portfolio_owner",
+  "just_sold",
+  "serial_buyer",
+  "serial_seller",
+  "recorded_mortgage",
+  "no_recorded_debt",
+  "aging_mortgage",
+  "value_below_loan",
+  "foreclosure_filed",
+  "auction_scheduled",
+  "tax_lien",
+  "code_violations",
+  "vacate_order",
+  "fire_vacate",
+  "hpd_litigation",
+  "vacant_storefront",
+  "underbuilt",
+  "vacant_land",
+  "teardown",
+  "land_just_bought",
+  "assemblage",
+  "rezoning_filed",
+  "new_building_permit",
+  "new_co",
+  "entitled_not_built",
+  "loan_maturing",
+  "io_balloon",
+  "weak_coverage",
+  "occupancy_down",
+  "noi_down",
+  "dscr_below_1",
+  "loan_modified",
+  "maturity_extended",
+  "servicer_advancing",
+  "special_servicing",
+  "delinquent",
+  "ll97_covered",
+  "ll97_fine_2024",
+  "ll97_fine_2030",
+  "evictions",
+  "facade_unsafe",
+  "j51_ending",
+  "421a_ending",
+  "low_inspection_grade",
+  "lihtc_year15",
+  "subsidy_expiring",
+  "oz_year10"
+]

changedInput schema / properties / signals / maxItems
```
Previous value: -49New value: +50
```

Changed3 schema fields changedOct 20, 2026

changedInput schema / properties / signals / description

Previous value: -"One or more signal keys: long_hold, absentee_owner, entity_owner, portfolio_owner, just_sold, serial_buyer, serial_seller, recorded_mortgage, no_recorded_debt, loan_maturing_est, value_below_loan, foreclosure_filed, tax_lien, code_violations, vacate_order, fire_vacate, hpd_litigation, vacant_storefront, underbuilt, vacant_land, teardown, land_just_bought, assemblage, rezoning_filed, new_building_permit, new_co, entitled_not_built, loan_maturing, io_balloon, weak_coverage, occupancy_down, noi_down, dscr_below_1, loan_modified, maturity_extended, servicer_advancing, special_servicing, delinquent."New value: +"One or more signal keys: long_hold, absentee_owner, entity_owner, portfolio_owner, just_sold, serial_buyer, serial_seller, recorded_mortgage, no_recorded_debt, aging_mortgage, value_below_loan, foreclosure_filed, tax_lien, code_violations, vacate_order, fire_vacate, hpd_litigation, vacant_storefront, underbuilt, vacant_land, teardown, land_just_bought, assemblage, rezoning_filed, new_building_permit, new_co, entitled_not_built, loan_maturing, io_balloon, weak_coverage, occupancy_down, noi_down, dscr_below_1, loan_modified, maturity_extended, servicer_advancing, special_servicing, delinquent, ll97_covered, ll97_fine_2024, ll97_fine_2030, evictions, facade_unsafe, j51_ending, 421a_ending, low_inspection_grade, lihtc_year15, subsidy_expiring, oz_year10."

changedInput schema / properties / signals / items / enum

Previous value: -[
-  "long_hold",
-  "absentee_owner",
-  "entity_owner",
-  "portfolio_owner",
-  "just_sold",
-  "serial_buyer",
-  "serial_seller",
-  "recorded_mortgage",
-  "no_recorded_debt",
-  "loan_maturing_est",
-  "value_below_loan",
-  "foreclosure_filed",
-  "tax_lien",
-  "code_violations",
-  "vacate_order",
-  "fire_vacate",
-  "hpd_litigation",
-  "vacant_storefront",
-  "underbuilt",
-  "vacant_land",
-  "teardown",
-  "land_just_bought",
-  "assemblage",
-  "rezoning_filed",
-  "new_building_permit",
-  "new_co",
-  "entitled_not_built",
-  "loan_maturing",
-  "io_balloon",
-  "weak_coverage",
-  "occupancy_down",
-  "noi_down",
-  "dscr_below_1",
-  "loan_modified",
-  "maturity_extended",
-  "servicer_advancing",
-  "special_servicing",
-  "delinquent"
-]New value: +[
+  "long_hold",
+  "absentee_owner",
+  "entity_owner",
+  "portfolio_owner",
+  "just_sold",
+  "serial_buyer",
+  "serial_seller",
+  "recorded_mortgage",
+  "no_recorded_debt",
+  "aging_mortgage",
+  "value_below_loan",
+  "foreclosure_filed",
+  "tax_lien",
+  "code_violations",
+  "vacate_order",
+  "fire_vacate",
+  "hpd_litigation",
+  "vacant_storefront",
+  "underbuilt",
+  "vacant_land",
+  "teardown",
+  "land_just_bought",
+  "assemblage",
+  "rezoning_filed",
+  "new_building_permit",
+  "new_co",
+  "entitled_not_built",
+  "loan_maturing",
+  "io_balloon",
+  "weak_coverage",
+  "occupancy_down",
+  "noi_down",
+  "dscr_below_1",
+  "loan_modified",
+  "maturity_extended",
+  "servicer_advancing",
+  "special_servicing",
+  "delinquent",
+  "ll97_covered",
+  "ll97_fine_2024",
+  "ll97_fine_2030",
+  "evictions",
+  "facade_unsafe",
+  "j51_ending",
+  "421a_ending",
+  "low_inspection_grade",
+  "lihtc_year15",
+  "subsidy_expiring",
+  "oz_year10"
+]

changedInput schema / properties / signals / maxItems
```
Previous value: -38New value: +49
```

AddedOct 20, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: exact credit economics (25 free rows/day on paid plans, 1 credit per row after), the quote-before-run workflow, the 'likely' estimate caveat, default page size, max rows, newest-first ordering, and offset paging. It also describes the row shape (BBL, address, owner of record, signals with dates) and the per-signal lot counts.

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?

Purpose is front-loaded and nearly every sentence carries operational weight, but the middle section is a dense wall of key-to-ask mappings, and the signals list partially duplicates the enum already enumerated in the schema. It is long yet mostly earns its length.

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 an 8-parameter, enum-heavy search tool with a paid quote flow, the description covers everything an agent needs: filtering, matching semantics, result contents, credit cost, the mandatory confirmation step, pagination, and where to go for contacts. An output schema exists, so it need not explain return values further.

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 75% and the schema already documents most parameters, so the description's main added value is the ask-to-signal-key mapping, which tells an agent which of the 50 enum values to pick for a given user intent. It also confirms that boroughs/ZIPs/ntas combine and that results narrow by building type, adding meaning beyond the raw field descriptions.

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 ('Lists NYC lots that carry one or more property signals') and immediately defines what a signal is with concrete examples. An agent can distinguish this from sibling searches like search_nyc_underused_properties or search_nyc_preforeclosures without opening the schema.

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

Usage Guidelines4/5

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

Strong when-to-use guidance: it maps real-world asks ('tired landlords', 'loans coming due') to concrete signal keys, and routes the agent to run_nyc_signals_search for paid rows and to unlock_nyc_property_report/unlock_nyc_owner_contacts for contacts. It stops short of stating when NOT to use this tool versus overlapping sibling searches such as search_nyc_preforeclosures, which also surface foreclosure/auction signals.

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?