Agent Salon SF

START HERE for choosing a service under a budget, with extras, or on a date. Use search_merchants for name/address lookup; use this tool for the service decision. Compare a supported service intent, optional budget/date/neighborhood, strict or nearby geography, and selected add-ons (blow_dry, haircut, toner, shampoo, deep_conditioning, iron_finish, extensions). Returns options, uncertain and excluded service decisions with per-fact sources/dates, known subtotal including requested/mandatory extras, unresolved charges, explicit conditions, hours conflicts and exact next actions. Starting prices and required consultations never become guaranteed final quotes. Deposit is advance payment, not an added charge. There is no provider-confirmed availability; date-specific results are conditional. Time-of-day, stylist and hair-length requirements are unsupported filters here; retain them for merchant confirmation. Ordering is geographic/alphabetic, not a quality rating. No booking or hold is created. Paginated: limit <= 50, offset; use next_offset across all three result groups.

{
  "type": "object",
  "properties": {
    "service_intent": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "color, balayage, balayage color, creative color, color consultation, highlights, haircut, mens haircut, womens haircut, wash cut style, or blowout; unsupported intents are errors"
    },
    "budget": {
      "description": "USD cap for the requested service and selected/mandatory extras. A lower bound is not proof the full price fits.",
      "type": "number",
      "minimum": 0
    },
    "date": {
      "description": "Valid YYYY-MM-DD in America/Los_Angeles; not a confirmed appointment",
      "type": "string"
    },
    "neighborhood": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "geography": {
      "default": "strict",
      "description": "strict by default; nearby requires a neighborhood and explicit permission to include nearby salons.",
      "type": "string",
      "enum": [
        "strict",
        "nearby"
      ]
    },
    "selected_addons": {
      "description": "Only extras the user requested. Mandatory extras are added automatically; unknown charges are not free.",
      "maxItems": 7,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "blow_dry",
          "haircut",
          "toner",
          "shampoo",
          "deep_conditioning",
          "iron_finish",
          "extensions"
        ]
      }
    },
    "salon": {
      "description": "Optional salon slug or ref from search results to compare only that salon.",
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "require_availability": {
      "description": "Require provider-confirmed availability. None exists today; opening hours and candidate times cannot satisfy this.",
      "type": "boolean"
    },
    "limit": {
      "default": 20,
      "description": "Total entries across options/uncertain/excluded; continue with next_offset",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "offset": {
      "default": 0,
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "service_intent"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Filter collection=public-research for researched menus, add-ons, public stylist information and policies. Call get_merchant for the full public_research object. Discovery and name/address lookup, not an extras-inclusive price decision. For a supported service with budget, extras or date, start with compare_options. Find San Francisco hair salons and barbers by name/street (q), neighborhood (with nearby), service, date/time and online booking. Returns compact task summaries by default: depth (profiled = researched in depth; listed = public records + the business’s own site, see depth_note), booking_cta, hours_for_day (published hours for `date`, not live slots), up to 3 matched_offerings with prices, license_status, freshness, availability_basis (published_hours / schedule_candidates = unconfirmed / none); profiled salons add candidate_start_times. Unknown values are null. For published hours/detail only, call check_availability. Before selecting a budget option, call compare_options; follow next_action to confirm unresolved charges and actual appointment availability with the merchant.

{
  "type": "object",
  "properties": {
    "neighborhood": {
      "description": "Neighborhood slug, label or alias (e.g. \"soma\", \"mission\") or an area (e.g. \"union-square\")",
      "type": "string"
    },
    "service": {
      "description": "Service tag (e.g. \"balayage\"), intent slug (e.g. \"hair-color\", \"open-saturday\", \"mens-haircut\") or free text",
      "type": "string"
    },
    "day": {
      "description": "Open on this day per published hours: Mo..Su or e.g. \"saturday\"",
      "type": "string"
    },
    "open_after": {
      "description": "Closes after HH:MM (on `day` if given)",
      "type": "string"
    },
    "has_booking": {
      "description": "Only salons with (true) / without (false) an online booking link",
      "type": "boolean"
    },
    "q": {
      "description": "Business name or street, fuzzy (e.g. \"cinta\", \"hairshaper\", \"23 grant\")",
      "type": "string"
    },
    "include_nearby": {
      "description": "With neighborhood: also include salons within ~400 m (match=\"nearby\", distance_label). Default true.",
      "type": "boolean"
    },
    "date": {
      "description": "YYYY-MM-DD in the city’s timezone (default today): hours_for_day is computed for this date",
      "type": "string"
    },
    "time_after": {
      "description": "HH:MM — with date: only intervals open after this time count",
      "type": "string"
    },
    "time_before": {
      "description": "HH:MM — with date: only intervals open before this time count",
      "type": "string"
    },
    "open_on_date": {
      "description": "Only salons open on `date` per published hours (not live slots)",
      "type": "boolean"
    },
    "view": {
      "description": "summary = compact task view (default); full = every field",
      "type": "string",
      "enum": [
        "summary",
        "full"
      ]
    },
    "collection": {
      "description": "Only independently researched public-source profiles; missing fields are UNKNOWN; booking stays on salon website",
      "type": "string",
      "const": "public-research"
    },
    "depth": {
      "description": "Only salons of this depth: profiled (booking-system depth), detailed (priced menu + booking link + hours or durations), listed (the rest)",
      "type": "string",
      "enum": [
        "profiled",
        "detailed",
        "listed"
      ]
    },
    "haircut_type": {
      "description": "Only salons with an offering of this normalized haircut type (profiled salons)",
      "type": "string",
      "enum": [
        "cut",
        "cut_wash",
        "cut_wash_style",
        "buzz",
        "beard_trim",
        "blow_dry",
        "other"
      ]
    },
    "hair_length": {
      "type": "string",
      "enum": [
        "short",
        "medium",
        "long",
        "any"
      ]
    },
    "max_price": {
      "description": "Base offering price in USD, not the complete service with extras; use compare_options for that. Only offerings whose price is KNOWN to be at most this (fixed or bounded range); starting prices do not count",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "stylist": {
      "description": "Stylist display name (profiled salons)",
      "type": "string"
    },
    "specialty": {
      "type": "string"
    },
    "require_availability": {
      "description": "Only offerings with PROVIDER-CONFIRMED start times in the date/after/before window. Schedule-derived candidate start times never satisfy it; salons that have only candidates are returned under `unconfirmed` with unconfirmed_reason. No salon has provider-confirmed availability today.",
      "type": "boolean"
    },
    "after": {
      "description": "HH:MM earliest start (with date); applied to start times only under require_availability",
      "type": "string"
    },
    "before": {
      "description": "HH:MM latest start (with date); applied to start times only under require_availability",
      "type": "string"
    },
    "limit": {
      "description": "Default 10, max 25",
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Published facts for one salon, NOT live availability and NOT an extras-inclusive quote. For a service/budget/extras/date decision use compare_options with salon=ref. For one salon (ref from search_merchants) and a date: published opening hours on that date (open/closed — NOT live appointment slots), offerings matching the service with published prices and durations, the booking link and step-by-step booking instructions. Profiled salons add candidate start times (candidate start times from the salon's published staff schedule; existing bookings are not subtracted, so some may already be taken — confirm on the booking page). Same contract as GET /api/v1/availability?ref=.

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "description": "\"<city>/<vertical>/<slug>\""
    },
    "date": {
      "description": "YYYY-MM-DD (default today in the city’s timezone)",
      "type": "string"
    },
    "service": {
      "description": "e.g. \"balayage\", \"mens-haircut\" or free text",
      "type": "string"
    },
    "time_after": {
      "type": "string"
    },
    "time_before": {
      "type": "string"
    }
  },
  "required": [
    "ref"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

All published facts for one salon by ref "<city>/<vertical>/<slug>" (from search results), with crawl_log (every source fetched or checked, with time, result and the facts it gave) and last_verified_at: address, phone, hours, licence, registry, services with published prices, booking link, per-field sources (verification), what we verified and what we did not.

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "description": "e.g. \"san-francisco/hair-salon/hairshaper\""
    }
  },
  "required": [
    "ref"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Use collection=public-research for public-source profiles with menus, add-ons, stylist information and policies; get_merchant returns the full public_research object. Salons covered (San Francisco), ordered profiled, detailed, then listed, with depth, neighborhood, price floor and range, stylist count, availability basis and freshness, last_verified_at and verification date. Paginated: limit (default 50, max 200), offset, depth=profiled|detailed|listed.

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "const": "public-research"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "depth": {
      "description": "profiled = booking-system depth; detailed = priced menu + booking link + hours or durations; listed = the rest",
      "type": "string",
      "enum": [
        "profiled",
        "detailed",
        "listed"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Base offering lookup by haircut type, length or stylist. Use compare_options for a supported service with budget, extras or date; preserve any unsupported stylist/length/time requirements for merchant confirmation. Find haircut offerings (and optionally stylists and candidate start times) that satisfy ALL given constraints, across profiled salons (hand-normalized menus) and listed salons (type and inclusions inferred from the service name; offering.comparable says whether it can be compared apples-to-apples). Start times are candidate start times from the salon's published staff schedule; existing bookings are not subtracted, so some may already be taken — confirm on the booking page (slotBasis "schedule_candidates", bookingsSubtracted false, availability_basis "schedule_candidates" = UNCONFIRMED). require_availability=true is satisfied only by provider-confirmed availability (the booking provider’s own open times, existing bookings subtracted). No salon on this site has provider-confirmed availability today: profiled salons have candidate start times from the published staff schedule (existing bookings not subtracted, so they may already be taken) and listed salons have published opening hours only. Offerings with matching candidate start times are listed under `unconfirmed`; confirm on the booking page. Hard constraints are never relaxed silently; when nothing matches, noMatch.reason explains which constraint blocked and nearest suggests the smallest change. Prices are published menu or online-booking prices in USD; this search does not add requested or mandatory extras. Times are salon-local (America/Los_Angeles).

{
  "type": "object",
  "properties": {
    "haircut_type": {
      "type": "string",
      "enum": [
        "cut",
        "cut_wash",
        "cut_wash_style",
        "buzz",
        "beard_trim",
        "blow_dry",
        "other"
      ]
    },
    "hair_length": {
      "type": "string",
      "enum": [
        "short",
        "medium",
        "long",
        "any"
      ]
    },
    "q": {
      "type": "string",
      "maxLength": 100
    },
    "max_price": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "neighborhood": {
      "type": "string",
      "maxLength": 80
    },
    "stylist": {
      "type": "string",
      "maxLength": 80
    },
    "specialty": {
      "type": "string",
      "maxLength": 60
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "after": {
      "type": "string",
      "pattern": "^\\d{2}:\\d{2}$"
    },
    "before": {
      "type": "string",
      "pattern": "^\\d{2}:\\d{2}$"
    },
    "require_availability": {
      "default": false,
      "type": "boolean"
    },
    "limit": {
      "default": 10,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Full record for one salon as markdown: facts, hours, every haircut service with price/duration/inclusions, stylists, policies, attributes, evidence, booking rules, candidate start times from the published schedule. Every fact carries a status tag and date.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Salon slug, e.g. \"hairshaper\""
    },
    "format": {
      "default": "markdown",
      "type": "string",
      "enum": [
        "markdown",
        "json"
      ]
    }
  },
  "required": [
    "slug"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One stylist, under the name the salon's booking system shows: salon, bookable status, specialty evidence with sources, services and prices, candidate start times from the published schedule, and booking link.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Stylist slug, e.g. \"hairshaper-shirley\", or a display name like \"Shirley\""
    },
    "format": {
      "default": "markdown",
      "type": "string",
      "enum": [
        "markdown",
        "json"
      ]
    }
  },
  "required": [
    "slug"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

NOT live availability. Use compare_options for budget/extras/date decisions. Candidate start times for one offering at one salon, optionally one stylist and a date/time window: candidate start times from the salon's published staff schedule; existing bookings are not subtracted, so some may already be taken — confirm on the booking page. Results carry slotBasis "schedule_candidates" and bookingsSubtracted false; freshness tells you how old the capture is.

{
  "type": "object",
  "properties": {
    "salon": {
      "type": "string"
    },
    "offering": {
      "type": "string",
      "description": "Offering id or slug from get_salon"
    },
    "stylist": {
      "type": "string"
    },
    "date": {
      "description": "Salon-local date",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "after": {
      "type": "string",
      "pattern": "^\\d{2}:\\d{2}$"
    },
    "before": {
      "type": "string",
      "pattern": "^\\d{2}:\\d{2}$"
    },
    "limit": {
      "default": 50,
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "required": [
    "salon",
    "offering"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The salon's own booking URL plus exact remaining steps for a given service, stylist, and start time. This site never books on the user's behalf; precision says how much the link pre-selects.

{
  "type": "object",
  "properties": {
    "salon": {
      "type": "string"
    },
    "offering": {
      "type": "string"
    },
    "stylist": {
      "type": "string"
    },
    "start": {
      "description": "ISO start time from get_availability",
      "type": "string"
    }
  },
  "required": [
    "salon"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}