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

# Create prompts

> Define a prompt's model, parameters, messages, and response format in the Braintrust UI, or define it in code and push with the bt CLI.

Create prompts directly in the Braintrust UI or define them in code and push them with the SDK. Once created, extend prompts with tools and MCP servers, test them in playgrounds, and improve them with Loop.

## Create a prompt

You can create a prompt in the UI or define it in code. Use the UI for quick, visual iteration, and use the SDK to version prompts alongside your application code and push them from your existing workflow.

> [tab] UI
>
> Create prompts directly in the Braintrust UI:
>
> 1. Go to [\*\* Prompts\*\*](https://www.braintrust.dev/app/~/prompts) and click **+ Prompt**.
>
> 2. Configure the prompt:
>    * **Name**: Descriptive display name
>    * **Slug**: Unique identifier for code references (remains constant across updates)
>    * **Model and parameters**: Model selection, temperature, max tokens, etc.
>    * **Messages**: System, user, assistant, or tool messages with text or images
>    * **Templating syntax**: Mustache or Nunjucks for variable substitution
>    * **Response format**: Freeform text, JSON object, or structured JSON schema
>    * **Description**: Optional context about the prompt's purpose
>    * **Tags**: Optional labels for organizing and filtering prompts
>    * **Metadata**: Optional additional information
>
> 3. Click **Save as custom prompt**.
>
> > [accordion] Prompt caching for Anthropic and Bedrock models
> >
> > When using Anthropic or AWS Bedrock (Converse API) models, a cache control button appears on each message for [Anthropic prompt caching](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching). Click it to set a TTL of 5 minutes or 1 hour. When a message has multiple content blocks, you can set cache control on each block individually. Cache control settings are preserved when switching between Anthropic models and cleared when switching to a different provider.
>
> > [accordion] Parameters for reasoning models
> >
> > For reasoning models, the available parameters depend on the selected reasoning effort. GPT-5.1 and later expose a `temperature` setting only when **Reasoning effort** is `none`. Raising the reasoning effort removes the `temperature` setting. Older GPT-5 models (`gpt-5`, `gpt-5-mini`, `gpt-5-nano`) and GPT-5 Pro don't accept `temperature` at any reasoning effort.

> [tab] SDK
>
> Define prompts in code, then push them to Braintrust with the [`bt` CLI](https://docs.braintrust.dev/reference/cli/quickstart):
>
> **1. Define the prompt in code**
>
> ```typescript title="summarizer.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> import * as braintrust from "braintrust";
>
> const project = braintrust.projects.create({
>   name: "Summarizer",
> });
>
> export const summarizer = project.prompts.create({
>   name: "Summarizer",
>   slug: "summarizer",
>   description: "Summarize text",
>   tags: ["summarization"],
>   model: "claude-sonnet-4-5-20250929",
>   params: {
>     temperature: 0.7,
>     max_tokens: 1000,
>     response_format: { type: "json_object" },
>   },
>   messages: [
>     {
>       role: "system",
>       content: "You are a helpful assistant that can summarize text.",
>     },
>     {
>       role: "user",
>       content: "{{{text}}}",
>     },
>   ],
>   metadata: { version: "1.0" },
> });
> ```
>
> ```python title="summarizer.py" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> import braintrust
>
> project = braintrust.projects.create(name="Summarizer")
>
> summarizer = project.prompts.create(
>     name="Summarizer",
>     slug="summarizer",
>     description="Summarize text",
>     tags=["summarization"],
>     model="claude-sonnet-4-5-20250929",
>     params={
>         "temperature": 0.7,
>         "max_tokens": 1000,
>         "response_format": {"type": "json_object"},
>     },
>     messages=[
>         {"role": "system", "content": "You are a helpful assistant that can summarize text."},
>         {"role": "user", "content": "{{{text}}}"},
>     ],
>     metadata={"version": "1.0"},
> )
> ```
>
> > [accordion] Assign an environment at creation time
> >
> > To associate a prompt with a specific deployment environment in TypeScript, pass the `environments` field:
> >
> > ```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> > export const summarizer = project.prompts.create({
> >   name: "Summarizer",
> >   slug: "summarizer",
> >   environments: ["production"],
> >   messages: [{ role: "user", content: "{{{text}}}" }],
> > });
> > ```
> >
> > Python `project.prompts.create(...)` does not expose an environment-assignment parameter, so use the UI or API if you need to associate environments from Python.
> >
> > See [Version prompts](https://docs.braintrust.dev/evaluate/prompts/versions.md) for details on assigning versions to environments.
>
> **2. Push to Braintrust**
>
> ```bash TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> bt functions push summarizer.ts
> ```
>
> ```bash Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> bt functions push summarizer.py
> ```

To inject variables at runtime, use [Mustache or Nunjucks templating](https://docs.braintrust.dev/evaluate/prompts/templating.md) in a prompt's messages.

## Add tools

[Tools](https://docs.braintrust.dev/deploy/functions.md#deploy-tools) extend your prompt's capabilities by allowing the LLM to call functions during execution:

* Query external APIs or databases.
* Perform calculations or data transformations.
* Retrieve information from vector stores or search engines.
* Execute custom business logic.

> [tab] UI
>
> To add tools to a prompt in the UI:
>
> 1. When creating or editing a prompt, click **+ Tool/MCP**.
> 2. Select tool functions from your library or add raw tools as JSON.
> 3. Click **Save tools**.

> [tab] SDK
>
> To add tools to a prompt in code, use the `tools` parameter:
>
> ```typescript {21} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> import * as braintrust from "braintrust";
>
> const project = braintrust.projects.create({
>   name: "RAG app",
> });
>
> export const docSearch = project.prompts.create({
>   name: "Doc Search",
>   slug: "document-search",
>   model: "gpt-5-mini",
>   messages: [
>     {
>       role: "system",
>       content: "You are a helpful assistant that can answer questions about the Braintrust documentation.",
>     },
>     {
>       role: "user",
>       content: "{{{question}}}",
>     },
>   ],
>   tools: [toolRAG],
> });
> ```
>
> ```python {19} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> import braintrust
>
> project = braintrust.projects.create(name="RAG app")
>
> doc_search = project.prompts.create(
>     name="Doc Search",
>     slug="document-search",
>     model="gpt-5-mini",
>     messages=[
>         {
>             "role": "system",
>             "content": "You are a helpful assistant that can answer questions about the Braintrust documentation.",
>         },
>         {
>             "role": "user",
>             "content": "{{{question}}}",
>         },
>     ],
>     tools=[tool_rag],
> )
> ```

When a prompt includes tools, your application code handles the tool calls returned at runtime. See [Handle tool calls](https://docs.braintrust.dev/evaluate/prompts/use-in-code.md#handle-tool-calls).

## Add external MCP servers

Connect public [MCP (Model Context Protocol)](https://modelcontextprotocol.io/introduction) servers that your organization or a third party hosts to give your prompts access to external tools and data. Unlike the [Braintrust MCP server](https://docs.braintrust.dev/integrations/developer-tools/mcp.md), which MCP clients use to work with Braintrust data, these are servers that Braintrust calls. Use them to:

* Evaluate complex tool-calling workflows.
* Experiment with external APIs and services.
* Reuse existing MCP integrations without building custom tools.

MCP servers used by prompts must be public, support OAuth authentication, and use `http` or `https`. To protect against [server-side request forgery (SSRF)](https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html), Braintrust validates the resolved target of each request.

> [!NOTE]
>
> MCP tools attached to prompts work in playgrounds and experiments, but not when you invoke the prompt through the SDK.

### Add to a prompt

To add an MCP server to a prompt:

1. When creating or editing a prompt, click **+ Tool/MCP**.
2. Enable any of the project's [configured MCP servers](#add-to-a-project).
3. To add a prompt-specific MCP server, click **Configure MCP servers**, then click **+ MCP server**:
   * Provide a name, the public URL of the server, and an optional description.
   * Click **Add server**.
   * Authenticate the MCP server in your browser.

For each MCP server, you'll see a list of available tools. Tools are enabled by default, but you can disable individual tools or click **Disable all**.

After testing a prompt-specific MCP server, you can promote it to a project-wide server by clicking **...** > **Save to project MCP servers**.

### Add to a project

Configure MCP servers at the project level so any prompt in the project can use them:

1. Go to ** Settings** > [** Extensions**](https://www.braintrust.dev/app/~/configuration/extensions).
2. Under **MCP**, click **Create MCP server**, or  **MCP server** if the project already has a server, and provide a name, the public URL of the server, and an optional description.
3. Click **Save**.

With [shared project credentials](https://docs.braintrust.dev/loop/mcp.md#connect-a-server), prompts in playgrounds and experiments can authenticate without a browser connection. Prompts use credentials supplied with the request first, then the project's saved credentials. OAuth access tokens refresh automatically while the refresh token remains valid.

All calls using saved credentials share the external account's or API key's permissions. [Prompt-specific servers](#add-to-a-prompt) still authenticate through the browser.

Using saved project credentials in prompts requires data plane v2.20.0 or later for self-hosted deployments.

> [!NOTE]
>
> When you edit a project MCP server, you can change its name, description, and URL path, but not the scheme, host, or port of its URL. To connect to a different host, create a new MCP server and set up its credentials again.

## Test prompts

Playgrounds provide a no-code environment for rapid prompt iteration:

1. Create or select a prompt.
2. Add a dataset or enter test inputs.
3. Run the prompt and view results.
4. Adjust parameters or messages.
5. Compare different versions side-by-side.

See [Use playgrounds](https://docs.braintrust.dev/evaluate/playgrounds.md) for details.

You can also test prompts by chatting directly with them from the prompt details page. Each chat interaction is automatically logged as a trace in your project's logs. To navigate back to the prompt from these traces, see [Navigate to trace origins](https://docs.braintrust.dev/observe/examine-traces.md#navigate-to-trace-origins).

## Optimize with Loop

Use Loop to generate and improve prompts:

Example queries:

* "Generate a prompt for a chatbot that can answer questions about the product"
* "Add few-shot examples based on project logs"
* "Optimize this prompt to be friendlier and more engaging"
* "Improve this prompt based on the experiment results"

Loop analyzes your data and suggests improvements automatically.

## Best practices

Keep these guidelines in mind as you write and refine a prompt's messages:

**Start simple**: Begin with clear, direct instructions. Add complexity only when needed.

**Use few-shot examples**: Include 2-3 examples in your prompt to guide model behavior.

**Be specific**: Define exactly what you want, including format, tone, and constraints.

**Test with real data**: Use production logs to build test datasets that reflect actual usage.

**Iterate systematically**: Change one thing at a time and measure impact with experiments.

**Version everything**: Save prompt changes so you can track what works and roll back if needed.

## Next steps

* [Use templating](https://docs.braintrust.dev/evaluate/prompts/templating.md) to inject runtime variables with Mustache or Nunjucks.
* [Use prompts in code](https://docs.braintrust.dev/evaluate/prompts/use-in-code.md) to invoke prompts from your application.
* [Version prompts](https://docs.braintrust.dev/evaluate/prompts/versions.md) to pin versions and assign them to environments.
* [Manage prompts](https://docs.braintrust.dev/evaluate/prompts/manage.md) to duplicate prompts and customize the **Prompts** page.
* [Use playgrounds](https://docs.braintrust.dev/evaluate/playgrounds.md) for rapid iteration.
* [Write scorers](https://docs.braintrust.dev/evaluate/write-scorers.md) to evaluate prompt quality.


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