# Travel Companions — full reference

> Complete tool reference for agents. Summary and links: https://travel.coticsy.com/llms.txt

## Agent instructions

Travel Companions helps people find travel companions for a trip.

How to use these tools:
1. Searching is public. Use search_trips (people posting trips: destination, dates, needs) or search_travelers (who is going somewhere). Pass the destination city and ISO country code, dates as YYYY-MM-DD, and free text in q.
2. Results contain masked traveler cards (first name + last initial, age range, city). Relay each match's "why" sentence to the user. Never guess private details.
3. To post a trip or see personal matches the user must be signed in. If a tool returns UNAUTHENTICATED, ask the user to connect their Travel Companions account and retry.
4. Before any contact, the user must confirm they are 18+ and accept the Terms (https://travel.coticsy.com/terms): show them the link, get an explicit yes, then call accept_terms. Never accept on the user's behalf without asking.
5. Connections are double opt-in: request_connection, then the other traveler accepts. Messages are relayed; contact details are only revealed after both sides are ID-verified (reveal_contact).
6. Errors include "nextStep": follow it literally (it names the tool to call or the link to show).
7. delete_my_account is permanent: confirm with the user first.
Safety: suggest meeting in public places and using report_user / block_user if anything feels wrong.

## Calling tools

- MCP: POST https://travel.coticsy.com/mcp (JSON-RPC, Streamable HTTP, stateless). tools/list returns input and output JSON Schemas.
- REST: POST https://travel.coticsy.com/v1/tools/{name} with the arguments as a JSON body. Auth: "Authorization: Bearer <OAuth token>" or "X-API-Key: tc_...".
- Anonymous GET example: https://travel.coticsy.com/v1/trips?to.city=Lisbon&to.country=PT&startDate=2027-03-01&endDate=2027-03-10
- Errors: {"error":{"code","message","nextStep","requiredTrustLevel"}}. RATE_LIMITED responses include Retry-After.
- Suggested needs tags: share_room, share_car, split_costs, photographer, language_help, safety_buddy, local_guide, activity_partner, nightlife, hiking, road_trip, food_tour, co_working, family_friendly, women_only

## Tools

### search_trips
Search travel companions. Access: public. Read-only.
Find travelers looking for companions. Works without an account. Filter by destination, origin, dates, needs (share_room, split_costs...), languages, sex, age range. Free text `q` matches plans and interests semantically. Results are ranked by compatibility and include masked traveler cards (first name + initial, age range, city).
Arguments:
  - to: object {city, country, lat, lon, radiusKm} — Destination filter
  - from: object {city, country, lat, lon, radiusKm} — Origin filter
  - startDate: string — Calendar date, YYYY-MM-DD
  - endDate: string — Calendar date, YYYY-MM-DD
  - minOverlapDays: integer
  - kind: one of solo|group|meetup
  - needs: array — Match trips that list any of these needs
  - languages: array — Travelers who speak any of these languages
  - sex: array — Traveler sex filter, e.g. ["female"] for women-only
  - ageMin: integer
  - ageMax: integer
  - verifiedOnly: boolean
  - q: string — Free text, semantically matched against plans and interests
  - limit: integer
  - cursor: string
REST: POST https://travel.coticsy.com/v1/tools/search_trips

### search_travelers
Search travelers. Access: public. Read-only.
Browse masked traveler cards (not trip posts). Filter by destination of their open trips, languages, age, nationality, interests, or free text. Useful when the user asks who is going somewhere rather than for a specific date window.
Arguments:
  - to: object {city, country, lat, lon, radiusKm} — Travelers with open trips to this destination
  - languages: array
  - sex: array
  - ageMin: integer
  - ageMax: integer
  - nationality: string — ISO 3166-1 alpha-2 country code, e.g. US
  - interests: array — Match travelers listing any of these interests
  - verifiedOnly: boolean
  - q: string — Free text matched against bio, interests and trip plans
  - limit: integer
  - cursor: string
REST: POST https://travel.coticsy.com/v1/tools/search_travelers

### get_trip
Get a trip. Access: public. Read-only.
Get the public view of one trip by id, including the masked traveler card.
Arguments:
  - tripId (required): string — Opaque identifier
REST: POST https://travel.coticsy.com/v1/tools/get_trip

### get_traveler_card
Get a traveler card. Access: public. Read-only.
Get the public, masked card of a traveler by their public id.
Arguments:
  - publicId (required): string — Opaque identifier
REST: POST https://travel.coticsy.com/v1/tools/get_traveler_card

### list_popular_destinations
Popular destinations. Access: public. Read-only.
Destinations with the most open trips right now. Useful to suggest where companions are easiest to find.
Arguments:
  - country: string — ISO 3166-1 alpha-2 country code, e.g. US
  - limit: integer
REST: POST https://travel.coticsy.com/v1/tools/list_popular_destinations

### list_needs_taxonomy
List suggested needs. Access: public. Read-only.
Suggested `needs` tags. Any snake_case tag is accepted, but these are the common ones.
Arguments:
  (no arguments)
REST: POST https://travel.coticsy.com/v1/tools/list_needs_taxonomy

### get_my_status
Get my account status. Access: public. Read-only.
Tells the agent what the current user can do: trust level, plan, whether a profile exists, and the next steps to unlock more (create profile, accept terms, verify ID).
Arguments:
  (no arguments)
REST: POST https://travel.coticsy.com/v1/tools/get_my_status

### create_or_update_profile
Create or update my profile. Access: account. Changes data.
Create the traveler profile on first call (all required fields) or update parts of it later. Birth date and postal code stay private; others see an age range and city only.
Arguments:
  - displayName: string — Full name or first name. Public view shows first name + last initial.
  - birthDate: string — Private. Used to derive a public age range. Must be 18+.
  - sex: one of female|male|non_binary|other|prefer_not_to_say
  - nationality: string — ISO 3166-1 alpha-2 country code, e.g. US
  - languages: array
  - home: object {city, country, region, zip, lat, lon} — A place. Provide lat/lon when known for better geo matching.
  - bio: string
  - interests: array
  - travelStyle: one of budget|mid|luxury|backpacker|flexible
  - smoker: boolean
  - companionPreferences: object {sex, ageMin, ageMax, languages, verifiedOnly}
  - preferredLanguage: string — Language the user prefers to be addressed in
  - extra: object — Free-form additional attributes
REST: POST https://travel.coticsy.com/v1/tools/create_or_update_profile

### get_my_profile
Get my profile. Access: account. Read-only.
Return the full profile of the authenticated user.
Arguments:
  (no arguments)
REST: POST https://travel.coticsy.com/v1/tools/get_my_profile

### post_trip
Post a trip. Access: account. Changes data.
Publish a trip to find companions. kind=solo (default) for a traveler seeking companions, kind=group to organize a group with N spots, kind=meetup when already at the destination. Requires a profile.
Arguments:
  - kind: one of solo|group|meetup — solo: looking for 1+ companions; group: organizer with N spots; meetup: already at destination
  - from (required): object {city, country, region, zip, lat, lon} — Where the traveler departs from
  - to (required): object {city, country, region, zip, lat, lon} — Destination
  - startDate (required): string — Calendar date, YYYY-MM-DD
  - endDate (required): string — Calendar date, YYYY-MM-DD
  - flexibilityDays: integer — How many days the dates can shift
  - needs: array — What the traveler wants from a companion, e.g. share_room, split_costs
  - plans: string — Free text plans and expectations
  - budgetRange: one of under_500|500_1500|1500_4000|over_4000|flexible
  - groupSizeWanted: integer — How many companions wanted
  - companionPreferences: object {sex, ageMin, ageMax, languages, verifiedOnly}
  - visibility: one of public|link_only|private
  - exactDatesPublic: boolean — If false, public views show the week range instead of exact dates
  - extra: object
REST: POST https://travel.coticsy.com/v1/tools/post_trip

### update_trip
Update a trip. Access: account. Changes data.
Update fields of one of my trips.
Arguments:
  - tripId (required): string — Opaque identifier
  - changes (required): object {kind, from, to, startDate, endDate, flexibilityDays, needs, plans, budgetRange, groupSizeWanted, companionPreferences, visibility, exactDatesPublic, extra}
REST: POST https://travel.coticsy.com/v1/tools/update_trip

### close_trip
Close a trip. Access: account. Changes data.
Close or cancel one of my trips so it no longer appears in search.
Arguments:
  - tripId (required): string — Opaque identifier
  - reason: one of found_companion|cancelled|other
REST: POST https://travel.coticsy.com/v1/tools/close_trip

### list_my_trips
List my trips. Access: account. Read-only.
List the authenticated user's trips, optionally filtered by status.
Arguments:
  - status: one of open|full|closed|cancelled
REST: POST https://travel.coticsy.com/v1/tools/list_my_trips

### get_my_matches
Get matches for my trip. Access: account. Read-only.
Ranked compatible travelers for one of my trips, with reasons. Uses my profile preferences and the other side's preferences.
Arguments:
  - tripId (required): string — Opaque identifier
  - limit: integer
REST: POST https://travel.coticsy.com/v1/tools/get_my_matches

### create_group_trip
Create a group trip. Access: account. Changes data.
Create a group trip with multiple open spots. Same fields as post_trip; kind is forced to group.
Arguments:
  - from (required): object {city, country, region, zip, lat, lon} — Where the traveler departs from
  - to (required): object {city, country, region, zip, lat, lon} — Destination
  - startDate (required): string — Calendar date, YYYY-MM-DD
  - endDate (required): string — Calendar date, YYYY-MM-DD
  - flexibilityDays: integer — How many days the dates can shift
  - needs: array — What the traveler wants from a companion, e.g. share_room, split_costs
  - plans: string — Free text plans and expectations
  - budgetRange: one of under_500|500_1500|1500_4000|over_4000|flexible
  - groupSizeWanted: integer
  - companionPreferences: object {sex, ageMin, ageMax, languages, verifiedOnly}
  - visibility: one of public|link_only|private
  - exactDatesPublic: boolean — If false, public views show the week range instead of exact dates
  - extra: object
REST: POST https://travel.coticsy.com/v1/tools/create_group_trip

### meet_at_destination
Meet at destination. Access: account. Changes data.
Post a meetup for someone already at (or about to arrive at) a destination. kind is forced to meetup.
Arguments:
  - from (required): object {city, country, region, zip, lat, lon} — Where the traveler departs from
  - to (required): object {city, country, region, zip, lat, lon} — Destination
  - startDate (required): string — Calendar date, YYYY-MM-DD
  - endDate (required): string — Calendar date, YYYY-MM-DD
  - flexibilityDays: integer — How many days the dates can shift
  - needs: array — What the traveler wants from a companion, e.g. share_room, split_costs
  - plans: string — Free text plans and expectations
  - budgetRange: one of under_500|500_1500|1500_4000|over_4000|flexible
  - groupSizeWanted: integer — How many companions wanted
  - companionPreferences: object {sex, ageMin, ageMax, languages, verifiedOnly}
  - visibility: one of public|link_only|private
  - exactDatesPublic: boolean — If false, public views show the week range instead of exact dates
  - extra: object
REST: POST https://travel.coticsy.com/v1/tools/meet_at_destination

### join_group_trip
Join a group trip. Access: terms accepted (18+). Changes data.
Request to join an open group trip. Requires terms acceptance. Owner must accept via respond_to_connection.
Arguments:
  - tripId (required): string — Opaque identifier
  - message: string
REST: POST https://travel.coticsy.com/v1/tools/join_group_trip

### accept_terms
Accept terms. Access: account. Changes data.
Record that the user is 18+ and accepts the Terms of Service. Required before connecting with other travelers. Send them {base}/terms first.
Arguments:
  - confirmAge18 (required): boolean
  - acceptTerms (required): boolean
  - termsVersion: string — Defaults to the current TERMS_VERSION
REST: POST https://travel.coticsy.com/v1/tools/accept_terms

### request_connection
Request a connection. Access: terms accepted (18+). Changes data.
Send a connection request to the owner of a trip. Both sides must accept before contact is shared. Requires accept_terms first.
Arguments:
  - targetTripId (required): string — Opaque identifier
  - myTripId: string — Opaque identifier
  - message: string
REST: POST https://travel.coticsy.com/v1/tools/request_connection

### respond_to_connection
Respond to a connection. Access: terms accepted (18+). Changes data.
Accept or decline an incoming connection request.
Arguments:
  - connectionId (required): string — Opaque identifier
  - decision (required): one of accept|decline
REST: POST https://travel.coticsy.com/v1/tools/respond_to_connection

### list_connections
List my connections. Access: terms accepted (18+). Read-only.
List incoming and outgoing connection requests and accepted connections.
Arguments:
  - status: one of pending|accepted|declined|expired|withdrawn
REST: POST https://travel.coticsy.com/v1/tools/list_connections

### send_message
Send a message. Access: terms accepted (18+). Changes data.
Send a relayed message on an accepted connection. Emails stay private.
Arguments:
  - connectionId (required): string — Opaque identifier
  - body (required): string
REST: POST https://travel.coticsy.com/v1/tools/send_message

### get_messages
Get messages. Access: terms accepted (18+). Read-only.
List relayed messages on an accepted connection.
Arguments:
  - connectionId (required): string — Opaque identifier
  - limit: integer
REST: POST https://travel.coticsy.com/v1/tools/get_messages

### reveal_contact
Reveal contact. Access: ID verified. Read-only.
Reveal the counterpart's email (and phone if set) after both sides accept. Requires ID verification (trust level 3).
Arguments:
  - connectionId (required): string — Opaque identifier
REST: POST https://travel.coticsy.com/v1/tools/reveal_contact

### leave_review
Leave a review. Access: terms accepted (18+). Changes data.
Leave a 1-5 star review of a companion from an accepted connection, once the trip is over (from the day after its end date). One review per traveler per trip.
Arguments:
  - connectionId (required): string — Opaque identifier
  - rating (required): integer
  - text: string
REST: POST https://travel.coticsy.com/v1/tools/leave_review

### subscribe_match_webhook
Subscribe to match webhooks. Access: account. Changes data.
Register an HTTPS URL that receives signed POSTs when new matches or connection events fire for this user. Agents use this to proactively notify travelers. The signing secret is returned once.
Arguments:
  - url (required): string
  - events: array
REST: POST https://travel.coticsy.com/v1/tools/subscribe_match_webhook

### report_user
Report a traveler. Access: account. Changes data.
Report a traveler for spam, scam, harassment, fake profile or safety concerns.
Arguments:
  - publicId (required): string — Opaque identifier
  - reason (required): one of spam|scam|harassment|fake_profile|inappropriate|safety|other
  - details: string
REST: POST https://travel.coticsy.com/v1/tools/report_user

### block_user
Block a traveler. Access: account. Changes data.
Block a traveler. Neither side will see the other in search or be able to connect.
Arguments:
  - publicId (required): string — Opaque identifier
REST: POST https://travel.coticsy.com/v1/tools/block_user

### export_my_data
Export my data. Access: account. Read-only.
Return everything stored about the authenticated user (GDPR/CCPA export).
Arguments:
  (no arguments)
REST: POST https://travel.coticsy.com/v1/tools/export_my_data

### delete_my_account
Delete my account. Access: account. Changes data.
Permanently delete the account, profile, trips and messages. Irreversible. The agent must confirm with the user first.
Arguments:
  - confirm (required): boolean
REST: POST https://travel.coticsy.com/v1/tools/delete_my_account

### start_id_verification
Start ID verification. Access: terms accepted (18+). Changes data.
Create a Stripe Identity verification session. Send the returned URL to the user. Unlocks the verified badge and contact reveal.
Arguments:
  (no arguments)
REST: POST https://travel.coticsy.com/v1/tools/start_id_verification

### start_premium_checkout
Start premium checkout. Access: account. Changes data.
Create a Stripe Checkout (Link-compatible) session for Premium. Send the returned URL to the user.
Arguments:
  - plan: one of premium|business
REST: POST https://travel.coticsy.com/v1/tools/start_premium_checkout

### get_subscription
Get subscription. Access: account. Read-only.
Return the current plan, status and usage limits.
Arguments:
  (no arguments)
REST: POST https://travel.coticsy.com/v1/tools/get_subscription

### find_shared_stay
Find a shared stay. Access: terms accepted (18+). Read-only.
Affiliate search for hotels/villas near the destination that two matched travelers can share.
Arguments:
  - connectionId: string — Opaque identifier
  - city (required): string
  - country (required): string — ISO 3166-1 alpha-2 country code, e.g. US
  - checkIn (required): string — Calendar date, YYYY-MM-DD
  - checkOut (required): string — Calendar date, YYYY-MM-DD
  - guests: integer
REST: POST https://travel.coticsy.com/v1/tools/find_shared_stay

### find_flights_together
Find flights together. Access: terms accepted (18+). Read-only.
Affiliate flight search for matched travelers sharing an itinerary.
Arguments:
  - fromCity (required): string
  - toCity (required): string
  - date (required): string — Calendar date, YYYY-MM-DD
  - passengers: integer
REST: POST https://travel.coticsy.com/v1/tools/find_flights_together

### find_travel_insurance
Find travel insurance. Access: account. Read-only.
Affiliate link for travel insurance suitable for companion trips.
Arguments:
  - startDate (required): string — Calendar date, YYYY-MM-DD
  - endDate (required): string — Calendar date, YYYY-MM-DD
  - travelers: integer
REST: POST https://travel.coticsy.com/v1/tools/find_travel_insurance

### find_esim
Find an eSIM. Access: account. Read-only.
Affiliate link for destination eSIMs.
Arguments:
  - country (required): string — ISO 3166-1 alpha-2 country code, e.g. US
  - days: integer
REST: POST https://travel.coticsy.com/v1/tools/find_esim