Skip to content
DWKD

Tool note

Gemini Grounding and What a Citation Proves

A url_citation proves a span was attributed to a page — not that the page says it, and an uncited sentence is neither a warning nor a clearance.

Grounding with Google Search returns the answer plus annotations of type url_citation, each carrying a url, a title, and a start_index and end_index into the answer text.

It is the most over-read signal in the stack. An annotation is a span-to-URL mapping produced by the same system that produced the span. Knowing what that does and does not establish is the difference between a feature you can defend and a footnote that launders a guess.

Why this exists

The failure mode is a shipping decision made on the presence of a footnote. Citations render, the answers look sourced, and the feature ships into a workflow where being wrong costs somebody something.

So be precise. A url_citation proves the page was in play during generation, and that this range of characters is attributed to it. It does not prove:

  • That the page says it. Attribution and sentence come from the same generation step. Nothing independent checked one against the other.
  • That the page is right. A grounded answer can be an accurate quotation of a wrong source, and that is the worst output in this category — fluent, cited, false.
  • That the page is the whole basis. Model parameters contributed too, and that contribution carries no annotation.
  • Anything about an uncited sentence. Absence of an annotation is not a warning and not a clearance. It is silence.
  • That the page still says it. There is no content hash and no timestamp you control; a citation to a page edited yesterday looks identical to one that was not.

How to use it

Index arithmetic is where most implementations quietly break. The offsets point into the answer text as returned. Strip markdown, trim whitespace, translate, or insert footnote markers before applying the annotations, and every span shifts so your citations point at the wrong sentences. Apply annotations to the unmodified string, and insert markers from the highest index down to the lowest so earlier offsets stay valid.

Verify the offset unit yourself rather than assuming it. Take one answer containing an em dash or an accented name, slice it with the indexes your SDK handed you, and check the slice is the sentence you expected. A byte-versus-character mistake is invisible on ASCII content, which is why it ships.

Store the annotation set with the answer, never derive it at render time: url, title, span, model id, retrieval date. A cached grounded answer is a snapshot of the web; with no retrieval date it ages invisibly.

Sample and check on a schedule rather than per request: twenty answers a week, a person opening the cited page to confirm the claim is supported. If you display citations as evidence you are making a claim about that source, and only you can check it. For anything you would be embarrassed to be wrong about, require two independent domains; syndicated copies and two pages on one host are one source.

Watch what composition does to coverage. Grounding composes with code execution, URL context and Maps grounding, and the Gemini 3 models can combine built-in tools with your own function calling. When they do, a sentence’s provenance splits: part from search, part from a computed result. The url_citation set covers only the search part, so cited coverage is not sourced coverage. Label a computed number as computed.

Where it goes wrong

Never make citation count a success metric or an A/B outcome. More footnotes is not more true, and optimizing for it teaches the system to pad.

Never treat grounded output as the authority for a clinical, legal, financial or safety decision. Its job is to find the source a qualified person reads — say so in the product copy.

Turn grounding off for questions your own systems answer. A model reaching the open web for something your database knows is a wrong answer wearing a citation, and harder to spot than a plain hallucination.

And keep live grounded calls out of any eval you need to be stable. The answer depends on what search returned that minute, so the eval measures the web’s weather rather than your change. Freeze the retrieved pages as fixtures.

Copy and Clear become available when the worksheet is ready.

SHIPPING A GROUNDED ANSWER - ACCEPTANCE CHECKLIST

Feature: Owner: Date:

A. SPAN RENDERING - THE PART THAT BREAKS SILENTLY

any trim, markdown strip, translation or sanitization.

  1. Get an answer containing an em dash or an accented name.
  2. Slice with start_index / end_index as returned.
  3. Assert the slice equals the sentence you expected.

Result: offsets are bytes | UTF-16 units | codepoints

Verified on by on

the marker and logs a warning.

quotation mark, and a 2-line answer with 6 annotations.

B. WHAT YOU PERSIST WITH EVERY GROUNDED ANSWER

answer_text

  • annotations

retrieved_at

model_id

grounding_tools_used search | url_context | maps | code_exec

uncited_spans count, for monitoring only

domains

question_text

review_state unchecked | supported | unsupported

Rule: if retrieved_at is missing, the answer may not be cached

or re-displayed. An undated web snapshot is a liability.

C. THE CLAIM LADDER - WRITE WHICH RUNG THIS FEATURE IS ON

Rung 1 "A page was consulted." <- annotation proves it

Rung 2 "This span is attributed to it." <- annotation proves it

Rung 3 "The page supports this claim." <- ONLY human or

independent check

Rung 4 "The claim is true." <- requires a source of

truth, not a search

Rung 5 "You may act on this." <- requires a qualified

human, every time

This feature is on rung:

The UI language must not imply a rung above .

Words that imply rung 4 and must not be used: verified,

confirmed, fact-checked, accurate, validated.

D. SAMPLED VERIFICATION (the step everyone skips)

Cadence: Reviewer:

For each sampled answer:

yes / partly / no / page changed / page gone

  • Would a subject-matter expert sign this?

Log per week: answers sampled, unsupported count, dead links,

pages changed since retrieved_at. Escalate at .

E. SOURCE QUALITY RULES (write yours; these are the defaults)

  • Two INDEPENDENT domains required for:

Same host, or syndicated copy, counts as one source.

facts, pricing, versions or legal text, a vendor or

government page beats an article about one.

  • Domains that never justify an assertion:
  • Recency rule: for , reject a source older

than and say so in the answer.

  • Jurisdiction rule: how you handle country-specific law

F. QUESTIONS TO ANSWER BEFORE LAUNCH

  1. What does a user see when grounding returns no citations at

all? answer - "nothing different" is the wrong answer

  1. What happens when the search tool errors? Fall back to an

ungrounded answer, or refuse?

  1. Is grounding ON for questions my own data already answers?

It should be off.

  1. Who is paged when the unsupported rate crosses threshold?
  2. What is the retention period for answer_text and why?
  3. Can a user report a bad citation in one click, and where

does that report go?

  1. Are grounded steps excluded from the stable eval set, with

frozen page fixtures used instead?

  1. Does anything downstream treat a cited sentence as

machine-checkable truth? If yes, remove that assumption.