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

# Writing prompts that work

> What to ask for, how to scope it, which requests the editor cannot do at all, and the one kind of request that costs real money.

The chat is not a search box and it is not a genie. It drives a fixed set of
typed operations against your content, and a request works when it maps onto
one of them. Once you can feel where that edge is, the hit rate goes up sharply.

## What it can actually do

Everything below is a real operation, which is why the editor never has to
guess whether it is allowed:

| You want to…               | Say something like                                                                |
| -------------------------- | --------------------------------------------------------------------------------- |
| Change wording             | *"Rewrite the hero subheading to lead with the free trial"*                       |
| Change a number or a label | *"The price is 49, not 47"* — or just use the Properties panel                    |
| Add a section              | *"Add a testimonials section under the hero"*                                     |
| Remove a section           | *"Delete the stats band"*                                                         |
| Reorder                    | *"Move the FAQ above the pricing table"*                                          |
| Add or edit a list row     | *"Add a fourth FAQ about refunds"*                                                |
| Change an image            | *"Use a warmer photo for the hero"* — see [asset manager](/features/asset-picker) |
| Change page metadata       | *"Set the meta description to …"*                                                 |
| Create or rename a page    | *"Create an /about page using the Campaign template"*                             |
| Translate                  | *"Translate this page into German"*                                               |
| Restyle the site           | *"Give the site a warm, earthy green theme"*                                      |

And the hard edge, which no phrasing gets around:

* It **cannot** change your components, layout code, routes, or anything else in
  the repository.
* It **cannot** edit a field your developers did not declare as content. If the
  badge colour on a pricing card is not in the block's schema, asking nicely
  will not surface it — that is [one line for a developer](/integration/custom-blocks) to add.
* It **cannot** invent a block type that does not exist on your site.

When a request lands outside that boundary, the chat says so rather than
silently doing something adjacent.

## Scope it by selecting, not by describing

The biggest single improvement to your results costs nothing: turn on the
element picker (the cursor button in the composer), click the thing you mean,
and *then* type.

Without a selection you have to write *"in the second testimonial card, the one
from the logistics customer, change the quote so it mentions onboarding
speed."* With a selection you write *"mention onboarding speed."* Shorter,
unambiguous, and much less likely to edit the wrong card.

## Be specific about the outcome, not the mechanism

The model is better at *what you want the page to say* than at *how you imagine
it being built*.

| Works less well                         | Works better                                                   |
| --------------------------------------- | -------------------------------------------------------------- |
| *"Use an h3 with a 24px margin"*        | *"Make this heading smaller than the one above it"*            |
| *"Add a grid component with 3 columns"* | *"Add three feature cards under the hero"*                     |
| *"Make it better"*                      | *"Make it shorter and lead with the outcome, not the feature"* |

Requests that name tone, audience or intent work well: *"rewrite for a technical
buyer"*, *"cut this by half"*, *"make the CTA sound less pushy"*.

## One request at a time, mostly

The planner handles compound requests — *"change the headline and add a CTA at
the bottom"* — but every extra clause is another chance to get one of them
wrong, and a partially-wrong plan is more annoying to unpick than two clean
ones. Batch when the parts are related; split when they are not.

## What things cost

Chat runs on your organisation's own API key, and the price of a turn varies by
more than you would guess from the length of what you typed. From a measured
run on the demo site:

| Request                                                    | Cost         |
| ---------------------------------------------------------- | ------------ |
| **Translate the whole page to German** (a four-block page) | **\$0.1685** |
| Turn the hero into a bold call-to-action                   | \$0.0471     |
| Add an FAQ section                                         | **free**     |
| Add a testimonials section                                 | **free**     |

Two things generalise from that, even though your numbers will differ.

**Whole-page rewrites — translation above all — cost roughly ten times a
single-block edit**, because they rewrite every text-bearing block rather than
the one you were looking at. That is the one request worth being deliberate
about. Nothing in the interface warns you.

**Some requests are genuinely free.** Adding a standard section is answered
without calling a model at all.

The Properties panel is always free. If you know exactly which field and exactly
what value, typing it there costs nothing and cannot be misread.

## When the site has no API key

If the header shows **Add an API key**, chat still answers, but with a much
smaller brain: a short list of literal phrases rather than a model. The
suggestion chips on the first screen change to the three it can genuinely
execute, and a sentence of your own invention will usually come back asking for
a key. Everything else — the preview, the Properties panel, click-to-select — is
unaffected.

## Teach it your voice once

Rather than repeating *"keep it in our house style"* on every request, put it in
the site's **editorial brief** — an overview, a tone, and a list of
constraints, in Site settings. The planner reads it on every turn.

→ [The editorial brief](/editing/brief)

## When a result is wrong

Three things, in order:

1. **Undo it.** The undo button on the message that caused it, or Ctrl+Z.
2. **Say what was wrong** in the next message — *"too formal, and keep the
   original headline"*. It has the context of what it just did.
3. **Give it a thumbs-down.** The **Bad response** button on a message takes an
   optional note, and those reports are what the prompts get tuned against.

If it is consistently wrong in the same way on the same site, that is usually a
content-model problem rather than a phrasing problem — worth passing to whoever
maintains the integration, with [chat troubleshooting](/observability/chat-troubleshooting).