Agent Recipes

Prompts that work well once you’ve connected an AI agent to Shout. Each recipe lists what to say, the scopes the key needs, the MCP tools the agent will use, and what to expect back.

Copy the prompts as-is or adapt them — agents chain the tools themselves; you never have to name a tool unless you want to.

1. Create a survey and get the link

Create a customer-feedback survey in Shout called “Post-purchase feedback”. Ask for an overall satisfaction rating out of 5 stars, an NPS question, a multiple-choice question about which product they bought (Starter, Pro, Enterprise), and an optional free-text “anything else?” question. Then give me the link to fill it in.

• Scopes: forms:write, forms:read
• Tools used: create_form, then get_form to read back the result and its URL
• Expect: the form is created as a real draft in your account — open it in the Shout builder to tweak wording or theme before sending. The agent gets back the form’s ID, structure and link.

Nineteen question types are supported (ratings, NPS, likert, multiple choice, text, dates, file upload, signature and more — the same set listed in the Forms reference). If you ask for something exotic the agent will be told which types exist and can adjust.

2. Summarise this week’s responses

Look at my “Post-purchase feedback” form in Shout and summarise the responses from the last 7 days: overall satisfaction trend, common themes in the free-text answers, and anything that looks urgent.

• Scopes: forms:read, responses:read
• Tools used: list_forms (to find the form), list_responses with a since filter, get_response for detail
• Expect: a digest, not a data dump — counts, patterns, quotes. For large forms the agent pages through responses with cursors; if there are thousands, ask it to sample or to focus on one question.

Free-text answers are end-user content, so they arrive wrapped in <untrusted_data> markers — the agent is explicitly told not to follow instructions found inside them (why).

3. Triage the support inbox

List the open tickets in my Shout support inbox, newest first. For each one, give me a one-line summary and a suggested priority. Then draft — but don’t send — a reply to the most urgent one.

• Scopes: tickets:read (add tickets:write only if you want it to act, not just read)
• Tools used: list_inboxes, list_tickets, get_ticket — and reply_to_ticket / set_ticket_status only if the key allows writes
• Expect: a prioritised worklist with summaries, plus a draft you can approve.

Replies send real email

reply_to_ticket sends a real email to the customer — there is no draft state on the server. Keep triage keys read-only, review every draft yourself, and only use a tickets:write key in a flow where you approve each send. API replies are honestly attributed (sender shows the key’s name, not a person).

4. Add contacts from a spreadsheet

Here are new sign-ups from our event [paste rows or attach the CSV]. Add each one as a contact in Shout with their name, email and company.

• Scopes: contacts:write (plus contacts:read to check results)
• Tools used: create_contact per row; update_contact for corrections
• Expect: one contact per row. Contacts are de-duplicated by email — if an address already exists, the agent is told about the existing contact instead of creating a twin, and can use update_contact to fill in new details. For very large sheets, remember the rate limit: a few hundred rows is fine, tens of thousands belongs in a script against the REST API.

5. Look up a customer before you reply

Who is jane@acme.com in our Shout account? Show me her contact details, her recent support tickets, and whether she’s answered any of our surveys recently.

• Scopes: contacts:read, tickets:read, forms:read, responses:read
• Tools used: list_contacts (filter by email), get_contact, list_tickets (filtered by contact), get_ticket, list_responses
• Expect: a single customer picture stitched from CRM, inbox and survey data — the kind of cross-referencing that’s tedious by hand and instant for an agent.

6. Ask how to do something in Shout

How do I add skip logic to a question in Shout?

• Scopes: none — how_do_i works with any valid key
• Tools used: how_do_i
• Expect: curated, step-by-step guidance from Shout’s own help content, so the agent answers from real product knowledge instead of guessing at menus.

Limits worth knowing

Honest constraints, so you can design around them:

• 120 requests per minute per key (sliding window). Agents doing big pagination walks or bulk imports will hit it; over the limit they get a 429 with a Retry-After and generally wait it out. Bulk jobs belong in code against the REST API.
• No webhook tools over MCP, deliberately. A webhook is a standing data-forwarding channel, and an agent that could create one could be manipulated into exfiltrating your data continuously. Manage webhooks over REST only.
• No deletes over MCP. Agents can create and update, never destroy — smaller blast radius if a session goes wrong.
• Ticket replies are email-only in v1, and they really send — see recipe 3.
• Scopes bound everything. A recipe only works if the key holds the scopes listed; asking the agent to call whoami shows what it can actually do.