CiteGuard
Queries arXiv to verify citation existence and metadata, and can fetch open-access full text for claim support.
Checks the global DOI registry via the doi.org Handle system to confirm DOI registration and resolve official URLs, serving as a fallback when open scholarly sources lack metadata.
Uses Semantic Scholar as a scholarly source for verifying citation existence, metadata, and supporting claim-level evidence.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@CiteGuardVerify the citation: 'Vaswani et al. 2017' is real"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
CiteGuard
中文 · English →
CiteGuard 是一个"证伪优先"的引用核验工具:面向 agent 写作工作流,对每条引用核对三件事——这篇论文存不存在、元数据(标题/作者/年份/venue/DOI)对不对、它到底支不支持你写的那句话——直接查询 OpenAlex / Crossref / arXiv / Semantic Scholar 等真实学术库,可作为 MCP 工具被 Claude Code、Codex、Cursor 等主流 agent 直接调用。
LLM 写作助手会幻觉参考文献:编造不存在的论文、拼错真实论文的元数据、引用与论点无关的真论文。CiteGuard 扮演那个"多疑的审稿人":它把每条引用当作 论点 → 引用 → 证据 问题去证伪;拿不准的时候明确说"查不准",而不是猜一个答案。
状态: Alpha(
v0.1.1,已发布至 PyPI 与 MCP 官方 registry)。当前积极开发的产品面是citeguard.*审计包、CLI、MCP server、批量工作流、缓存回放与发布门禁;历史遗留的写作 agent 实验仅保留在源码签出中,不属于发布包。
看看效果
源码签出场景还可以运行 python3 scripts/demo_verify.py 看实时效果(会真实访问 OpenAlex + arXiv);已安装包场景请优先使用 citeguard / citeguard-mcp 入口。
Verifying 2 citations against OpenAlex + arXiv ...
[OK] VERIFIED (confidence 0.7)
Vaswani et al., "Attention Is All You Need", arXiv:1706.03762
sources checked: openalex, arxiv
Citation resolves to a real record and the provided metadata matches.
[X] NOT_FOUND (confidence 0.8419)
(LLM-fabricated) "Quantum Teleportation of Citation Hallucinations in Synthetic Benchmarks"
sources checked: openalex, arxiv
Could not be verified in openalex, arxiv.输出为实时采集,置信度与匹配到的记录会随源数据漂移。
中文文献同样开箱即用(GB/T 7714 解析 + 全球 DOI 注册表兜底,均为真实输出):
$ citeguard extract refs_zh.md # GB/T 7714 中文参考文献
{"title": "迈向第三代人工智能", "authors": ["张钹", "朱军", "苏航"],
"venue": "中国科学: 信息科学", "year": 2020, "reference_format": "gbt7714"}
$ citeguard verify --title "迈向第三代人工智能" --doi "10.1360/SSI-2020-0204"
verdict: not_found # 开放学术源没有它的元数据……
doi_registration:
registered: true # ……但全球 DOI 注册表确认论文真实存在
resolution_url: engine.scichina.com/doi/10.1360/SSI-2020-0204Related MCP server: MCP Refchecker
它做什么
CiteGuard 对照 OpenAlex、Crossref、arXiv、Semantic Scholar 回答两个问题。
1. 论文存在吗?元数据对吗?
verify_citation / audit_citations 解析引用(标识符优先,否则按标题检索),逐字段比对你提供的元数据:
判定 | 含义 |
| 论文存在,你提供的元数据全部吻合 |
| 论文存在但某字段不符——附修正后的引用建议 |
| 在所查源中无法核实(标记高风险,但不断言伪造) |
| 多个候选难以区分——要求提供 DOI / arXiv id 消歧 |
2. 论文支持这个论点吗?(深度模式)
check_claim_support 先解析论文,再用 reranker + NLI 集成判断其摘要与你的论点句的关系:
判定 | 含义 |
| 摘要蕴含该论点 |
| 有部分/相关证据,但不够强 |
| 摘要未涉及该论点——弃权,不等于"不支持" |
| 摘要与论点相矛盾 |
支撑性结果带机器可读的 evidence_scope 字段,agent 不会把摘要级证据当成全文结论。全文级支撑有两条可选通道:调用方提供合法摘录或本地 text/PDF 文件;或设置 CITEGUARD_OA_FULLTEXT=1,让 CiteGuard 自动拉取源明确标记为开放获取(OA)的论文全文(arXiv 全部适用,PDF 解析需 pip install "citationguard[pdf]")。CiteGuard 不抓取受限源、不绕过付费墙;远程全文仅限 OA 地址且默认关闭。
两条守护原则保证它"诚实":源不可达永远不会升级成"伪造"(只降低置信度,设置 outage_limited=true 并上报 sources_available / sources_failed / source_failure_mode);insufficient_evidence / not_found 一律表述为"无法确认",最终裁决留给人或宿主 agent。此外,标识符是硬裁决:DOI / arXiv id 会先在其权威源(Crossref / arXiv)直查,命中即定音、压过任何同名记录;权威查询失败时结果降级为 ambiguous 并标记 outage_limited,绝不用纯标题匹配冒充高置信结论(输出附 identifier_lookup 字段)。多源查询并发执行,总预算默认 8 秒(CITEGUARD_SOURCE_BUDGET),慢源记为 budget_exceeded 而不拖垮整次核验。
快速上手
核心验证库运行于 Python ≥ 3.9;Python ≥ 3.10 的基础安装同时携带 MCP SDK,使 registry 的裸包安装可以直接启动 citeguard-mcp。
ℹ️ 包名说明:本项目在 PyPI 的发布名是
citationguard——安装用pip install citationguard,代码里仍然import citeguard,命令行入口也仍是citeguard/citeguard-mcp。PyPI 上的citeguard包是另一个组织的无关项目,请勿混淆。
通过 PyPI 安装:
python -m pip install citationguard # 含 MCP server(Python >= 3.10)
python -m pip install "citationguard[models]" # + 支撑性深度模式的 reranker/NLI 模型栈(较重)源码签出场景:python -m pip install -e .(extras 同上)。
先检查本地配置,再从命令行核验引用:
citeguard status # 本地就绪状态;加 --check-sources 做实时源探测
citeguard verify \
--title "Attention Is All You Need" \
--author "Ashish Vaswani" \
--year 2017 \
--arxiv-id 1706.03762
citeguard audit examples/citations.json --jobs 4 # 批量:JSON 数组或 .jsonl
citeguard audit examples/references.md --high-risk-only # 提取并审计参考文献文件
citeguard support \
--claim "The Transformer relies entirely on attention." \
--title "Attention Is All You Need" \
--arxiv-id 1706.03762
citeguard support-audit examples/claim_citations.json # 批量"论点/引用"对
citeguard support-audit examples/claim_citations.jsonl --high-risk-only
citeguard support-set examples/citations.json \
--claim "Citation auditing should verify existence, metadata, and claim support."
citeguard extract examples/references.md # 从文稿中提取引用候选
citeguard counterevidence --claim "The Transformer relies entirely on attention."提取支持 Markdown/纯文本参考文献、GB/T 7714 中文著录格式([J]/[M]/[C]/[D] 等标记,自动解析出标题/作者/期刊)、LaTeX \bibitem、BibTeX、编译产物 .bbl、LaTeX \bibliography{refs} / \addbibresource{refs.bib} 外链(含 \input{...} / \include{...} 子文件)以及 .docx——全部只用标准库(即 Markdown/LaTeX/BibTeX/BBL/DOCX 引用提取)。提取行保留 source_path / source_locator / 行号范围,审计结果可回指原始参考文献条目。
所有命令输出 JSON,带稳定的 next_action 枚举、风险排序和机器可读错误。完整 CLI 说明(含 cache 检查/导出/清理与离线 fixture 回放)见 docs/cli_reference.md;agent 侧完整字段契约见 docs/agent_output_contract.md。
作为 agent 工具接入(MCP)——推荐路径
CiteGuard 已收录进 MCP 官方 registry(io.github.xiaweiyi713/citeguard),支持 registry 浏览的客户端可直接搜索安装。手动安装:
已发布包:
python -m pip install citationguard # MCP server 需要 Python >= 3.10
citeguard-mcp # stdio 传输源码签出:
python -m pip install -e ".[mcp]"
citeguard-mcp在任意 MCP 客户端中注册(以 Claude Code 为例):
{
"mcpServers": {
"citeguard": { "command": "citeguard-mcp" }
}
}工具 | 用途 |
| 不做实时查询,检查 MCP/Python 就绪度、缓存、源配置与模型依赖状态 |
| 核验单条引用;返回判定、规范记录、逐字段差异、修复建议与所查源 |
| 批量核验引用;逐条报告 + 判定计数汇总 |
| 判断某篇论文是否支持某论点句(深度模式) |
| 判断一组引用是否共同支持一个论点 |
| 检索潜在反证线索;仅为复核线索,不构成矛盾判定 |
| 批量判断"论点/引用"对并汇总支撑判定 |
连接后先调一次 citeguard_status_tool——它在不发起实时查询的前提下报告源健康、缓存与模型就绪状态;详见 docs/mcp_setup.md 与 docs/agent_output_contract.md。
mcp-name: io.github.xiaweiyi713/citeguard
支持 skill 的 agent 客户端可使用 skills/citeguard-verify/SKILL.md,让 CiteGuard 在你写作时主动核验引用(呈现结果而不静默改动你的文本),适用于 Codex、Claude Code、Cursor 等 MCP 客户端。
作为 Python 库
import os
from citeguard.retrieval.scholarly_clients import build_live_metadata_source
from citeguard.verification import parse_citation, verify_citation, check_claim_support
source = build_live_metadata_source(["openalex", "arxiv"], mailto=os.environ["CITEGUARD_MAILTO"])
result = verify_citation(parse_citation(title="Attention Is All You Need", arxiv_id="1706.03762"), source)
print(result.verdict.value, result.confidence) # -> verified 0.7
support = check_claim_support("The Transformer relies entirely on attention.",
parse_citation(title="Attention Is All You Need", arxiv_id="1706.03762"),
source)
print(support.verdict.value, support.engine)配置
环境变量 | 默认值 | 用途 |
|
| 查询哪些源(另支持 |
| — | OpenAlex/Crossref 礼貌池的真实联系邮箱;未设置则不发送 |
| — | 可选,改善 Semantic Scholar 访问 |
| 系统用户缓存目录 | 本地 SQLite 解析缓存 |
| — | JSON/JSONL 引用 fixture,用于确定性离线运行 |
|
| 实时学术 API 调用超时(秒) |
|
| 设为 |
|
| 设为 |
| 英文模型 | 支撑性深度模式模型——非英文论点请配置多语模型 |
完整运行时契约(重试/退避、证据超时、缓存路径、远程证据边界)见 docs/configuration.md。
支撑性深度模式首次使用时下载模型权重,可用 citeguard models warmup 预下载。未安装 [models] 时,支撑性检查运行带标注的 heuristic 引擎(永不输出 supported 或 contradicted);citeguard status 会报告 support_models.engine=heuristic_fallback 与 next_action=install_or_configure_dependency。
中文支持
文本匹配对 CJK 友好(中文字符保留并按字符 bigram 分词,零额外依赖);GB/T 7714 中文参考文献(作者. 标题[J]. 期刊, 年, 卷(期): 页 等)可被自动解析为结构化字段后核验。判定中文论点的支撑性时,请将 CITEGUARD_RERANKER_MODEL / CITEGUARD_NLI_MODEL 指向多语模型。
中文论文的现实边界:中国学者的英文论文(SCI/EI/arXiv)覆盖完整;中文核心期刊多数不在 OpenAlex/Crossref 体系内(其 DOI 注册于中国 DOI/ISTIC),按标题核验通常返回 not_found——这表示"开放源查不到",不构成伪造指控。Crossref 对纯中文标题检索无效,CiteGuard 会自动跳过该查询以省去无效请求。带 DOI 的中文引用有兜底:开放源查不到时,CiteGuard 会查询全球 DOI 注册表(doi.org Handle 系统,覆盖中国 DOI/ISTIC 等所有注册机构),在结果的 doi_registration 字段报告该 DOI 是否真实注册及其官方解析地址——已注册说明"元数据未开放"而非"论文不存在";未注册会进一步降低可信度,但同样不构成伪造证明。可用 CITEGUARD_DOI_REGISTRY=0 关闭。
知网(CNKI)与万方未接入:两者没有开放/免费 API,我们不爬取受限内容。ChinaXiv 可行性调研结论为 NO-GO(其 OAI 端点受访问限制)——见 docs/chinaxiv_spike.md;可插拔的源接口保留,一旦出现开放端点即可添加适配器。
解析流程
解析输入;自由文本中的 DOI / arXiv id / 年份会被自动提取。
标识符优先:DOI 或 arXiv id 可确定性解析论文。
否则按标题检索所选源,以标题为主的匹配分对候选打分。
只比对你实际提供的字段,逐字段给出差异。
给出判定(存在性/元数据,或基于摘要级证据的支撑性)。
边界与已知限制
当前能力范围: 存在性 + 元数据核验、摘要级支撑性核验、用户提供的本地全文证据文件、多引用论点检查、多源适配器、SQLite 缓存、Markdown/LaTeX/BibTeX/BBL/DOCX 参考文献提取、MCP server、Claude Code skill、离线 eval。
已知限制
标识符是可靠路径。 有 DOI 或 arXiv id 时解析是确定性的——能提供就提供。
仅按标题匹配是尽力而为。 同一标题可能对应多条记录(如原始论文 + 年份不同的再版);无标识符时,正确的引用也可能匹配到同名记录而在
year/venue上报metadata_mismatch。请把仅标题匹配下的年份/venue 不符当作"待确认"。支撑性判定默认是摘要级的,除非你提供全文证据。 它判断摘要、采集到的元数据片段和你提供的合法本地 text/PDF 证据;弃权(
insufficient_evidence)常见且符合设计。支撑性 eval 是合成种子 fixture,按 train/dev/test 切分——是回归夹具,不是最终人工评审基准。
尚未实现: 对任意或受限来源的自动全文获取、跨论文全文多跳综合、反证判定(counter-evidence verdicting)、大规模人工评审基准。当前仅支持显式开启的开放获取全文和用户授权的本地/摘录证据。见 ROADMAP.md。
测试与复现
python3 -m unittest discover -s tests -v # 完整单测套件;MCP stdio 冒烟在缺 SDK 时自动跳过
python3 scripts/smoke_mcp.py --require-sdk # MCP stdio 冒烟;MCP SDK 需要 Python 3.10+
python3 scripts/eval_verification.py # 离线确定性的存在性/元数据 eval
python3 scripts/eval_support.py --report --split test --quality-gate
python3 scripts/release_package_gate.py # 开发/契约门禁,不授予发布声明资格
python3 -m pip install -e ".[models]"
python3 scripts/automated_release_review.py --output automated-release-review.json
python3 scripts/release_package_gate.py --release-claim-mode software --automated-review-report automated-release-review.json --require-build-tools单测与 eval 全部离线,在 CI 中运行。eval 数据集位于 data/eval/。支撑性 eval 工作流——指标、质量门禁、标注溯源 sidecar、盲评标注包——见 docs/support_eval.md;发布冒烟与发布流程见 docs/release_checklist.md。
生产模型自动评审可放行普通软件版本,但不会、也不能把维护者合成标签升级为人工评审基准;此类声明仍需真实独立标注和裁决。
项目结构
citeguard/
verification/ # 核心:解析、消解、核验、审计、缓存、支撑性、eval
cli.py # 零依赖 `citeguard` 命令:status/verify/audit
runtime.py # 共享的环境、源、缓存与状态配置
mcp/ # FastMCP server,暴露状态 + 核验工具
retrieval/ # 学术源适配器(OpenAlex/Crossref/arXiv/Semantic Scholar)+ 检索器
verifiers/ # 存在性/元数据 + reranker+NLI 支撑性集成
citation/ graph/ audit/ # 共享模型与工具
benchmark/ # 支撑性评测指标、校准与实验工件(随包发布)
skills/citeguard-verify/ # 可复用的 Codex/Claude/Cursor agent skill
scripts/ # demo + eval + 语料/模型工具
data/eval/ # 离线基准
docs/ # 发布文档、架构、benchmark 笔记、调研笔记
legacy/ # 历史写作 agent 原型(orchestrator/planner/writer/api),仅存在于源码签出,不随包发布
tests/ # unittest 套件新代码请从 citeguard 或 citeguard.* 导入。历史遗留的根包兼容层已移除,源码签出与发布包统一暴露 citeguard.* 产品面;见 docs/public_api_migration.md。
文档
安装与参考:
docs/claude_code_quickstart.md·docs/troubleshooting.md·docs/configuration.md·docs/mcp_setup.md·docs/cli_reference.md·docs/agent_output_contract.md·docs/error_codes.md·docs/public_api_migration.md基准评测:
docs/support_eval.md·docs/benchmark_design.md·docs/benchmark_todo.md·docs/support_labeling_guidelines.md发布与安全:
docs/release_checklist.md·docs/security_compliance.md架构:
docs/architecture.md· 路线图:ROADMAP.md· ChinaXiv 调研:docs/chinaxiv_spike.md
引用
学术使用请引用 CITATION.cff 中的软件记录。
贡献
见 CONTRIBUTING.md。基于 MIT License 发布。
Available Tools
7 toolsaudit_citations_toolA
Verify MANY citations at once.
citations is a list of objects, each with any of:
raw_text, title, authors, year, venue, doi, arxiv_id.
Returns a per-citation report plus summary, risk_ranking, and
review_summary. Agents should branch on review_summary.triage_plan,
compact risk_reason, and suggested_fix.kind /
suggested_fix.requires_user_confirmation instead of parsing prose. Set
review_summary.suggested_fix_summary.auto_apply_allowed=false means batch
repairs must be proposed to the user, not silently applied. Set
high_risk_only=true to return only high-risk result rows while preserving
full-batch review_summary counts and filtered.returned_indexes /
filtered.omitted_indexes for original-input traceability.
| Name | Required | Description | Default |
|---|---|---|---|
| citations | Yes | ||
| max_workers | No | ||
| high_risk_only | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains output fields, instructs agents to branch on structured fields rather than prose, describes high_risk_only filtering behavior, and warns that batch repairs must be proposed to the user rather than silently applied. It does not cover auth, rate limits, or error behavior, but the key operational behaviors are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and information-rich, with the core purpose front-loaded. Most sentences add meaningful guidance, but there are a few awkward phrases such as 'Set review_summary.suggested_fix_summary.auto_apply_allowed=false means...' which could be cleaner. Overall, it earns its length given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the lack of output schema, and the absence of annotations, the description covers a lot: input shape, key output fields, actionable guidance for agents, and high_risk_only behavior. The main gap is max_workers semantics and a bit more detail on what risk_ranking and per-citation report contain, but the description is largely sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It thoroughly documents the citations parameter's object shape and the high_risk_only parameter's effect, but it does not explain max_workers at all beyond the schema's name and default. This partial coverage leaves one parameter semantically underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific statement: 'Verify MANY citations at once.' This gives a verb, resource, and scope, and the emphasis on 'many' differentiates it from sibling tools like verify_citation_tool, which appears to handle single citations. It also describes the returned report structure, reinforcing the tool's batch purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates the tool is for verifying many citations at once, which establishes a primary use case. It does not explicitly name alternatives or say when not to use this tool, but the batch-focused language and sibling list provide enough context for an agent to infer the appropriate selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
audit_claim_support_toolA
Judge MANY claim-citation support pairs at once.
items is a list of objects with a required claim plus any citation
fields accepted by verify_citation_tool: raw_text, title, authors,
year, venue, doi, arxiv_id, full_text, full_text_file, and
optional per-item lang. An item may
alternatively provide citations, a non-empty list of citation objects, to
assess whether a claim is supported by the cited set. Returns a per-item
support report plus summary, risk_ranking, and review_summary. Agents
should branch on review_summary.triage_plan, compact risk_reason, and
suggested_fix.kind / suggested_fix.requires_user_confirmation instead
of parsing support prose or silently editing citations.
review_summary.suggested_fix_summary.auto_apply_allowed=false means batch
repairs must be proposed to the user, not silently applied. Items may include
lawful caller-provided full_text excerpts or full_text_file paths; those
are tagged as evidence_scope=full_text, and CiteGuard will not fetch gated
full text. Set
high_risk_only=true to return only high-risk rows while preserving
full-batch review_summary counts and filtered.returned_indexes /
filtered.omitted_indexes for original-input traceability.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | ||
| items | Yes | ||
| max_workers | No | ||
| high_risk_only | No | ||
| counterevidence_top_k | No | ||
| include_counterevidence | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it delivers: it names the return components, instructs agents to branch on triage_plan and suggested_fix, warns against silently editing citations, explains auto_apply_allowed=false, describes evidence_scope=full_text behavior, and clarifies high_risk_only preservation. This is strong, actionable transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and dense with useful operational details, and every sentence contributes information. It loses a point because the paragraphs are long and the structure could be improved with bullets or shorter scannable sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with no output schema and no annotations, the description covers invocation, input shape, output routing, and filtering behavior well. Gaps remain around counterevidence-related parameters and explicit sibling selection, but the core guidance is sufficient for correct basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description gives detailed semantics for `items` and `high_risk_only`, which is valuable given 0% schema coverage. However, three parameters (`max_workers`, `counterevidence_top_k`, `include_counterevidence`) are not explained, and the top-level `lang` parameter is not clearly distinguished from the per-item `lang`. Compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Judge MANY claim-citation support pairs at once.' It clearly conveys batch action on claim-citation pairs, but it does not explicitly differentiate the tool from siblings such as check_claim_support_set_tool or verify_citation_tool, so it stops short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'at once' phrasing implies this tool is for batch assessment, and the description gives substantial guidance on constructing items and handling output. However, it never explicitly says when to choose this tool over alternatives or provides exclusions, leaving some selection reasoning to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_claim_support_set_toolA
Judge whether a SET of cited papers supports one claim sentence.
citations is a list of citation objects accepted by verify_citation_tool.
Citation objects may include lawful caller-provided full_text excerpts or
full_text_file paths; those are tagged as evidence_scope=full_text, and
CiteGuard will not fetch gated full text. The result aggregates
per-citation support checks and exposes support_mode_details with the
policy no_unstated_multi_hop_or_full_text_support. A supported aggregate
requires at least one resolved citation to strongly support the claim;
contradictions are surfaced as high-risk.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | ||
| claim | Yes | ||
| citations | Yes | ||
| counterevidence_top_k | No | ||
| include_counterevidence | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers: it explains caller-provided full-text handling, the evidence_scope tagging, that gated full text will not be fetched, the aggregation behavior, the support_mode_details policy, the minimum support requirement, and how contradictions are surfaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a crisp summary and then efficiently adds behavioral details. It is somewhat dense and jargon-heavy, but each sentence contributes meaningful information and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core behavior is well covered, including input semantics, aggregation policy, support threshold, and risk signaling. However, with no output schema and no annotations, the description leaves counterevidence parameters and the full return shape underspecified, making it adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It thoroughly explains the citations parameter, including accepted object shapes and full-text evidence rules, and claim is self-evident. However, lang, counterevidence_top_k, and include_counterevidence are not explained at all, leaving majority of parameters underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Judge whether a SET of cited papers supports one claim sentence.' The emphasis on SET and aggregated per-citation checks clearly distinguishes it from the singular sibling check_claim_support_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the context clear: it is for judging a set of citations together and aggregating their support. It references verify_citation_tool for citation object format, which helps routing, but it never explicitly states when not to use this tool or names alternatives such as check_claim_support_tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_claim_support_toolA
Judge whether a cited paper SUPPORTS a claim sentence (abstract-level).
Resolves the paper (existence), then assesses support with a reranker+NLI
ensemble. Verdicts: supported | weakly_supported | insufficient_evidence |
contradicted. insufficient_evidence means the abstract does not address the
claim - NOT that the paper is unsupportive. Agents may pass lawful
caller-provided full_text excerpts or full_text_file paths; those are
tagged as evidence_scope=full_text, and CiteGuard will not fetch gated
full text. Deep models are downloaded on first use; without them the engine
falls back to "heuristic" (no supported/contradicted verdicts) and says so.
Set CITEGUARD_RERANKER_MODEL / CITEGUARD_NLI_MODEL to use multilingual
models for non-English claims.
| Name | Required | Description | Default |
|---|---|---|---|
| doi | No | ||
| lang | No | ||
| year | No | ||
| claim | Yes | ||
| title | No | ||
| venue | No | ||
| authors | No | ||
| abstract | No | ||
| arxiv_id | No | ||
| raw_text | No | ||
| full_text | No | ||
| evidence_text | No | ||
| full_text_file | No | ||
| evidence_chunks | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses the paper-resolution step, the reranker+NLI ensemble, the precise meaning of insufficient_evidence, the no-gated-full-text-fetching policy, first-use model downloads, heuristic fallback, and multilingual configuration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence adds operational value: purpose first, then verdict semantics, evidence scope, failure modes, and multilingual tuning. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with no annotations and no output schema, the description covers verdict semantics, fallback behavior, evidence scope, and model configuration. It stops short of describing the full return payload and the exact rules for identifying the paper, so some call details still rely on parameter-name inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only explicitly explains full_text, full_text_file, and two environment variables. The remaining parameters such as doi, arxiv_id, abstract, raw_text, evidence_text, evidence_chunks, lang, year, venue, and authors are left to be inferred from their names, with no guidance on how paper resolution uses them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific action (judge whether a cited paper supports a claim) on a clear object, and it lists the exact verdicts. It does not explicitly differentiate from siblings such as verify_citation_tool or audit_claim_support_tool, but the tool's function is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful input guidance: agents may pass full_text or full_text_file, and multilingual models can be enabled via environment variables. However, it never states when to choose this tool over alternatives like check_claim_support_set_tool or search_counterevidence_tool, so cross-tool routing is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
citeguard_status_toolA
Return MCP configuration and dependency status.
Call this first when setting up CiteGuard or diagnosing surprising results.
By default it does not contact OpenAlex/Crossref/arXiv/Semantic Scholar and
does not load model weights. Set check_sources=true to run a lightweight
per-source live probe using health_query.
| Name | Required | Description | Default |
|---|---|---|---|
| health_query | No | Attention Is All You Need | |
| check_sources | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and handles it well. It discloses the default behavior ('does not contact OpenAlex/Crossref/arXiv/Semantic Scholar and does not load model weights') and the opt-in live probe (`check_sources=true`). This is more transparent than most tool descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no waste: purpose, when-to-use, and behavioral defaults are each front-loaded in their own sentence. The structure is easy to scan and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool returns, when to call it, and the default/opt-in behavior for source checks. It doesn't describe the output structure, but given there is no output schema and this is a status tool, the provided information is sufficient for an agent to invoke and interpret the result at a high level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does. It explains that `check_sources=true` triggers a lightweight live probe and that `health_query` is used for that probe, adding meaning beyond the schema's type/default fields. It doesn't detail accepted query formats, but the default value provides a usable example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Return MCP configuration and dependency status.' It clearly positions the tool as an entry-point diagnostic for setting up CiteGuard or troubleshooting, which distinguishes it from the citation-verification and claim-support sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call this first when setting up CiteGuard or diagnosing surprising results,' giving clear context for when to use this tool. It doesn't explicitly name alternatives or state when not to use it, but the 'first' ordering implies it precedes the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_counterevidence_toolA
Search for scholarly records that may contain counter-evidence.
This tool returns review candidates only. It does not prove contradiction and does not change a support verdict; run claim-support checks on any promising candidate before editing text or replacing citations.
| Name | Required | Description | Default |
|---|---|---|---|
| claim | Yes | ||
| top_k | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing behavioral limitations: the tool returns candidates only, does not prove contradiction, and does not alter support verdicts. It stops short of describing return structure or read-only guarantees, but the search-oriented language and limitation statements provide strong transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence states the tool's purpose, and the second clarifies scope and next steps. Every sentence adds value with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter search tool with no output schema, the description gives enough high-level context to invoke it correctly and know what to do with results. It could be slightly more complete by describing the shape of a 'review candidate,' but the workflow guidance and clarity of purpose make it largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the two parameters, but it does not explain claim or top_k. The parameter names and titles are somewhat self-explanatory, so this is not a 1, but the description adds no explicit parameter-level meaning and top_k is entirely unaddressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Search for scholarly records that may contain counter-evidence.' It further distinguishes the tool from siblings by explicitly stating it returns review candidates only and does not prove contradiction or change a support verdict, so an agent can tell it apart from verification or audit tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when not to rely on this tool: it does not prove contradiction and does not change a support verdict. It also gives the correct follow-up action, 'run claim-support checks on any promising candidate before editing text or replacing citations,' which aligns with the sibling tools while not requiring the agent to infer the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
verify_citation_toolA
Verify ONE citation against live scholarly sources (OpenAlex/Crossref/arXiv).
Provide either a free-text citation in raw_text, or structured fields
(title, authors, year, doi, arxiv_id, venue). Returns a verdict
(verified | metadata_mismatch | not_found | ambiguous), the canonical record,
per-field diffs, a suggested corrected citation when confident, and which
sources were checked. A not_found verdict means "could not be verified",
not a definitive proof of fabrication. Evidence and full-text inputs belong
to the claim-support tools, not to existence/metadata verification.
| Name | Required | Description | Default |
|---|---|---|---|
| doi | No | ||
| year | No | ||
| title | No | ||
| venue | No | ||
| authors | No | ||
| arxiv_id | No | ||
| raw_text | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses live sources, the exact verdict vocabulary, the returned components (canonical record, diffs, suggested corrected citation, sources checked), and explains that not_found means unable to verify rather than proof of fabrication. This prevents misinterpreting a negative result.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose first, then input modes, then return value, then caveats. Every sentence adds functional value and there is no repetition of schema properties or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, it covers the main return values and the critical not_found caveat, and it is explicit about scope (existence/metadata verification, not claim support). It does not detail the exact shape of per-field diffs or the ambiguous verdict, but the tool can be invoked correctly from this definition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds the key distinction between raw_text and structured fields and names all seven parameters, which is helpful. But it gives no format guidance (e.g., author list format, DOI form, arxiv_id form) and doesn't clarify behavior when both raw_text and structured fields are supplied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Verify ONE citation against live scholarly sources (OpenAlex/Crossref/arXiv).' It also distinguishes this tool from claim-support siblings by stating evidence and full-text inputs belong to those tools, not to existence/metadata verification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly explains the input mode ('either a free-text citation in raw_text, or structured fields') and gives an explicit when-not: evidence/full-text inputs belong to claim-support tools. However, it does not name a specific sibling tool like check_claim_support_tool, only the category, so the routing is slightly less direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
7 tool updates
v0.1.3- First observed
audit_citations_tool - First observed
audit_claim_support_tool - First observed
check_claim_support_set_tool - First observed
check_claim_support_tool - First observed
citeguard_status_tool - First observed
search_counterevidence_tool - First observed
verify_citation_tool
TDQS
Scored across 7 tools
The suite clearly separates status, citation verification, claim-support checking, and counterevidence search, but check_claim_support_set_tool overlaps heavily with audit_claim_support_tool, which can also assess a claim against multiple citations. Agents may struggle to choose between these set-level support tools despite their long descriptions.
Names follow a rough verb_noun_tool pattern, but there are notable inconsistencies: citeguard_status_tool breaks the verb-first pattern, and singular/plural forms vary (verify_citation vs audit_citations, check_claim_support vs audit_claim_support). The names are readable but not perfectly uniform.
Seven tools is well-scoped for a citation-integrity server: single and batch variants, existence verification, claim-support assessment, counterevidence discovery, and a status/diagnostic tool. Each tool earns its place without excessive overlap at the count level.
The surface covers the core domain well: verify, audit, claim-support check, counterevidence search, and diagnostics. Minor gaps exist—such as no dedicated full-text retrieval or direct correction-application tool—but suggested fixes and user-confirmation flows are described, so agents can work around these.
Maintenance
Related MCP Connectors
Academic research MCP server for paper search, citation checks, graphs, and deep research.
Read-only MCP over an agentic SLR workspace with per-claim citation verification
Read-only MCP over an agentic SLR workspace with per-claim citation verification
An MCP server that gives your AI access to the source code and docs of all public github repos
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to verify BibTeX citations and URLs against academic databases like Semantic Scholar and DBLP. It allows users to ensure bibliography accuracy and link accessibility directly within their research workflows.1MIT
- AlicenseAqualityDmaintenanceMCP server for verifying academic citations via Semantic Scholar, OpenAlex, and CrossRef.1MIT
- AlicenseAqualityDmaintenanceMCP server enabling AI agents to search and retrieve scientific papers, citations, and author profiles from Crossref, OpenAlex, and Semantic Scholar with no API keys required.53MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that lets LLMs search, verify, and read papers from arXiv, preventing hallucinated academic references.MIT