Mercantry Registry

Filter-based search over the restaurant registry (coverage cities + timezones in get_registry_meta). NOT ranked: results come back in deterministic order (merchant_id ASC by default; distance ASC when lat/lng given and order_by="distance"). Returns compact records with pagination. Use get_merchant for the full signal dump on a specific merchant. All filters are optional and combinable.

{
  "type": "object",
  "properties": {
    "neighborhood": {
      "type": "string",
      "description": "Exact neighborhood name, e.g. 'Mission'"
    },
    "lat": {
      "type": "number",
      "description": "Latitude for geo-radius filter (requires lng and radius_km)"
    },
    "lng": {
      "type": "number"
    },
    "radius_km": {
      "type": "number",
      "description": "Radius in km around lat/lng"
    },
    "cuisine_tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Match ANY of these cuisines, e.g. ['japanese','korean']"
    },
    "attribute_tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Match ALL of these attributes, e.g. ['outdoor_seating','vegetarian_friendly']"
    },
    "price_band_min": {
      "type": "integer",
      "minimum": 1,
      "maximum": 4
    },
    "price_band_max": {
      "type": "integer",
      "minimum": 1,
      "maximum": 4
    },
    "open_at": {
      "type": "string",
      "description": "ISO-8601 datetime; only merchants open at this time. With an explicit offset ('2026-07-18T19:00:00+09:00' or trailing Z) the instant is evaluated in each merchant's own timezone; without one it means each merchant's local wall clock"
    },
    "bookable_only": {
      "type": "boolean",
      "description": "Only merchants the registry can book right now (phone-verified, accepts reservations, not opted out)"
    },
    "party_size": {
      "type": "integer",
      "minimum": 1,
      "description": "Only merchants that can seat this party size"
    },
    "sandbox": {
      "type": "boolean",
      "description": "Filter by merchant kind. true = sandbox test merchants only (safe integration targets: they book end-to-end and return a SIMULATED confirmation, never dialing a real venue). false = real merchants only — use this for any booking a human will act on. Omitted = both. Every result carries `sandbox`; never present a sandbox confirmation to a user as a real reservation."
    },
    "order_by": {
      "type": "string",
      "enum": [
        "merchant_id",
        "distance"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "type": "integer",
      "minimum": 0
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Every field the registry holds on one merchant: schema fields, structured hours, raw feedback history, platform-observed operational stats, and per-field provenance with timestamps. Maximal data, zero opinion — the registry never scores or ranks.

{
  "type": "object",
  "properties": {
    "merchant_id": {
      "type": "string"
    }
  },
  "required": [
    "merchant_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

V1 does NOT hold live table availability — availability is checked on the phone call at booking time. This tool returns the merchant's reservation policy, structured hours, and holiday exceptions so you can pick a plausible time before calling place_booking.

{
  "type": "object",
  "properties": {
    "merchant_id": {
      "type": "string"
    }
  },
  "required": [
    "merchant_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Request a table reservation. Returns booking_id with state 'queued' immediately; fulfillment is asynchronous (a call is placed to the merchant). Poll get_booking_status or supply callback_url for webhooks. RETRY SAFETY: pass a unique client_reference_id (recommended: always); if this call times out or errors ambiguously, retry with the SAME client_reference_id and the registry returns the already-created booking instead of double-booking the restaurant. Never re-call place_booking after a timeout without one. If the merchant counter-offers a time within window_minutes and accept_within_window=true, it is auto-accepted (recommended). Otherwise the booking pauses in needs_input for you to resolve via modify_booking. Merchants on the human_call channel are fulfilled by a human operator during the operator window published in get_registry_meta — those bookings queue until worked (up to the channel SLA), so book ahead rather than for the next hour.

{
  "type": "object",
  "properties": {
    "merchant_id": {
      "type": "string"
    },
    "party_size": {
      "type": "integer",
      "minimum": 1
    },
    "datetime": {
      "type": "string",
      "description": "Requested time, ISO-8601. Naive ('2026-07-18T19:00') means the merchant's LOCAL wall time (see the merchant's timezone field); an explicit offset ('2026-07-18T19:00:00+09:00') is also accepted"
    },
    "window_minutes": {
      "type": "integer",
      "minimum": 0,
      "maximum": 240,
      "description": "Acceptable +/- window around datetime"
    },
    "accept_within_window": {
      "type": "boolean",
      "description": "Auto-accept merchant counter-offers inside the window (recommended: true)"
    },
    "reservation_name": {
      "type": "string",
      "description": "Name for the reservation"
    },
    "contact": {
      "type": "string",
      "description": "Optional phone/email for confirmation relay to the end human"
    },
    "special_requests": {
      "type": "string",
      "maxLength": 280
    },
    "callback_url": {
      "type": "string",
      "format": "uri",
      "description": "Webhook URL for booking state-change events"
    },
    "client_reference_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Your unique ID for this booking request (a UUID is ideal). Retrying with the same value returns the existing booking (idempotent_replay: true) instead of creating a duplicate; the same value with different parameters is rejected as client_reference_conflict"
    },
    "sandbox_outcome": {
      "type": "string",
      "enum": [
        "confirmed",
        "no_answer",
        "counter_offer",
        "fully_booked",
        "merchant_declined",
        "bad_data"
      ],
      "description": "TEST ONLY, sandbox merchants (sandbox: true): force the simulated call's result so you can exercise a specific branch on demand — confirmed, no_answer (retries then fails), counter_offer (pauses in needs_input), fully_booked, merchant_declined, bad_data. Rejected for real merchants; omit it in production"
    }
  },
  "required": [
    "merchant_id",
    "party_size",
    "datetime",
    "reservation_name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

State machine position for a booking: pending → queued → in_progress → confirmed | failed | needs_input (plus cancelled). Includes structured details on confirmation (confirmed_time, confirmation_code, merchant_instructions), structured failure reason (no_answer | fully_booked | closed | policy_mismatch | merchant_declined | bad_data), or needs_input options awaiting your decision. include_events=true returns the full audit log.

{
  "type": "object",
  "properties": {
    "booking_id": {
      "type": "string"
    },
    "include_events": {
      "type": "boolean"
    }
  },
  "required": [
    "booking_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Amend a booking before or after the call. For a booking in needs_input: pass accept_option_index to take one of the merchant's offered times (confirms immediately), or pass a new datetime/party_size to re-queue an amended request. Modifying an already-confirmed booking cancels it and books the new request (new booking_id returned).

{
  "type": "object",
  "properties": {
    "booking_id": {
      "type": "string"
    },
    "datetime": {
      "type": "string",
      "description": "New requested time, ISO-8601; naive means the merchant's local wall time"
    },
    "party_size": {
      "type": "integer",
      "minimum": 1
    },
    "window_minutes": {
      "type": "integer",
      "minimum": 0,
      "maximum": 240
    },
    "accept_option_index": {
      "type": "integer",
      "minimum": 0,
      "description": "Index into needs_input_options to accept"
    }
  },
  "required": [
    "booking_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Cancel a booking in any non-terminal state, or a confirmed reservation (the registry notifies the merchant). Cancellation is mandatory when the human no longer wants the table — no-shows destroy merchant trust and are tracked per developer key.

{
  "type": "object",
  "properties": {
    "booking_id": {
      "type": "string"
    },
    "reason": {
      "type": "string"
    }
  },
  "required": [
    "booking_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Report how a confirmed reservation actually went. Accepted only against a confirmed booking_id, once per booking, within 14 days of confirmation. Structured fields first; optional free text ≤ 500 chars. This corpus is served raw to all agents via get_merchant — it is never editorialized or turned into a score.

{
  "type": "object",
  "properties": {
    "booking_id": {
      "type": "string"
    },
    "reservation_honored": {
      "type": "boolean",
      "description": "Did the merchant honor the reservation?"
    },
    "seated_on_time": {
      "type": "boolean"
    },
    "matched_description": {
      "type": "boolean",
      "description": "Did the merchant match the registry's description?"
    },
    "would_repeat": {
      "type": "boolean"
    },
    "free_text": {
      "type": "string",
      "maxLength": 500
    }
  },
  "required": [
    "booking_id",
    "reservation_honored"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Evaluate the registry itself: per-city coverage (with each city's IANA timezone), merchant/bookable counts, verification and freshness stats, feedback corpus size, schema version, and the documented deterministic ordering rule. Honest by design — including how stale the data is.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}