> For the complete documentation index, see [llms.txt](https://docs.flowcp.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowcp.ai/guides/offer-prompts.md).

# Offer prompts

Tools let an AI agent *call* your API; skills give it the *know-how* to use them. **Prompts** are different again: they are reusable, parameterized message templates that a client surfaces directly to the **user** — most often as slash-commands. Picking a prompt drops a ready-made starting message into the conversation, for example:

> *Summarize ticket **{{ticket\_id}}** in a **{{tone}}** tone.*

This guide explains how to author prompts and how AI clients consume them.

## How clients consume a prompt

When a prompt is enabled, the runtime advertises the MCP **prompts** capability and offers it to connected clients via the standard protocol:

* **`prompts/list`** — the client lists the available prompts, each with its title, description, and declared arguments. Clients typically render these as slash-commands the user can pick.
* **`prompts/get`** — when the user selects a prompt and fills in its arguments, the client fetches the rendered message. The runtime substitutes the argument values into the template and returns a single user message (plus any embedded resources you attached).

Because prompts are **user-controlled**, they are not called automatically by the model — the user chooses them.

## Arguments and placeholders

A prompt can declare **arguments** the user fills in at selection time. Each argument has a `snake_case` name, a description, and a required flag. Reference an argument anywhere in the body — or in an embedded resource's text — as `{{argName}}`:

```
Summarize ticket {{ticket_id}} in a {{tone}} tone.
```

At `prompts/get`, `{{ticket_id}}` and `{{tone}}` are replaced with the values the user supplied. Required arguments must be provided; optional ones left blank resolve to an empty string. A placeholder with no matching argument is left as-is, so a typo is easy to spot.

## Argument autocomplete (suggested values)

Each argument can carry an optional list of **suggested values**. When you add them, the runtime advertises the MCP **completions** capability and answers the client's `completion/complete` requests for that argument — so as the user types, the client can offer ranked autocomplete suggestions instead of a blank field.

* Enter one value per line in the argument's **Suggested values** box.
* Suggestions are matched against what the user has typed (prefix matches first, then substring), and a response returns at most **100** values.
* Suggested values are hints, not a fixed list — clients still allow free-form input, and the value is never validated against the suggestions.

Leave the box empty for free-text arguments with no suggestions.

## Embedded resources

A prompt can optionally carry **embedded resources** — inline reference blocks (`uri`, `mimeType`, `text`) returned alongside the message. Use these to attach context the model should see, such as a policy snippet or an example payload. Placeholders in a resource's text are substituted too.

## Managing prompts from an agent

Prompts can be managed two ways: from the dashboard (below) or by an AI agent connected to the [FlowCP MCP server](/guides/agent-driven-onboarding.md). The agent surface exposes prompts as tools — `list_prompts`, `create_prompt`, `update_prompt`, and `delete_prompt` — so an agent can author and toggle prompts for a server without leaving the chat. Like the dashboard, new prompts start **disabled**.

## Opening the prompts list

From your app's dashboard, click the **Prompts** tab. The page lists every prompt on the selected server, each with an on/off switch. If your app has multiple environments (branches), use the branch buttons to switch between them.

## Creating a prompt

1. Click **New prompt**.
2. Fill in the fields:
   * **Name** — a `snake_case` identifier, e.g. `summarize_ticket`. This is the prompt name clients call.
   * **Title** — an optional display title shown to the user.
   * **Description** — a one-line summary so the user knows what the prompt does.
   * **Message template** — the body of the message, with `{{argName}}` placeholders for any arguments.
   * **Arguments** — add one row per argument (name, description, required), with optional **suggested values** (one per line) that power argument autocomplete.
   * **Embedded resources** — optional reference blocks returned with the message.
3. Click **Create prompt**.

New prompts are created **disabled**, following the platform's default-deny model — see [Default-deny model](/security/default-deny-model.md).

## Generating prompts with AI

To get started quickly, click **AI Suggestions** on the Prompts page. FlowCP reads the selected server's tools and asks an LLM to propose **three** prompts that help a user drive those tools, complete with `{{argName}}` placeholders and declared arguments.

Each suggestion shows its name, description, and a preview of the template. Click **Use this** on the one you want — it opens the prompt editor **pre-filled** (including its arguments) so you can review and refine it before saving. Nothing is created until you click **Create prompt**, and (like every prompt) it starts disabled.

AI Suggestions require an AI provider to be configured for the platform. If it isn't, the button reports that suggestions aren't available — you can still author prompts manually.

## Enabling a prompt

Toggle the switch on a prompt's row to **On** to offer it to AI clients. Changes take effect immediately — no re-publish required. Disabled prompts are never listed or returned.

## Editing and deleting

* Click the **pencil** icon to edit a prompt's name, title, description, body, arguments, or embedded resources. Renaming re-derives the slug.
* Click the **trash** icon to delete a prompt. This cannot be undone.

## Writing effective prompts

* **Lead with the task.** The body should read like the message a user would type to kick off the work.
* **Declare every placeholder.** Each `{{argName}}` should have a matching argument so the client can prompt the user for it.
* **Keep arguments minimal.** Ask only for what changes between uses.
* **Use embedded resources for context**, not for the instruction itself.