Prompt

6 minute read

Image Alt Text Prompt: Describe Images in Context

A reusable image alt text prompt that decides each image's role, writes short alt text in context and leaves decorative images empty. Includes a real test run and checks.

Abstract illustration for Image Alt Text Prompt: Describe Images in Context

This image alt text prompt writes short, accurate alt text for the images on a page, using the image itself and the text around it. It also tells you which images are decorative and should have empty alt text. As a result, screen reader users get the information the image adds, and search engines get a clear description.

The page explains each variable, gives the full prompt and shows one real run on an invented product page. It also lists the checks that catch vague or stuffed descriptions. You still review every line, because a model can misread an image.

What this image alt text prompt does

The prompt follows the logic of the W3C alt text decision tree. First it decides what job each image does on the page: informative, functional, decorative or complex. Then it writes alt text for that job, usually in one short sentence, and empty alt text for decorative images.

It also follows Google's image guidance: describe the image in context, keep it useful and avoid keyword stuffing. If an image needs a longer explanation, such as a chart, it says so instead of cramming the data into the alt attribute.

When to use it

Use it when a page has many images without alt text, or when the existing alt text repeats the file name or the page keyword. It also helps before publishing a new product or tutorial page.

  • A product page whose photos all say "product image".
  • A tutorial with screenshots that screen reader users cannot follow.
  • An audit that found hundreds of images with missing alt attributes.

However, for charts and diagrams that carry real data, the page text or a table is the better place for the detail. Use the prompt's suggestion for a short alt and a longer description elsewhere.

Inputs and variables

Replace every bracketed variable before you run the prompt. A model that can see images gives far better results than one that only reads file names.

  • [PAGE_PURPOSE]: one sentence on what the page is for, for example "product page for a stainless steel water bottle".
  • [IMAGES]: the images themselves, attached in order, plus each file name.
  • [SURROUNDING_TEXT]: the caption or paragraph next to each image, so the model knows why the image is there.
  • [STYLE]: any house rules, for example "US English, no ending period".

Only upload images you have the right to use. Do not upload photos of identifiable people to a public AI tool without their consent.

Reusable prompt — version 1.0

Copy the prompt below as it is. It asks for the image's role first, which prevents long descriptions of decorative images.

You are helping a web editor write alt text for the images on a page about [PAGE_PURPOSE].

<task>
For each image in <images>, decide its role and write alt text for that role.
</task>

<rules>
1. Roles: informative (adds information), functional (a link or button), decorative (adds nothing), complex (a chart or diagram with data).
2. Informative: describe what matters for this page in one short sentence, usually under 125 characters.
3. Functional: describe the action or destination, not the picture.
4. Decorative: return an empty alt text ("").
5. Complex: write a short alt and suggest where the full data should go on the page.
6. Do not start with "image of" or "picture of". Do not repeat nearby text word for word.
7. Do not add keywords, brand claims or details you cannot see. If you are unsure what an image shows, say so.
8. Follow <style>.
</rules>

<output_format>
Table: file name | role | alt text | note
</output_format>

<style>[STYLE]</style>
<images>
[IMAGES]
[SURROUNDING_TEXT]
</images>

Rule 7 matters most for SEO. It stops the model from turning alt text into a keyword list, which helps neither readers nor search engines.

How to use it

Run this image alt text prompt in a chat model that accepts image uploads. Small batches of five to ten images keep the descriptions specific.

  1. Export the image list for the page with file names and nearby text.
  2. Attach the images in order and fill in the variables.
  3. Run the prompt and review the table next to the live page.
  4. Paste the approved alt text into your CMS, leaving decorative images empty.
  5. Check the page with a screen reader or an accessibility checker.

Example input and output

We ran version 1.0 once on Claude Opus 5.5 on November 15, 2026. The page and images are invented. This run used written descriptions of the images instead of uploads, so it tests the rules, not image recognition. The output is trimmed, and trims are marked with "…".

PAGE_PURPOSE: product page for a stainless steel water bottle
STYLE: US English, no ending period
IMAGES:
1. bottle-front.jpg: a silver bottle with a black lid on a white background
2. bottle-lid-open.jpg: the lid open, showing a wide mouth with an ice cube
3. divider-wave.svg: a thin blue wavy line between sections
4. cold-hours-chart.png: a bar chart comparing hours cold for three sizes
…
| file name | role | alt text | note |
| bottle-front.jpg | informative | Silver stainless steel water bottle with a black screw lid | |
| bottle-lid-open.jpg | informative | Open bottle with a wide mouth that fits an ice cube | |
| divider-wave.svg | decorative | "" | |
| cold-hours-chart.png | complex | Bar chart of hours each bottle size keeps drinks cold | Put the hours in a table below the chart |
…

In this run, the model left the divider empty and flagged the chart for a table instead of listing numbers. That single run is an illustration, not a benchmark.

How to check the output

Compare each line with the image and the page before you publish.

  • Accuracy: the alt text matches what the image shows, with nothing invented.
  • Role: decorative images are empty, and links describe their destination.
  • Length: informative alt text stays short; long detail lives in the page.
  • No stuffing: keywords appear only where they describe the image naturally.
  • Context: the text explains why the image is on this page, not just what it is.

Troubleshooting

These fixes address the bad outputs we see most often.

  • Every image gets a long description: lower the limit in rule 2 to 100 characters.
  • The model guesses brand names: repeat rule 7 and supply the product name yourself.
  • Decorative images get text: list known decorative files in [SURROUNDING_TEXT].
  • Text-only models invent details: switch to a model that can see the images.

Limitations

A model can misread an image, miss small text or confuse similar products. Therefore, a person who knows the page must approve every line. The prompt also cannot judge legal accessibility compliance for your site.

Outputs vary by model, version and input. Good alt text supports accessibility and image search, but nothing guarantees rankings or image traffic.

Version history

Each version carries a date, so you can tell which prompt produced older alt text.

  • 1.0: November 15, 2026. First version, tested once on Claude Opus 5.5.

Frequently asked questions

Quick answers to the questions readers ask most about this topic.

Which AI models does this image alt text prompt work with?

Use a chat model that accepts image uploads, such as current multimodal models from OpenAI, Anthropic or Google. Text-only models can only guess from file names and will invent details.

How long should alt text be?

Usually one short sentence. Describe what the image adds to this page; put long details, such as chart data, in the page text or a table instead of the alt attribute.

Should decorative images have alt text?

No. Give purely decorative images an empty alt attribute so screen readers skip them. The prompt marks these images as decorative and returns empty alt text.

Does alt text help SEO?

Google uses alt text, along with the surrounding content, to understand images. Write it for people first; stuffing keywords into alt text helps neither readers nor search engines.

Sources

These pages support the alt text guidance and the prompting approach above.

  1. W3C WAI: An alt decision tree w3.org
  2. Google Search Central: Image SEO best practices developers.google.com
  3. Anthropic: Claude prompting best practices platform.claude.com