Claude API Web Search: Enable Tools and Check Citations

Claude API web search can return source citations, but enabling the tool does not prove that a request performed a search or that each assertion is supported. Keep tool-result status and cited answer spans, then review the source support. Model support and tool versions should come from current official documentation, not a frozen model list.

Select a supported tool version deliberately

Claude’s official web-search documentation currently lists basic web_search_20250305, dynamic-filtering web_search_20260209 and response-inclusion web_search_20260318. The request below uses the basic version to keep the example narrow. Supply a model whose current capabilities accept it; do not infer support from the model’s name alone.

Keep the search result separate from the answer

The request function uses the Messages API; the inspection function is also testable with a synthetic response. ANTHROPIC_API_KEY stays in the environment. No live Anthropic call is represented as having been run for these fixtures.

import os
import requests

def inspect_citations(response):
    if response.get("stop_reason") in {"pause_turn", "tool_use", "max_tokens"}:
        raise ValueError("Incomplete turn; continue or retry before accepting the answer")
    text, citations, errors = [], [], []
    searched = False
    for block in response.get("content", []):
        if block.get("type")=="web_search_tool_result":
            searched = True
            content = block.get("content")
            if isinstance(content, dict) and content.get("type")=="web_search_tool_result_error":
                errors.append(content.get("error_code", "unknown"))
        if block.get("type")=="text":
            text.append(block.get("text", ""))
            for cite in block.get("citations", []):
                if cite.get("type")=="web_search_result_location":
                    citations.append({"url":cite.get("url"), "title":cite.get("title"),
                        "cited_text":cite.get("cited_text"), "answer_span":block.get("text", ""),
                        "support_review":"not_reviewed"})
    return {"answer":"".join(text), "search_performed":searched,
        "citations":citations, "search_errors":errors,
        "status":"needs_review" if citations and not errors else "insufficient_evidence"}

def request_web_answer(question, model, session=requests):
    response = session.post("https://api.anthropic.com/v1/messages",
        headers={"x-api-key":os.environ["ANTHROPIC_API_KEY"],
                 "anthropic-version":"2023-06-01"},
        json={"model":model, "max_tokens":1200,
            "tools":[{"type":"web_search_20250305", "name":"web_search", "max_uses":2}],
            "messages":[{"role":"user", "content":question}]}, timeout=90)
    response.raise_for_status()
    return inspect_citations(response.json())

Test absence, failure and unsupported claims

Use separate synthetic cases: an answer without a search block, a successful search with a citation, a search-result error and an incomplete pause_turn. The parser must not accept a paused turn as a finished answer. A cited case remains needs_review; it never changes automatically to verified.

The citation check should also catch a subtler failure: a valid URL and quoted passage that discusses the topic but does not establish the answer’s quantity, date or conclusion. Store a supports, contradicts or not_established review for that span. A citation count is not an accuracy score.

Choose native search or your own acquisition contract

Native search is useful when the model’s supported tool meets your source requirements. When you need a specific Google query, market or separately inspectable extraction, SearchCans search can supply a distinct discovery stage. It does not replace the Claude server tool’s protocol. Use the source-preserving custom tool for that implementation, evidence review for support checks and the grounding architecture for orchestration.

This workflow is an integration and acceptance method, not a prediction about industry-wide adoption or a claim that citations eliminate hallucinations.