# How to Write Good Requests to an AI Assistant in Agility

> Source: https://agilitycms.com/docs/editors/writing-good-ai-requests

An AI assistant connected to Agility does what you ask, with your permissions. Most disappointing results come from requests that leave it guessing: which instance, which items, which fields, and whether it should only suggest changes or actually save them. This article shows how to write requests that get the right result the first time, with before and after examples you can adapt.

If you haven't connected an assistant yet, start with [Using AI Assistants with Agility CMS](/docs/editors/using-ai-assistants-with-agility). For ready-made requests for common jobs, see the recipes for [SEO titles and descriptions](/docs/editors/ai-recipe-seo-metadata), [translations](/docs/editors/ai-recipe-translate-content) and [content audits](/docs/editors/ai-recipe-content-audit).

## The six parts of a good request

A good request answers six questions. You won't need all six every time, but the more of them you answer, the less the assistant has to guess.

| Part | The question it answers | Example |
| --- | --- | --- |
| **Where** | Which instance, locale, content list or sitemap? | "In the Marketing Site instance, en-us locale, Blog Posts list" |
| **Which** | Which items exactly? | "Posts published in 2025 with an empty Summary field" |
| **What** | What should it do: list, draft, save, or publish? | "Draft a summary for each. Don't save yet." |
| **Rules** | What must the result follow? | "Under 160 characters, plain language, only facts from the post" |
| **Leave alone** | What must not change? | "Only change the Summary field. Keep every other field exactly as it is." |
| **Show me** | What should it give back? | "A table with title, current summary, draft summary and character count" |

### Where: name the place

If you can reach more than one instance, an assistant without a named instance has to guess or ask. Content lists and sitemaps have names your team may use loosely, so use the name you see in Agility.

**Before:**

```text
Find the blog posts with no summary.
```

**After:**

```text
In the Marketing Site instance, en-us locale, look at the Blog Posts content
list and find the items where the Summary field is empty.
Don't change anything.
```

### Which: narrow the items

"All" is rarely what you mean, and big lists take time. Filter by date, by a field, by a page section, or by a number you can check.

**Before:**

```text
Update the product pages.
```

**After:**

```text
In the Marketing Site instance, en-us locale, list the pages under /products
on the website sitemap that were last modified before January 1, 2026.
Show me page name, path and last modified date. Don't change anything yet.
```

### What: say whether to suggest or to act

This is the most important part. Words like "fix", "clean up" and "update" don't say whether you want suggestions or saved changes. Say which.

- **List** or **report**: read only, nothing changes.
- **Draft** or **suggest**: the assistant writes text and shows it to you, nothing is saved.
- **Save**: the change is saved to **Staging**. It isn't live yet.
- **Publish**: the change goes live, if your role allows it.

**Before:**

```text
Fix the meta descriptions on our blog.
```

**After:**

```text
For each Blog Posts item where the SEO Description field is empty, draft a
description of 150 to 160 characters from the post's own text.
Show me the drafts as a table with character counts. Don't save yet.
```

### Rules: describe a good result

Tell the assistant what "good" looks like: length, tone, audience, terms to use or avoid, and where its facts may come from. Examples work better than adjectives.

**Before:**

```text
Make the case study summaries better.
```

**After:**

```text
Rewrite the Summary field of the five newest Case Studies items.
Each summary: two sentences, under 200 characters, says who the customer is
and the result they got, uses only facts from the case study body.
Write "Agility CMS" in full the first time. No exclamation marks.
Here are two summaries we like, match their style:
- "..."
- "..."
Show me before and after side by side. Don't save yet.
```

### Leave alone: protect everything else

When the assistant updates an item, it saves the whole item. Say which fields may change, and that everything else must stay as it is. Also tell it to skip items someone else is working on.

```text
Only change the Summary field. Keep every other field exactly as it is.
Skip any item that already has unpublished changes in Staging.
```

### Show me: ask for something you can check

Ask for output you can review quickly: a table, counts, and links to open each changed item in Agility.

```text
When you're done, list what you changed with a link to open each item
in Agility, and list anything you skipped and why.
```

## Work in steps, not one big request

Break bigger jobs into read, draft, save:

1. **Read first.** "Don't change anything yet, just list..." shows you the scope before any edits.
2. **Draft and review.** Ask for drafts in a table. Correct individual rows ("Make number 4 shorter").
3. **Try a few.** "Save the first three only." Check them in Agility.
4. **Then the rest.** "That looks right. Save the remaining drafts the same way."

If the assistant stops part way through a long list, say "Continue from where you stopped."

## Your changes land in Staging, so review them

When the assistant saves, the change goes to **Staging**. Saving alone doesn't change your live site; if the item was already published, the live version stays as it is until someone publishes the new one. Before anything goes live:

- **Open the changed items** from the links the assistant gives you.
- **Check other fields didn't change.** [Version History](/docs/editors/versioning) lets you compare a version with the one before it and revert if needed.
- **Use Preview** to see the change in your site's design. The assistant reads field values, not your rendered pages, so it can't tell you whether something looks right.
- **Publish, or request approval,** the way you normally would. See [Previewing, Publishing, and Content States](/docs/editors/preview-and-publishing).

> [!IMPORTANT]
> **Publishing includes nested linked content by default.** If you, or the assistant, publish a page or content item, its nested linked content is published too, including saved changes nobody has reviewed. To publish only the item, tick **Publish this item only** in the Publish prompt. If you ask the assistant to publish, review the nested content first.

Only ask the assistant to publish when your organization has agreed that this kind of content can be published that way. See [Choose how much the assistant does](/docs/editors/using-ai-assistants-with-agility#choose-how-much-the-assistant-does) and [When to Use AI, and When Not To](/docs/editors/when-to-use-ai).

## Habits that help

- **Check who you're connected as** before bulk work: "Which Agility user am I connected as?" The assistant acts as that user, with that user's role.
- **Ask it to explain its plan.** "Before you start, tell me which tools you'll use and which items you'll change." Correct the plan, then say "Go ahead."
- **Give it your terms.** Paste your product names, glossary or style rules into the request. The assistant doesn't know your house style unless you show it.
- **Ask for sources.** "Only use facts that appear in the item. If you're unsure, leave the field empty and tell me." This reduces invented details.
- **Read permission errors as information.** If something fails with a permission error, your role doesn't allow it. The assistant can't do more than you can.
- **Save good requests.** When a request works well, keep it in a shared document so your team can reuse it.

## A template to start from

```text
In the [instance] Agility instance, [locale] locale, [content list or sitemap]:

Find [which items, with a filter].
For each one, [list / draft / save / publish] [what].

Rules:
- [length, tone, audience]
- [where facts may come from]
- [terms to use or avoid]

Only change [field names]. Keep every other field exactly as it is.
Skip any item that already has unpublished changes in Staging.

Show me [a table with these columns] [before saving / after saving],
with a link to open each item in Agility.
```

## Related articles

- [Using AI Assistants with Agility CMS](/docs/editors/using-ai-assistants-with-agility)
- [When to Use AI, and When Not To](/docs/editors/when-to-use-ai)
- [Fill In Missing SEO Titles and Descriptions with AI](/docs/editors/ai-recipe-seo-metadata)
- [Draft Translations for Another Locale with AI](/docs/editors/ai-recipe-translate-content)
- [Audit Your Content with AI](/docs/editors/ai-recipe-content-audit)