Hercules property data

Search NYC properties and units

search_nyc_properties

Read-onlyIdempotent

Free. Never spends credits. Lists NYC lots, condo units and co-op apartments that match building, sale, value, equity and owner filters, 20 rows per page. For condo or co-op owners, set filters.grain to unit (it is set for you when the asset classes are only condo and co-op): each condo or co-op row is then one condo unit or co-op apartment with its own last sale, estimated value, equity and owner, and names its building. When the person asks for the buildings, set grain to lot. Estimated value (estValueMin, estValueMax) is a sale-based estimate from comparable sales; always say estimated. The city's market value is never shown or filtered. On lots, equity is estimated for 1-3 family homes only. A co-op apartment with no open share loan has 100% equity; with an open share loan its equity is unknown and it never matches an equity filter. ownerBuildingsMin and ownerBuildingsMax count the owner's properties, buildings and units together. Filters the user's plan does not include are left off and named in the result. For one unit's details, call get_nyc_unit with the building BBL and the unit.

Input Schema

Name	Required	Description
`zips`	No	NYC ZIP codes the person named.
`cursor`	No	nextCursor from the previous page.
`filters`	No	The same filters as the Hercules NYC map: assetClasses (condo, coop, one_two_family and more), sale price and dates, estValueMin and estValueMax, equityPctMin, ownerBuildingsMin and ownerBuildingsMax, ownedYearsMin, absenteeOwnerOnly, zips, ntas, signals and more. Leave out anything the person did not ask for.
`boroughs`	No	Whole NYC boroughs. For part of a borough use filters.ntas.

Output Schema

Name	Required	Description	Default
`rows`	Yes
`grain`	Yes
`total`	Yes
`leftOff`	Yes
`nextCursor`	Yes
`totalCapped`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 22, 2026
- addedInput schema / properties / filters / properties / includeNonHomeUnits
```
Added value: +{
+  "type": "boolean"
+}
```

Changed2 schema fields changedOct 22, 2026

addedOutput schema / properties / rows / items / properties / ownerOccupancy

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "likely_absentee",
+        "owner_occupied",
+        "unknown"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / rows / items / properties / ownerOccupancyBasis

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

Changed2 schema fields changedOct 21, 2026

changedInput schema / properties / cursor / pattern

Previous value: -"^[1-5][0-9]{9}(\\|([1-5][0-9]{9}(#[A-Z0-9]{1,8})?)?)?$"New value: +"^(?:[1-5][0-9]{9}(\\|([1-5][0-9]{9}(#[A-Z0-9]{1,8})?)?)?|d:\\d{1,3}:[1-5][0-9]{9})$"

addedOutput schema / properties / rows / items / properties / distressScore

Added value: +{
+  "maximum": 100,
+  "minimum": 0,
+  "type": "integer"
+}

AddedOct 21, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Annotations cover read-only/idempotent safety; the description adds substantive behavior beyond them: free/never spends credits, 20-row pagination, plan-gated filters silently omitted and named in the result, estimated value never to be called market value, and the specific equity semantics for lots and for co-op units with or without an open share loan. This is exactly the interpretive context an agent cannot get from structured fields.

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-loads the free/no-credits fact and the grain decision, then stacks caveats. Nearly every sentence adds decision-relevant information, though the run of edge cases (co-op equity, ownerBuildings counting, city market value) makes it dense for a single paragraph.

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?

An output schema exists, so return values need not be described. Given a 4-parameter tool with a huge nested filter object, the description covers pagination, plan gating, grain auto-selection, estimate semantics, and the handoff to get_nyc_unit — enough to call it correctly without reading code.

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 100%, so baseline is 3; the description still earns above baseline by explaining grain's auto-set rule, estValueMin/Max being a comparable-sales estimate, equityPctMin's limited applicability and co-op unknown-equity case, and that ownerBuildingsMin/Max counts properties, buildings and units together. Large filter families (signals, landUses, zoningFamilies) are left entirely to the schema.

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

Purpose4/5

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

States a specific verb and resource set: lists NYC lots, condo units and co-op apartments matching building/sale/value/equity/owner filters, with page size. It clearly differentiates from get_nyc_unit, but does not distinguish itself from the many other NYC search siblings (search_nyc_signals, run_nyc_signals_search, search_nyc_underused_properties).

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?

Gives concrete conditional routing: set filters.grain to unit when the person is a condo/co-op owner and to lot when they want buildings, and call get_nyc_unit for a single unit's details. No guidance on when to prefer this tool over the signals/underused/preforeclosure search siblings, which is the main remaining ambiguity for an agent.

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?