Nora search

Flow

1. Ask. The broker types a request on the dashboard and starts a search.
2. Interpret. Nora returns a criteria object, splitting requirements from preferences. The UI renders it as editable controls.
3. Search. The server calls search_spaces on the Broker Tool MCP server as the broker.
4. Show. The dashboard renders exact matches, then near matches, each with checks, key fields and a one-line reason. Editing a criterion re-runs step 3 only.

Criteria contract

Nora’s only output. The model returns structured output only; the server validates it against the schema and checks every neighborhood name against the Broker Tool’s list before searching. Listing data never goes into the interpretation prompt.

{
  "rsf":           { "min": 5000, "max": 7000, "required": true },
  "full_floor":    { "value": true, "required": true },
  "furnished":     { "value": true, "required": true },
  "neighborhoods": { "values": ["Union Square", "Flatiron", "NoHo"], "required": false },
  "term_months":   { "min": 36, "max": 36, "required": false },
  "statuses": ["Active"], "include_near_matches": true, "limit": 10
}

Anything Nora can’t map to a field is returned in unparsed and shown to the broker, never guessed into a filter.

Match rules (first match wins)

1. Excluded: status is not in statuses (default Active only), or the broker can’t see the listing.
2. Exact: every required criterion is met, and the listing was verified within 60 days.
3. Near: one or two required criteria are missed or unknown, and size, if missed, is within 15% of the range.
4. Not shown: everything else.

Preferred criteria never decide which group a listing is in. They only rank within a group.

Field states

Ranking

Computed in the Broker Tool so every client gets the same order. Score is points earned over points available, 0–100. Ties go to the most recently verified listing. Near matches sort by fewest gaps first, then score.

MCP tools

Both are read-only and idempotent. Full JSON Schemas are in mcp/tools.json; real request and response pairs from the mock are in mcp/examples/.

search_spaces(criteria) →
{
  "searched_at": "2026-10-21T21:14:00Z",
  "listings_scanned": 21,
  "excluded_by_status": 1,
  "exact_matches": [ { "listing": {…}, "match": "exact", "checks": [...], "score": 99, "score_parts": [...] } ],
  "near_matches":  [ { "listing": {…}, "match": "near",  "checks": [...], "score": 74 } ]
}

listing.furnished = { "state": "verified" | "unverified" | "unknown", "value": true | false | null }
check = { "key": "furnished", "required": true, "result": "met" | "missed" | "unknown", "detail": "…" }

get_space_details({ "id": "L-1115" }) → full record + asking_rent_psf, building_class,
                                        ceiling_height, listing_broker, notes
                                        error: not_found (missing or not visible)

Server routes

Two routes on the current Next.js app. Editing criteria calls only the second, so the model isn’t re-run on every change.

POST /api/nora/interpret
{ "input": "I'm looking for 5,000–7,000 square feet around…" }
200 { "criteria": { … see contract … }, "unparsed": [] }

POST /api/nora/search
{ "criteria": { … }, "request_id": "uuid" }
  → calls search_spaces over MCP with the broker's session
200 { "result": { …search_spaces output… },
      "summary": "6 listings meet every requirement…",
      "reasons": { "L-1041": "Meets every requirement. It's in Union Square…" } }

Summaries and per-listing reasons are templated from checks and returned fields (see explain() in src/nora.js). If a model rewrites them later, validate that every figure and field it mentions appears in the result.

Permissions and data

• The MCP call carries the broker’s identity. The Broker Tool applies its existing visibility rules; Nora adds none and bypasses none.
• get_space_details runs the same check, so a link to a result can’t leak a listing.
• Results are not cached across brokers. Re-running a search always hits the Broker Tool.
• Rent and lease economics stay out of model prompts.

Acceptance

Run node tests/engine.test.js (Node 18+, no installs). Port the same cases to the real server’s test suite.

Edge cases

• Nothing understood: no search runs; Nora asks for size, area, floor or term.
• No exact matches: say so first, then near matches. Never move a near match into the exact group.
• Neighborhood not in the Broker Tool’s list: show it in unparsed with “not a known area”.
• Listing changes between search and open: details reflect the new record; if it’s gone or no longer visible, say so and offer to re-run.
• MCP timeout or error: keep the criteria, show the error and a retry. Don’t show stale results as current.

Phases

Files in this package