# Improve text with AI assist

*Ask AI to rewrite or draft a block, static prompt or Markdown document while you edit it, and review the suggestion before you keep it.*

Online version: https://promptmason.ai/docs/ai-assist

AI assist rewrites the text you're editing, or drafts it from a few words. It only suggests: your text changes when you click **Accept**, and nothing is saved until you save the item.

## Before you start

AI assist needs two things:

- The **AI assist** switch on in **Settings → Features**.
- The local model downloaded, or an AI provider set up with your own key.

Until both are true, the **AI assist** button doesn't appear. See [Set up AI](https://promptmason.ai/docs/ai-setup).

## Where the button appears

The **AI assist** button (with a sparkle icon) sits at the right end of the editor's toolbar while you edit:

![The block editor toolbar with the AI assist button at its right end.](https://promptmason.ai/images/docs/ai-assist-button-in-editor-toolbar.webp)

- **Blocks:** when you create a block or edit one.
- **Build:** on the **+ Embedded Block** card, and in the window that opens when you edit a block on the Canvas.
- **Prompts:** when you write or edit a static prompt.
- **Build → Markdown** tab: with **Edit** chosen, beside **Copy** and **Download .md**.

A dynamic prompt is made of blocks, so it has no AI assist button of its own: use it on each block. When you're viewing an item rather than editing it, **Evaluate** shows instead (see [Evaluate a block, prompt or document](https://promptmason.ai/docs/evaluate)).

## Improve text

1. Open the block, static prompt or Markdown document for editing.
2. Click **AI assist**.
3. Choose what to ask for:
   - Click one of the **Suggestions**: **Tighten this**, **Make this clearer** or **Strengthen this**. It runs straight away. You can also press 1, 2 or 3, unless you're typing in the box below.
   - Or type in **What should change? (optional)**, for example "shorter, more formal". Leave it empty for a general improvement. The box takes up to 300 characters.

   To change the three suggestions, see [Customize the AI instructions](https://promptmason.ai/docs/ai-instructions#suggestions).
4. If you have more than one model set up, check **Model** and choose another if you want.
5. Click **Run**, or press Enter.

    ![The AI assist box with three suggestion buttons, a What should change? box and a Run button.](https://promptmason.ai/images/docs/ai-assist-box-with-suggestions.webp)

6. A suggestion panel opens below your text. It shows "[Provider] is writing…" while the text arrives, then "Suggestion from [Provider]".
7. To see what changed, click **Show changes**. Added lines and removed lines are marked against your current text. Click **Hide changes** to go back.

    ![The suggestion panel with added and removed lines marked against the original text.](https://promptmason.ai/images/docs/ai-assist-show-changes.webp)

8. Click **Accept** to put the suggestion in the editor, or **Discard** to leave your text as it was.

9. Save the item as usual.

To close the AI assist box without running anything, press Esc. Your edit stays open.

## Draft from a few words

If the text is short (under 200 characters) and you don't type an instruction, AI assist treats the text as a brief and writes from it. For example, type "role: a friendly travel agent for families" in a new block and click **Run**.

If the text is empty, AI assist writes from the item's name. With no name either, it writes from what that kind of block or prompt is for.

To change the 200-character length, set **Short-text length** in [the AI instructions](https://promptmason.ai/docs/ai-instructions).

## Run it from the keyboard

In an editor that has AI assist, press Ctrl+Shift+A. It runs with no instruction, using your default provider and its first model. To change the key, see [Keyboard shortcuts](https://promptmason.ai/docs/keyboard-shortcuts).

## Stop a suggestion

While a suggestion is being written, the **AI assist** button turns into **Stop**, and the panel has a **Stop** button too. Stopping keeps what arrived so far, and the panel says **You stopped this early, so it is only part of a suggestion. Accept replaces all of your text with what is shown.** Click **Discard** unless you want that part.

## Warnings in the suggestion panel

| Message | What it means and what to do |
|---|---|
| **This suggestion leaves out** followed by one or more items in double braces, such as {{client name}}, then **Check it before you accept.** | The rewrite dropped a [variable](https://promptmason.ai/docs/variables) or a hidden note that was in your text. Discard and run again, or accept and add it back by hand. |
| **You changed the text after asking for this suggestion. Accept replaces all of it, including those changes.** | You kept typing while it ran. Accept only if you're happy to lose those edits. |
| **No changes from your current text.** | Shown under **Show changes** when the suggestion is the same as your text. |
| **Only the spacing between lines is different.** | Shown under **Show changes** when only blank lines changed. |

In a Markdown document, double braces are ordinary text, so this check doesn't apply there.

## Before text is sent to a provider

Before AI assist or Evaluate sends text to a cloud provider, the **Before you use AI assist** window says what will be sent and where, for example: "AI assist sends this block's text and your instruction to Anthropic. It only sends when you click Run."

- Click **Send** to go ahead, or **Cancel** to send nothing.

    ![The Before you use AI assist window naming where the text is sent, with Send and Cancel buttons.](https://promptmason.ai/images/docs/ai-assist-before-you-use-window.webp)

- The window shows each time until you tick **Don't show this again** and click **Send**.

The local model never shows this window, because none of your text leaves your computer.

## What is sent

With a cloud provider, AI assist sends the text in the editor exactly as typed (including changes you haven't saved, and any hidden notes written as `{{! like this }}`), the item's name, your instruction, and PromptMason's AI assist instructions. For a block, while **Use my own blocks as examples** is on (it's off at first), it also sends a few of your other blocks of the same type from the same library (three at first), so the result matches how you write. Blocks tagged with a block pack's name, such as `Starter pack`, aren't used as examples. To turn this on or off, see [Send less with AI assist](https://promptmason.ai/docs/ai-privacy#send-less-with-ai-assist); to change how many blocks are sent, see [Use your own blocks as examples](https://promptmason.ai/docs/ai-instructions#use-your-own-blocks-as-examples). Variables are sent as written, such as {{client name}}, never with values filled in.

With the local model, none of your text leaves your computer. For what every AI feature sends, see [What AI features send, and where](https://promptmason.ai/docs/ai-privacy). To change what AI assist tells the model, see [Customize the AI instructions](https://promptmason.ai/docs/ai-instructions).

## In version history

When you save an item after accepting a suggestion, that version gets an **AI assist** tag in its history. Pointing to the tag shows which provider and model the suggestion came from. See [Version history](https://promptmason.ai/docs/version-history).

## Limits

AI assist works on up to 20,000 characters in a block or prompt, and up to 100,000 in a Markdown document. Longer text shows **AI assist works on text up to** followed by the limit and **characters. Shorten the text and try again.** The local model can handle less than a cloud provider: see [Free, private AI on your PC](https://promptmason.ai/docs/local-model#messages-and-what-to-do).

## When your library is paused

If your library is paused (you're on the Free plan with more than 25 blocks or 15 prompts, for example after your 14 days of Pro end), you can't edit, so AI assist can't run. See [When your library is paused](https://promptmason.ai/docs/paused-library).

## If something goes wrong

Problems show in a message in the corner of the window, with an **Open Settings → AI & connected apps** button. It closes by itself after 15 seconds, or click the X. Your text isn't changed.

| Message | What to do |
|---|---|
| **Set up AI assist first: download the local model, or add an API key, in Settings → AI & connected apps.** | Set up a provider. See [Set up AI](https://promptmason.ai/docs/ai-setup). |
| **Add an API key for** [provider] **in Settings → AI & connected apps first.** | Add the key for the provider you chose, or choose another under **Model**. |
| **Add the server address for** [provider] **in Settings → AI & connected apps first.** | Add your server's address under **Advanced → Your own AI server**. |
| **Enter a model name for** [provider] **in Settings → AI & connected apps.** | Type a model name under **Models** for that provider and click **Save**. |
| [Provider] **didn't respond within** [N] **seconds. Try again in a moment.** | Wait and try again. |
| **Couldn't connect to** [address] ([reason]). **Check your internet connection, proxy settings, and the server address.** | Check that you're online. For your own server, check the address and that the server is running. |
| The provider's own error message (for example, about an invalid key or an unknown model), or [Provider] **returned an error (HTTP** [number]**)** | Read the provider's message. It usually points to the key, the model name or your account with the provider. Click **Test connection** in Settings to check. |
| [Provider] **returned an empty response. Try again.** | Try again. |
| [Provider] **ran out of room before it finished the document, so nothing was changed. Try again with a shorter document.** | Shorten the document and try again. |
| **AI assist couldn't finish. Check your connection and try again.** | Check that you're online and try again. |
| A message about the local model | See [Free, private AI on your PC](https://promptmason.ai/docs/local-model#messages-and-what-to-do). |

## Want a hand?

Paste this prompt into Claude, ChatGPT or another AI assistant, together with this guide, to be walked through it step by step:

> I want to use AI assist in PromptMason to improve a block I'm writing, or to draft one from a few words. Walk me through running it, reading the suggestion and keeping only the changes I want.