用于处理 EGRUL（俄罗斯联邦法人统一国家登记处）和 EGRIP（俄罗斯联邦个体经营者统一国家登记处）的 MCP 服务器（Model Context Protocol — AI 助手连接外部工具的开放协议）。数据源来自俄罗斯联邦税务局（FTS）的官方开放数据转储。
状态： v0.1.2 — 开源版本（通过 SQLite 自托管）已完全就绪 + 托管版 Pro 客户端（用于 api.atomno.ru 的 HTTP 客户端 HostedClient）。已发布至 PyPI，并被 Glama 和 Smithery 收录。托管版 Pro 基础设施正在积极开发中。覆盖率 100.00%（345 个测试，ruff clean，fastmcp 3.2.4，通过 --cov-fail-under=100 强制执行）。
配套项目： mcp-fns-check（基于 EGRUL 的风险检查层）。
AI 助手（Cursor、Claude Desktop、Cline 或任何 MCP 客户端）可见的七个 MCP 工具：
工具 | 描述 | 参数 |
| 按 INN 搜索（10 位数字为法人，12 位为个体经营者） |
|
| 按 OGRN (13) 或 OGRNIP (15) 搜索 |
|
| 按名称进行模糊搜索 (FTS5) |
|
| 包含所有部分的完整卡片 |
|
| 仅获取带有股份的创始人 |
|
| 仅获取当前负责人 |
|
| 批量检查（最多 100 个 INN） |
|
此外还有一个用于检查服务器是否存活的 ping 工具。
Payload 的完整规范请参考 src/mcp_egrul/schemas.py（Pydantic 模型 CompanyCard、IECard、SearchResult、BulkResult）。
Related MCP server: onec-meta-mcp
# Без локального clone — работает «из коробки»
uvx atomno-mcp-egrul
# Или установка глобально
pipx install atomno-mcp-egrul
atomno-mcp-egrul
# Или классический pip в venv
pip install atomno-mcp-egrul
atomno-mcp-egrul需要 Python 3.11+ 和 uv（pip 的快速替代品，可选）。
git clone https://github.com/atomno-labs/mcp-egrul
cd mcp-egrul
uv venv
uv pip install -e ".[dev]"或者通过 pip 安装：
python -m venv .venv
.venv/Scripts/activate # Windows
# source .venv/bin/activate # Linux/macOS
pip install -e ".[dev]"atomno-mcp-egrul默认传输协议为 stdio（标准输入/输出 JSON-RPC）。适用于连接 Cursor / Claude Desktop / Claude Code。
claude_desktop_config.json){
"mcpServers": {
"egrul": {
"command": "uvx",
"args": ["atomno-mcp-egrul"]
}
}
}.cursor/mcp.json 或全局 ~/.cursor/mcp.json）{
"mcpServers": {
"egrul": {
"command": "uvx",
"args": ["atomno-mcp-egrul"]
}
}
}如果不使用
uv，请将"command": "uvx", "args": ["atomno-mcp-egrul"]替换为"command": "atomno-mcp-egrul"（需要pip install atomno-mcp-egrul或pipx install atomno-mcp-egrul）。
# 1. Скачайте дампы ФНС (acceptance на сайте ФНС — раз в жизни).
# Источники:
# ЕГРЮЛ — https://www.nalog.gov.ru/opendata/7707329152-egrul/
# ЕГРИП — https://www.nalog.gov.ru/opendata/7707329152-egrip/
# Положите их в структуру:
mkdir -p dumps/egrul/2026-04-24 dumps/egrip/2026-04-24
cp ~/Downloads/EGRUL_*.zip dumps/egrul/2026-04-24/
cp ~/Downloads/EGRIP_*.zip dumps/egrip/2026-04-24/
# 2. Первоначальный полный импорт (однократно, ~30-60 минут):
docker compose --profile import run --rm \
mcp-egrul-import atomno-mcp-egrul-import --registry egrul --full
docker compose --profile import run --rm \
mcp-egrul-import atomno-mcp-egrul-import --registry egrip --full
# 3. Запустите сервер + фоновый cron-демон:
docker compose up -d
docker compose logs -f mcp-egrul-scheduler导入后约 10 分钟，所有工具（search_by_inn、search_by_name 等）即可响应来自本地 FTS 快照的数据。
容器内 /data 卷的结构：
/data/
├── mcp_egrul_data.sqlite # SQLite + FTS5
└── dumps/ # read-only монтируется из ./dumps
├── egrul/
│ └── YYYY-MM-DD/*.zip
└── egrip/
└── YYYY-MM-DD/*.zipCron 守护进程 (atomno-mcp-egrul-scheduler) 会在您将最新转储放入 dumps/<registry>/<YYYY-MM-DD>/ 后自动获取，时间为莫斯科时间凌晨 03:00。如果没有新数据，任务将以 nothing_to_import 结束，且不会在 import_log 中产生多余记录。
来源：
EGRUL open-data: https://www.nalog.gov.ru/opendata/7707329152-egrul/
EGRIP open-data: https://www.nalog.gov.ru/opendata/7707329152-egrip/
格式：ZIP 压缩的每日 XML 存档，完整快照约 15 GB。法律上，您必须在接受许可协议后从 FTS 网站下载它们——服务器本身不会自动下载存档（严格限制）。
CLI：
# Полный первоначальный импорт (однократно):
atomno-mcp-egrul-import --registry egrul --full
atomno-mcp-egrul-import --registry egrip --full
# Инкремент (cron / ручной): загружается только если появилась более
# свежая YYYY-MM-DD-папка, чем последний успешный `import_log.source_dump_date`.
# Если новее нет — exit-code 5 и сообщение `nothing_to_import`.
atomno-mcp-egrul-import --registry egrul --incremental
# Фоновой cron-демон с ежедневным 03:00 MSK (вызывать вручную редко;
# обычно запускается сервисом mcp-egrul-scheduler в docker-compose).
atomno-mcp-egrul-scheduler --run-nowatomno-mcp-egrul-import 的退出代码：
代码 | 含义 |
0 | 导入成功 |
2 | 无效的配置 / CLI 参数 |
4 | 摄取错误（XML 损坏、缺少转储目录、数据库错误） |
5 |
|
api.atomno.ru 代理）当用户设置 ATOMNO_API_KEY 时，所有七个工具将自动代理到托管的 Pro API（SPEC §5.4, §5.4.1）。此模式下不使用本地 SQLite，托管 Pro 提供：
今日最新数据（无开放数据转储的每日延迟）：直接抓取 egrul.nalog.ru + 服务器端的 Dadata 回退。
无速率限制的批量端点 (POST /companies/bulk) — 一个请求代替 N 个本地 gather。
AI 卡片摘要、变更历史、按负责人姓名搜索（Pro 专属工具 — 将随 Phase 2 的托管服务器一同发布，见 §5.4.1）。
价格：Pro 版每月 10 美元，或与 mcp-fns-check 捆绑每月 15 美元（捆绑密钥）。免费层级：无需注册即可每天每 IP 30 次请求（SPEC §1）。
Cursor 中的配置 (.cursor/mcp.json)：
{
"mcpServers": {
"egrul": {
"command": "uvx",
"args": ["atomno-mcp-egrul"],
"env": {
"ATOMNO_API_KEY": "your-pro-key-here"
}
}
}
}行为与错误 — 没有静默回退：如果托管 API 不可用，客户端会抛出类型化异常，而不是静默返回过期的本地转储数据。HTTP ↔ MCP 错误代码映射见 SPEC §5.4.1：
托管 API HTTP 响应 | 客户端异常 |
|
200 | — | — |
400 |
|
|
401 |
|
|
403 |
|
|
404 (code=not_found) |
|
|
404 (wrong route) |
|
|
413 |
|
|
429 |
|
|
5xx |
|
|
timeout / DNS fail |
|
|
INN/OGRN 验证保留在客户端（在 HTTP 请求前检查校验位 — 避免对无效标识符进行往返请求）。
变量 | 描述 | 默认值 |
| EGRUL/EGRIP 快照的 SQLite 文件路径 |
|
| HTTP 客户端的 User-Agent |
|
| HTTP 超时（秒） |
|
| FTS 转储目录，结构 |
|
| 日志级别 |
|
| 调度程序时区 (cron 03:00) |
|
| (Pro) 托管订阅密钥 — 启用对 | 未设置 |
| (Pro) 托管 API 的基础 URL |
|
示例请参考 .env.example。
apps/mcp-egrul/
├── pyproject.toml
├── LICENSE # MIT
├── README.md # ЭТОТ ФАЙЛ
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── .gitignore
├── src/mcp_egrul/
│ ├── __init__.py
│ ├── server.py # FastMCP entrypoint, регистрация 7 тулзов + ping
│ ├── context.py # ServiceContext (DI: SQLiteStore + HTTP-клиент)
│ ├── config.py # Чтение env-vars в типизированные поля
│ ├── constants.py # Все магические числа и enum'ы
│ ├── validators.py # Контрольные цифры ИНН (10/12) и ОГРН (13/15)
│ ├── schemas.py # Pydantic-модели CompanyCard/IECard/SearchResult/...
│ ├── errors.py # McpEgrulError и подклассы
│ ├── db/
│ │ ├── __init__.py
│ │ └── sqlite.py # Async-клиент (aiosqlite), init/query/upsert/search + import_log
│ ├── sources/
│ │ ├── __init__.py
│ │ ├── base.py # Абстрактный интерфейс Source
│ │ ├── opendata.py # ФНС open-data адаптер (read-local → SQLite upsert)
│ │ ├── opendata_parser.py # Потоковый lxml.iterparse парсер ЕГРЮЛ/ЕГРИП XML
│ │ └── hosted_adapter.py # HTTP-клиент hosted Pro API (SPEC §5.4.1)
│ ├── tools/
│ │ ├── __init__.py
│ │ ├── search_by_inn.py
│ │ ├── search_by_ogrn.py
│ │ ├── search_by_name.py
│ │ ├── get_full_card.py
│ │ ├── get_founders.py
│ │ ├── get_director.py
│ │ └── bulk_cards.py
│ └── scripts/
│ ├── __init__.py
│ ├── import_opendata.py # CLI `atomno-mcp-egrul-import` (ручной / одноразовый)
│ └── scheduler.py # CLI `atomno-mcp-egrul-scheduler` (apscheduler cron 03:00 MSK)
└── tests/
├── __init__.py
├── conftest.py
├── fixtures/
│ ├── egrul_sample.xml # Мини-ЕГРЮЛ (2 валидных + 1 skip на неизвестный статус)
│ └── egrip_sample.xml # Мини-ЕГРИП (active + closed)
├── test_validators.py
├── test_schemas.py
├── test_config.py # Config.from_env + _parse_float_env (валидация env)
├── test_sqlite_store.py
├── test_cards.py # _cards.py: parse_iso_date/datetime + build_*card
├── test_server_ping.py # FastMCP tool-layer + server.main()
├── test_tools.py # 7 тулзов: happy-path + validation + not_found
├── test_opendata_parser.py # XML-парсер (zip, xml, skip-на-неизвестный-статус)
├── test_opendata_source.py # OpenDataSource.run_ingest (full/incremental)
├── test_integration_import.py # Полный цикл import → search → get_card
├── test_import_cli.py # CLI `atomno-mcp-egrul-import`
├── test_scheduler_cli.py # CLI `atomno-mcp-egrul-scheduler` + _run_scheduler
└── test_hosted_adapter.py # HostedClient + маршрутизация тулзов (respx-моки)pytest -v --cov=src/mcp_egrul当前覆盖率：100.00%（345 tests passed，ruff clean，1529 条语句 + 382 个分支，0 遗漏）。通过 --cov-fail-under=100 策略强制执行 — 任何回归都会破坏 CI。测试涵盖：
INN/OGRN/OGRNIP 验证器（校验位）；
Config.from_env + float-env 变量解析器（验证而非静默回退）；
所有 7 个 MCP 工具（happy-path + 验证 + not_found + 批量部分）；
SQLite 存储 + FTS5 + import_log；
EGRUL/EGRIP XML 解析器（zip, xml, 跳过状态未知的记录）；
OpenDataSource.run_ingest（完整/增量/nothing_to_import）；
完整的集成周期 import fixture → search → get_card → bulk；
两个 CLI（atomno-mcp-egrul-import, atomno-mcp-egrul-scheduler）— cron 任务注册、参数解析、_run_daily_ingest 在 all-happy/nothing_to_import/McpEgrulError 情况下的表现、带有 mock-ed asyncio.Event 的 _run_scheduler 完整周期；
通过 mcp.call_tool() 的 FastMCP 工具层 — 错误序列化为结构化字典，带有有效和无效 env 的 server.main()；
HostedClient（托管 Pro API 代理）— 所有 7 个方法的 happy-path，SPEC §5.4.1 中的所有 HTTP 错误（401/403/404/413/429/5xx），超时/ConnectError，服务器返回的无效 JSON/payload，批量客户端验证，async with 上下文；以及托管模式下的工具路由（设置 ATOMNO_API_KEY 时 — 请求发送到 api.atomno.ru 而非 SQLite，HTTP 前的 INN 验证）；
XML 解析器的边缘情况（75 个针对 _parse_company/_parse_ie/_parse_share/_parse_director/_parse_founders/地址回退/遗留属性/无效 INN/OGRN/KPP 长度的独立单元测试）；
SQLite 存储的私有辅助函数（_wrap, _prepare_row, _row_to_dict, _normalize_bm25, 通过 _ensure 自动初始化，拒绝无效的 finish_import 状态）；
ServiceContext 重入幂等性，atexit-cleanup，Config.from_env ValidationError → atomno-mcp-egrul-import CLI 的退出代码 2。
测试中从不直接调用外部 API — 仅通过 respx（HTTP 模拟）和本地 XML 固定数据（tests/fixtures/）。
所有来源均为 FTS 公开数据（EGRUL / EGRIP 开放数据集），其传播受《信息法》及 EGRUL 特定规范许可（见 SPEC §8）。
法人实体不属于 152-FZ（个人数据法）范畴。
负责人和创始人的姓名由 FTS 本身在公开登记处发布 — 转发这些数据是合法的。
不对任何外部 API 进行写操作。
密钥仅通过环境变量处理，仓库中仅包含不含值的 .env.example。
本服务是针对 FTS 公开数据的聚合器和便捷接口。与 FTS 无关联。使用风险自负。本服务回答中的信息不能替代完整的法律或财务评估。
MIT。根目录下的 LICENSE 文件。
Массовая выгрузка до 100 карточек за один вызов.
Вернёт объект с полями cards (успешные) и errors (точечные ошибки
по отдельным ИНН) — один плохой ИНН не ломает весь bulk.
| Name | Required | Description | Default |
|---|---|---|---|
| inns | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses important behavioral aspects like returning both successful cards and per-TIN errors, and that one bad TIN doesn't break the whole call. However, it omits whether the operation is read-only or has side effects, and no mention of authorization or rate limits.
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 two short sentences with no fluff. The first sentence front-loads the core purpose and capacity, and the second explains the return structure and error handling. Every word contributes value.
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 input schema (one parameter) and the existence of an output schema (not provided but implied), the description sufficiently covers maximum batch size, return format (cards/errors), and partial failure behavior. It is complete for its complexity.
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?
Although the schema has no description for the 'inns' parameter, the description mentions 'отдельным ИНН' (individual TINs), clarifying that the array contains Russian tax identifiers. With 0% schema coverage, the description adds meaning beyond the raw 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 clearly states the tool performs a massive upload of up to 100 cards per call, specifying the action (выгрузка) and resource (карточек). It distinguishes itself from siblings like search_by_inn by handling multiple INNs and returning partial errors.
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 indicates usage for batch card retrieval with a capacity limit of 100, but does not explicitly state when not to use it or list alternatives. However, the context of sibling tools and the capacity hint provide implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Текущий руководитель юр.лица по ИНН (только 10-значный ИНН).
| Name | Required | Description | Default |
|---|---|---|---|
| inn | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states it returns the current director, but fails to mention aspects like error handling, data freshness, auth requirements, or side effects. This is insufficient.
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 a single sentence, very concise and front-loaded with the key action and constraint. Every word earns its place, though it could be slightly expanded for additional clarity without losing brevity.
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 single-parameter tool and the existence of an output schema, the description is minimally adequate but lacks details on edge cases or error responses. It covers the basic purpose but not the full context of usage.
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 schema has 0% description coverage. The tool description adds value by specifying that the INN must be exactly 10 digits. However, it doesn't fully compensate for missing schema descriptions, e.g., no mention of format beyond digit count.
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 retrieves the current director of a legal entity by INN. It specifies the exact resource (director), action (get), and constraint (10-digit INN for legal entities). This distinguishes it from siblings like get_founders or search_by_inn.
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 does not provide any guidance on when to use this tool versus alternatives such as get_founders or search_by_inn. It only describes what it does without contextual or comparative usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Учредители юр.лица по ИНН (только 10-значный ИНН).
| Name | Required | Description | Default |
|---|---|---|---|
| inn | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only mentions the TIN length constraint but does not disclose whether this is a read-only operation, error handling, or any side effects.
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 a single sentence that conveys the core purpose and a key constraint without any unnecessary words. It is efficiently structured and front-loaded.
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 presence of an output schema (not shown), the description does not need to detail return values. However, it lacks information on error handling, input validation details, or the structure of the founders data, which could be incomplete for an agent.
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 has 0% description coverage, leaving the 'inn' property undocumented. The description adds the crucial constraint that only a 10-digit TIN is accepted, which is valuable beyond the schema definition.
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 retrieves founders of a legal entity by TIN and specifies the requirement of a 10-digit TIN. This distinguishes it from siblings like get_director which targets a different role.
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?
No explicit guidance on when to use this tool over alternatives like search_by_inn or get_director. It does not state prerequisites or exclusions, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Полная карточка (все секции: реквизиты, ОКВЭД, учредители, директор).
Хотя бы один из inn / ogrn обязателен. Если переданы оба — используется inn.
| Name | Required | Description | Default |
|---|---|---|---|
| inn | No | ||
| ogrn | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 that at least one of inn/ogrn is required and inn takes precedence, but does not mention read-only nature, authentication needs, or error handling for missing parameters.
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 two sentences and front-loads the purpose. It is concise with no unnecessary words, though structure could be improved with bullet points for clarity.
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 presence of an output schema and only two parameters, the description covers the primary requirements: purpose and parameter constraints. It lacks mention of error cases or usage limitations, but is largely complete for a simple 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 input schema has 0% description coverage, but the description adds meaning by clarifying that inn and ogrn are alternative identifiers, at least one is mandatory, and inn is used if both are provided. This significantly compensates for the schema's lack of parameter descriptions.
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 explicitly states 'Full card (all sections: details, OKVED, founders, director)', clearly indicating it retrieves a complete company card. This distinguishes it from sibling tools like get_director and get_founders, which target specific sections.
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 retrieving full card data, but does not explicitly contrast with siblings or state when to use this tool over alternatives like search_by_inn or get_director. No exclusion criteria or context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Диагностика: сервер жив, сообщает версию и размер локального слепка.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description takes full burden. It discloses that the tool reports version and snapshot size, which is useful. However, it does not mention read-only nature, safety, or potential side effects, though for a ping tool these are minimal.
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 a single, focused sentence that front-loads the main purpose ('Диагностика') and immediately specifies what the tool reports. No wasted words.
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 zero parameters, an output schema exists (not shown but referenced), and a set of sibling tools, the description is complete for this simple tool: it tells the agent exactly what the tool returns and its role as a health check.
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?
There are zero parameters, so the description need not add parameter info. Baseline for zero parameters is 4, and the description appropriately focuses on the tool's output rather than parameters.
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 is for diagnostics: checking server liveness, version, and snapshot size. It uses a specific verb ('диагностика') and resource ('сервер'), and is distinct from sibling tools that handle cards, directors, or searches.
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 health checks but does not explicitly state when to use this tool vs alternatives, nor does it mention exclusions or prerequisites. Given the clear purpose, usage is implied but not guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Карточка юр.лица или ИП по ИНН (10 цифр — ООО/АО, 12 — ИП/физлицо).
| Name | Required | Description | Default |
|---|---|---|---|
| inn | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must cover behavioral traits. It only states the searchby TIN and format, omitting any details on error handling, rate limits, or return behavior.
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 extremely concise (one short phrase) and front-loaded with the core purpose, containing no wasted words.
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 lookup tool with an output schema, the description is minimally complete but lacks details on error cases and what the card contains, leaving some gaps.
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 has no parameter descriptions (0% coverage), but the description adds critical semantic meaning by explaining the TIN length and entity mapping, significantly aiding correct usage.
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 returns a card of a legal entity or individual entrepreneur by TIN, and distinguishes it from siblings by specifying TIN format (10/12 digits) and entity types.
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 this tool is for TIN-based lookup, distinct from siblings like search_by_name or search_by_ogrn, but provides no explicit when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fuzzy-поиск юр.лиц по названию через FTS5.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | максимум результатов (1..50). | |
| query | Yes | строка запроса (минимум 2 символа). | |
| only_active | No | фильтровать только записи со статусом 'active'. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions fuzzy search via FTS5 but omits details like matching behavior, result ordering, or handling of misspellings.
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?
Description is a single sentence, concise but lacking structure. It could benefit from additional context without being lengthy.
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 no annotations and only input schema provided, the description omits important behavioral traits and result format expectations. Even with an output schema, more context would be helpful.
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 descriptions for all parameters. The description adds no new meaning beyond 'fuzzy', so baseline 3 applies.
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?
Description clearly states it is a fuzzy search of legal entities by name using FTS5, which is specific and distinguishes from siblings like search_by_inn and search_by_ogrn.
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?
No explicit guidance on when to use this tool versus alternatives. It implicitly targets name-based searches, but without stating exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Карточка по ОГРН (13 цифр) или ОГРНИП (15 цифр).
| Name | Required | Description | Default |
|---|---|---|---|
| ogrn | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavior. It only states what the tool does (retrieve a card) but omits details about error handling, side effects, or what happens for invalid inputs. This is insufficient for an agent to fully anticipate behavior.
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 a single sentence, which is highly concise and front-loaded. However, it could be structured with separate sentences for clarity, but for a simple tool it is appropriately sized.
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 existence of an output schema (not shown), the description may not need to detail return values. It provides the parameter format but lacks any mention of error handling or usage context. For a simple lookup tool, it is minimally adequate.
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 schema has 0% description coverage, so the description must compensate. It adds meaningful format constraints: 13 digits for OGRN and 15 digits for OGRNIP, which is valuable beyond the plain string type in 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 clearly states that the tool retrieves a card by OGRN (13 digits) or OGRNIP (15 digits), making the purpose and resource specific. It distinguishes itself from sibling tools like search_by_inn and search_by_name by indicating the identifier type.
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 offers no explicit guidance on when to use this tool versus alternatives or when not to use it. The context is only implied by the tool name and description, with no mention of prerequisites or exclusions.
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.2bulk_cardsget_directorget_foundersget_full_cardpingsearch_by_innsearch_by_namesearch_by_ogrnScored across 8 tools
Each tool targets a distinct query type: bulk export, specific fields (director, founders), full card, health check, and three search methods (INN, name, OGRN). No overlapping purposes.
Most tools use a verb_noun pattern (get_director, get_founders, search_by_inn, etc.). Ping and bulk_cards are minor deviations but still clear.
Eight tools cover a complete set of operations for a business registry: multiple search methods, specific field lookups, bulk export, and health check. No extraneous tools.
Covers essential read operations for a registry: search by various identifiers, retrieval of full cards and specific fields, bulk export. Missing filtering or advanced search (e.g., by region) but acceptable for a focused server.
MCP server for US nursing facility search and ownership lookup (NursingHomeDatabase).
MCP server for Russian books search, details, and recommendation candidates.
MCP server for medicaid-intelligence
Agent-native MCP server over 49M+ US public and government records, privacy-first, always current.
