一个开源的模型上下文协议 (MCP) 服务器，旨在将 AI 生成的文本重写为人类创作的风格，并为那些常被检测器误判的作者提供一流的支持。
斯坦福大学的研究人员测试了七种主流 AI 检测器，针对非英语母语者撰写的托福作文进行检测，结果显示 61.3% 被归类为 AI 生成。而美国八年级母语学生撰写的同类作文则被正确分类。这一发表在《Patterns》（Cell Press, 2023）上的单一研究结果，正是本项目存在的理由。
检测器所称的“AI”统计特征，实际上也是以下群体的特征：
神经多样性作者，尤其是自闭症成年人，他们的文风倾向于较低的词汇多样性、更具体的词汇以及重复的短语结构。
ESL（英语作为第二语言）作者，他们的教科书式语法读起来过于规律，显得不自然。
正式学科的学者，他们的语域设计上就是统一的，且密集使用话语标记。
2026 年的一项 Springer 研究测量了 Originality.ai 在学术写作上的真实误报率为 14%，比该公司声称的比例高出一个数量级。2026 年对 ZeroGPT 的独立测试显示，学生作文的误报率为 26.4%，ESL 作者的误报率超过 21%。
这些检测器被部署在学术、就业、出版和签证流程中。HumanizeMCP 为受影响的作者提供了一种自我辩护的工具，它基于已发表的同行评审规避文献，而非商业“人性化”工具所采用的闭源启发式方法。
完整的证据基础位于 research/。请阅读 docs/ETHICS.md 以了解我们在合法无障碍使用与学术欺诈之间划定的界限。
Related MCP server: originality-mcp
HumanizeMCP 是一个 模型上下文协议 (Model Context Protocol) 服务器。任何支持 MCP 的客户端（Claude Code、GitHub Copilot CLI、Continue、Zed、Cursor 等）都可以调用其工具。它在本地运行，不发送任何遥测数据，唯一的网络调用是首次运行时可选的 Hugging Face 模型下载。
核心功能：
9 步流水线（预处理、表面提示替换、水印清除、文体平滑、受控改写、检测器引导迭代、可选回译、语调保留、验证），遵循 research/06_implementation_recommendations.md 中的设计。
风格预设（casual、blog、academic、esl、neurodivergent、preserve 等），可按调用配置。
本地检测器基准测试，针对开源模型（RoBERTa-OpenAI-detector、Fast-DetectGPT、Binoculars），并在用户提供密钥时支持商业 API 的可选适配器。
验证与迭代循环 (humanize_and_verify)，持续进行人性化处理，直到达到目标检测分数或耗尽预算。
# Using uv (recommended)
uv venv
source .venv/bin/activate
uv pip install -e .
# Or with pip
python -m venv .venv
source .venv/bin/activate
pip install -e .首次调用 Hugging Face 模型时，会将权重下载到 ~/.cache/huggingface/。基础检测器 (roberta-base-openai-detector) 大小约为 500MB。
Claude Code (~/.config/claude-code/mcp.json 或等效文件)：
{
"mcpServers": {
"humanize": {
"command": "humanize-mcp"
}
}
}GitHub Copilot CLI (~/.copilot/mcp-config.json)：
{
"mcpServers": {
"humanize": {
"command": "humanize-mcp"
}
}
}如果您安装在 virtualenv 中，请将 command 指向脚本的绝对路径 (/path/to/.venv/bin/humanize-mcp)。
从任何 MCP 客户端：
> use humanize on the following text with style="academic":
>
> In this paper, we delve into the multifaceted intricacies of consensus
> mechanisms — leveraging robust theoretical frameworks to underscore the
> pivotal role of decentralized governance in fostering trust.服务器返回的重写文本会删除 delve 词簇，拆分破折号，改变句子长度，并且（如果使用 humanize_and_verify）会通过本地检测器确认重写后的文本分数低于请求的 AI 阈值。
所有工具均可通过 MCP 调用。类型签名由 Pydantic 强制执行。
humanize(text, style="default", preserve_voice=True, intensity=0.7) -> str对 text 运行完整的人性化流水线。intensity 取值范围为 [0, 1]，对应研究档案中的最小/平衡/激进杠杆。
humanize(
text="The implementation leverages a robust framework...",
style="academic",
preserve_voice=True,
intensity=0.7,
)
# -> "The implementation uses a sturdy framework..."detect_tells(text) -> TellsReport在不重写的情况下定位 AI 提示。返回行号、字符偏移量、严重程度（1-5 星，匹配 research/02_ai_tells_catalog.md）以及替换建议。
detect_tells("We delve into the intricate tapestry of...")
# -> TellsReport(
# tell_count=3,
# tells=[TellLocation(category="excess_vocabulary", fragment="delve",
# line=1, char_start=3, char_end=8, severity=5,
# suggestion="examine"),
# ...],
# summary={"excess_vocabulary": 3},
# )score_humanity(text, detectors=["roberta-base"]) -> HumanityReport运行一个或多个本地检测器，并返回每个检测器的概率以及汇总结果。结论为 "human"、"uncertain"、"ai" 或 "unknown" 之一。
score_humanity(text, detectors=["roberta-base", "fast_detect_gpt"])
# -> HumanityReport(
# detector_scores=[DetectorScore(detector="roberta-base",
# probability_ai=0.87, ...),
# DetectorScore(detector="fast_detect_gpt",
# probability_ai=0.91, ...)],
# aggregate_probability_ai=0.89,
# verdict="ai",
# )apply_style(text, style) -> str纯语域转换，不进行人性化处理。当您想要在不触碰 AI 提示的情况下进行学术到博客或正式到非正式的转换时非常有用。
list_styles() -> list[str]枚举当前在 styles/ 中注册的风格预设。
humanize_and_verify(text, style="default", target_ai_score=0.3, max_iterations=3) -> VerifyResult人性化处理、评分，如果分数高于目标则以更高强度重新人性化，重复此过程直到达到目标或达到 max_iterations。返回最终文本以及处理前后的分数和每次迭代的日志。
result = humanize_and_verify(text, target_ai_score=0.2, max_iterations=5)
print(result.final_score.aggregate_probability_ai) # e.g. 0.18
print(result.target_reached) # True定义在 styles/ 中。该集合会随着项目的成熟而演变；调用 list_styles() 获取实时列表。MVP 版本包含：
预设 | 设计用途 | 备注 |
| 通用重写 | 平衡强度，保守的语调保留 |
| 个人邮件、社交帖子 | 去除正式感，提高突发性 |
| 长篇个人写作 | 保持段落节奏 |
| 会议论文、论文 | 保留话语标记，删除 |
| L2 英语作者 | 保留更简单的语法，移除被检测器标记的表面提示 |
| 自闭症/神经多样性作者 | 保留重复的短语结构，低词汇多样性 |
| “不要改变我的语调” | 仅处理表面提示，无改写步骤 |
预设架构以及如何添加自定义预设的文档位于 docs/ARCHITECTURE.md。
+------------------------+
| MCP Client (Claude |
| Code, Copilot, ...) |
+-----------+------------+
| stdio (MCP)
v
+------------------------+
| server.py (FastMCP) | <-- this package
+-----+-----+-----+------+
| | |
v v v
+--------+ +--------+ +----------+
| pipe- | | styles | | bench- |
| lines/ | | | | mark/ |
+--------+ +--------+ +----------+
| |
v v
+----------------------------+
| 9-pass pipeline: |
| 1. preprocess |
| 2. surface tells |
| 3. watermark scrub |
| 4. stylometric smoothing |
| 5. DIPPER paraphrase |
| 6. detector-guided loop |
| 7. back-translation (opt) |
| 8. style transfer |
| 9. verification |
+----------------------------+完整架构和扩展点：docs/ARCHITECTURE.md。
基准测试工具位于 benchmark/ 中，目前正在构建中。下方的标题数字是占位符，基准测试工程师将用 RAID 测试集的测量值替换它们。
检测器 | 人性化前 (平均 P(AI)) | 人性化后 (平均 P(AI)) | 降低幅度 |
RoBERTa-OpenAI | 待定 | 待定 | 待定 |
Fast-DetectGPT | 待定 | 待定 | 待定 |
Binoculars | 待定 | 待定 | 待定 |
GPTZero (API) | 待定 | 待定 | 待定 |
Originality.ai (API) | 待定 | 待定 | 待定 |
本地复现：
python -m benchmark.run --dataset raid_subset --pipeline default本工具是为合法的无障碍和公平使用而构建并记录的：
自身写作被误判的神经多样性作者。
学术提交被工具标记的 ESL 作者，该工具在他们的群体中被独立测量出 21-61% 的误报率。
正式学科的学者，其文风触发了不应部署在其机构工作流程中的脆弱检测器。
试图逃避检测器驱动的去平台化的记者或散文家。
本工具不是为以下目的构建的，维护者也不会协助：
在需要原创作者身份的评分学术作业中，将 LLM 生成的作品作为自己的写作提交。
生成虚假信息、垃圾邮件或旨在大规模欺骗的内容。
在安全关键环境（医疗建议、法律文件、安全相关披露）中击败检测器。
技术流水线对两类人群的支持是相同的；这是不可避免的，也是 Tor、Signal 以及历史上所有改写工具所采取的相同伦理立场。请阅读 docs/ETHICS.md 中的完整声明。
我们不提供同形异义字攻击、闭源模型水印剥离、零宽字符注入或任何破坏屏幕阅读器等无障碍工具的技术。那些是漏洞利用，而不是人性化。
如果您在研究中使用 HumanizeMCP，请引用该档案和本项目：
@software{humanize_mcp_2026,
author = {Olivas, Kit},
title = {HumanizeMCP: an open-source MCP server for accessibility-first
AI-text humanization},
year = {2026},
url = {https://github.com/kitfoxs/humanize-mcp},
version = {0.1.0},
note = {Research dossier in research/, evidence base in
research/references.bib}
}research/ 中的研究档案本身是一份可引用的文档，并包含了本项目所基于的同行评审工作的完整参考书目。
MIT。参见 LICENSE。
由 Kit Olivas (@kitfoxs) 和 Ada Marie 构建。
研究档案借鉴了 Liang 等人 (Stanford, 2023)、Dugan 等人 (RAID, 2024)、Krishna 等人 (DIPPER, 2023)、Cheng 等人 (Adversarial Paraphrasing, 2025)、David & Gervais (AuthorMist, 2025)、Kobak 等人 (vocabulary shift study, 2024)、Juzek & Ward (focal-word analysis, 2024) 等人的工作。完整引用见 research/references.bib。
特别感谢那些公开讲述误报伤害的作家、学生和学者，正是他们的经历促成了这项工作。
Apply a style preset to text without running humanization passes.
Useful when the caller wants pure register translation (formal to
casual, academic to blog, etc.) without removing AI tells. The set
of legal style names is whatever :func:list_styles returns.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The input prose. | |
| style | Yes | Name of a style preset registered in ``styles/``. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It clearly discloses that this tool does NOT humanize and performs only style/register transformation. It could add details about side effects or atomicity, but for a text-transform tool the key behavioral trait is well covered.
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: a single lead sentence stating core action and exclusions, followed by a brief usage context. No redundant wording exists.
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 simple parameter set (text, style), output schema existence, and sibling context, the description fully covers what the tool does, when to use it, and how to obtain valid style values. No critical information is missing.
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 100%, but the description adds value beyond the schema by clarifying that 'style' is a registered preset (from list_styles) and providing examples of register translation. This supplements the schema's generic type/description information.
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 uses a specific verb ('Apply') and resource ('style preset to text') and clearly distinguishes itself from siblings by stating 'without running humanization passes.' This makes its purpose unambiguous.
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?
Explicitly states when to use: 'Useful when the caller wants pure register translation... without removing AI tells.' It also points to list_styles for legal style names, providing clear guidance on prerequisites and differentiation from humanization tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Locate AI writing tells in the input text.
Reports surface signatures catalogued in
research/02_ai_tells_catalog.md: excess vocabulary (the "delve"
cluster), em-dash overuse, sentence-initial discourse markers,
copular templates, conversational scaffolding, and parallel-structure
overuse. Each tell carries a 1-indexed line number, character offsets,
a 1-to-5 severity, and an optional substitution suggestion.
The intended use is diagnostic: surface what would be edited by
:func:humanize so a writer can decide which tells to preserve and
which to remove.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The input prose to scan. |
| Name | Required | Description |
|---|---|---|
| tells | Yes | |
| summary | No | Count of tells per category. |
| tell_count | Yes | |
| text_length | Yes |
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 details what the tool reports (specific signature categories) and the output structure (line number, offsets, severity, substitution), plus its diagnostic role. It does not mention read-only nature or error handling, but the scanning behavior is well defined.
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, with the core action in the first sentence. The subsequent sentences add concrete detail about signature types, returned fields, and intended use without redundancy.
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 single-parameter detection tool with an output schema, the description is thorough: it states the purpose, lists detection categories, describes the output fields, and explains why a writer would use it. Some limitations (e.g., input length, language) are omitted, but they are minor and the overall context is clear.
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 input schema already describes the single parameter 'text' as 'The input prose to scan' (100% coverage). The description adds minimal extra parameter meaning, only reinforcing that it scans prose. Therefore it meets the baseline of 3.
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 'Locate' and a clear resource 'AI writing tells in the input text', then enumerates concrete tell categories and output fields. This clearly distinguishes it from sibling tools like humanize (which edits) by framing itself as diagnostic.
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 states the intended use: 'diagnostic: surface what would be edited by humanize so a writer can decide which tells to preserve and which to remove.' This tells the agent when to use it (before humanize) and expresses a clear alternative (humanize) but does not explicitly address all sibling tools like score_humanity, which might also be diagnostic.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rewrite AI-generated text so it reads as human-authored.
Runs the configured pipeline of passes (preprocess, surface-tell
substitution, watermark scrub, stylometric smoothing, optional
paraphrase passes; see docs/ARCHITECTURE.md) and returns the final
text. For diagnostic output (per-pass diff, before/after detector
scores) use :func:humanize_and_verify instead.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The input prose to humanize. Markdown formatting is tolerated and normalized in the preprocess pass. | |
| style | No | Name of a style preset registered in ``styles/``. Common presets include ``"casual"``, ``"blog"``, ``"academic"``, ``"esl"``, ``"neurodivergent"``, ``"preserve"``. Use :func:`list_styles` to enumerate what is actually available at runtime. | default |
| intensity | No | Continuous control in [0, 1] mapping to the ``minimal`` / ``balanced`` / ``aggressive`` levers documented in the research dossier. Roughly: 0.0-0.33 minimal, 0.34-0.66 balanced, 0.67-1.0 aggressive. Higher values run more passes and apply heavier per-pass edits. | |
| preserve_voice | No | When True, the pipeline retains identifying stylistic features the author would want to keep (sentence-length distribution, lexical idiom, characteristic punctuation). When False, the pipeline is free to flatten voice in pursuit of detector evasion. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the internal pipeline (preprocess, surface-tell substitution, watermark scrub, stylometric smoothing, optional paraphrase passes), which is valuable behavioral context. It does not explicitly state whether the tool is read-only or has side effects, but for a text transformation tool this is largely implicit.
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: a one-sentence purpose, one sentence on process, and one sentence pointing to an alternative. Every sentence adds value with no filler or redundancy.
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 (configurable pipeline) and rich schema/output schema, the description is complete enough for selection. It explains the purpose, distinguishes from the diagnostic variant, and provides a pointer to further architecture docs without over-explaining return values already covered by the output schema.
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 100%, so the baseline is 3. The tool description itself does not add substantial parameter meaning beyond the schema; it references docs and list_styles but repeats concepts already covered in the schema's property descriptions. Thus it does not exceed the baseline.
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+outcome: 'Rewrite AI-generated text so it reads as human-authored.' It distinguishes itself from sibling humanize_and_verify by explicitly noting that the latter provides diagnostic output.
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 tells when to use this tool vs the alternative: use humanize for the final text, and humanize_and_verify for diagnostic output. It also points to list_styles for enumerating available style presets, giving practical usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Humanize, then iterate against detectors until a target score is met.
v0.2.0 (Bet 3): wraps :class:pipelines.IterativeHumanizer, which
implements the Cheng et al. 2025 detector-guided loop (research/04
section 1.3). Each iteration:
Locates the worst-scoring paragraph in the current text.
Generates candidates_per_iteration stochastic paraphrase
candidates of that paragraph (via ParaphrasePass.paraphrase_candidates).
Scores each candidate, keeps the lowest, splices it back in.
Re-scores the whole text. If at or below target_ai_score, returns.
This replaces the v0.1.0 loop, which re-ran the deterministic 9-pass
pipeline at ramped intensities. As documented in
docs/REVIEW_v0.1.0.md section 2.9, every pass except 9-heavy is
idempotent on its own output, so iterations 2-3 of the old loop did no
work. The new loop is meaningfully different because it depends on
stochastic candidate generation: only non-deterministic search can
converge on a lower score after a deterministic fixed point.
The function always returns a result, even if the target was not
reached; callers should check target_reached to know.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The input prose to humanize. | |
| style | No | Name of a style preset; see :func:`list_styles`. | blog |
| max_iterations | No | Hard upper bound on improvement iterations. Must be >= 1. Iteration 0 is always the baseline humanization and does not count against this bound. | |
| target_ai_score | No | The aggregate probability_ai value below which the loop exits. Must be in [0, 1]. Cheng et al. 2025 use 0.15 as their stop value; we keep 0.3 ("comfortably human") as the default for backwards compatibility with v0.1.x callers. | |
| target_detector | No | Which detector field the loop optimizes against. ``"trusted_mean"`` (default) uses the suite's mean over detectors without documented bias caveats. ``"raw_mean"`` uses the unweighted mean across all detectors. Any other value is treated as a specific detector name (e.g. ``"roberta_openai"``). | trusted_mean |
| candidates_per_iteration | No | How many stochastic paraphrase candidates to generate per iteration. The Cheng et al. 2025 paper uses 3-5; we default to 3 as a quality / latency tradeoff. Must be >= 1. |
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| notes | No | |
| iterations | Yes | |
| final_score | Yes | The full output of :func:`score_humanity`. |
| initial_score | Yes | The full output of :func:`score_humanity`. |
| total_time_ms | No | Total wall-clock time including baseline humanization. |
| target_reached | Yes | |
| target_ai_score | Yes | |
| target_detector | No | Which detector field the loop optimized against. One of "trusted_mean", "raw_mean", or a specific detector name. |
| per_iteration_scores | No | Whole-text AI probability after iteration 0 (baseline) then after each accepted improvement. Empty if scoring was unavailable. |
| candidates_per_iteration | No | How many stochastic paraphrase candidates were generated per iteration. 1 reduces the loop to deterministic paraphrasing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden and does well: it explains the stochastic candidate generation, the per-iteration splicing, and the critical behavior that the function always returns a result, requiring the caller to check 'target_reached'. It also discloses the algorithm's reliance on non-determinism to break fixed points, adding meaningful behavioral context.
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 one-sentence purpose and uses numbered steps for algorithm clarity. The historical comparison to v0.1.0 adds several sentences, but it serves to explain why the loop is stochastic, which is behaviorally relevant. It is longer than strictly necessary but well-structured and justifiable for 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?
The description covers the iterative process, parameter behavior, and return-value expectations (checking 'target_reached'). It does not explicitly contrast with sibling tools, but the tool is complex and the description provides enough detail to understand its role. The presence of an output schema also offloads return-structure details.
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 100% with detailed descriptions for all six parameters, so the schema already provides defaults, constraints, and semantics. The description does mention 'candidates_per_iteration' and 'target_ai_score' in the loop description, but this adds only illustrative context rather than new parameter meaning beyond the schema's own thorough explanation.
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 'Humanize, then iterate against detectors until a target score is met' clearly specifies the verb (humanize and verify), resource (text), and goal (target score). This distinguishes the tool from siblings like 'humanize' by emphasizing the iterative detector-guided loop rather than a single-pass transformation.
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 implies the tool is for cases where a target AI score must be reached, but it never explicitly states when to prefer this over sibling tools such as 'humanize' or 'score_humanity'. It provides no exclusions or alternative conditions, and the 'always returns a result even if target was not reached' note is more behavioral than usage-oriented.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the names of all currently registered style presets.
Style presets are loaded from the styles/ package. If the package
is unavailable an empty list is returned.
list of str
Sorted list of preset names, e.g. ["academic", "blog", "casual", "esl", "neurodivergent", "preserve"].
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the return type (list of str), sorted order, example values, and an edge case (empty list if package unavailable). This gives the agent an accurate expectation of behavior, though it doesn't explicitly state side-effect-free behavior (which is implied by 'list').
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 well-structured: a single purpose line, a brief source/edge-case note, and a Returns section with type and example. Every sentence adds value without unnecessary fluff, and the formatting is clean.
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 simple, parameter-less listing tool with an output schema, the description is complete. It explains what is returned, the ordering, a representative example, and what happens if the package is unavailable. No critical information is missing for the agent to effectively invoke and use this tool.
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 tool has zero parameters, and the schema is an empty object. The description adds no parameter details, but none are needed. The baseline for a zero-parameter tool is 4, and the description provides relevant return-value context that compensates adequately.
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 clearly states the tool's function: 'List the names of all currently registered style presets.' This uses a specific verb (list) and resource (style presets), distinguishing it from siblings like apply_style or humanize. It also adds context about the source package and an example output.
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 provides clear context by explaining the purpose (listing preset names) and the behavior when the package is unavailable. While it doesn't explicitly mention alternatives or when not to use it, the intended use as a lookup tool is evident. The absence of explicit exclusions is acceptable for such a simple read-only operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score how AI-like the text reads to one or more open detectors.
Wraps the local detector adapters in benchmark/. The default
detector list is ["roberta-base"] (the canonical academic
baseline; see research/01_detector_landscape.md). Other adapters
such as "fast_detect_gpt" and "binoculars" are added as the
benchmark package matures.
Aggregate probability is the arithmetic mean of detector scores that
returned successfully. If every detector failed, aggregate is
-1.0 and the verdict is "unknown".
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The input prose to score. | |
| detectors | No | Names of detector adapters to run. Defaults to ``["roberta-base"]`` if not given or empty. |
| Name | Required | Description |
|---|---|---|
| verdict | Yes | One of "human", "uncertain", "ai", or "unknown". |
| text_length | Yes | |
| detector_scores | Yes | |
| aggregate_probability_ai | Yes | Mean of successful detector probability_ai scores. Equals -1.0 if no detector returned a score. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosure. It explains key behaviors: aggregate probability as arithmetic mean, failure handling (if every detector fails, aggregate is -1.0 and verdict is 'unknown'), and the default detector list. This goes beyond the schema and gives the agent a solid understanding of expected outcomes and edge cases.
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 well-structured: a clear one-sentence purpose, followed by concise details on defaults, adapter examples, and aggregate behavior. Every sentence earns its place without unnecessary fluff. It is appropriately sized for 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?
The description covers the tool's purpose, parameters, default behavior, and edge-case output. Since an output schema exists, the return structure is already defined, but the description adds crucial context about the aggregate value and verdict string. For a tool with 2 parameters and moderate complexity, this is 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 coverage is 100%, but the description adds meaningful context. It clarifies the 'detectors' parameter with the default value, the empty-list behavior, and examples of allowed adapter names. The description also explains how outputs are aggregated, which is directly relevant to interpreting the parameters. This significantly enriches the schema.
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: 'Score how AI-like the text reads to one or more open detectors.' This clearly states the tool's function and distinguishes it from siblings like humanize (which transforms text) and detect_tells (which likely identifies tells). The reference to detectors also sets it apart.
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 implies usage for scoring AI-likeness but does not explicitly state when to prefer this over alternatives. It mentions the default detector list and adapters, giving context about configuration, but it does not contrast with sibling tools or provide exclusion criteria. Usage guidance is clear enough for a scoring tool but not explicitly framed as 'use when...'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0apply_styledetect_tellshumanizehumanize_and_verifylist_stylesscore_humanityScored across 6 tools
Most tools are clearly distinct: detect_tells, score_humanity, apply_style, and list_styles each serve unique purposes. The only potential confusion is between humanize and humanize_and_verify, but their descriptions clearly delineate the simple pipeline from the iterative verification loop, so agents should be able to choose correctly.
All tool names follow a consistent verb_noun pattern: humanize, detect_tells, score_humanity, apply_style, list_styles, humanize_and_verify. Even the compound name follows the convention. No mixing of styles or vague verbs.
Six tools is well-scoped for a text humanization server. Each tool covers a distinct aspect: core humanization, diagnostic analysis, scoring, style control, and verification loop. This is an appropriate size without redundancy or bloat.
The toolset provides complete coverage of the humanization workflow: humanize for direct rewriting, humanize_and_verify for iterative improvement, detect_tells for diagnostics, score_humanity for evaluation, and apply_style/list_styles for style manipulation. There are no obvious gaps in the lifecycle.
An MCP server that integrates with Discord to provide AI-powered features.
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
Walter Remote MCP Server — AI humanization and detection tools
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
