> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Prompts
> Understand the prompt tools available through Profound MCP
Profound MCP gives AI assistants tools to see which prompts a category tracks, read the answers AI engines gave to them, create new prompts, update existing ones, and activate, disable, or delete them in bulk. To connect your MCP client to the hosted server, refer to the [Connection guides](/mcp/common-mcp-clients).
## How the tools work together
Prompts are scoped to a category, so before doing anything with prompts, the assistant resolves the category with [`list_categories`](/mcp/capabilities/discovery-tools#list-categories).
Ask which prompts the category runs. The assistant lists them with [`list_prompts`](#list-prompts), narrowing by status, topic, or tag when you ask for it.
Ask what AI engines say. The assistant retrieves the raw answers behind the metrics with [`get_prompt_answers`](#get-prompt-answers).
Ask to track new prompts and the assistant drafts and previews them with [`create_prompts`](#create-prompts). Ask for a change to existing prompts and it previews field-by-field changes with [`update_prompts`](#update-prompts).
Ask to pause prompts, resume them, or remove them for good. The assistant transitions them in bulk with [`update_prompts_status`](#update-prompts-status).
## Behavior and safety
Write tools default to preview mode: the assistant receives a plan of the change first, and nothing persists until it applies that plan with `preview: false`.
### Behaviors
| Behavior | What it means |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Preview before apply | `create_prompts`, `update_prompts`, and `update_prompts_status` return a plan first and persist nothing until the change is applied |
| Creates aren't idempotent | Each applied `create_prompts` call creates new prompts, so applying twice with the same input creates duplicates |
| Collections replace | On update, `tags`, `regions`, `platforms`, and `personas` replace the whole set instead of merging into it |
| Deletion is permanent | `update_prompts_status` with `deleted` removes prompts and their historical data |
| Auto-created references | When a prompt names a topic or tag that doesn't exist yet, the tool creates it instead of returning an error |
| Live data | Tools read from the Profound API, so results reflect your current access and data |
### MCP hints
The read tools (`list_prompts` and `get_prompt_answers`) only retrieve data and change nothing in Profound. The following MCP hints are set on the write tools:
| Tool | Hints | What it means |
| ----------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `create_prompts` | `idempotentHint: false` | Retrying an applied call creates more prompts |
| `update_prompts` | `destructiveHint: true`, `idempotentHint: true` | `tags`, `regions`, `platforms`, and `personas` are replaced, and the same input applied twice yields the same state |
| `update_prompts_status` | `destructiveHint: true`, `idempotentHint: true` | `deleted` is permanent, and prompts that already have the target status are skipped |
## Prompt tools
| Tool | Usage |
| ----------------------- | -------------------------------------------------------------- |
| `list_prompts` | List a category's prompts, with status, tag, and topic filters |
| `get_prompt_answers` | Read the answers AI engines gave for a category's prompts |
| `create_prompts` | Create one or more prompts in a category |
| `update_prompts` | Update fields on existing prompts |
| `update_prompts_status` | Activate, disable, or delete prompts in bulk |
Lists the prompts configured in a category, with their IDs and details. The other prompt tools take prompt IDs from this list.
**Example prompts**:
* "Which prompts are we tracking in the Banking category?"
* "Show me the disabled prompts under the savings accounts topic."
**Inputs**
| Input | Required | Default | Description |
| ------------------- | -------- | ------- | ---------------------------------------------------------------------- |
| `category_id` | Yes | - | Category to list prompts for |
| `status` | No | `all` | One of `active`, `disabled`, or `all` |
| `tag_ids` | No | `null` | Include only prompts carrying these tags |
| `topic_ids` | No | `null` | Include only prompts under these topics |
| `exclude_tag_ids` | No | `null` | Exclude prompts carrying these tags |
| `exclude_topic_ids` | No | `null` | Exclude prompts under these topics |
| `combine` | No | `AND` | How `tag_ids` and `topic_ids` combine when both are set: `AND` or `OR` |
| `limit` | No | `100` | Maximum prompts to return |
| `cursor` | No | `null` | Pagination token from a previous response's `next_cursor` |
Retrieves the answers AI engines gave for a category's prompts over a date range: the raw text behind the visibility metrics.
**Example prompts**:
* "What did AI engines answer for our savings prompts last week?"
* "Pull the answers behind last month's visibility drop."
**Inputs**
| Input | Required | Default | Description |
| ------------- | -------- | ------- | ------------------------------------------------------------------------------- |
| `category_id` | Yes | - | Category to retrieve prompt answers for |
| `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
| `end_date` | Yes | - | Window end (inclusive) in `YYYY-MM-DD` format |
| `prompt_id` | No | `null` | Narrow the results to a single prompt |
| `country` | No | `null` | Narrow to one or more countries, by name or ID. Can't be combined with `region` |
| `region` | No | `null` | Narrow to one or more regions, by name or ID. Can't be combined with `country` |
| `limit` | No | `100` | Number of prompts returned per page of results |
| `offset` | No | `0` | Offset for pagination |
Creates one or more prompts in a category. Each prompt names the question to ask, the topic it belongs to, and the platforms and regions to run it on.
**Example prompts**:
* "Start tracking 'What are the best running shoes for flat feet?' on ChatGPT in the US."
* "Create prompts for these questions under the savings accounts topic."
**Inputs**
| Input | Required | Default | Description |
| ------------- | -------- | ------- | --------------------------------------------------------- |
| `category_id` | Yes | - | Tracked category, from `list_categories` |
| `prompts` | Yes | - | The prompts to create |
| `preview` | No | `true` | When `true`, show what would happen; when `false`, create |
Each entry in `prompts` accepts:
| Field | Required | Default | Description |
| ---------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt` | Yes | - | The prompt text |
| `topic` | Yes | - | Topic ID or name. A name that doesn't exist is created |
| `platforms` | Yes | - | Platform IDs or names to run the prompt on |
| `regions` | Yes | - | Region IDs or names to run the prompt in |
| `language` | No | `en-US` | Prompt language |
| `tags` | No | `[]` | Tag IDs or names. A name that doesn't exist is created |
| `analysis_types` | No | `["visibility"]` | Analysis types to run: `visibility`, [`sentiment`](https://help.tryprofound.com/articles/3189907319-about-sentiment), or [`accuracy`](https://help.tryprofound.com/articles/5793584301-about-factcheck) |
| `personas` | No | `[]` | Persona IDs or names |
| `asset` | No | `null` | Asset the prompt is associated with |
**Notes**:
* Topic and tag names are matched exactly: a misspelled name creates a new topic or tag instead of joining the existing one, splitting your data between the two. The preview counts these in `topics_created` and `tags_created`, so check it for unintended new topics or tags before confirming.
* Creates aren't idempotent: applying the same call twice creates duplicate prompts.
Updates one or more existing prompts. The preview returns a field-by-field comparison per prompt: old and new values for single fields, and added and removed values for collections.
**Example prompts**:
* "Move the pricing prompts to the 'Fees' topic."
* "Tag the savings prompts with 'high priority'."
**Inputs**
| Input | Required | Default | Description |
| ------------- | -------- | ------- | ------------------------------------------------------------ |
| `category_id` | Yes | - | Tracked category that owns the prompts |
| `prompts` | Yes | - | The prompt updates to apply |
| `preview` | No | `true` | When `true`, return the planned changes; when `false`, apply |
Each entry in `prompts` accepts:
| Field | Required | Default | Description |
| ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Yes | - | The prompt to update, from `list_prompts` |
| `prompt` | No | `null` | New prompt text |
| `topic` | No | `null` | New topic |
| `tags` | No | `null` | New tag set |
| `regions` | No | `null` | New region set |
| `platforms` | No | `null` | New platform set |
| `personas` | No | `null` | New persona set |
| `analysis_types` | No | `null` | New analysis types: `visibility`, [`sentiment`](https://help.tryprofound.com/articles/3189907319-about-sentiment), or [`accuracy`](https://help.tryprofound.com/articles/5793584301-about-factcheck) |
| `language` | No | `null` | New language |
| `asset` | No | `null` | New associated asset |
**Notes**:
* For `tags`, `regions`, `platforms`, and `personas` fields, passing `null` doesn't change the value, `[]` clears it, and a non-empty list replaces the whole set. To add one tag, the assistant submits the complete tag set including the existing tags.
Changes the status of prompts:
* `active` - resumes daily runs
* `disabled` - stops future runs and preserves history
* `deleted` - permanently deletes the prompts and their historical data
Use the `deleted` status with caution: it permanently removes the prompts and their historical data.
**Example prompts**:
* "Disable the holiday prompts, we'll bring them back in November."
* "Delete the test prompts you created earlier."
**Inputs**
| Input | Required | Default | Description |
| ------------- | -------- | ------- | ------------------------------------------------- |
| `category_id` | Yes | - | Tracked category that owns the prompts |
| `prompt_ids` | Yes | - | IDs of the prompts to change status for |
| `status` | Yes | - | `active`, `disabled`, or `deleted` |
| `preview` | No | `true` | When `true`, return the plan; when `false`, apply |
**Notes**:
* Applying the status to prompts that already have this same status doesn't change anything.