{"name":"turnout-agent","title":"Turnout Agent API","description":"Turnout's agent surface: the public event catalogue, an organization's own metrics, and drafting tools — the same tools over REST, with the same scopes, budgets and ledger.","version":"1.0.0","protocolVersion":"2025-06-18","protocolVersions":["2025-06-18","2025-03-26","2024-11-05"],"instructions":"Turnout publishes event-catalogue reads, an organization's own analytics, and (from R2) drafting writes. Reads of the public catalogue are anonymous; every tool that touches an organization's own data needs a credential with the matching scope. Every metric carries its own numerator and denominator. `not_available` means the denominator is zero or the input is missing — it is never a zero value. Prefer the narrowest tool: `event_analytics` for one event, `get_organization_analytics` for a period, `discover_events` for the public catalogue. Writes require an idempotency key (`params._meta.idempotencyKey`) and return the same response if the key is repeated.","transport":{"kind":"streamable-http","endpoint":"/api/agent/v1/mcp","method":"POST","contentType":"application/json","stateless":true,"authentication":{"optional":true,"note":"Anonymous callers may use the public catalogue tools; every credential tool needs `Authorization: Bearer tnt_…` (or x-turnout-agent-key)."}},"capabilities":{"tools":{"listChanged":false},"resources":{"supported":false},"prompts":{"supported":false},"logging":{"supported":false}},"tools":[{"name":"discover_events","description":"Search public events: organizers' own published events on Turnout first, then the imported catalogue. When to use it: Use when you need to know what is happening: to find an organizer's published event to offer a user, to find comparable events, to check whether a date is busy, or to answer a question about a place, category or timeframe.","annotations":{"title":"discover_events","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"requiredScopes":[],"auth":"anonymous","kind":"read"},{"name":"get_event","description":"One event by slug: this organization's own event with a credential, else a published public event. When to use it: Use when you already have a slug and need that event's details, either from the caller's own account or from the public sources.","annotations":{"title":"get_event","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"requiredScopes":[],"auth":"anonymous","kind":"read"},{"name":"get_organizer","description":"Public organizer profile from the catalogue: name and upcoming events. When to use it: Use to enrich an event with who runs it, or to see everything one organizer has listed.","annotations":{"title":"get_organizer","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"requiredScopes":[],"auth":"anonymous","kind":"read"},{"name":"check_availability","description":"Reports whether the organization already has an event in a slot, and where the next free one is. When to use it: Use before proposing or creating a date, or when a caller asks whether a slot is free.","annotations":{"title":"check_availability","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"requiredScopes":["events:read"],"auth":"credential","kind":"read"},{"name":"suggest_event","description":"Evidence for planning an event from a brief: comparable events, category, timing and gaps. When to use it: Use when someone describes an event idea and needs evidence about what already exists and where there is room.","annotations":{"title":"suggest_event","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"requiredScopes":[],"auth":"anonymous","kind":"read"},{"name":"get_organization_analytics","description":"The organization's own registrations, funnel, attribution, attendance and agent usage for a window. When to use it: Use for a question about the organization's events over a period: this week, this month, this quarter, a trend over time, or how the events are performing in general.","annotations":{"title":"get_organization_analytics","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"requiredScopes":["analytics:read"],"auth":"credential","kind":"read"},{"name":"event_analytics","description":"One of the organization's events: registrations, attendance, funnel, channels, agent usage. When to use it: Use for a specific event's performance, before or after it runs.","annotations":{"title":"event_analytics","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"requiredScopes":["analytics:read"],"auth":"credential","kind":"read"},{"name":"preview_campaign","description":"What a campaign would send to, who would be excluded and why, and the one measured baseline. When to use it: Use before drafting or scheduling a campaign, to see the reachable audience and the honest baseline.","annotations":{"title":"preview_campaign","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"requiredScopes":["analytics:read"],"auth":"credential","kind":"read"},{"name":"get_campaign_opportunity","description":"Ranked next actions (remind, promote, fix attribution), each with its own evidence. When to use it: Use when asked what to do next, or which event needs attention.","annotations":{"title":"get_campaign_opportunity","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"requiredScopes":["analytics:read"],"auth":"credential","kind":"read"},{"name":"get_budget_status","description":"This credential's budget: calls and cost used today, ceilings, and last-24h usage per tool. When to use it: Use when a call was refused for budget, or to plan a batch without hitting a ceiling.","annotations":{"title":"get_budget_status","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"requiredScopes":["analytics:read"],"auth":"credential","kind":"read"},{"name":"create_rsvp","description":"Register one person for a published event, on the agent path of the funnel. When to use it: Use when a caller explicitly asks to register someone (or themselves) for an event and has given a name and an email address.","annotations":{"title":"create_rsvp","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"requiredScopes":["rsvp:write"],"auth":"credential","kind":"write"},{"name":"create_event_draft","description":"Create an event as a draft — not visible publicly, accepting no registrations. When to use it: Use when someone asks to set up, schedule or draft an event.","annotations":{"title":"create_event_draft","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"requiredScopes":["events:write"],"auth":"credential","kind":"write"},{"name":"update_event","description":"Change one of the organization's own events (draft or published). When to use it: Use when a detail of an existing event has changed: time, venue, capacity, title or description.","annotations":{"title":"update_event","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"requiredScopes":["events:write"],"auth":"credential","kind":"write"},{"name":"publish_event","description":"Publish a draft event: make it publicly visible and able to accept registrations. When to use it: Use only when the caller has explicitly decided the event should go live.","annotations":{"title":"publish_event","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},"requiredScopes":["events:write"],"auth":"credential","kind":"write"},{"name":"cancel_event","description":"Cancel an event so it stops accepting registrations. Does not notify anyone. When to use it: Use when an event will not happen and registrations must stop.","annotations":{"title":"cancel_event","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},"requiredScopes":["events:write"],"auth":"credential","kind":"write"},{"name":"create_campaign_draft","description":"Write a campaign draft for an event: a proposal with a body, not a send. When to use it: Use when someone asks for a reminder, announcement or email to be prepared for an event's registrations.","annotations":{"title":"create_campaign_draft","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"requiredScopes":["campaigns:write"],"auth":"credential","kind":"write"},{"name":"schedule_campaign_reminders","description":"Queue reminders for a draft's mailable audience. Queues — it does not send. When to use it: Use only after a draft has been reviewed and the caller has confirmed it should be prepared for delivery.","annotations":{"title":"schedule_campaign_reminders","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},"requiredScopes":["campaigns:write"],"auth":"credential","kind":"write"}],"rest":{"toolList":"/api/agent/v1/tools","toolCall":"POST /api/agent/v1/tools/{name}","openapi":"/api/agent/v1/openapi.json","discovery":"/.well-known/turnout-agent.json"},"consistency":{"registryIssues":[]}}