yeehaw-mcp: Instructions file for Codex

AGENTS.md — Yeehaw usage contract

Rules an agent can't infer from the schema. Endpoint: https://yeehaw.bot/mcp (JSON-RPC over HTTP POST). No auth.

When to call what

• find_events — the workhorse. Use for any "what's happening / what's on / things to do" question about Austin.
• overview — call FIRST when you need to trust freshness, or to answer "how much coverage is there?" / "is a source down?". Returns counts + per-source last-ingest + health. No arguments.

find_events arguments

• date_range (required unless id is set): one of today, tomorrow, this_weekend, next_7_days, next_30_days.
• id (optional): fetch exactly one event by its id. When set, date_range and all other filters are ignored. Use it to render/cite a specific event.
• query (optional): free-text; matches event title OR venue name. Substrings are escaped (no LIKE-wildcard injection).
• category (optional): one of music, tech, comedy, arts, film, food, sports, festival, family, community, civic.
• neighborhood (optional): east-austin, downtown, south-congress, rainey, the-domain, north-loop, east-sixth, the-drag (shorthands like east, soco, domain, rainey resolve too).
• price_max (optional): 0 means known-free only (unpriced events excluded — "free" is an affirmative claim). >0 includes unpriced events; the human summary states how many weren't price-filtered.
• limit (optional): default is sensible; results come back ranked then chronological.

What you get back

Each event: id, title, when (ISO 8601), venue, category, price_min/price_max (often null), url (deep link to the source), image, lat/lng, source, confidence. There is also a top-level human one-line summary you can surface verbatim.

Honest caveats (don't over-promise to your user)

• Prices are sparse. Most events have null prices (upstream feeds don't expose them). Don't claim "free" unless price_min === 0. Link to url for ticketing.
• Cite the source. Every event has a source + url — attribute it; don't present Yeehaw data as your own knowledge.
• Austin only (V1). For other cities, say so.
• ask_yeehaw is not live yet — only find_events and overview are advertised in tools/list. Don't call tools that aren't listed.