lk-tko-mcp
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., "@lk-tko-mcpCheck the current debt for contragent with INN 7701234567"
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.
lk-tko-mcp
An MCP server (Model Context Protocol) in Python that gives Claude tool access to the LK system (personal account, project lk-tko-v2).
What it is and why
MCP is an open protocol through which an external process gives the LLM a set of “tools”: ordinary functions with typed arguments. By connecting the server to Claude Code, you can ask Claude to call a specific function (“get counterparty status by INN”, “calculate penalties for a period for lkUser”, etc.) instead of explaining the context in text or manually digging into the DB/code every time.
The goal of this pet project is to build a reusable tool layer over the LK business logic that you can use from any future Claude Code session, not just inside the main repository.
Related MCP server: MCP4Acumatica
Stack
Python 3.10+, dependency manager —
uvSDK:
mcp[cli](v2, packagemcp==2.1.0), classmcp.server.MCPServerTransport: stdio (Claude Code launches the process and communicates with it over stdin/stdout)
Integration stack
The first tool (get_contragent_status) talks to the CUBA REST API v2 of lk-tko-v2 (OAuth2 password grant + generic entity search on rtneo$Contragent) — not directly to the DB. The request format is confirmed by working examples from curls.txt in the lk-tko-v2 repository.
Structure
lk-tko-mcp/
├── server.py # MCPServer + @mcp.tool() функции — вся логика инструментов
├── lk_client.py # REST-клиент к lk-tko-v2 (OAuth2 + entity search)
├── run.py # точка входа, которую регистрирует Claude Code
├── .env.example # шаблон переменных окружения для доступа к ЛК (реальный .env не коммитится)
├── pyproject.toml
└── uv.lockRunning and verifying locally
uv run mcp dev run.py # открывает MCP Inspector в браузере — можно вручную вызывать toolsConnecting to Claude Code
claude mcp add lk-tko-mcp -- uv run run.py
claude mcp list # проверить, что статус ConnectedDevelopment plan
Scaffold — done. A server with
pingandget_contragent_status; runs locally and via Inspector.REST client — done.
lk_client.py: OAuth2 password grant with token caching +search_entity()on top of CUBA REST v2.First real integration — done and verified live.
get_contragent_statusactually calls the lk-tko-v2 REST API vialk_client.search_entity("rtneo$Contragent", ...); verified via MCP Inspector with real data from the test environment.Connecting to Claude Code — done.
claude mcp add lk-tko-mcp -- uv run run.py, status✔ Connected. A guide for onboarding other developers — seeONBOARDING.md.Debt/billing (Priority 1 from RESEARCH.md) — done, 6 of 7 verified.
get_contragent_debt,get_debt_by_phone,get_debt_by_email,get_serviced_periods,get_calculation_amount_type,get_contract,get_fine_details— all implemented via two new REST helpers inlk_client.py(call_v3for custom v3 controllers,call_servicefor declarative v2 services).get_contragent_billsis implemented but blocked by a bug on the lk-tko-v2 side (see note below).get_calculations_tabs,get_debt_breakdown_by_real_estate,find_contragents_with_debt_older_than— not implemented, they have no REST wrapper in lk-tko-v2 at all (confirmed by grep across the entire repository).
Known issues
get_contragent_billsfails with 500. A bug on the lk-tko-v2 side:BillRepository.getBillsByContragentAndPeriod(line 71) references a nonexistent aliasb.documentNumberinstead ofe.documentNumber— this breaks JPQL compilation on any call to/app/rest/v3/bill. A separate task has been filed to fix it in lk-tko-v2; our code is not at fault here.
Expanding the toolset — one tool per specific recurring scenario (e.g., period/penalties for lkUser — see project memory
project_lk_user_config), don't abstract in advance.(Optional) team access —
claude mcp add lk-tko-mcp --scope project -- uv run run.pywill create.mcp.jsonin the repository, which can be committed (without secrets).
Verification (after filling in .env)
# 1. Юнит-уровень, без Claude
uv run python -c "from lk_client import search_entity; print(search_entity('rtneo$Contragent', [{'property':'inn','operator':'=','value':'<реальный ИНН>'}]))"
# 2. Через MCP Inspector
uv run mcp dev run.py
# 3. End-to-end
claude mcp add lk-tko-mcp -- uv run run.py
claude mcp listSecurity notes
.envis not committed; real secrets (client_id/secret, login/password) are stored only locally.By default, point to the local dev instance of lk-tko-v2 (
http://localhost:8080) rather than staging/prod — there may be non-anonymized personal data there.The
Contragententity has no pre-confirmed "status" field —get_contragent_statusreturns the found entity in full; the field for the real status needs to be determined based on the actual REST API response.
Available Tools
10 toolsget_calculation_amount_typeC
Тип расчёта начислений и текущий долг по лицевому счёту/ИНН.
| Name | Required | Description | Default |
|---|---|---|---|
| pa_or_inn | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It only labels the output ('type of calculation and current debt') and does not mention read-only behavior, error cases, authentication needs, or result shape. An agent gets no insight into side effects or failure modes.
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 compact fragment with no filler or redundant phrasing. It front-loads the two output aspects before the input scope. The lack of a verb makes it slightly less structured, but the length is appropriate for a one-parameter lookup.
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?
With one parameter, no output schema, and no annotations, the description minimally covers the return aspects (calculation type and current debt) and the input. However, it does not explain what 'type of calculation' means nor differentiate this tool from the debt-focused siblings, leaving tool selection partially ambiguous.
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 clarifies that pa_or_inn means 'personal account/INN' ('по лицевому счёту/ИНН'), which is the essential semantic for correctly supplying the single parameter. It stops short of specifying accepted formats or how to distinguish a personal account from an INN.
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 is a Russian noun phrase ('Тип расчёта начислений и текущий долг...') rather than a clear verb+resource statement. It conveys the resource domain — accrual calculation type and current debt — but remains vague about the exact operation and does not distinguish this tool from sibling debt tools like get_contragent_debt.
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?
There is no guidance about when to use this tool versus alternatives such as get_contragent_debt, get_debt_by_phone, or get_debt_by_email. The input scope (personal account/INN) is implied, but no exclusions, conditions, or alternative tool names are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_contractB
Список договоров контрагента с суммами начислений/платежей/пеней/долга.
contragent_id — UUID контрагента (см. поле "id" в get_contragent_status).
| Name | Required | Description | Default |
|---|---|---|---|
| contragent_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It says the result is a list of contracts with amounts, but it does not state whether the operation is read-only, how errors are returned, whether pagination applies, or what the actual response structure looks like.
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 filler. The main purpose is front-loaded, and the parameter clarification is placed second where it is easy to find.
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 read-style tool, the description gives enough to understand what is returned at a high level and where the parameter comes from. However, with no output schema and no annotations, the lack of response details and usage boundaries leaves moderate gaps for an agent that needs to invoke or interpret the tool correctly.
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 only defines contragent_id as a string with no description, while the tool description adds that it is a UUID and points to the exact source field ('id' in get_contragent_status). This is valuable semantic clarification for the only parameter and compensates well for the 0% schema description coverage.
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 states the resource (counterparty contracts) and the included data (accruals, payments, penalties, debt), so an agent can tell it is a contract-list tool. However, it is phrased as a noun phrase rather than a direct verb+resource, and it does not explicitly differentiate it from siblings like get_contragent_debt or get_contragent_bills.
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 only usage guidance is that contragent_id comes from the 'id' field in get_contragent_status, which helps with parameter sourcing but not tool selection. There is no indication of when to prefer this tool over the sibling tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_contragent_billsB
Счета контрагента за период.
contragent_id — UUID контрагента (см. поле "id" в get_contragent_status). date_from/date_to — даты в формате dd.MM.yyyy.
| Name | Required | Description | Default |
|---|---|---|---|
| date_to | No | ||
| is_paid | No | ||
| date_from | No | ||
| contragent_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does not state that the operation is read-only, what it returns, whether it supports filtering by is_paid, or any pagination/error behavior. The only added behavioral context is the date format and the source of contragent_id, which are mostly parameter semantics.
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 well-organized: a one-line purpose statement followed by concise parameter definitions. There is no redundancy or filler; every sentence adds some useful information.
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 read-style tool with four parameters, the description is minimally adequate: it explains the key identifier and date format. But with no annotations and no output schema, the lack of any explanation for is_paid and the absence of return-value or behavior details leave meaningful gaps 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?
Schema description coverage is 0%, so the description must compensate. It usefully explains contragent_id as the UUID from get_contragent_status and specifies the dd.MM.yyyy format for date_from/date_to. However, it completely omits the is_paid parameter and does not clarify what true/false values represent.
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 identifies a specific resource: counterparty bills/invoices over a date period. It is clearly distinct from sibling tools like get_contragent_debt or get_contragent_status, though it is phrased as a noun phrase rather than an explicit action sentence like 'Returns...'.
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 intended use is implied by 'Счета контрагента за период' and the date parameters: use this tool to get counterparty bills within a period. However, there is no explicit guidance about when NOT to use it or how it relates to alternatives like get_contragent_debt.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_contragent_debtA
Долг контрагента (основной долг, пени, госпошлина) по лицевому счёту или ИНН.
| Name | Required | Description | Default |
|---|---|---|---|
| pa_or_inn | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It usefully explains that the debt includes principal, penalties, and state fee, and that lookup is by account or INN. But it does not describe return shape, error behavior, or any requirements beyond the parameter.
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 efficient sentence with no filler. The key information—debt components and lookup keys—is front-loaded and every part 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?
For a simple one-parameter read tool, the description covers the essential lookup keys and debt composition. However, with no output schema and no annotations, the agent must infer return format and must rely on sibling tool names to understand when this tool is preferred over phone/email debt lookups.
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 clarify the parameter. It does clarify that pa_or_inn can be either a personal account or an INN, which adds meaning beyond the raw property name. It does not specify format, length, or whether both identifiers are accepted simultaneously.
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 identifies the resource (contragent's debt) and the key lookup dimensions: by personal account or INN. The tool name includes 'get', making the operation clear. It does not explicitly contrast with sibling tools like get_debt_by_phone or get_debt_by_email, but the identifier-based scoping is enough to distinguish it.
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?
Usage context is implied: call this tool when you have a personal account or INN and need a contragent's debt. However, there is no explicit when-not-to-use guidance or mention of alternatives such as get_debt_by_phone and get_debt_by_email.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_contragent_statusB
Найти контрагента ЛК по ИНН и вернуть его данные.
Возвращает найденную сущность Contragent целиком через REST API lk-tko-v2 — отдельного поля "статус" может не быть, это нужно смотреть по реальным данным, которые вернёт CUBA REST.
| Name | Required | Description | Default |
|---|---|---|---|
| inn | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that the REST API returns the whole Contragent entity and that a dedicated 'status' field may be absent, which is a significant caveat. It does not mention missing-result behavior, permissions, or other side effects, but the read-only nature is clear from the verb.
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?
Two sentences, with the core action first and the important caveat second. No wasted words; the caveat earns its place because it corrects a likely false expectation created by the tool name.
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 low-complexity one-parameter read operation with no output schema, the description gives the core behavior and a key caveat. It is still incomplete about when to choose it versus siblings and about what happens when no counterparty is found, so it does not reach fully self-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. It does clarify that the single inn parameter is the Russian taxpayer ID used to search, going beyond the schema's bare 'inn' string. It stops short of specifying expected format or validation rules, but for a single well-known identifier this is near-sufficient.
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 states a precise verb (find) and resource (contragent by INN, Contragent entity). It is distinguishable from sibling debt/phone/email/bills tools by being a general entity lookup. However, it doesn't explicitly differentiate itself from siblings, and the tool name focuses on 'status' while the description says no separate status field may exist.
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 guidance is given on when to choose this tool over siblings such as get_contragent_debt or get_contragent_bills. The intended use (lookup by INN) is implied but not stated as a decision rule, and no exclusions or alternative conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_debt_by_emailB
Долг по всем лицевым счетам, привязанным к email.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It adds a useful behavioral fact: debt is returned across all personal accounts associated with the email, implying a read-only lookup. But it does not disclose error behavior, empty results, authorization, or what specifically is returned.
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?
One short sentence with no filler and the key scope ('всем лицевым счетам') front-loaded. It is concise but perhaps too sparse to compensate for missing usage and output details.
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 tool with no output schema and no annotations, the description should explain what the result is (debt amount? list of debts?) and edge-case behavior. It leaves these to inference, making it incomplete for an agent trying to invoke it confidently.
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 clarifies that email is the account-linking identifier, but it does not specify format, normalization, or behavior for unknown emails. The single parameter is self-descriptive, so this is adequate, not more.
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 states the resource ('debt') and the addressing key ('email'), adding a scope detail: aggregate debt across all personal accounts tied to that email. This differentiates it from get_debt_by_phone, though it is phrased as a noun phrase rather than an explicit verb phrase.
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 guidance says when to prefer this tool over siblings such as get_debt_by_phone or get_contragent_debt. The use case is only implied by the email parameter and tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_debt_by_phoneB
Долг по всем лицевым счетам, привязанным к телефону.
| Name | Required | Description | Default |
|---|---|---|---|
| phone | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It adds useful information by stating that the result spans all personal accounts linked to the phone, but it does not disclose details such as phone normalization, missing-account behavior, or absence of 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 concise sentence with no filler, and the key scope 'all personal accounts linked to the phone' is front-loaded. It could have been more informative, but it is efficiently worded.
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 one-parameter tool with no annotations and no output schema, the description should at least specify the phone input format and when to prefer this over get_debt_by_email. It conveys the return concept but leaves the invocation contract underspecified.
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 does not compensate by explaining the expected phone format, normalization, or validation rules. An agent cannot determine from the definition whether to provide an E.164 number, local digits, or a country-coded string.
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 identifies the resource: debt for all personal accounts associated with a phone number. This also differentiates it from the sibling get_debt_by_email by specifying the lookup channel, though it lacks an explicit verb.
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: use this tool when you have a phone number and need the debt across attached personal accounts. It does not explicitly mention alternatives or when not to use it, but the intended scenario is evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_fine_detailsA
Детализация пеней по лицевому счёту за период, по договорам и месяцам.
date_from/date_to — даты в формате dd.MM.yyyy.
| Name | Required | Description | Default |
|---|---|---|---|
| date_to | Yes | ||
| date_from | Yes | ||
| personal_account | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It adds useful behavioral context by specifying the grouping dimensions (contracts and months) and the date format. However, it does not explicitly state that the operation is read-only, nor what response shape or error behavior to expect.
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: one sentence for purpose and one for date format, with no filler or redundant restatement of the tool name. Both sentences add value and the key detail about date format is placed directly after the purpose.
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 three-parameter read-oriented tool with no output schema and no annotations, the description is reasonably complete: it explains what is returned (fine detailization by contracts and months) and how to format dates. It stops short of describing the exact output fields or edge-case behavior, which would be needed for a perfect score.
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, but the description compensates by tying personal_account to the subject of the detailization and explicitly documenting date_from/date_to as dd.MM.yyyy. It does not clarify whether dates are inclusive or what format personal_account should take, but the main semantics are covered.
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 resource: a breakdown of penalties (пеней) for a personal account over a period, grouped by contracts and months. It distinguishes the tool's focus from general debt or bill tools, though it uses a noun phrase rather than an explicit verb and does not directly reference sibling alternatives.
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 intended use is implied: call this tool when fine/penalty detailization for a personal account over a date range is needed. However, it provides no explicit guidance about when not to use it or which sibling tool to prefer for related debt or bill information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_serviced_periodsB
Периоды обслуживания (даты начала/окончания) лицевого счёта или ИНН.
| Name | Required | Description | Default |
|---|---|---|---|
| pa_or_inn | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the transparency burden. It only names the returned data and gives no context about side effects, authorization, error behavior, or response format; the read-only nature is only inferable from the tool name.
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 compact noun phrase with no filler words; all included phrases ('service periods', 'start/end dates', 'personal account or INN') are informative. It is concise, but it is structured as a fragment rather than a sentence.
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 one-parameter retrieval tool with no output schema, the description supplies the essential return concept (start/end dates) and input semantics. It does not describe edge cases or the full response shape, but those are low-complexity gaps for 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?
With 0% schema description coverage, the description clarifies that the single required 'pa_or_inn' parameter accepts a personal account or INN. It adds real semantic value, though it does not give format examples or disambiguation rules.
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 names the resource ('service periods') and scopes it to a personal account or INN, and adds the data shape (start/end dates), so an agent can tell it apart from debt/bill/status siblings. It lacks an explicit verb, relying on the tool name 'get' for the action.
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?
Usage is implied: if the agent needs service periods for a personal account or INN, this is the tool. There is no explicit 'use this when...' or any mention of conditions/exclusions relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pingA
Проверка того, что сервер жив и подключён.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. 'Checking that the server is alive and connected' clearly conveys a read-only health check and implies no side effects. It is transparent enough for a zero-parameter ping tool, though it does not mention timeout or error 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 clear sentence with no filler or redundant wording. It front-loads the essential purpose and is appropriately sized for a trivial zero-argument tool.
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 ping/health-check tool with zero parameters and an output schema, the description provides everything needed to decide to invoke it and understand its function. No additional context is required.
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, so the schema is already complete. There is nothing for the description to add about parameters; the baseline of 4 applies because nothing is missing.
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 identifies the operation: checking that the server is alive and connected. This distinguishes it from the sibling tools, which are all contragent/debt/billing queries, so an agent can immediately recognize this as the liveness probe.
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 intended use is implied by the health-check description, but there is no explicit guidance about when to call it, when not to call it, or what to do based on the result. The sibling tools are unrelated enough that confusion is unlikely, which keeps this above 2.
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.
10 tool updates
v0.1.0- First observed
get_calculation_amount_type - First observed
get_contract - First observed
get_contragent_bills - First observed
get_contragent_debt - First observed
get_contragent_status - First observed
get_debt_by_email - First observed
get_debt_by_phone - First observed
get_fine_details - First observed
get_serviced_periods - First observed
ping
TDQS
Scored across 10 tools
There are several debt-related tools (get_contragent_debt, get_debt_by_phone, get_debt_by_email, get_calculation_amount_type, get_contract) whose outputs overlap in debt/penalty figures; descriptions clarify different lookup keys or levels, but an agent could still struggle to choose among them. ping and the document/period tools are clearly distinct.
All tools follow a get_ prefix and snake_case, and most use a readable get_<resource>_<detail> or get_<detail>_by_<identifier> pattern. The deviations are minor: ping has no get_, and names like get_calculation_amount_type are less intuitive than the rest.
Ten tools is a reasonable size for a debt/contract lookup server. Each tool covers a distinct query need without excessive redundancy or an overwhelming surface.
The set provides solid read-only coverage: contragent lookup, debt by multiple identifiers, bills, contracts, service periods, and fine details. A minor gap is the lack of a direct debt lookup by contragent UUID, which would require using an INN from get_contragent_status as a workaround.
Maintenance
Related MCP Connectors
Public Data Ukraine Mcp connects AI agents to real public APIs via MCP. Tools include
Let AI agents query data and act across all your business apps via MCP.
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceBridges Claude Code to the Rowan Rose CRM, translating MCP tool calls into REST API requests for contacts, cases, documents, and more.-
- AlicenseNot gradedqualityAmaintenanceEnables Claude to interact with Acumatica ERP through a remote MCP server with per-user OAuth, role-based access, and 44 tools for querying and managing ERP data.18Apache 2.0
- AlicenseBqualityBmaintenanceMCP server that enables Claude Code to access, monitor, and manage MikroTik RouterOS devices via its REST API, with 92 tools for read-only and optional write operations.92Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables Claude to read weclapp data such as customers, invoices, and articles via a secure MCP server.-