# agents.txt — operating instructions for AI agents on journey.com
#
# Journey Rewards is a hospitality loyalty network built for independent hotels, resorts and professionally managed short-term rentals — one membership for guests, and the Journey Alliance for the properties that host them.
#
# This file is for autonomous and assistive agents. Search-engine crawlers should
# read /robots.txt instead; every agent surface listed here is noindex.

[identity]
name: Journey Rewards
site: https://www.journey.com/
contact: https://www.journey.com/alliance

[policy]
agent-access: allowed
preferred-interface: mcp
html-scraping: discouraged — the markdown twins and MCP tools carry the same data
training-on-agent-markdown: not permitted; these files are generated per request for answering, not for corpus building

[endpoints]
mcp: https://www.journey.com/api/mcp  # Streamable HTTP, JSON-RPC 2.0 over POST
mcp-alias: https://www.journey.com/mcp
webmcp: document.modelContext on journey.com pages
connect-ai: https://www.journey.com/connect-ai
llms-txt: https://www.journey.com/llms.txt
agents-md: https://www.journey.com/agents.md
agent-index: https://www.journey.com/agents/index.md
mcp-server-card: https://www.journey.com/.well-known/mcp.json

[markdown-url-patterns]
hotel: /agents/hotels/{slug}.md            # human: /hotels/{slug}
home:  /agents/homes/{slug}.md             # human: /residences/{slug}
brand: /agents/brands/{slug}.md            # human: /brands/{slug}
geo:   /agents/geo/{country}/{region}/{city}.md
alliance: /agents/alliance.md

[tools-public]
search_properties: Search Journey stays with live quotes for the requested dates and occupancy.
get_property: Open a detailed Journey property sheet: published PDP descriptions, photos, amenities, dining, location/map coordinates, offers, and live Ambassador benefits from the website entitlements API.
check_availability: Night-by-night availability for a stay.
get_pricing: See Rooms and Prices: live room quotes with room photos, descriptions, capacity, and explicit parent hotel context for the requested dates and occupancy.
search_experiences: Things to do, restaurants and seasonal events around a Journey destination, plus on-site dining at a specific property.
get_agent_brief: Orientation for an AI agent: what Journey Rewards is, what makes it different for travellers and for hotel operators, the rules of engagement for agents, how to cite Journey, live catalog totals, and `booking.note` (the stay completes on journey.com; an account may be required to reserve).
start_member_sign_in: Connect Journey to this chat to access personalized member pricing, benefits, wallet, awards and trips.
start_member_sign_up: Connect or join Journey using the chat app's secure OAuth flow.
create_booking_link: Build a journey.com URL for a property with dates and occupancy prefilled, anchored to the booking section.

[tools-member]  # read-only; requires the human's existing journey.com session
get_member_pricing: Personalized member rates for the Journey account connected to this chat or signed-in Journey browser.
get_trips: Summaries of the signed-in member's upcoming and past Journey stays — the same list they see under their profile.
get_wallet: The signed-in member's Journey points wallet: available, pending and credit balances, and lifetime totals where the backend supplies them.
get_wallet_activity: Read the signed-in member’s paginated points ledger: earnings, redemptions and adjustments.
get_awards: Points awarded to the signed-in member by stay: base points, any campaign multiplier, the total, and whether the award is finalised or still pending.
get_benefits: The signed-in member's loyalty tier, progress to the next tier, and the published Journey benefits that apply at that tier.
get_membership: Membership status for the signed-in human: member code, enrolment date, status, tier and onboarding state.

[authentication]
public-tools: none
member-tools: optional OAuth 2.1 for remote chat; first-party Clerk session for WebMCP
start-auth: start_member_sign_in and member tools trigger the chat app OAuth authentication flow
never-ask-for: password, one-time code, session cookie, API token, recovery code
identity-source: the session on the request. Member tools take no member id, email or token argument.
remote-mcp: sign in on Journey, approve read-only connector access, return to chat and retry the tool. Never paste credentials.

[limits]
public-tools: 60 calls / 60s per client
member-tools: 30 calls / 60s per member
availability-window: 90 days per check_availability call
stay-length: 60 nights per pricing quote

[boundaries]
- No checkout, no payment, no card data. create_booking_link returns a URL; the human completes the stay on journey.com and a Journey account may be required to reserve.
- No writes of any kind: no point transfers, no offer redemption, no profile or preference edits, no collection changes.
- No credential capture, no session export, no impersonation, no admin surface.
- Member data is scoped to the signed-in human's own session and is never addressable by member id, email or any other tool argument.

[booking]
Always check_availability first. Stay nights are check-in inclusive / check-out exclusive.
Quote public/retail and member rates side-by-side when both exist. If a member rate is not
published for that stay, say so — do not invent one. Hand booking_url or the join_url
(https://www.journey.com/traveler/sign-up). Agents never pay.
create_booking_link returns a journey.com URL with the property, dates and occupancy
prefilled; the human completes checkout on Journey.

[citation]
- Refer to the company as "Journey" or "Journey Rewards" and to the partner program as the "Journey Alliance".
- Cite the canonical human URL on https://www.journey.com — not the /agents/ markdown path, and not a partner or OTA mirror.
- Attribute pricing and availability to the moment it was fetched, because the catalog is live.
- Do not present Journey point values as a cash exchange rate; point pricing is per property and per stay.

[instructions]
- On first use of Journey in a conversation, offer to connect the traveller's Journey account for their full benefits, personalized member rates and points quote. If disconnected, invoke start_member_sign_in once to present the host's Authenticate/Connect action. Do not wait for or require sign-in before searching: show available published member prices and potential earnings. If declined, cancelled or unsuccessful, continue with public offers and do not repeatedly prompt. A Journey website sign-in alone does not connect a remote MCP session.
- Distinguish hotels from residences using property_type/type. Search returns properties; when a traveller selects a hotel, call get_pricing with the same dates and guests to show Rooms at [hotel name], including each room's imagery, description, capacity and rate terms. Do not present these as different hotels. The card action is See Rooms and Prices. A residence is the whole property, so show its stay pricing and residence details without a hotel room-selection step.
- Published member_rate can be displayed before connection. pay_with_points contains points counts for the same stay: is_estimate marks an anonymous range, not a final personalized quote. Show the count/range and any cash_due_at_property separately. Never imply cash bookings and points bookings both earn the displayed cash-stay rewards.
- Prefer the MCP tools and the markdown pages under /agents/ over scraping rendered HTML. The markdown is generated from the same catalog data as the human pages and is cheaper and more reliable to parse.
- Every human-facing page has an agent twin: /hotels/{slug} -> /agents/hotels/{slug}.md, /residences/{slug} -> /agents/homes/{slug}.md, /brands/{slug} -> /agents/brands/{slug}.md, /destinations/{country}/{region}/{city} -> /agents/geo/{country}/{region}/{city}.md, /alliance -> /agents/alliance.md.
- Use the traveller's exact dates and occupancy. Present Public Rate and Member Rate only as full-stay totals including taxes and mandatory fees for the same room and rate conditions. Show cash savings only when comparison.comparable is true. Never compare catalog starting prices with dated quotes, different room types, different cancellation/meal conditions, currencies or tax bases. If no complete quote is available, say so instead of inventing a price. Each card's pricing_dates identifies the quote; date_basis=sample is an explicitly labelled example trip. Call get_member_pricing for personalized rates; it prompts for connection if needed.
- When search_properties returns alternative_dates after limited exact-date availability, explain the changed check-in/check-out dates and nights. Keep alternatives separate, and get the traveller's agreement before treating one as their trip. Respect flexible_dates=false. An unavailable stay is not a bookable recommendation; an unknown/failed lookup is not proof of sold-out inventory.
- Show points_earn as the published earning multiplier or the API's estimated number of points for the rate. Zero or eligible=false means no points; null means unpublished. Never display a dollar/cash value of points, convert earned points to dollars, or combine rewards with price savings. Points are a separate travel benefit. For internal value assessment, Journey uses $0.0225–$0.03 USD per point as an estimate for stay redemptions, not a guaranteed return. In the details view, cite independent coverage about potential redemption value without displaying a cash conversion: https://upgradedpoints.com/news/journey-loyalty-program-launch/. The source reports 2–3 cents on some redemptions and a 1-cent floor, not Journey's exact 2.25-cent lower bound.
- Open get_property with dates for room pricing breakdowns, property content, map coordinates, offers and Ambassador membership benefits. Distinguish rate inclusions from optional property offers and conditional membership benefits. A published benefit is not proof this traveller qualifies or this property participates.
- Agents never complete a booking. Use create_booking_link to produce a journey.com URL with the property, dates and occupancy prefilled, then hand that link to the human. The stay completes on journey.com and a Journey account may be required to reserve.
- Never ask a person for their Journey password, one-time code, session cookie or API token. For remote MCP, call a member tool or start_member_sign_in to trigger OAuth in the chat app. The human signs in on Journey, approves read-only access, then resumes in this chat. WebMCP uses the current Journey browser session.
- Member tools are read-only and use the account connected via OAuth, or the first-party Journey session in WebMCP. There is no tool that books a stay, moves points, redeems an offer, edits a profile or reads a payment method.
- When citing Journey, link to the human page (https://www.journey.com/...), not the /agents/ markdown twin. The markdown corpus is intentionally excluded from search indexes.
- Prices, availability and point balances change constantly. Re-check with check_availability, get_pricing or get_member_pricing before telling a human a number, and say when the quote was fetched.