JamBase

PREFERRED tool when an agent wants events for a specific artist by name. Looks up the artist by `artistName`, then runs `searchEvents` against the matched artist id. Combines two upstream calls so the agent doesn't have to chain them manually. **`perPage` lever** (default 100, max 100): an artist tour is a finite enumerable set the user almost always wants in full ('show me all Goose dates'), so the default fills the schema ceiling. Drop to `perPage: 5–10` only when the prompt is explicitly 'next show' or 'tonight' style. When referencing a specific show, always include its **JamBase Event URL** from the result.

findArtistAndFetchEvents

PREFERRED tool when an agent wants events at a specific venue by name. Looks up the venue by `venueName`, then runs `searchEvents` against the matched venue id. **`perPage` lever** (default 20, max 100): keep the default for typical 'what's on at Brooklyn Bowl' style prompts; drop to `perPage: 5–10` on narrow 'next show at Brooklyn Bowl' / 'top 5 upcoming' style prompts; ask for `perPage: 40–100` on broad 'all upcoming shows at Red Rocks this summer' style prompts where the user wants the full lineup. When referencing a specific show, always include its **JamBase Event URL** from the result.

findVenueAndFetchEvents

Reverse-lookup a single artist by ANY supported `<dataSource>:<id>` identifier — use this whenever you already hold a Spotify URI, a MusicBrainz MBID, a Ticketmaster artist id, or a `jambase:` id (e.g. `spotify:3WrFJ7ztbogyGnTHbHJFl2`, `musicbrainz:e2305342-0bde-4a2c-aed0-4b88694834de`, or `jambase:44003`) and want the normalized JBD artist back. Prefer this over `searchArtists` whenever the user message contains a third-party id — it skips the search round-trip entirely.

getArtist

Fetch a single canonical city by its identifier (e.g. `jambase:city:1`). Use this when you already have a city id from a prior `searchCities` result and want the full single-record detail (timezone, parent metro, coordinates).

getCity

Reverse-lookup a single event (concert or festival) by ANY supported `<dataSource>:<id>` identifier — use this whenever you already hold a Ticketmaster event id, an AXS / DICE / Eventbrite / SeatGeek / See Tickets id, or a `jambase:` id (e.g. `ticketmaster:G5vYZ4ZpZAfdJ` or `jambase:10000001`) and want the full normalized JBD event object back. Prefer this over `searchEvents` whenever the user message contains a third-party id — it skips the search round-trip entirely. Always include the **JamBase Event URL** from the result when presenting this event to the user.

getEvent

Fetch a single metro area by its identifier (e.g. `jambase:metro:501`). Use this when you already have a metro id from a prior `getMetros` result and want the full single-record detail (member cities with ids).

getMetro

Reverse-lookup a single livestream by ANY supported `<dataSource>:<id>` identifier — use this whenever you already hold a third-party stream id or a `jambase:` id (e.g. `jambase:str_8821001`) and want the normalized JBD livestream back (broadcast channel, free/paid, end time). Prefer this over `searchStreams` whenever the user message contains a third-party id.

getStream

Reverse-lookup a single venue by ANY supported `<dataSource>:<id>` identifier — use this whenever you already hold a SeatGeek venue id, a Ticketmaster venue id, an AXS / DICE / Eventbrite venue id, or a `jambase:` id (e.g. `seatgeek:18` or `jambase:50001`) and want the normalized JBD venue back (capacity, address, geo). Prefer this over `searchVenues` whenever the user message contains a third-party id.

getVenue

Returns JamBase News articles tagged with the given artist. Accepts either `artistId` (canonical JamBase id) or `artistSlug` (e.g. 'phish').

getArticlesForArtist

Returns JamBase News articles about any performer on the given event, published within ±N days of the event date (default 90). Resolves the event via the JamBase events endpoint to enumerate performers, then queries the article cache for articles tagged with any of those performers. There is no direct event↔article link in the data model — matches are performer-level. Each returned article carries a `matchedPerformers` field naming which event-performer(s) caused it to match.

getArticlesForEvent