citytracker.ai

Return an orientation overview of the CityTracker data model (NYC real-estate: DOB filings/permits, ACRIS documents, HPD violations, tax lots, companies) plus the list of documented curated assets. Call this first to learn what data exists and how to explore it. The overview also states what is NOT in the schema, so it is the fastest way to tell a question this data can answer from one it cannot. Takes no arguments.

overview

Describe the columns and data types for a table in the public schema of the read-only replica. For the documented replica tables, the result is enriched with a `label`, entity-level `notes`, a per-column `description`, and a `docs_url` for the REST API dataset over the same table (null otherwise; it documents the API, not these columns). A column the documentation does not cover gets description: null. The `notes` are the authoritative domain rules — column semantics vary by table (e.g. ACRIS party roles depend on doc_type), so read `notes` before querying. Foreign-key columns also carry a `references` object ({table, column}) naming the exact join target — join to that, not to a table you infer from the column name (e.g. filing.filing_company_id references company_raw_data, not company).

describe_table

List the base tables in the public schema of the read-only replica database. Returns a flat `tables` list of names plus a `labels` map of table -> human-readable label for every documented table (undocumented tables are omitted from `labels`). Use it to confirm a table exists before querying it — table names are not always the obvious ones (NYC PLUTO tax-lot data is `tax_lot`, not `pluto`). Takes no arguments.

list_tables

Run a single read-only SQL SELECT against the NYC real-estate replica and return up to 1000 rows as {columns, rows, truncated}. Writes, multiple statements and EXPLAIN ANALYZE are rejected; the database connection is read-only, so nothing this tool does can modify data. Target: the CityTracker NYC real-estate replica, documented at https://citytracker.ai/api/asset/docs (one page per dataset, with columns, filters and source links). Call `describe_table` before writing a query: this schema has per-table traps (foreign keys that point at *_raw_data rather than the table their name suggests, and columns whose meaning varies by table) that the entity-level `notes` spell out. Limits: a 15s statement timeout, a 1000-row cap and a total response-size cap. `truncated: true` means rows were dropped — the result is a partial prefix, NOT a complete answer, so never total or count it as if it were; re-run with an aggregate (COUNT/SUM/GROUP BY) or a narrower filter instead. A timeout means the query was too broad, not that the data is missing: add a filter on an indexed key or a date range and retry.

query