Grounding Claude on Your Own Knowledge Base with search_result Blocks

Minimal implementation: pass results straight through

Take the top few hits from your own full-text search (in my case a simple inverted index over article metadata) and repackage them as search_result blocks for the Messages API.

import anthropic
 
client = anthropic.Anthropic()
 
def to_search_results(hits):
    blocks = []
    for h in hits:
        blocks.append({
            "type": "search_result",
            "source": h["url"],
            "title": h["title"],
            "content": [{"type": "text", "text": p} for p in h["paragraphs"]],
            "citations": {"enabled": True},
        })
    return blocks
 
hits = my_search("how to choose prompt cache TTLs", top_k=5)
 
resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            *to_search_results(hits),
            {"type": "text", "text": "Using only the sources above, summarize TTL choices in three points."},
        ],
    }],
)

Each text block in the response carries a citations array with cited_text, source, and the index of the fragment it referenced, all structured. No more guessing article names out of prose.

Before / After: moving off hand-rolled concatenation

Here is the change side by side. First, the old hand-rolled approach.

# Before: concatenate body text into one string
context = ""
for i, h in enumerate(hits):
    context += f"## Source {i+1}: {h['title']}\n{h['full_text']}\n\n"
 
prompt = f"""Answer using the sources below, and cite as [Source N] at the end.
{context}
Question: {question}"""
# -> citations are prose; matching relies on regex and breaks on paraphrase

Now replaced with search_result.

# After: pass as structured search results
resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [*to_search_results(hits),
                    {"type": "text", "text": question}],
    }],
)
 
# citations come back as structured data
for block in resp.content:
    if block.type != "text":
        continue
    for c in getattr(block, "citations", None) or []:
        print(c.source, "->", c.cited_text[:40])

Two practical effects. First, the instruction telling the model to write citations in prose became unnecessary, and I could pass only the relevant paragraphs from search instead of full_text. That dropped per-request input tokens by about 40% on my workload. Second, the match rate: because results come back keyed by ID, post-processing matching is structurally unnecessary, and the 30% I had been checking by hand essentially vanished.

Wiring citations back into article links

The biggest upside of structured citations is how cleanly they drop into a UI. Insert linked footnotes at the relevant spots in the answer text.

def render_with_footnotes(content_blocks):
    html, notes = [], []
    for block in content_blocks:
        if block.type != "text":
            continue
        cites = getattr(block, "citations", None) or []
        if not cites:
            html.append(escape(block.text))
            continue
        marks = []
        for c in cites:
            idx = len(notes) + 1
            notes.append((idx, c.source, c.title))
            marks.append(f'<sup><a href="#fn{idx}">[{idx}]</a></sup>')
        html.append(escape(block.text) + "".join(marks))
    foot = "".join(
        f'<li id="fn{i}"><a href="{escape(src)}">{escape(t)}</a></li>'
        for i, src, t in notes
    )
    return "".join(html) + f"<ol>{foot}</ol>"

Put the article's canonical URL in source and each footnote links straight to the right article. Since I split content per paragraph, adding an anchor to the URL to jump to the exact paragraph slotted in without trouble. From the reader's side, "where did this answer come from" is now traceable at a glance, and the internal tool's trustworthiness rose noticeably.

Returning search_result from a tool

If your search is split out as a separate tool (or an MCP server), you can return search_result blocks as the contents of a tool_result. The agent calls search itself and the results arrive with citations attached.

# pack search_result into the tool_use response
tool_result = {
    "type": "tool_result",
    "tool_use_id": tu.id,
    "content": to_search_results(my_search(tu.input["query"], top_k=5)),
}
messages.append({"role": "user", "content": [tool_result]})

In this shape, citations stay consistent even across multi-step loops of search, grounded answer, and deeper follow-up. I wired this into my fact-checking pipeline and run it on a schedule from Claude Code. The search itself stays sealed inside the tool, and only ID-bearing results reach the API, so the separation of concerns lands cleanly too.

Measured results in production

A rough before/after comparison from a few weeks of running it. These are measurements from an internal workload, so treat them as reference figures, but the trend held steady.

Latency fell as a side effect of narrowing the passed text from full bodies to relevant paragraphs. Cost and latency dropped together while provenance became traceable — a rare, clean win.

Three gotchas I hit in production

The migration was not flawless. Here are the actual errors and mismatches, with fixes.

1. Forget citations.enabled and the citations come back empty. If you are passing blocks but the citations array is always empty, suspect this first. I made the result builder enforce the flag and throw immediately when it is missing.

2. Coarse fragments produce coarse citations. Put one long block in content and the citation points at "the whole paragraph," dropping footnote precision. Splitting per paragraph — and breaking long paragraphs closer to sentence level — kept the cited range usefully narrow.

3. A search miss cannot be rescued by citations. Obvious in hindsight: search_result shows grounding from the documents you passed. If the relevant article never made it into top_k, Claude honestly answers that the sources contain no basis. When citations come back empty repeatedly, suspect your own search recall before the API. In production I monitor it alongside search hit counts.

If you try this next

If you still have a self-hosted RAG concatenating context by hand, I'd recommend swapping in search_result somewhere low-stakes first — a read-only verification agent, say. Just having citations return by ID lets a whole chunk of post-processing code disappear, and you feel the verifiability of answers step up. For the fine details, Anthropic's Citations documentation is the accurate primary source.

Having my own tools correctly cite my own writing back to me is a small thing, but it's the kind of quiet reassurance that compounds when you keep running this for the long haul. Thanks for reading.