# Citation batch check

`citation-batch-check` · version 1.0.0 · Text · free, no key needed

Check an ordered batch of citations (span+quote or quote anchors) against supplied sources; returns the first failure.

**Use when you need to: verify all citations in an answer against sources · check every quote in a report against supplied documents · batch citation verification for rag answer.**

## Decide before calling

Read the [versioned contract](/v1/tools/citation-batch-check/versions/1.0.0) and the supported scope below. Reuse `citation-batch-check@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `citation-batch-check@1.0.0` for verify all citations in an answer against sources. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- verify all citations in an answer against sources
- check every quote in a report against supplied documents
- batch citation verification for rag answer
- find the first fabricated or misquoted citation
- validate many web annotation selectors at once
- check citations cite the right document version
- בדיקת כל הציטוטים בתשובה מול המקורות

## Not supported

- fetching sources or proving the supplied text is authentic
- judging whether a quote supports the claim it is cited for
- fuzzy or normalized matching
- reporting every failure (only the first, in batch order)

## Behavior

- Implements W3C Web Annotation Data Model (Recommendation 2017-02-23) 4.2.4 TextQuoteSelector, 4.2.5 TextPositionSelector; r68 supplied-text profile 1.0.0; every result carries reference_version.
- Checks only caller-supplied text: authenticity_checked is always false. Sources are unique (source_id, version) pairs; citation_id values must be unique (duplicate is invalid_input).
- Each citation has a TextPositionSelector {start, end} plus a required quote (checked as in citation-passage-check), or a TextQuoteSelector {exact, prefix?, suffix?} plus an optional claimed_start (checked as in citation-anchor-check). quote with a quote selector, or claimed_start with a position selector, is invalid_input.
- All citations are validated structurally first; then, when the total text length (UTF-16 units) of the sources scanned by quote selectors exceeds max_scan_units, the call is limit_exceeded before any matching.
- Citations are checked in array order and the first failure is returned with citation_index, citation_id, selector_type and the per-selector detail (same fields and reason order as the single-citation tools); citations_checked counts the citations compared.
- Positions count Unicode code points from 0; no normalization of text, quotes or labels.

## Input

- `sources` (array of object, required): min items 1; max items 16
- `citations` (array of object, required): min items 1; max items 256

## Output

- `valid` (boolean, required)
- `reason` (one of null, "unknown_source", "version_mismatch", "span_reversed", "span_out_of_range", "quote_mismatch", "exact_not_found", "prefix_mismatch", "suffix_mismatch", "ambiguous_anchor", "position_mismatch", required)
- `first_discrepancy` (object or null, required)
- `citations_checked` (integer, required): min 0
- `authenticity_checked` (constant false, required)
- `reference_version` (constant "W3C Web Annotation Data Model (Recommendation 2017-02-23) 4.2.4 TextQuoteSelector, 4.2.5 TextPositionSelector; r68 supplied-text profile 1.0.0", required)

## Limits

- max input bytes: 1048576
- max sources: 16
- max text bytes: 524288
- max quote bytes: 16384
- max context bytes: 1024
- max label bytes: 256
- max citations: 256
- max scan units: 16777216

## Example

Request input:

```json
{
  "sources": [
    {
      "source_id": "alphabet",
      "version": "v1",
      "text": "abcdefghijklmnopqrstuvwxyz"
    }
  ],
  "citations": [
    {
      "citation_id": "c1",
      "source_id": "alphabet",
      "version": "v1",
      "selector": {
        "type": "TextPositionSelector",
        "start": 4,
        "end": 7
      },
      "quote": "efg"
    },
    {
      "citation_id": "c2",
      "source_id": "alphabet",
      "version": "v1",
      "selector": {
        "type": "TextQuoteSelector",
        "exact": "xyz",
        "prefix": "w"
      },
      "claimed_start": 23
    }
  ]
}
```

Response:

```json
{
  "result": {
    "valid": true,
    "reason": null,
    "first_discrepancy": null,
    "citations_checked": 2,
    "authenticity_checked": false,
    "reference_version": "W3C Web Annotation Data Model (Recommendation 2017-02-23) 4.2.4 TextQuoteSelector, 4.2.5 TextPositionSelector; r68 supplied-text profile 1.0.0"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "citation-batch-check",
  "version": "1.0.0",
  "input": {
    "sources": [
      {
        "source_id": "alphabet",
        "version": "v1",
        "text": "abcdefghijklmnopqrstuvwxyz"
      }
    ],
    "citations": [
      {
        "citation_id": "c1",
        "source_id": "alphabet",
        "version": "v1",
        "selector": {
          "type": "TextPositionSelector",
          "start": 4,
          "end": 7
        },
        "quote": "efg"
      },
      {
        "citation_id": "c2",
        "source_id": "alphabet",
        "version": "v1",
        "selector": {
          "type": "TextQuoteSelector",
          "exact": "xyz",
          "prefix": "w"
        },
        "claimed_start": 23
      }
    ]
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/citation-batch-check/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"sources":[{"source_id":"alphabet","version":"v1","text":"abcdefghijklmnopqrstuvwxyz"}],"citations":[{"citation_id":"c1","source_id":"alphabet","version":"v1","selector":{"type":"TextPositionSelector","start":4,"end":7},"quote":"efg"},{"citation_id":"c2","source_id":"alphabet","version":"v1","selector":{"type":"TextQuoteSelector","exact":"xyz","prefix":"w"},"claimed_start":23}]}'
```

The machine-readable contract is at [/v1/tools/citation-batch-check/versions/1.0.0](/v1/tools/citation-batch-check/versions/1.0.0).

### CLI

```sh
node cli.mjs run citation-batch-check 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Citation anchor check](/tools/citation-anchor-check): Check a quote anchor (exact text plus prefix/suffix) matches exactly one place in a supplied source version.
- [Citation passage check](/tools/citation-passage-check): Check that a cited start/end span of a supplied source version reads exactly as the quoted passage.
- [Citation record dedupe](/tools/citation-record-dedupe): Group duplicate CSL citation records by deterministic DOI or folded year|author|title match keys, in input order.
- [Citation record normalize](/tools/citation-record-normalize): Normalize one CSL 1.0.2 citation record: NFC, whitespace, empty values, DOI wrapper, page dashes, dates; lists changes.
- [Markdown sections chunk](/tools/markdown-sections-chunk): Chunk a CommonMark document into sections at its top-level ATX and setext headings, with levels, paths and spans.
- [Bleu ngrams count](/tools/bleu-ngrams-count): Count BLEU clipped n-gram matches and totals per order for tokenized segments, with optional clipping tables.