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

# Authoring Prompts

> The parts that make up a prompt version: blocks and their roles, few-shot examples, variables, conditions, tool definitions, and model config.

You author a prompt version in the editor, opened from a project's **Chat Prompts** list. The editor's **Editor** tab holds five panes, switched with a pill row (or `⌘/Ctrl` + `1`–`5`):

| Pane | What you build |
| - | - |
| **Blocks** | The ordered messages the model sees. |
| **Variables** | The `{{ placeholders }}` your application fills at render time, each renderable into text or used only in conditions. |
| **Tools** | The tool definitions the model may call, and the tool-choice directive. |
| **Config** | The model and generation settings: model, temperature, and max tokens. |
| **Preview** | The assembled prompt, rendered against test values. |

Editing blocks, variables, tools, and config, and publishing versions, needs a **developer**, **admin**, or **owner** role; a **viewer** opens the editor read-only. See [Roles and permissions](https://to11.ai/docs/platform/prompts/versions.md#permissions).

This page describes each part a version holds: its [blocks](#blocks), the [variables](#variables) your application fills in, its [conditions](#conditions), its [tool definitions](#tool-definitions), and its [model config](#model-configuration). For how versions are frozen and served, see [Versions](https://to11.ai/docs/platform/prompts/versions.md); for rendering the result, see [Rendering prompts](https://to11.ai/docs/platform/prompts/rendering.md).

> [!NOTE]
>
> **The running example.** The snippets on this page all build one small prompt: a weather assistant (slug `weather-concierge`) that answers everyday questions like "Do I need a jacket?". It's an illustrative example, not a built-in, and the same prompt is rendered from an application in [Rendering prompts](https://to11.ai/docs/platform/prompts/rendering.md).

## Blocks

A version is an ordered list of **blocks**, the messages sent to the model. Each block has a **role**, **content** (which may contain [variables](#variables)), an optional [condition](#conditions), and a **required** flag. Roles carry distinct meaning:

| Role | Purpose |
| - | - |
| **`system`** | The model's standing instructions and persona: who it is, what it must and must not do. Highest-authority framing, set once at the top. |
| **`developer`** | Instructions from you, the application author, that outrank the end user's message. Use it for operating rules the user shouldn't be able to override by asking. It renders as-authored; the SDK maps it for the provider you call ([the developer role](https://to11.ai/docs/platform/prompts/rendering.md#the-developer-role)). |
| **`user`** | A turn from the end user. The final `user` block usually carries the live question via a variable; earlier `user` blocks can seed [few-shot examples](#few-shot-examples). |
| **`assistant`** | A turn from the model. In authored prompts these are almost always [few-shot examples](#few-shot-examples): a demonstration of the answer you want, optionally including a tool call the model should imitate. |
| **`tool`** | The **result** of a tool call, paired to an earlier `assistant` tool call by its call id. A `tool` block is always a result, never a tool *definition* (those live in the [Tools pane](#tool-definitions)). |

Add, edit, duplicate, reorder, or delete blocks from the Blocks pane. A **required** block can't be deleted, so the structural shape of a prompt, such as a mandatory safety `system` block, is preserved across edits.

### Few-shot examples

Few-shot prompting means showing the model a handful of example turns before the real one, so it learns the shape of the answer from demonstration rather than description. In to11 you build a few-shot example as a sequence of blocks in the order a real exchange would occur:

1. A **`user`** block with an example question.
2. An **`assistant`** block with the ideal reply. If the ideal reply is to *call a tool*, the assistant block carries a tool call (a name and arguments) instead of, or alongside, text.
3. A **`tool`** block with the result that call returned, linked to the assistant's call by id.
4. A final **`assistant`** block showing how the model should answer once it has the tool result.

The `weather-concierge` example uses exactly this sequence: a `user` example asks about the weather, the `assistant` demonstrates calling `get_current_weather`, a `tool` block returns a sample reading, and a final `assistant` block shows the phrasing to answer with. The live question then arrives in the last `user` block:

```text theme={null}
I'm in {{ city }}. {{ user_message }}
```

Because few-shot turns are ordinary blocks, you can gate them with [conditions](#conditions). Show a VIP-flavored example only when a `tier` variable marks the caller a VIP, for instance.

## Variables

A **variable** is a placeholder your application fills in when it renders the prompt. Reference one anywhere in a block's content with `{{ variable }}`:

```text theme={null}
You are {{ assistant_name }}, a weather concierge for to11 customers.
```

Every variable you reference is tracked in the **Variables** pane, where you set its **type**, whether it's **required**, an optional **default**, and whether it's **renderable** (see [below](#renderable-variables)). Types:

| Type | Value |
| - | - |
| `string` | A short single-line string. |
| `text` | A longer multi-line string. |
| `number` | A numeric value. |
| `boolean` | `true` / `false`. |
| `enum` | One of a fixed set of allowed strings. |
| `json` | An arbitrary JSON value. |
| `array` | A list of values. |
| `date` | A calendar date. |
| `datetime` | A date and time. |
| `message_list` | A list of prior conversation turns, spliced in as messages. |

Your application supplies the values at render time (`variables: { assistant_name: "Roker", city: "New York" }`). A required variable with no value supplied and no default is an error at render time.

### Renderable variables

Each variable has a **renderable** flag, on by default. A renderable variable does two jobs: its value is interpolated into the prompt text wherever you write `{{ }}`, and it can be tested by a [condition](#conditions). One variable can do both at once: gate a stricter-policy block on `fraud_score` and also render `{{ fraud_score }}` inside an instruction.

Turn **renderable** off for a value that should only drive conditions and never appear in the text, such as an internal `tier`, `locale`, or `is_beta` flag. A non-renderable variable can still be used in conditions but is never interpolated, and referencing it with `{{ }}` is flagged as an error when you author the prompt (rather than rendering as empty).

A variable used as a condition operand must be **scalar** (`string`, `number`, `boolean`, `enum`). That still covers set and substring tests: `in` checks whether a scalar is one of a fixed list (`region in ["us", "eu"]`), and `contains` checks whether one string contains another. A variable typed `array`, `json`, or `message_list` can be rendered but can't itself be tested by a condition.

## Conditions

A **condition** on a block decides whether that block renders. A block with no condition always renders; a block with a condition renders only when the condition holds. Conditions are built in the editor from comparison rows combined with `and` / `or` groups. They evaluate against your **[variables](#variables)** (scalar values only), never against the rendered text.

The available operators:

| Operator | Meaning |
| - | - |
| `==` / `!=` | Equal / not equal. |
| `>` `<` `>=` `<=` | Ordered comparison. Numeric when both sides are numbers, lexical when both are strings. |
| `in` | Membership: the left value is one of a list. |
| `contains` | The left string contains the right substring. |
| `and` / `or` / `not` | Combine or negate other conditions. |

For example, a `system` block that adds white-glove instructions only for top-tier callers carries the condition `tier == "vip"`. When the supplied variables include `tier: "vip"` the block renders; otherwise it's dropped from the assembled prompt. If `tier` should never appear in the prompt text, turn off its [renderable](#renderable-variables) flag. The **Preview** pane lets you set test values and watch blocks turn on and off.

## Tool definitions

Tools let the model call functions in your application. A **tool definition** describes one callable function so the model knows it exists and what arguments it takes. Definitions live in the **Tools** pane, separate from blocks, and each has:

| Field | Meaning |
| - | - |
| **`name`** | The function name the model calls (letters, numbers, `_`, `-`; up to 64 characters). |
| **`description`** | What the function does. The model reads this to decide when to call it. |
| **`parameters`** | A JSON Schema object describing the arguments. |

For example, the `weather-concierge` prompt defines a `get_current_weather` tool:

```json theme={null}
{
  "name": "get_current_weather",
  "description": "Get the current weather for a set of coordinates.",
  "parameters": {
    "type": "object",
    "properties": {
      "latitude":  { "type": "number" },
      "longitude": { "type": "number" }
    },
    "required": ["latitude", "longitude"]
  }
}
```

> [!NOTE]
>
> A tool **definition** (in the Tools pane) declares a function the model *can call*. A `tool` **block** (in the Blocks pane) is the *result* of a call, used to build [few-shot examples](#few-shot-examples). They are different things: definitions offer a capability; blocks demonstrate a past exchange.

### Tool choice

Alongside the definitions, a version carries a **tool choice** directive that tells the model how freely it may call them:

| Choice | Effect |
| - | - |
| **Auto** | The model decides whether to call a tool. |
| **None** | The model may not call any tool. |
| **Required** | The model must call some tool. |
| **Specific** | The model must call the named tool. A specific choice must name a tool that exists in the version. |

Tool definitions are always offered to the model; unlike blocks, they carry no condition or required flag. When you render the prompt, the definitions and the tool-choice directive come back in a provider-neutral shape that the SDK converts to your provider's format; see [Rendering prompts](https://to11.ai/docs/platform/prompts/rendering.md#tools-and-tool-choice).

## Model configuration

The **Config** pane sets how the model is called for this version: the **model**, the **temperature**, and the **max tokens**. These are stored with the version as its model config, separate from the messages. Any other generation settings a prior version carried (for example `top_p` or a `seed`) are preserved through publish even though the pane doesn't edit them.

Your application reads these values when it renders the version and passes them on its own model call; see [Model configuration](https://to11.ai/docs/platform/prompts/rendering.md#model-configuration) for how. The model is sent to your provider as written, so enter the id your provider expects, for example `gpt-4o` for OpenAI.

## What authoring a skill does not share

Everything above describes a **chat prompt**. A [skill](https://to11.ai/docs/skills/concepts.md) is the other kind of prompt, and it owns none of these parts — a skill is delivered to a machine as files, not sent to a model as a request:

* **No variables.** Nothing substitutes into a skill, so `{{ … }}` would reach the agent literally. Publishing a skill that contains that syntax is refused.
* **No model settings.** No model, temperature or token limit: a skill makes no request.
* **No tool definitions, roles or conditions.** A skill's blocks are files, and it delivers all of them.

A skill also carries a **required description**, where a chat prompt's is optional, and it is **authored through the to11 CLI** rather than in this editor.

**Opening a skill in the dashboard shows its files, not this editor**, and there
is no edit button anywhere on it. That is deliberate: see
[Reading a skill in the dashboard](https://to11.ai/docs/skills/concepts.md#reading-a-skill-in-the-dashboard)
for what the browser does offer, and
[Publishing skills](https://to11.ai/docs/skills/publishing-skills.md) for how one is written,
stored and changed.

**The kind is chosen once.** A prompt is a chat prompt or a skill from the moment it is created, and that never changes — there is no converter, because the conversion loses content in both directions. See [What a skill is](https://to11.ai/docs/skills/concepts.md#the-kind-is-permanent).

## Next steps

> [card] [Versions](https://to11.ai/docs/platform/prompts/versions.md)
>
> Freeze a draft into a version; `latest` follows it.

> [card] [Rendering prompts](https://to11.ai/docs/platform/prompts/rendering.md)
>
> Render the version and its variables, tools, and config from your app.


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