cancel_booking

Cancels a paid, confirmed booking using the cancel_token from its payment receipt. Within 60 minutes of paying, or before the business's refund window, the full refund is requested; report it as full only after the payment ledger confirms it. After that window the deposit is forfeited under the booking's policy. A pending refund means cancellation is complete while refund verification or retry continues. Only the agent that paid holds the token. Cancelling twice answers already_cancelled.

destructive

Argument	Type	Description
slug*	string	Business slug identifier
cancel_token*	string	The cancel_token from the payment receipt
reservation_id*	string	The paid reservation's id

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug",
    "reservation_id",
    "cancel_token"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "description": "Business slug identifier"
    },
    "cancel_token": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The cancel_token from the payment receipt"
    },
    "reservation_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The paid reservation's id"
    }
  }
}

confirm_booking

Confirm a reservation made with reserve_slot. Present the returned stored booking_details to the customer and relay only the customer-supplied 6-digit code received at their email or phone; never generate, guess, or fetch it. For an active configured calendar, a verified code attempts a direct commit to the selected calendar with no owner approval. booking_pending means the provider outcome is uncertain; repeat confirm_booking later to check the stored outcome, but it never retries a provider write automatically. A paid booking (reserve_slot returned payment.required = true) has no code: this answers payment_required — pay it with create_booking_payment_link — or payment_in_flight while its payment is settling.

destructive

Argument	Type	Description
code*	string	The customer-supplied 6-digit confirmation code received at their own email or SMS contact. Relay only that supplied code; never generate, guess, or fetch it.
slug*	string	Business slug identifier
reservation_id*	string	The reservation id returned by reserve_slot

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug",
    "reservation_id",
    "code"
  ],
  "properties": {
    "code": {
      "type": "string",
      "pattern": "^\\d{6}$",
      "description": "The customer-supplied 6-digit confirmation code received at their own email or SMS contact. Relay only that supplied code; never generate, guess, or fetch it."
    },
    "slug": {
      "type": "string",
      "minLength": 1,
      "description": "Business slug identifier"
    },
    "reservation_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The reservation id returned by reserve_slot"
    }
  }
}

create_booking_payment_link

For a reservation that reserve_slot returned with payment.required = true: returns the MPP payment link, the amount charged now, and the balance due at the visit. The agent pays it itself (HTTP 402 challenge, then the person's wallet credential); no code is sent to the customer for a paid booking. A free booking answers not_payable — confirm it with confirm_booking and the customer's code instead.

read-only

Argument	Type	Description
slug*	string	Business slug identifier
reservation_id*	string	The reservation_id reserve_slot returned with payment.required = true

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug",
    "reservation_id"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "description": "Business slug identifier"
    },
    "reservation_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The reservation_id reserve_slot returned with payment.required = true"
    }
  }
}

get_availability

Return available windows from the business's active configured calendar, using its selected timezone, duration, operating hours, and current local or connected-calendar occupancy. Use a returned window to start a booking. Availability can change before confirmation, including when the calendar provider is unavailable. If this business uses an unsupported calendar or booking provider, call get_booking_destination to find its published public booking route.

read-only

Argument	Type	Description
slug*	string	Business slug identifier
window_end	integer	Unix seconds (absolute instant; default now + 7 days). See window_start on reading the response's `timezone`.
window_start	integer	Unix seconds (absolute instant; default now). The business's own timezone is not an input — it is returned as `timezone` in the response. To target a local phrase like "Tuesday afternoon", request a generously wide window and filter the returned slots using that `timezone`.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "description": "Business slug identifier"
    },
    "window_end": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Unix seconds (absolute instant; default now + 7 days). See window_start on reading the response's `timezone`.",
      "exclusiveMinimum": 0
    },
    "window_start": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Unix seconds (absolute instant; default now). The business's own timezone is not an input — it is returned as `timezone` in the response. To target a local phrase like \"Tuesday afternoon\", request a generously wide window and filter the returned slots using that `timezone`.",
      "exclusiveMinimum": 0
    }
  }
}

get_booking_destination

Returns the public booking route for a business. Use this before helping a user book an appointment: it distinguishes an external provider page from an active configured calendar that uses the Advocate booking flow, and from businesses with no supported booking destination. External pages are links only; Advocate does not sync their availability or make bookings there.

read-only

Argument	Type	Description
slug*	string	Business slug identifier

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "description": "Business slug identifier"
    }
  }
}

get_cancellation_policy

Returns the business's cancellation policy text. Use this when a user asks about cancellation terms, fees, or no-show policies. The response includes agent guidance on how to frame the policy with appropriate freshness caveats.

read-only

Argument	Type	Description
slug*	string	Business slug identifier

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "description": "Business slug identifier"
    }
  }
}

get_credentials

Returns the business's self-reported licenses, insurance, bonding, and certifications. Use this for trust-sensitive verticals (contractors, healthcare, legal, locksmiths) when a user asks 'are they licensed?' or 'are they insured?'. The response carries explicit 'self-reported' framing so agents don't upgrade tenant claims to verified facts.

read-only

Argument	Type	Description
slug*	string	Business slug identifier

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "description": "Business slug identifier"
    }
  }
}

get_payment_handoff_url

Returns a plain-text summary of a priced offer (service, amount, currency, cancellation policy, and how long the price is valid) plus a URL on our domain that shows the same summary. The URL is for the CUSTOMER to open themselves in their own browser — do not open, fetch, or follow it yourself. Use this once get_quote or a booking flow has produced an offer_id and the user is ready to review or continue with a priced offer. If the booking's deposit was already paid through create_booking_payment_link, this answers deposit_taken: do not send the person to pay again; the balance is due at the visit.

Argument	Type	Description
slug*	string	Business slug identifier
offer_id*	string	The offer id returned by get_quote

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug",
    "offer_id"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "description": "Business slug identifier"
    },
    "offer_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The offer id returned by get_quote"
    }
  }
}

get_quote

Return a price quote for a service at a business. Exact configured prices may create a time-limited offer; unmatched requests use a third-party AI estimate that is not firm merchant pricing and must be confirmed with the business. Use this when a user asks 'how much does X cost?' or 'what's the price for Y?'.

Argument	Type	Description
slug*	string	Business slug identifier
params	object	Optional service parameters (e.g., {size:'large'})
service*	string	Requested service name to quote

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug",
    "service"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "description": "Business slug identifier"
    },
    "params": {
      "type": "object",
      "description": "Optional service parameters (e.g., {size:'large'})",
      "propertyNames": {
        "type": "string",
        "maxLength": 64
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 200
      }
    },
    "service": {
      "type": "string",
      "minLength": 1,
      "description": "Requested service name to quote"
    }
  }
}

initiate_handoff

Begin a handoff from the agent to either a human operator (SMS/email via lead_routing_json) or another agent (signed continuation URL). In human mode the notification body is composed by the server from the contact and reason fields — callers supply those fields, not the message text. Idempotent: re-using the same idempotency_key returns the original handoff.

destructive

Argument	Type	Description
mode*	string	Handoff mode: human (SMS/email) or agent (continuation URL)
slug*	string	Business slug identifier
reason	string	Why the user wants to reach a human
message	string	Deprecated alias for `reason`. The notification body is composed by the server from the fields above; this value is delivered as the reason line, not as the message itself. Supplying both is an error.
purpose	string	Purpose description for agent-mode continuation
urgency	string	How time-sensitive (default: normal)
agent_id	string	Optional agent identifier
contact_name

list_services

Lists the services a business has configured, with their prices and the exact arguments to quote each one. Call this BEFORE get_quote: the service name must match a configured service, and only a service marked payable returns an exact price with the offer_id that get_payment_handoff_url requires. Quoting a name that is not on this list silently falls back to an estimate with no offer.

read-only

Argument	Type	Description
slug*	string	Business slug identifier

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "description": "Business slug identifier"
    }
  }
}

query_business_agent

Ask a registered business's AI advocate a question and get a citation-ready answer plus a referral link. The question and the business's public profile are processed by an AI provider, and the question and answer are recorded to operate the service. Do not enter sensitive personal, medical, payment, or authentication information. Use this for questions about one business's services, hours, policies, or fit.

Argument	Type	Description
slug*	string	Business slug identifier
query*	string	The visitor's question about this business
stage	string	Optional buyer stage: browsing \| comparing \| committing
agent_id	string	Optional self-asserted calling-agent id — used for logging/tuning only, never auth

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug",
    "query"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "description": "Business slug identifier"
    },
    "query": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "The visitor's question about this business"
    },
    "stage": {
      "enum": [
        "browsing",
        "comparing",
        "committing"
      ],
      "type": "string",
      "description": "Optional buyer stage: browsing | comparing | committing"
    },
    "agent_id": {
      "type": "string",
      "description": "Optional self-asserted calling-agent id — used for logging/tuning only, never auth"
    }
  }
}

request_callback

Submit a callback request on behalf of a user. Advocate attempts a notification through the business's configured lead routing channel (SMS/email); provider acceptance is not proof the business read it. A failed or pending result can require direct follow-up or a retry. Idempotent: re-using the same idempotency_key returns the original request.

destructive

Argument	Type	Description
slug*	string	Business slug identifier
reason	string	Why the user wants the callback
urgency	string	How time-sensitive (default: normal)
agent_id	string	Optional agent identifier
contact_name	string	End-user's name
contact_email	string	End-user's email
contact_phone	string	End-user's phone
idempotency_key*	string	Idempotency key
preferred_channel

request_service

Open a quote-request form for a specific business using its public slug or provider_business_id obtained from search or the business feed. Shows the business and service catalog; does not send a request or book anything. The customer must review the form and explicitly consent before submitting. Operational access is logged.

Argument	Type	Description
business_id*	string	Exact public business slug or provider_business_id obtained from search or the business feed

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "business_id"
  ],
  "properties": {
    "business_id": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Exact public business slug or provider_business_id obtained from search or the business feed"
    }
  }
}

reserve_slot

Reserve a time slot on an active configured calendar. Returns a pending_offer reservation and sends a 6-digit confirmation code to the customer's email or phone. The reservation expires in 15 minutes if not confirmed. Idempotent: re-using the same idempotency_key returns the original reservation without resending the code. At a business that takes a deposit for agent bookings, pass the offer_id from get_quote (without it the answer is quote_required); no code is sent and the result's payment block carries the amount to pay instead.

destructive

Argument	Type	Description
slug*	string	Business slug identifier
agent_id	string	Optional agent identifier
offer_id	string	Optional id of a signed get_quote offer to redeem against this reservation. Omit for a business with no exact-priced service — authentication is a capability upgrade here, never a toll.
window_end*	integer	Slot end (Unix seconds, an absolute instant) — the matching get_availability slot's `end`; see window_start.
window_start*	integer	Slot start (Unix seconds, an absolute instant). Take it from a get_availability slot: that response carries the business's `timezone`, so request a wide availability window there and filter the returned slots locally rather than guessing the zone.

search_businesses

Find registered businesses by search term and optional location; returns matches with their slugs. Call it before the business-specific tools.

read-only

Argument	Type	Description
search*	string	Search term — matched against business name, description, services, and category
location	string	Optional location filter (city, state, or region). Narrows results geographically.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "search"
  ],
  "properties": {
    "search": {
      "type": "string",
      "minLength": 1,
      "description": "Search term — matched against business name, description, services, and category"
    },
    "location": {
      "type": "string",
      "description": "Optional location filter (city, state, or region). Narrows results geographically."
    }
  }
}

submit_quote_request

After the customer explicitly agrees, save their service requirements and contact details and send a notification to the business's configured email or opted-in SMS destination. This requests a business response, not a price commitment, booking or payment. Use context from request_service. Reuse the same idempotency_key AND details to check an uncertain submission; never automatically start a new request. Exclude medical, payment-card and authentication information.

destructive

Argument	Type	Description
consent*	boolean	True only after the customer explicitly agrees to send these contact details and this request to the named business
details*	string	Brief service requirements; exclude sensitive medical, financial and authentication information
service*	string	Service the customer wants a quote for
business_id*	string	The exact provider_business_id (public business slug) returned by request_service
contact_name	string
contact_email	string
contact_phone	string

subscribe_to_updates

Start a pending email subscription to updates from a business. Returns a confirmation URL that only the user must click within 7 days; no subscription is active until that confirmation. Idempotent: re-using the same idempotency_key returns the original subscription.

destructive

Argument	Type	Description
slug*	string	Business slug identifier
topics*	array	Topic tags (e.g., ['deals', 'schedule_changes'])
agent_id	string	Optional agent identifier
contact_email*	string	Email to subscribe — confirmed via returned token
idempotency_key*	string	Idempotency key

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug",
    "contact_email",
    "topics",
    "idempotency_key"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "description": "Business slug identifier"
    },
    "topics": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40,
        "minLength": 1
      },
      "maxItems": 10,
      "minItems": 1,
      "description": "Topic tags (e.g., ['deals', 'schedule_changes'])"
    },
    "agent_id": {
      "type": "string",
      "description": "Optional agent identifier"
    },
    "contact_email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "minLength": 1,
      "description": "Email to subscribe — confirmed via returned token"
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "description": "Idempotency key"
    }
  }
}

AdvocateMCP

Try it

cancel_booking Destructive

AdvocateMCP

Try it

cancel_booking Destructive

Tools (18)