Google Image Search Doesn't Care That She's Smiling

What image searchers actually type, and how to write alt text that answers them on every image of every site, automatically.

6 min read

People who find you through image search type a name, and your alt text probably describes a mood.

You can fix that across a whole network of sites in one pass.
This piece shows you which words image searchers use, which ones they never type, and a small build step that writes alt text around the right words for every content image that has none.

What good alt text gets you

Google Images and the image blocks in web results send visitors to your pages, and Google reads alt text, along with computer vision and the page content, to understand what each image shows.
An alt that repeats the subject of the H1 confirms what the page is about, and when the image is a link, Google treats its alt like the anchor text of that link.
AI answer engines such as ChatGPT search and Perplexity read the text of your pages, so an image without alt adds nothing to their answer, while a subject-first alt adds one more fact tied to the right name.
Most auto-generated alts describe a mood, so few images compete on the names people search, and your published images can take that place without one new line of content.

What image searchers type

Open Google Search Console, filter the performance report on the Image search type, and read the queries.
They fall into two families with almost no overlap.

The first family carries entities and subjects.
People type the name of a restaurant, a place, a brand, a product model, a person or a discipline.
They search for a composter type, a GPS model number, a town square, a coach's name.

The second family stays almost empty.
Nobody types "woman", "smiling", "sitting", "blue" or "screenshot".
Those words fill most auto-generated alt text, and they match nothing that real people ask for.

That gap is one reason a site can have alt text on every image and still get little image traffic.
The descriptions are accurate, but they describe the pixels instead of naming the thing.

Name the subject first, then describe what the image shows

The rule that follows from the queries is short.
When the image shows the subject of the page, the alt starts by naming that subject, exactly as the title, the H1 or the nearby text name it.
It then says what the image shows of that subject.

Three examples show the difference.

On a gardening site, "Several models of Bokashi composters in different colors…" becomes "Bokashi composters shown in a product grid".
On a GPS watch review, "A smartwatch on a wrist showing a map" becomes "Trekline T5 displays a mapped route on someone's wrist in a mountain meadow".
On a small bakery's team page, "Portrait of Claire Martin, team member, smiling…" becomes "Claire Martin kneads dough on a flour-dusted wooden table".

Each new alt puts the searchable word first.
It drops the filler ("several models", "portrait of", "team member") that nobody searches for.
It keeps one concrete detail of the scene, so a screen reader user still learns what the picture shows.

Never attach a subject the image doesn't show

The rule has a hard limit.
An image only gets the page's subject when it actually shows it.
A stock photo of a laptop on a restaurant page stays "laptop on a wooden desk", and it never turns into a restaurant description.

Advertising banners that have nothing to do with the page become decorative, so they keep an empty alt instead of filling the page with an unrelated description.
Separators, background patterns and icons without information get the same treatment.

This limit matters for two reasons.
A visually impaired reader deserves an honest description.
A page also gains nothing when its alt promises a subject that the image doesn't contain.

The guardrails that keep it clean

Automatic alt text goes wrong in predictable ways, so the pipeline rejects those ways before anything reaches the HTML.

  • The alt stays at 125 characters or fewer, in one sentence of 5 to 15 words.
  • It never opens with "image of", "photo of" or their equivalent in the page's language.
  • It refuses keyword stuffing: a word of 4 letters or more cannot appear 3 times, and the alt cannot line up 4 comma-separated segments.
  • It uses the language of the page, and a reply in another language gets rejected.

When a reply breaks one of these rules, the model gets one corrected request that includes its rejected answer and the reason for the rejection.
A second failure leaves the image for the next run.
Existing alt text never gets overwritten, so a failed run leaves the site exactly as it was.

How it runs on a network of sites

The tool behind this is a small command line script written in Bun.
It finds the content images whose alt is missing or empty, and it leaves every existing alt as it is.
It skips headers, navigation, footers, sidebars, tracking pixels and anything under 32 pixels.

For each image, it sends a vision model the image itself, reduced to 768 pixels, together with the page context: the page language, the title, the H1, the caption or nearby text, and the text of the link around the image.
The model answers in JSON constrained by a schema, with the alt, its language and a decorative flag.

The answers live in one JSON store per site, versioned with the site's code.
Each entry uses the SHA-256 of the image file and the page language as its key, so the same image used on 40 pages gets described once, and a multilingual site gets one alt per language.
The build then writes the alt from the store into the HTML without any network call.
A second pass changes nothing, and every change shows up as a readable diff in the store.

The descriptions run through a ChatGPT subscription, with Codex CLI in non-interactive mode and the image attached, instead of a pay-per-call API.
One image takes about 27,000 tokens of plan usage and 5 to 6 seconds.
That setup regenerated about 1,100 images across some 20 sites.

What to do this week

Open the Image search type in Search Console for your best site and list the 20 top queries.
Mark each one as a subject (name, place, brand, model, person) or a visual word.
Then open 10 alt texts on your most visited pages and check whether the subject word comes first.

If it doesn't, rewrite those 10 by hand with the subject-first rule, because the build step only fills alts that are missing or empty.

To rewrite them, paste this prompt into ChatGPT, Claude or Gemini, attach the image and fill the last 3 lines:

You write the alt attribute of an image published on a web page.
- Describe factually what the image shows, in the language of the page.
- When the image shows the subject the page is about, start by naming that subject exactly as the page title or the H1 names it, then say what the image shows of it.
- When the image does not show that subject, describe it without attaching it to the page.
- Write 5 to 15 words and 125 characters at most, in one sentence with no final period.
- Never start with "image of", "photo of" or "picture of".
- Name the subject once, do not stack keywords and do not list items separated by commas.
- If the image is decorative or an ad unrelated to the page, answer "decorative".
Page title:
H1:
Text next to the image:

Check each answer against the image before you paste it: the color, the material, the time of day and the number of items must be true.

If you run several sites, automate the rule at build time with a versioned store, so every new image starts right.

Your competitors' images describe moods.
Yours can match the exact names people search, on every image that has no alt yet and on every one you publish next.
The Alt Text kit writes those subject-first alts at build time, about 100 images in 5 minutes, and you review each one as a single git diff before it ships.

Alt Text kit cover: Your Images Finally Name What They Show

Make your images searchable for $19 →

When to judge the change

Image search data moves slowly.
You need 3 to 4 weeks of Search Console data after the deployment before you can compare image impressions and clicks with the period before.
Judge the change on that window, page by page, and not on the first week.


People searching for images type product names and places, not moods. The demo-vs-product checklist in the kit helps you spot that kind of SEO gap before it costs you traffic. Structured logging and monitoring catch what your current setup misses.

→ Get the welcome kit