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

# Prompt, topic and tag write tools

> Create, update, archive and bulk-edit prompts, and create or rename topics and tags through MCP, with confirmation before changing existing prompts.

These tools manage the prompts a workspace monitors and the topics and tags that organize them. Read [MCP write access](https://docs.qwairy.co/mcp/write/overview.md) first for plans, scopes, roles, `dryRun`, `expectedVersion` and confirmation tokens. All tools require the `write:prompts` scope and the Manager role. Examples use synthetic data.

| Tool | Confirmation | REST equivalent |
| - | - | - |
| `create_prompts` | `cost_increase` | [`POST /brands/{brandId}/prompts`](https://docs.qwairy.co/developers/endpoints/prompts/manage) |
| `update_prompt` | `always` | [`PATCH /brands/{brandId}/prompts/{promptId}`](https://docs.qwairy.co/developers/endpoints/prompts/update) |
| `bulk_update_prompts` | `except_restore` | [`POST /brands/{brandId}/prompts/bulk`](https://docs.qwairy.co/developers/endpoints/prompts/bulk) |
| `create_topic` | `never` | [`POST /brands/{brandId}/keywords`](https://docs.qwairy.co/developers/endpoints/keywords/manage) |
| `update_topic` | `never` | [`PATCH /brands/{brandId}/keywords/{keywordId}`](https://docs.qwairy.co/developers/endpoints/keywords/update) |
| `create_tag` | `never` | [`POST /brands/{brandId}/tags`](https://docs.qwairy.co/developers/endpoints/tags/create) |
| `update_tag` | `never` | [`PATCH /brands/{brandId}/tags/{tagId}`](https://docs.qwairy.co/developers/endpoints/tags/update) |

`create_prompts` needs a confirmation token only when it puts prompts under monitoring, because that adds recurring credit use. The preview reports the amount. `update_prompt` always needs one, because it changes or archives an existing prompt. `bulk_update_prompts` needs one too, except for a plain restore of archived prompts that does not raise credit use. Topics and tags cannot be deleted through MCP: delete them from the dashboard or with the REST API.

`Branded` and `Non-branded` are system tags that Qwairy sets on each prompt from its text, in a workspace created from v1.21. Their names are reserved, whatever the case: `create_tag` with either name, `update_tag` renaming a tag to either name, and `update_tag` on one of the two system tags are refused with `INVALID_REQUEST`, including in a `dryRun` preview. In `create_prompts`, `update_prompt` and `bulk_update_prompts`, the ids of these two tags in `tagIds` are ignored, and a tag replacement keeps the system tag the prompt carries. When `update_prompt` changes the text, Qwairy sets the system tag again from the new text.

## create\_prompts

Create 1 to 20 prompts. Monitored prompts add a recurring credit use shown in the preview.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `brandId` | string | Yes | Workspace ID |
| `prompts` | object\[] | Yes | 1 to 20 prompts |
| `prompts[].text` | string | Yes | Prompt text, up to 500 characters |
| `prompts[].frequency` | string | No | `NONE`, `DAILY`, `WEEKLY` or `MONTHLY`. Omit to inherit the workspace schedule |
| `prompts[].keywordId` | string | No | Topic ID from `list_topics` |
| `prompts[].tagIds` | string\[] | No | Tag IDs from `list_tags` |
| `prompts[].countryCodes` | string\[] | No | Up to 50 countries from the workspace catalog. Empty means the default country |
| `prompts[].modelIds` | string\[] | No | Up to 30 models for this prompt only. Empty means the workspace models |
| `dryRun` | boolean | No | Preview without creating |
| `confirmationToken` | string | No | Token returned by the preview |

### Example

```text theme={null}
You: Add these two prompts to Acme Analytics under the topic "CRM software",
weekly.

Assistant: calls create_prompts with
  {"brandId": "brand_01", "prompts": [
    {"text": "Which CRM tools support small sales teams?", "frequency": "WEEKLY", "keywordId": "topic_01"},
    {"text": "How do I compare CRM pricing for a ten-person team?", "frequency": "WEEKLY", "keywordId": "topic_01"}
  ]}

Qwairy: returns a preview. Two prompts would be created and monitored weekly.
The recurring credit use is shown, and a confirmationToken is returned.

You: Confirm.

Assistant: repeats the call with the token. Both prompts are created.
```

***

## update\_prompt

Change the text, topic, tags, frequency, countries or models of a prompt, archive it or restore it. Send only the fields you want to change. Every call needs a confirmation token from a preview.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `brandId` | string | Yes | Workspace ID |
| `promptId` | string | Yes | Prompt ID |
| `expectedVersion` | integer | Yes | Prompt `version` you last read |
| `text` | string | No | New prompt text |
| `status` | string | No | `ACTIVE` or `ARCHIVED`. Archiving keeps answers and history |
| `frequency` | string | No | `NONE`, `DAILY`, `WEEKLY` or `MONTHLY` |
| `monitoringEnabled` | boolean | No | Whether the prompt is monitored |
| `keywordId` | string | No | Topic ID |
| `tagIds` | string\[] | No | Complete replacement list. An empty array removes all tags |
| `countryCodes` | string\[] | No | Complete replacement list of up to 50 countries |
| `modelIds` | string\[] | No | Complete replacement list of up to 30 models |
| `dryRun` | boolean | No | Preview without changing |
| `confirmationToken` | string | No | Token returned by the preview |

### Example

```text theme={null}
You: Archive the prompt about CRM pricing.

Assistant: reads the prompt, then calls update_prompt with
  {"brandId": "brand_01", "promptId": "prompt_02", "expectedVersion": 1, "status": "ARCHIVED"}

Qwairy: returns a preview with a confirmationToken and executes nothing.

You: Confirm.

Assistant: calls update_prompt again with the same arguments and the token.

Qwairy: archives the prompt. Its past answers stay available.
```

***

## bulk\_update\_prompts

Apply one operation to up to 20 prompts. Each prompt needs its expected version, and version mismatches are reported per item. A confirmation token is required, except for a plain restore of archived prompts that does not raise credit use.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `brandId` | string | Yes | Workspace ID |
| `operation` | string | Yes | `archive`, `restore`, `frequency`, `topic` or `tags` |
| `promptIds` | string\[] | Yes | Up to 20 prompt IDs |
| `expectedVersions` | object | Yes | Map of prompt ID to the `version` you last read |
| `frequency` | string | No | Used by the `frequency` operation |
| `keywordId` | string | No | Used by the `topic` operation |
| `tagIds` | string\[] | No | Used by the `tags` operation |
| `dryRun` | boolean | No | Preview the result of each item without changing |
| `confirmationToken` | string | No | Token returned by the preview |

Inspect the result of every item. A bulk call can update some prompts and report others as unchanged or not found.

### Example

```text theme={null}
You: Archive the prompts about our old product line.

Assistant: calls bulk_update_prompts with
  {"brandId": "brand_01", "operation": "archive",
   "promptIds": ["prompt_03", "prompt_04"],
   "expectedVersions": {"prompt_03": 2, "prompt_04": 5}, "dryRun": true}

Qwairy: previews each item. prompt_03 would be archived, and prompt_04 would be
unchanged because it is already archived.
```

***

## create\_topic and update\_topic

`create_topic` creates a topic in a workspace. `update_topic` renames one.

### Parameters

| Parameter | Tool | Required | Description |
| - | - | - | - |
| `brandId` | both | Yes | Workspace ID |
| `text` | both | Yes | Topic label. Up to 255 characters on creation |
| `keywordId` | `update_topic` | Yes | Topic ID |
| `expectedVersion` | `update_topic` | Yes | Topic `version` you last read |
| `dryRun`, `confirmationToken` | both | No | Preview and confirmation |

### Example

```text theme={null}
You: Create a topic called "CRM software" for Acme Analytics.

Assistant: calls create_topic with {"brandId": "brand_01", "text": "CRM software"}

Qwairy: creates the topic and returns its ID, which you can use in create_prompts.
```

***

## create\_tag and update\_tag

`create_tag` creates a tag. `update_tag` renames or recolors one.

| Parameter | Tool | Required | Description |
| - | - | - | - |
| `brandId` | both | Yes | Workspace ID |
| `name` | `create_tag` | Yes | Tag label, up to 120 characters |
| `tagId` | `update_tag` | Yes | Tag ID |
| `name` | `update_tag` | No | New label |
| `color` | both | No | Color value in hexadecimal form |
| `expectedVersion` | `update_tag` | Yes | Tag `version` you last read |
| `dryRun`, `confirmationToken` | both | No | Preview and confirmation |

### Example

```text theme={null}
You: Create a tag "Pricing" in blue.

Assistant: calls create_tag with {"brandId": "brand_01", "name": "Pricing", "color": "#2563EB"}
```

## Related

* [Discovery tools](https://docs.qwairy.co/mcp/tools/discovery.md) to resolve topic and tag IDs.
* [Prompt suggestions](https://docs.qwairy.co/mcp/write/prompt-suggestions.md) to create prompts from generated ideas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.