{ "openapi": "3.1.1", "info": { "title": "RAG Citation Debugger API", "version": "1.0.0", "summary": "Check a RAG answer's citations against the retrieved chunks: uncited claims, wrong sources, numbers.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://ragcitationdebugger.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Check a RAG answer's citations against the retrieved chunks: uncited claims, wrong sources, numbers.", "description": "Paste a generated answer with citation markers ([1], [doc2], [^3], ^1, 【4】) and the retrieved chunks. Each sentence is mapped to the chunks it cites and checked for lexical support: uncited claims, citations to chunks that do not support the sentence, numbers that are not in the cited chunk, better-matching chunks, markers pointing to non-existent chunks, and retrieved chunks that were never used.\n\nMethodology:\n- Markers recognised: [1], [1, 3], [doc2], [^1], ^1, 【4】 and (source: x). Markers placed after the full stop are attached to the preceding sentence. Labels resolve to chunk ids exactly, then by trailing number (doc2 ↔ 2), then a bare number n to the n-th chunk.\n- Support = share of the sentence's content words (stop words removed, light stemming) found in the cited chunk; the best cited chunk counts. ≥ threshold → supported, ≥ half the threshold → weak support, below → unsupported citation.\n- Numbers in the sentence must appear in at least one cited chunk, otherwise number-mismatch. Sentences with ≥ 3 content words or a number but no marker are uncited claims.\n- If another chunk covers the sentence clearly better (≥ threshold and +0.2), it is suggested as the correct citation. Chunks never cited are unused, or relevant-but-uncited if they would support a sentence.\n- This is lexical overlap, not entailment: paraphrases can look unsupported and negations can look supported. Treat results as pointers for review.", "tags": [ "ai-infra" ], "x-mcp-tool": "rag_citation_debugger", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RagCitationDebuggerInput" }, "examples": { "example1": { "summary": "Answer with a wrong number, a misattributed citation and an uncited claim", "value": { "answer": "The Eiffel Tower is 330 metres tall [1]. It was completed in 1888 for the World's Fair [2]. It was designed by the engineering company of Gustave Eiffel [3]. Around 7 million people visit it every year.", "chunks": "[{\"id\":\"1\",\"text\":\"The Eiffel Tower is a wrought-iron lattice tower in Paris. It is 330 metres (1,083 ft) tall, about the same height as an 81-storey building.\"},{\"id\":\"2\",\"text\":\"Construction of the tower began in 1887 and it was completed in 1889 as the centrepiece of the 1889 World's Fair (Exposition Universelle).\"},{\"id\":\"3\",\"text\":\"Paris has a population of about 2.1 million inhabitants and is the capital of France.\"},{\"id\":\"4\",\"text\":\"The tower is named after the engineer Gustave Eiffel, whose company designed and built the tower.\"},{\"id\":\"5\",\"text\":\"The Louvre is the world's most-visited museum.\"}]" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RagCitationDebuggerResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "RagCitationDebuggerInput": { "type": "object", "additionalProperties": false, "properties": { "answer": { "title": "Generated answer with citation markers", "type": "string", "maxLength": 100000 }, "chunks": { "title": "Retrieved chunks", "description": "JSON [{\"id\":\"doc1\",\"text\":\"…\"}] or one chunk per block starting with [id] or id: …", "type": "string", "maxLength": 500000 }, "supportThreshold": { "title": "Support threshold", "description": "Share of the sentence's content words that must appear in a cited chunk.", "type": "number", "minimum": 0.1, "maximum": 1, "default": 0.5 } }, "required": [ "answer", "chunks" ] }, "RagCitationDebuggerResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "sentences", "chunks", "unknownMarkers", "counts" ], "properties": { "sentences": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "index", "sentence", "markers", "cited", "verdict", "coverage", "checkWorthy", "missingNumbers", "bestChunk", "bestCoverage", "suggestedCitation" ], "properties": { "index": { "type": "integer" }, "sentence": { "type": "string" }, "markers": { "type": "array", "items": { "type": "string" } }, "cited": { "type": "array", "items": { "type": "string" } }, "verdict": { "type": "string", "enum": [ "supported", "number-mismatch", "weak-support", "unsupported-citation", "uncited-claim", "no-claim" ] }, "coverage": { "type": "number" }, "checkWorthy": { "type": "array", "items": { "type": "string" } }, "missingNumbers": { "type": "array", "items": { "type": "string" } }, "bestChunk": { "type": [ "string", "null" ] }, "bestCoverage": { "type": "number" }, "suggestedCitation": { "type": [ "string", "null" ] } } } }, "chunks": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "preview", "timesCited", "supportedSentences", "bestCoverage", "status" ], "properties": { "id": { "type": "string" }, "preview": { "type": "string" }, "timesCited": { "type": "integer" }, "supportedSentences": { "type": "integer" }, "bestCoverage": { "type": "number" }, "status": { "type": "string", "enum": [ "used", "cited-but-not-supporting", "relevant-but-uncited", "unused" ] } } } }, "unknownMarkers": { "type": "array", "items": { "type": "string" } }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }