Tour Buddy

Send a message to the Tour Buddy team: support, feedback, partnership or feature requests. category: inquiry | feedback | feature_request | support | partnership. This immediately creates a ticket and can send email replies to the supplied contact address. Use only when the user asks to contact support and has approved the message and address. The connected member is identified automatically. Returns the ticket id.

create_support_ticket

Create, update or delete one of the artist's OWN email templates (the ones get_artist_templates lists with is_system false). System templates are read-only: to change one, create a copy with the new wording. action: create | update | delete. create needs name and content (subject and phase optional; phase defaults to outreach). update needs template_id (from get_artist_templates) plus any of name, subject, content, phase — only the given fields change. delete needs template_id and removes the template for good, so confirm with the user first. phase is one of outreach, follow_up, negotiation, hold, confirmation and decides when the template is offered. Keep {{ venue_name }} / {{ date }} placeholders exactly as written; they fill in at send time. Returns success plus template (id, name, subject, content, phase) for create and update, success plus template_id for delete, or error when the template is not one of the artist's own.

manage_template

Generate the performance agreement for a booking and save it as a DRAFT. Nothing is sent. `fields` overrides the defaults pulled from the booking: event_date, set_time, guarantee, door_split, deposit, payment_terms, cancellation_terms, notes. Use once terms are agreed; then send_contract. Returns the draft id and a preview URL.

draft_contract

Open a booking for one stop on a tour and send the first outreach email to that stop's primary venue, rendered from the artist's template. date_index is the 0-based position of the date within the tour (see get_tour_with_stops); template_id defaults to the artist's own outreach template, falling back to an agent-approved system one. Errors if the stop already has an active booking. From a connected app this call creates nothing and sends nothing: it returns a preview plus an action_id and a one-time confirm_token, and the outreach goes out only when confirm_action is called with them (the pending action expires after 15 minutes; cancel_action discards it). Returns booking_id, booking_url, venue_name and email_sent once the outreach actually goes out.

send_outreach_to_tour_date

Add a venue to the artist's shortlist (favorites) and mark the artist-venue relationship. Use when the user says they like a room; they can remove it in the app. Returns success.

favorite_venue

File a venue's reply that the user received in their own inbox onto the booking thread, when it did not reach Tour Buddy (the venue dropped the capture address from CC). Use when the user says "the venue wrote back" and get_booking_by_id does not show that message. Args: booking_id; from_email (the venue's address); body (the reply text); subject; received_at ISO time; the message ids if your email tool exposes them. Idempotent per message id. Returns booking_id, thread_id, booking_status (outreach becomes awaiting_response) and needs_response.

record_received_email

Find venues on Tour Buddy by place and room. Use for "venues in Nashville under 300 cap" or "listening rooms in Oregon". For picks ranked by how well they fit a specific artist use suggest_venues_for_artist; for one venue by name use search_venues_by_name. Args: city; state (name or 2-letter code, e.g. "Tennessee" or "TN"); country (name or ISO code, e.g. "United States", "USA" or "US"); min_capacity / max_capacity; venue_type — one of other, club, bar, theater, community_space, outdoor, restaurant, brewery, listening_room, music_venue, house_show, coffee_shop (common phrasings such as "wine bar" or "concert hall" are mapped onto these); genre (one genre the room books); name (contains); verified_only; limit 1-50. Most venues carry venue_type "other", so filter on room type only when the user actually asked for one — it narrows hard. A capacity filter matches only rooms whose capacity is on record, so a venue with no capacity recorded is left out of "under 300 cap" rather than counted as zero. Returns a list of venue records: _id, name, description, address, city, state, country, capacity, venue_type, genres[], amenities, rating, ratings_count, contact_email, phone, booking_contact_name, website, social_links, booking_info, image_urls (absolute URLs only) and ai_analysis (Tour Buddy's fit/quality scores when researched). Read get_venue_by_id for one room's full write-up. On a plan with a monthly venue detail-view limit (Basic) the contact fields are omitted here (venue_contact_limited true); get_venue_by_id returns them and counts one view per new venue.

find_venues

Venues near a point on an existing tour's route, nearest first. Use for "anything between Boise and Bend?" or "find a room near Portland" while filling a gap in a routed tour; for venue search unrelated to a tour use find_venues. location_hint is free text and understands "between X and Y" (both ends are geocoded through Mapbox and the midpoint is searched) as well as a single place. The search covers roughly 150 miles around that point, narrowed to the artist's genres — artist_id defaults to the tour's own artist — and limit caps how many come back (default 5). Returns success, search_location, search_coords and venues[] with venue_id, name, city, state, capacity, venue_type, contact_email, match_score and distance_from_search in miles; an error if the tour is unknown or the hint cannot be geocoded. Pass a venue_id to smart_add_venue_to_tour to put it on the route. On a plan with a monthly venue detail-view limit the contact fields are omitted here (venue_contact_limited true); get_venue_by_id returns them.

find_venue_along_route

Flag a booking for the artist's attention: flag_type financial_mention | date_change | action_required | counter_proposal | status_change, with details. Use when a venue reply needs a human decision. Returns success.

flag_booking

Flag a venue for Tour Buddy's moderators: it is a duplicate of another listing, it has closed, or its record is wrong in a way update_venue cannot fix. For a duplicate, use reason="duplicate" and pass `duplicate_of` = the venue_id of the existing listing you believe should be kept. Resolve both records with search_venues_by_name first; they must be different IDs for the same room. A reason mentioning "duplicate" requires `duplicate_of`. For a closure, use reason="closed". Include supporting evidence or a source URL in `details` for either kind of report. Use this tool when the user asks to report or flag a venue as duplicate or closed. Creates a pending entry in the admin moderation queue and marks the venue for review. It does not merge or delete venues, or change their operational status. Tell the user the report was submitted for admin review. Returns moderation_entry_id and a note after the report is saved; errors come back as `error`. Each call creates a report, so do not resubmit after success.

flag_venue

Candidate show dates spread evenly across a touring window, skipping Sundays and Mondays because most rooms are dark early in the week. Use when the user has a window ("three weeks in May") but no dates yet. This is date arithmetic only — no venue is searched, held or booked. start_date and end_date are ISO ("2026-05-01" or "2026-05-01T00:00:00") and BOTH ends are playable — "May 20 to 22" is a three-day window, so three stops fit. num_suggested_dates is capped at 8 and trimmed further when the window is too short to hold that many, and a reversed range is swapped rather than refused. Returns success and dates[] as ISO timestamps with a short message, or success false with an error when no date could be placed. Feed the dates into create_tour.

generate_tour_dates

One booking in full: artist, venue, status, proposed_date, financial terms, flags and the entire email thread (messages with role, timestamp and content). Use to read a conversation before drafting a reply. Returns the booking record. From a connected app an unknown id and a booking in another account both answer with the same explicit "not found or not available to this account" error, so nothing in the answer says which ids exist.

get_booking_by_id

One tour in full: name, status, date range, start and end locations, and every stop in order with its date, city, chosen venue (name, capacity, contact) and outreach / booking status, plus route totals. Use for "how is my fall tour looking" or before changing a stop. Get tour_id from get_my_context (lists the member's tours). Returns the tour record, stops[] with venue details and status, route distance and travel time, and an outreach summary. From a connected app an unknown id and a tour in another account both answer with the same explicit "not found or not available to this account" error, so nothing in the answer says which ids exist.

get_tour_with_stops

Everything about one tour stop that planning the night around it needs: its date and location label, the venue chosen for it with address and coordinates, and the next stop on the route. Use before suggesting a hotel, a meal or a drive — the next stop says how far the band travels the following morning, and what is already saved keeps you from repeating work. date_index is 0-based within the tour's stops; get_tour_with_stops lists them. Returns success, date, location_label, venue (name, address, city, state, latitude, longitude), next_stop (date, venue_name, city, state, latitude, longitude — null on the last stop), existing_accessories grouped under lodging / food / attractions, and existing_travel_plan; an error if the tour id or the index is unknown.

get_tour_date_context

An artist's public profile: name, genres, bio, location and links. For an artist in your connected account scope, also includes private performance terms, technical requirements and touring preferences. This is a directory read, not an account-scoped one: an artist outside your connected account comes back as their PUBLIC profile, with the private terms above withheld — there is no ownership check to fail. Use for "tell me about this act" or to check what your own profile is missing. Returns the artist profile. From a connected app an id that matches no artist answers with an explicit "not found or not available to this account" error instead of an empty result.

get_artist_by_id

Everything about one confirmed gig: schedule (load-in, soundcheck, doors, set time), advance details, hospitality, venue contacts and ticketing. Use for day-of and logistics questions. Returns the gig record. From a connected app an unknown id and a gig in another account both answer with the same explicit "not found or not available to this account" error, so nothing in the answer says which ids exist.

get_gig_details

One venue in full: name, city/state, capacity, venue_type, genres, contact_email, booking_contact_name, website, booking notes and Tour Buddy's ai_analysis (fit and quality scores when researched). Use after find_venues / suggest_venues_for_artist when you need contact details or booking notes for a specific room. Returns None if the id is unknown.

get_venue_by_id

Actions drafted in this session that are still waiting for the user's confirmation. Use when the user asks "did that go out?" or to recover an action_id. Returns pending[] with action_id, tool, summary, preview and expires_at (never the confirm_token).

list_pending_actions

Artist profiles owned by the member: name, genres, location, website. Use to resolve which artist_id a request is about when get_my_context lists more than one. member_id defaults to the signed-in user. Returns a list of artist summaries with id, restricted to the connection's artist scope.

list_my_artists

All bookings for one artist, newest first, optionally filtered by status: outreach | awaiting_response | negotiating | hold | confirmed | declined | cancelled | pending. Cancelled bookings past their retention window are archived and never returned, even with status=cancelled. Use for "what's in my pipeline". For "what do I owe a reply on" use list_bookings_needing_response. Returns bookings with booking_id, venue_id, status, proposed_date, thread_id and financial terms, each with the row's venue embedded. From a connected app that venue is cut to a summary (_id, name, city, state, capacity, venue_type); call get_venue_by_id for one room in full — contact details, booking notes and Tour Buddy's analysis.

get_artist_bookings

The artist's shows, soonest first. upcoming_only=true hides past shows. Use for "what's coming up" and to find a gig_id for get_gig_details, update_gig or delete_gig. Returns gigs with id, date, status, venue_id, venue_name, city, state, door_time / show_time, guarantee, the public listing title and booking_id — null when the show was logged directly (create_gig or the app) rather than booked through Tour Buddy.

list_my_gigs

The artist's email templates plus the system templates their settings allow, optionally filtered by phase: outreach | follow_up | negotiation | hold | confirmation. Use to pick a template_id for create_booking_with_outreach or to show the user their options. Returns templates with _id, name, subject, content, phase, is_system and is_agent_approved.

get_artist_templates

Fuzzy, case-insensitive venue lookup by name ("the basement" finds "The Basement East"). Use when the user names a venue and you need its venue_id or contact. The name is matched as plain text, never as a pattern, and limit is 1-50 (default 10). Returns candidates with _id, name, location, capacity, venue_type and contact_email (omitted, with venue_contact_limited true, on a plan that meters venue detail views — get_venue_by_id returns it and counts one view).

search_venues_by_name

Get a booking email ready to send from the user's OWN email tool (Gmail, Outlook) when get_my_context says sending_identity.mode is host_email. Nothing is sent by this call. Use with booking_id to continue an existing conversation, or with venue_id (+ artist_id when the member has several acts) to start one. Pass the subject and body you drafted so the card shows the full message. Returns to (the venue's booking email), cc (a Tour Buddy capture address that files the venue's reply-all on the thread), a thread_id, the suggested subject, and instructions. Send with the user's email tool keeping the cc, then call record_sent_email.

prepare_booking_email

The member's unread notifications (action=list, newest first, up to limit) or mark them all read (action=mark_read). member_id defaults to the signed-in user. Returns unread[] — each item carries id, type, title, message, created_at and a `data` object with the ids the notification is about (a venue_invitation's data holds opportunity_id, venue_id and artist_id) — plus count; for mark_read returns the number marked.

notifications

Search everything Tour Buddy has remembered about this user, beyond what is already in context. query is an optional keyword filter; kind narrows to fact | preference | milestone | plan. Use for "what do you know about me?" or when you need an older detail. Returns memories[] with content, kind and saved_at, plus the user's active goals.

recall_memories

Tell Tour Buddy about a booking email the user just sent from their own email tool, so the thread and booking stay in sync. Call this right after the send succeeds, never before. Args: thread_id and (when continuing) booking_id from prepare_booking_email; from_email = the mailbox it went out from; subject and body as sent; provider_message_id = the id your email tool returned; rfc822_message_id (the Message-ID header) if you have it; sent_at ISO time. For a brand-new conversation also pass artist_id and venue_id and a booking is created in status outreach. Idempotent per message id. Returns booking_id, thread_id, booking_status and the reply-capture address.

record_sent_email

Queue a background re-research of a venue: website, booking contacts, capacity, upcoming events. Takes a minute or two and updates the venue record automatically. Use when a venue's details look stale or thin. Returns a success or error message; call get_venue_by_id later to see the refreshed record.

request_venue_refresh

Save several facts, preferences or goals the user stated in this conversation, in one call: durable facts, preferences, milestones, plans and goals they told you about themselves or their career. Each item goes through the same dedup gate as save_memory, so re-sending something Tour Buddy already knows is a no-op. Use it after a stretch of conversation that produced several such details, or when the user asks you to remember what they just told you. Send only what the user said here; ask them first if unsure. Args: `memories`: up to 50 of {content: one short third-person sentence (max 280 chars), kind: fact | preference | milestone | plan, expires_at: ISO date when it stops being true (optional)}; `goals`: up to 10 of {title, target_date (ISO, optional), description (optional)}; artist_id when the items are about one specific act. Never include other people's personal details, contact info, credentials or health data. Returns saved_count, deduped_count, dropped_count and the saved items.

save_memories

Remember something durable the user just told you about themselves or their career, so it carries into future conversations. content: one short declarative sentence in the third person ("Has a new album coming out at the end of the year"). kind: fact | preference | milestone | plan. expires_at: ISO date when this stops being true (e.g. an album release); omit for evergreen facts. goal_title: set this when the user states something they're working toward ("Book a west-coast tour this spring") — it creates a tracked goal alongside the memory. goal_target_date is its ISO deadline. Never save other people's personal details, contact info, or credentials. Returns deduped=true when this was already known — say so plainly instead of implying you learned something new.

save_memory

Drop one stop from a tour, with its venue options; the remaining stops keep their order and shift up. Use for "cut night three" or "we're dropping Spokane". date_index is 0-based — read get_tour_with_stops first, since every removal shifts the indexes after it. If the stop's primary venue already has a booking, the call refuses and comes back with that booking_id and booking_status. force=True overrides that refusal and removes the stop even with an ACTIVE BOOKING on it: the booking itself is not cancelled or withdrawn and the venue is not told, it simply stops being part of the tour — so only pass force when the user has explicitly said to remove a booked stop, and cancel the booking separately. Returns success, the removed venue name, removed_index and remaining_stops, or an error if the tour id or the index is unknown.

remove_tour_date

Save a tour you planned with the user as a real Tour Buddy tour, with its stops, so it shows in the app and can be booked from. Use after agreeing a route ("Bend to Seattle, May 13-17, these five rooms"). Args: name; start_location / end_location as "City, ST"; start_date / end_date YYYY-MM-DD (max one year); description (the intent in a sentence); `stops`: list of {date: YYYY-MM-DD, venue_id (optional, from find_venues), location_label (optional "City, ST"), reasoning (optional, why this room)}; `preferences`: {venue_types: [], capacity_range: {min, max}, genres: [], other_requirements: ""}; plan_summary; num_suggested_dates (defaults to the stop count). Counts toward the plan's monthly tour limit. Returns tour_id, status and the tour with its stops (same shape as get_tour_with_stops).

create_tour

Record the deal terms on a booking: guarantee (whole currency units), door_split (percent to the artist), currency, notes. Use when terms are proposed or agreed in the thread so the contract and invoice pick them up. Returns success.

add_booking_financial_info

Save the lodging, food or attraction picks for one tour stop so they show on the tour in Tour Buddy. Use after working out a stop's overnight: get_tour_date_context for where the stop is and what is already saved, web_search for real options, then this. date_index is 0-based; accessory_type is one of lodging, food or attractions. `items` is a list of {name (required), description, address, url, price_range ("$", "$$" or "$$$"), notes, source}, each stamped with the type and a save time. Saving replaces everything held under that accessory_type for that stop, so send the full list you want kept rather than only the new entries. Returns success, items_count and a message, or an error for an unknown tour, an out-of-range index, or an accessory_type outside the three.

save_tour_date_accessory

General web search, run against DuckDuckGo's HTML results page. Use for facts Tour Buddy does not hold: a venue's current booking email, a festival's dates, a promoter's name. For venues already on Tour Buddy use find_venues / get_venue_by_id first. Returns up to max_results results (10 at most), each with a title and a url and nothing else — there are no snippets or page text, so a result can only be judged by its title and url. A search that fails or matches nothing returns an empty list.

web_search

Send an email to the venue on an existing booking thread, from the artist's connected mailbox. Write subject and body in the artist's voice; Tour Buddy adds the thread headers so replies land in the same thread. Use reply_to_message_id to answer a specific message. For a venue not yet in the pipeline use create_booking_with_outreach. From a connected app this call sends nothing: it returns a preview of the email plus an action_id and a one-time confirm_token, and the message only goes out when confirm_action is called with them (the pending action expires after 15 minutes; cancel_action discards it). Returns success and thread_id once the message actually goes out; fails if the booking's auto-reply limit is reached.

send_booking_email

Email the drafted contract for e-signature (Dropbox Sign) to all signers. Draft it first with draft_contract and let the user approve the draft; afterwards track it with get_contract_status. From a connected app this call sends nothing on its own: it returns a preview plus an action_id and a one-time confirm_token, and the contract only goes out when confirm_action is called with them (the pending action expires after 15 minutes; cancel_action discards it). Returns success and the signature request id once the contract actually goes out.

send_contract

Start a booking with a venue and send the first outreach email from the artist's mailbox, rendered from one of the artist's templates (template_id from get_artist_templates; custom_subject / custom_content override the template text). Use for cold outreach to a venue not yet in the pipeline; for an existing booking use send_booking_email. Args: date as YYYY-MM-DD. From a connected app this call creates nothing and sends nothing: it returns a preview of the outreach plus an action_id and a one-time confirm_token, and the booking is opened and the email sent only when confirm_action is called with them (the pending action expires after 15 minutes; cancel_action discards it). Returns the booking id, thread id and send result once the outreach actually goes out.

create_booking_with_outreach

List verified venue candidates for an artist's booking search, filtered by location and capacity. Use for "where should I play in Nashville". Args: location (city or "City, ST" text, matched as plain text anywhere in a venue's stored location, never as a pattern); min_capacity / max_capacity; limit 1-50 (default 10). Returns venue summaries with _id, name, city, state, capacity, venue_type, genres, contact_email. Review the returned genres and booking details to assess fit; this tool does not compute an artist-specific ranking.

suggest_venues_for_artist

Replace the venue options on one tour stop with a fresh set of suggestions for the same place. Use when the user turns down the rooms proposed for a stop ("none of these work for night three"). date_index is 0-based within the tour's stops; the search reuses the stop's own location label (or the current venue's city), the artist's genres and the tour's saved preferences, and brings back up to three rooms. It overwrites the stop's existing options outright — including one already linked to a booking — so confirm with the user before calling it. Returns success, date_index, location and venues[] with venue_id, venue_name, priority, match_score, available and the venue's details; an error if the tour or the index is unknown, or if nothing else was found near that location.

shuffle_tour_date_venues