> ## 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 **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](/docs/platform/prompts/versions-and-releases#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 shipped, see [Versions & releases](/docs/platform/prompts/versions-and-releases); for rendering the result, see [Rendering prompts](/docs/platform/prompts/rendering).

<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](/docs/platform/prompts/rendering).
</Note>

## 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](/docs/platform/prompts/rendering#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.
</Note>

### 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](/docs/platform/prompts/rendering#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](/docs/platform/prompts/rendering#model-configuration) for how.

## Next steps

<CardGroup cols={2}>
  <Card title="Versions & releases" icon="git-branch" href="/docs/platform/prompts/versions-and-releases">
    Freeze a draft into a version and release it to an environment.
  </Card>

  <Card title="Rendering prompts" icon="code" href="/docs/platform/prompts/rendering">
    Render the version and its variables, tools, and config from your app.
  </Card>
</CardGroup>