How to write alt text at scale with an AI agent

Alt text answers one question: why is this image here? An agent can only answer it if you tell it where the image sits, so the setup below hands it the page, holds it to W3C's images guidance and ends in a short human review. You will need an agent that can see images, and a list of every image with the page it appears on.

How to write alt text at scale with an agent

1. List every image with its page. For each image, record the page URL, the paragraph around it, any caption, and whether it sits inside a link or button. If it does, note where that link goes.
2. Take out the images a person writes. Charts, graphs, diagrams and maps need a short label plus a long description, and that description often belongs in the page copy rather than in an attribute.
3. Give the agent the house rules. Paste the instruction block below as its standing instructions so every draft follows the same rules.
4. Have it classify each image before it writes. Ask for a class (decorative, functional, text, informative or complex) and a one-line reason. The classes come from W3C's alt decision tree.
5. Send one image per request, with its context. If the agent gets the images without their pages, it can only describe the pictures, because it has no way to know why each one is there.
6. Run one page's images first and read every draft. Wherever the drafts go wrong, tighten the rules before you run the rest.
7. Review each draft against the checklist. Read it aloud with the paragraph around it. W3C's tips suggest imagining you are reading the page over the phone to someone who needs it.
8. Check the empty ones by hand. An empty alt must be alt="" with nothing between the quotes. If the attribute is missing altogether, some screen readers announce the file name instead, according to W3C's decorative images page.
9. Redraft whenever an image moves to a new page. Nielsen Norman Group says never to reuse alt text for the same image without reanalyzing its new context.

Example calls

The standing instructions come straight from the guidance. W3C's informative images page says alt text should convey the image's meaning, which typically isn't a literal description of it. Its tips ask for the most concise description of the image's purpose and say words like "image" or "picture" are usually unnecessary. Nielsen Norman Group suggests alt text shouldn't run much longer than about 150 characters and asks for a closing period so the screen reader pauses.

You draft alt text for images on a website. Each request gives you one image,
the page it is on, the text around it, any caption, and whether it sits inside
a link or button.

First classify the image:
- decorative: adds nothing the page needs (borders, spacers, ambiance, or
  already described by nearby text)
- functional: the only content of a link or button
- text: shows words that are not repeated nearby
- informative: adds meaning the page text does not
- complex: a chart, graph, diagram or map

Then write:
- decorative: alt="" with no space between the quotes
- functional: where the link goes or what the button does, not the picture
- text: the same words as in the image
- informative: why the image is on this page, in one sentence, most important
  words first, under about 150 characters, ending with a period
- complex: flag it for a person and write nothing

Never begin with "image of", "photo of" or "picture of". Do not repeat what the
caption or nearby text already says. Mention race, gender, religion or other
identity only if it is part of why the image is there. Write in the page's
language. If you cannot tell why the image is on the page, say so instead of
guessing.

Each request then carries one image and its place on the page. This is the case W3C uses to illustrate informative images, laid out the way the agent would receive it:

{
  "image": "dog.jpg",
  "page": "/guide-dogs",
  "inLinkOrButton": false,
  "caption": null,
  "nearbyText": "Off-duty guide dogs often wear a bell. Its ring helps the blind owner keep track of the dog’s location"
}

Hold the draft against W3C's own answer. The paragraph explains what the bell is for but never says the dog is wearing one, so the image adds information:

<img src="dog.jpg" alt="Dog with a bell attached to its collar.">

When the surrounding text already describes the picture, the right answer is empty. W3C's sleeping-dog example shows this case:

<img src="sleepingdog.jpg" alt="">

Context can change the answer even when the picture stays the same. W3C's explanation of the text alternatives rule gives one image of the world two different alt texts, because it links to a different section on each site:

<!-- travel site, linking to its International Travel section -->
<img src="world.png" alt="International Travel">

<!-- university site -->
<img src="world.png" alt="International Campuses">

A second call reviews the first. You can run it as a separate agent pass, or give it to the person who chose the images:

For each draft, with the page text beside it, answer yes or no:
1. Read aloud after the paragraph before it, does it add what the image adds
   and nothing more?
2. Is it one sentence, under about 150 characters, most important words first,
   ending with a period?
3. Does it avoid "image of", "photo of" and "picture of"?
4. For a link or button, does it say where it goes or what it does?
5. For an image of text, does it give the same words?
6. For a decorative image, is it alt="" with no space between the quotes?
7. Does it mention identity only where that is why the image is there?
8. Is it in the page's language?
9. Is it free of filenames and placeholder text?
Any "no" goes to a person to rewrite.

The last check comes from W3C's list of failures, which names filenames and placeholder text as alt text that is no alternative at all.

What it costs

Each image costs one call to whichever vision model your agent already runs. This guide gives no per-call price: check that model's price page for its current rate.

The other cost is review. Nielsen Norman Group tested several popular chatbots on a rocket infographic, giving each a page screenshot and a prompt. The results were largely lackluster: the chatbots dropped important details for the sake of brevity and misidentified key parts of the image. The drafts were usable after editing, but guiding the chatbots took longer than writing the alt text by hand. In Nielsen Norman Group's words, "AI cannot read the mind of the author".

That finding argues for setting the job up this way, not for skipping it. Nielsen Norman Group's own advice is to give AI strict parameters and real context, then have the results reviewed by people who understand why the images are there. That is what this setup does. The classify-first step also puts review time where it counts: confirming a decorative image takes a single yes or no, while an informative one needs a real read.

When this is the wrong tool

When the reason for an image exists only in someone's head. W3C says only the author can judge whether an image is decorative or informative. In its stock-photo example, the alt text for a happy family states the impression the company wants to give, that it is family-friendly. An agent that describes what it sees will miss an impression the image is there to give.

For charts, diagrams and maps. Nielsen Norman Group finds that AI tends to write too much for complex images. They also need a two-part answer that someone has to fit to the page.

For controls whose action the agent cannot see. AI struggles with functional images because it may not understand what an interface element does. If your export lacks link destinations, write these by hand.

As the final word on accessibility. WCAG 2.2 asks that every image have a text alternative serving the equivalent purpose, and W3C leaves the purpose for the author to decide. Nielsen Norman Group recommends testing before publishing, ideally with a person with low or no vision.

Run this way, an image library comes back sorted into three piles: empty alts to confirm, one-sentence drafts to read against their pages, and a handful flagged for a person. Start with a single page. Once the rules hold there, run the rest.

Frequently asked questions

What is good alt text?

Good alt text says why the image is on the page, in a short phrase or sentence, rather than describing what it looks like. The same image can need different alt text on different pages.

Should decorative images have alt text?

No. A decorative image gets an empty attribute, alt="", with no space between the quotes, so screen readers skip it. Leaving the attribute out entirely can make some screen readers read the file name aloud.

How long should alt text be?

Nielsen Norman Group suggests alt text shouldn't be much longer than about 150 characters. W3C says that if an image needs more than a short phrase or sentence, it should get a long description elsewhere on the page.

Can AI write alt text on its own?

Nielsen Norman Group says not yet, because AI cannot know why the author included an image. It recommends using AI to draft or refine alt text with clear rules and context, followed by review from someone who knows the images' purpose.

Should alt text start with "image of"?

No. Screen readers already announce that an element is an image. Naming the type is worth it only when it helps, such as telling a painting from a photograph.