Hercules property data

Unlock NYC owner contacts

unlock_nyc_owner_contacts

Spends credits: the contacts price from get_nyc_property (usually 3 credits). Takes only the lot's BBL, including a condo unit's BBL from get_nyc_unit; for a unit whose report is locked it first unlocks the unit report (its report price, usually 1 credit), so quote both. Returns how to reach the party in control of that lot: a name, phone numbers (with line type and do-not-call flag) and email addresses, the contact's role (owner, principal, permit filer, owner's representative or office line), the date the contact was found and the newest recorded deed, lease or transfer. When a recorded deed, lease or transfer names a newer party than the city tax roll, that party is the one looked up. Needs the full report unlocked first (unlock_nyc_property_report). Free if already unlocked for this workspace. Credits are charged when a contact is returned, whatever its role; a miss costs nothing. When an unlocked contact is marked stale (a deed, lease or transfer was recorded after it was found, or it is old), call again with refresh: true to look it up again at the normal price; without refresh a repeat call is always free. Tell the user the cost and get their go-ahead before calling.

Input Schema

Name	Required	Description	Default
`bbl`	Yes	The 10-digit NYC borough-block-lot id, e.g. "1000300034". Get it from find_nyc_property.
`refresh`	No	Look a stale unlocked contact up again at the normal price. Ignored unless the contact is stale.

Output Schema

Name	Required	Description	Default
`bbl`	Yes
`stale`	Yes
`state`	Yes
`emails`	Yes
`person`	Yes
`phones`	Yes
`balance`	Yes
`foundAt`	Yes
`ownership`	Yes
`creditsCharged`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedOct 19, 2026

addedInput schema / properties / refresh

Added value: +{
+  "default": false,
+  "description": "Look a stale unlocked contact up again at the normal price. Ignored unless the contact is stale.",
+  "type": "boolean"
+}

addedOutput schema / properties / bbl
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / foundAt

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

addedOutput schema / properties / ownership

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "basis": {
+          "enum": [
+            "tax_roll",
+            "deed",
+            "lease",
+            "transfer"
+          ],
+          "type": "string"
+        },
+        "docType": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "newestEventDate": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "party": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "recordedDate": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "taxRollOwner": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "party",
+        "taxRollOwner",
+        "basis",
+        "docType",
+        "recordedDate",
+        "newestEventDate"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

changedOutput schema / properties / person / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "name": {
-        "type": "string"
-      },
-      "relation": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "name",
-      "relation"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "name": {
+        "type": "string"
+      },
+      "relation": {
+        "type": "string"
+      },
+      "role": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "name",
+      "relation",
+      "role"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

addedOutput schema / properties / stale
```
Added value: +{
+  "type": "boolean"
+}
```

changedOutput schema / required

Previous value: -[
-  "state",
-  "person",
-  "phones",
-  "emails",
-  "creditsCharged",
-  "balance"
-]New value: +[
+  "bbl",
+  "state",
+  "person",
+  "phones",
+  "emails",
+  "creditsCharged",
+  "balance",
+  "foundAt",
+  "ownership",
+  "stale"
+]

First observedOct 7, 2026

TDQS

A4.4/5.0

Behavior3/5

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

Annotations (readOnlyHint=false, idempotentHint=false) already signal a state-changing, non-idempotent operation; the description goes further with precise billing behavior: credits charged only when a contact is returned, a miss is free, repeat calls without refresh are free, and refresh re-charges at normal price. It does not, however, cover anything beyond cost/idempotency semantics such as rate limits, auth scopes, or failure modes. Solid added value over the annotations, but not exhaustive.

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 most important fact ('Spends credits: the contacts price...') and every subsequent sentence carries a distinct cost, prerequisite, or refresh rule. It is dense and long for a 2-parameter tool, with some stacking of clauses, but no sentence is pure filler.

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 restated, yet the description still orients the agent on the nature of the data. Prerequisites, credit accounting, the free-if-unlocked case, and the stale/refresh flow are all covered, leaving nothing an agent needs in order to call this correctly.

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, but the description adds real meaning: bbl may be a condo unit's BBL obtained from get_nyc_unit (not just find_nyc_property as the schema says), and refresh is 'ignored unless the contact is stale' plus its pricing implication. That is genuine clarification beyond the schema text.

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 ('unlock ... owner contacts') and then enumerates exactly what comes back: name, phone numbers with line type and DNC flag, emails, role, date found, and newest recorded deed/lease/transfer. It is clearly distinguishable from get_nyc_property (which supplies the price) and unlock_nyc_property_report (a prerequisite, not an equivalent).

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?

Explicitly states the prerequisite ('Needs the full report unlocked first (unlock_nyc_property_report)'), the free case ('Free if already unlocked for this workspace'), the repeat-call rule, and when to pass refresh: true. It also gives a procedural instruction to quote the cost and get user approval before calling.

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?