> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insito.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools & prompts

> The tools the Insito MCP server exposes, and example prompts to drive them.

The server exposes 15 tools covering apps, surveys, analytics, responses,
audience, and higher-level workflows. IDs accept either the short URL slug
(e.g. `a1b2c3d4`) or the full UUID — `list_apps` and `list_surveys` are the
easiest way to discover them.

## Apps

| Tool        | Description                                                             |
| ----------- | ----------------------------------------------------------------------- |
| `list_apps` | List the apps (projects) in your workspace.                             |
| `get_app`   | One app's details, including its SDK API key and identified-user count. |

## Surveys

| Tool              | Description                                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `list_surveys`    | List an app's surveys with status, trigger key, and response counts.                                                              |
| `get_survey`      | One survey's full configuration (status, trigger, questions, schedule).                                                           |
| `list_events`     | List the events an app can trigger surveys on (SDK auto-discovered + curated) — pick a valid `triggerKey` before `create_survey`. |
| `create_survey`   | Create a survey. It starts as a **draft**.                                                                                        |
| `update_survey`   | Edit a survey's draft — name, questions, trigger, schedule.                                                                       |
| `activate_survey` | Publish pending draft changes and make the survey **live**.                                                                       |
| `pause_survey`    | Pause a live survey so it stops showing to users.                                                                                 |

<Note>
  Insito uses a **draft → live** model. `create_survey` and `update_survey` write
  to the draft; nothing is shown to users until you run `activate_survey`. This
  mirrors the dashboard's builder, so an agent and a teammate can't step on each
  other's live surveys.
</Note>

### Question types

`create_survey` and `update_survey` take a `questions` array. Each question has
a `type` and type-specific fields:

| Type                            | Key fields                                                        |
| ------------------------------- | ----------------------------------------------------------------- |
| `nps`                           | `text` (the 0–10 recommend question)                              |
| `rating`                        | `text`, `ratingScale` (e.g. 5)                                    |
| `multiple_choice`               | `text`, `choices[]`, `multiSelect`, `allowOther`, `maxSelections` |
| `open_text`                     | `text`, `placeholder`, `maxLength`                                |
| `welcome_screen` / `end_screen` | `text` (heading), `body`, `buttonText`                            |

## Analytics & responses

| Tool            | Description                                                                           |
| --------------- | ------------------------------------------------------------------------------------- |
| `get_analytics` | NPS score, promoter/passive/detractor split, and 30-day trend for a survey.           |
| `get_responses` | List individual responses for an app, filterable by survey, platform, and date range. |
| `get_audience`  | Identified-user count and captured user properties for an app.                        |

<Note>
  Platform and locale audience breakdowns aren't available through the API yet
  — `get_audience` returns the user count and custom user-property distribution.
</Note>

## Composite tools

Higher-level tools that combine several API calls into one step:

| Tool                  | Description                                                                                                                                                              |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `summarise_responses` | Collects a survey's open-text answers (up to the 500 most recent responses) into a de-duplicated corpus with occurrence counts, ready for the agent to turn into themes. |
| `compare_periods`     | Compares a survey's NPS between two date ranges — score, response volume, promoter/detractor share, and deltas, with small-sample caveats.                               |
| `suggest_survey`      | Suggests a ready-to-create survey (name, trigger key, questions with copy) for a stated goal like "understand churn" — the output chains straight into `create_survey`.  |

## Example prompts

Once configured, drive everything in natural language:

* **Discover** — "List my Insito apps and their surveys."
* **Events** — "What events can I trigger a survey on in the Acme app?"
* **Create** — "In the Acme app, create an NPS survey called 'Onboarding NPS'
  that fires on the `onboarding_completed` event, with a 0–10 NPS question and an
  open-text 'What could be better?' follow-up. Then make it live."
* **Edit** — "Add an end screen saying 'Thanks!' to the Onboarding NPS survey
  and publish it."
* **Analyse** — "What's the NPS score for the Onboarding NPS survey, and how has
  it trended over the last 30 days?"
* **Browse** — "Show me the 10 most recent responses for the Acme app on iOS."
* **Segment** — "What user properties do we capture in the Acme app, and how
  many users have each?"
* **Summarise** — "Summarise the open-text feedback from the Onboarding NPS
  survey into themes."
* **Compare** — "Compare the Onboarding NPS survey's score in June vs May."
* **Design** — "Suggest a survey to understand why users cancel, then create it
  in the Acme app."

## Errors

Tools return readable errors an agent can recover from — a duplicate trigger
key, a validation problem, a missing ID, or an authentication failure all come
back as plain text explaining what to fix.