Click on "Install 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., "@ai-l1-support-agent Triage ticket #1024 and suggest next step from the knowledge base"
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.
Контролируемый AI-native процесс первой линии поддержки. Текущий статус:
этап 1: архитектура и доменные контракты — готово;
этап 2: MCP-инструменты и тестовые интеграции — готово;
этап 3: первичная классификация (triage), правила безопасности, ответы из KB и оценка качества — готово;
этап 4: LangGraph-оркестратор, контрольные точки и полный процесс обработки — готово;
этап 5: E2E-демонстрация, безопасная наблюдаемость и расширенная оценка качества — готово;
этап 6: формальный критерий качества, проверка стабильности и тестовая матрица Linux — готово;
этап 7: автономный wheel, CI и подготовка публичного репозитория — готово.
По умолчанию проект работает полностью локально: читает зафиксированный снимок тикетов,
пишет только в data/runtime/ и не изменяет публичный MockAPI.
Требования: Python 3.10–3.13 и uv.
uv sync --lockedЭто основной режим для проверки логики, демонстрации и разработки. Он читает зафиксированный
снимок заявок, не требует сети и сохраняет все изменения только в data/runtime/.
TICKET_SOURCE=fixture уже является безопасным значением по умолчанию.
# Обработать одну заявку из локального снимка
uv run support-agent-workflow poll --limit 1
# Прогнать пять изолированных сквозных сценариев
uv run support-agent-demo --run-id quick-startПовтор с тем же рабочим каталогом восстанавливает состояние из SQLite и не дублирует
побочные действия. Для полностью нового прогона используйте другой --run-id демонстрации
или задайте новые RUNTIME_PATH и SQLITE_PATH.
Этот режим подтверждает интеграцию с открытым API из задания. Агент получает настоящую заявку по сети, но ответы, статусы, Telegram-сообщения и GitHub Issues по-прежнему записывает только локально. Удалённая очередь не изменяется.
$env:TICKET_SOURCE = "remote"
$env:TICKETS_API_URL = "https://6a7ad74c8c69b3eb4a179621.mockapi.io/tickets/tickets"
$env:ALLOW_REMOTE_WRITES = "false"
$env:RUNTIME_PATH = "data/runtime/remote-quick-start"
$env:SQLITE_PATH = "data/runtime/remote-quick-start/agent.sqlite3"
uv run support-agent-workflow poll --limit 1Для следующего запуска в том же терминале можно вернуться к локальному снимку:
$env:TICKET_SOURCE = "fixture"RemoteTicketSource намеренно поддерживает только чтение. ALLOW_REMOTE_WRITES=false
зафиксирован как дополнительный предохранитель; удалённый адаптер записи в проекте вообще
не реализован. Локальный overlay не синхронизируется с MockAPI, поэтому состояние разных
экземпляров агента не является общим.
MockAPI является внешним сервисом. Если он или сеть недоступны, команда намеренно завершится
ошибкой ticket API is unavailable, не переключаясь незаметно на локальные данные. В таком
случае проверьте URL и повторите сетевой запуск позднее; автономный сценарий остаётся доступен.
uv run support-agent-mcpКоманда запускает MCP-сервер support-tools через stdio. Для локальной разработки .env
необязателен: безопасные значения уже являются значениями по умолчанию. Для изменения
настроек скопируйте .env.example в .env; секреты и рабочие файлы исключены из Git.
Related MCP server: helpdesk-mcp-server
Wheel содержит локальные тестовые заявки, набор оценочных сценариев, демонстрацию и
тестовую базу знаний, поэтому команды работают и вне исходного репозитория. Изменяемое
состояние создаётся в data/runtime/ текущего каталога или по путям из окружения.
uv build
uv venv .wheel-venv
uv pip install --python .wheel-venv/Scripts/python.exe dist/*.whl
.wheel-venv/Scripts/support-agent-eval.exe --runs 2Исходный архив и wheel собираются в dist/; каталог намеренно не хранится в Git.
Команда support-agent-workflow запускает LangGraph с сохраняемыми контрольными точками
поверх тех же сервисов, которые опубликованы как MCP-инструменты:
# Один тикет или вся очередь новых тикетов
uv run support-agent-workflow start 3
uv run support-agent-workflow poll --limit 10
# Состояние после рестарта процесса
uv run support-agent-workflow status 3
# Безопасная хронология метаданных контрольных точек и инструментов без содержимого заявки
uv run support-agent-workflow trace 3
# Возобновление ожидания пользователя или инженера
uv run support-agent-workflow user <ticket-id> "Уточнённые симптомы"
uv run support-agent-workflow engineer <ticket-id> "Подтверждённое решение" --author l2 --confirmedОдна заявка всегда использует идентификатор потока support-ticket:<ticket-id>.
Контрольные точки хранятся в SQLite, а все записи в заявки, Telegram, GitHub и черновики
дополнительно защищены стабильными ключами идемпотентности. Поэтому восстановление
контрольной точки и повтор узла не создают дубликаты побочных действий.
support-agent-demo запускает пять синтетических E2E-сценариев в отдельном каталоге,
не затрагивая обычный data/runtime/agent.sqlite3:
uv run support-agent-demo
uv run support-agent-demo --run-id interview-demoПокрыты ответ из KB, эскалация L2 и одноразовое решение, отчёт об ошибке и переиспользуемое
решение, уточнение пользователя с повторной классификацией, низкая уверенность и
safe_review. Завершённый запуск повторно читает сохранённый demo-report.json;
незавершённый каталог с тем же ID не перезаписывается. В отчёте есть фазы, количество
контрольных точек и событий аудита, но нет текстов заявок и содержимого вызовов инструментов.
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest --cov --cov-report=term-missing
uv run support-agent-eval --runs 3 --output data/runtime/evaluation.json
uv run support-agent-eval --case-id http-500-software-bugGitHub Actions проверяет форматирование, Ruff, строгий mypy, pytest с покрытием ветвей и стабильность тестового провайдера на Python 3.10 и 3.13. Отдельное задание собирает sdist/wheel, устанавливает wheel вне исходного репозитория и запускает оценку качества, демонстрацию и CLI процесса. Проверка через LM Studio не входит в CI, потому что требует локальную модель; её зафиксированный прогон описан ниже.
Тесты используют официальный MCP-клиент в памяти и отдельно запускают точку входа stdio.
Оценка качества прогоняет 20 подготовленных бизнес-сценариев классификации и решения через
выбранный LLM_PROVIDER, измеряет время каждого сценария и всего запуска; по умолчанию
используется воспроизводимый провайдер на основе правил.
Из 20 сценариев 13 помечены как safety_critical. Критерий качества выполнен, только если
доля успешных попыток не ниже 90%, все критические попытки успешны, ошибки провайдера и
схемы отсутствуют, а повторные запуски каждого сценария дают одинаковый смысловой
результат. --runs 3 проверяет не 20, а 60 попыток; хэш исходного набора сохраняется в
JSON-отчёте.
Первичная классификация возвращает строгий TriageDecision: достаточность и перечень
недостающих фактов, категорию, приоритет, маршрут, оценку уверенности (confidence),
извлечённые факты и флаги риска. После ответа
модели детерминированная политика отдельно проверяет:
недостаток фактов — запросить конкретное уточнение;
низкую уверенность при достаточных фактах — safe_review;
модельный priority — нормализовать независимой бизнес-политикой по явным признакам;
инъекцию инструкций — проигнорировать и отметить флагом;
лимит уточнений — передать в безопасную очередь исключений.
Поиск в KB выполняется до эскалации. Автоматический ответ разрешён только при совпадении
категории, порога релевантности и отсутствии exclusions статьи. Ответ состоит из текста
статьи и обязательной ссылки KB:<article_id>; свободной генерации решения нет.
Проверенные ответы пользователя не теряются после повторной классификации: они участвуют
в поиске и проверке применимости статьи, добавляются в выжимку для L2, отчёт об ошибке и
контекст будущего черновика статьи. Telegram-эскалация и GitHub Issue всегда содержат ссылку
на исходную заявку, построенную от настроенного TICKETS_API_URL.
Адаптер LM Studio уже реализован через совместимый с OpenAI строго структурированный ответ:
LLM_PROVIDER=lmstudio
LLM_BASE_URL=http://127.0.0.1:1234/v1
LLM_MODEL=google/gemma-4-12b-qat
LLM_API_KEY=
LLM_REASONING=noneПосле запуска локального сервера выбранную модель можно проверить командой
uv run support-agent-eval. google/gemma-4-12b-qat Q4_0 прошла текущий набор 20/20
за 74,9 секунды и E2E-демонстрацию 5/5 за 22,9 секунды при контексте 13 056 токенов.
Провайдер на основе правил остаётся безопасным значением по умолчанию для тестов и
воспроизводимой демонстрации. Подробнее:
проверка LM Studio.
Группа | Инструменты |
Заявки |
|
База знаний |
|
Эскалация |
|
Обратная связь |
|
Входные и выходные JSON Schema формируются MCP SDK из строгих Pydantic-моделей. Все
изменяющие инструменты требуют стабильный idempotency_key, журналируются в SQLite и
имеют соответствующие MCP annotations. knowledge_create_draft создаёт только черновик
со статусом pending_human_review; инструмента автоматической публикации намеренно нет.
TICKET_SOURCE=fixture — воспроизводимый режим по умолчанию.
TICKET_SOURCE=remote — чтение публичного MockAPI без права записи.
ALLOW_REMOTE_WRITES=false — зарезервированный явный предохранитель; текущий адаптер
вообще не реализует удалённые записи.
data/runtime/ — SQLite, локальные изменения, исходящие сообщения и тестовые Issues;
каталог исключён из Git.
data/knowledge_base/ — опубликованные тестовые статьи, которые входят в репозиторий.
data/fixtures/ — зафиксированные входные данные для тестов.
data/demo/ — пять синтетических заявок для изолированной E2E-демонстрации.
trace намеренно возвращает только метаданные. Полное состояние контрольной точки остаётся
локально в SQLite и должно защищаться как рабочие данные поддержки.
Проект распространяется по лицензии MIT. Правила безопасного сообщения об уязвимостях описаны в SECURITY.md.
Локальный снимок данных находится в data/fixtures/tickets.snapshot.json. Он используется
для воспроизводимых тестов; удалённый MockAPI рассматривается как источник только для чтения.
Add a mock user, L2 or developer response linked to the original ticket.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
| Name | Required | Description |
|---|---|---|
| event | Yes | |
| replayed | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and readOnlyHint=false, so mutability is clear. The description adds the 'mock' context and 'linked to original ticket', but does not disclose potential side effects, whether the ticket must exist, or behavior on duplicate idempotency keys beyond the annotation's implication.
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, front-loaded sentence with no unnecessary words. It immediately communicates the core 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 add operation, the description is minimally sufficient with annotations and schema covering idempotency and parameter details. However, it lacks guidance on prerequisites (e.g., whether the ticket must already exist) and does not clarify the difference from tickets_add_reply, making it a minimum viable description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only alludes to the author roles and linking to a ticket. It does not mention 'message', 'idempotency_key', or 'solution_confirmed', leaving the agent to rely solely on the schema. While the schema has title/enum/constraints, the description does not compensate for the low 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 clearly states the action ('Add') and the resource ('mock user, L2 or developer response linked to the original ticket'). This distinguishes the tool from siblings like feedback_list and tickets_add_reply by specifying the mock role context.
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 a use case: adding simulated feedback responses from user/L2/developer roles. However, it does not explicitly mention when to use this tool versus alternatives like tickets_add_reply, nor provide any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List mock user and engineer responses for a ticket in chronological order.
| Name | Required | Description | Default |
|---|---|---|---|
| ticket_id | Yes |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| events | Yes | |
| ticket_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint annotation, the description adds 'mock' and 'chronological order', which are useful behavioral traits. It doesn't cover edge cases like missing tickets, but annotations already establish safety, so the bar is met.
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 concise sentence of 12 words, front-loaded with the verb 'List', and every word adds value. No redundancy or unnecessary detail.
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-only list tool with only one parameter, an output schema, and readOnlyHint annotation, the description covers purpose, ordering, and data source (mock). Nothing critical 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 has one ticket_id parameter with 0% description coverage. The description's 'for a ticket' indirectly clarifies its purpose, but it doesn't add format or source details, leaving the schema param name to carry most of the meaning.
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 states a specific verb ('List'), resource ('mock user and engineer responses'), and scope ('for a ticket'), with ordering detail. This clearly distinguishes it from write siblings like feedback_add and tickets_add_reply.
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 phrase 'for a ticket' provides clear context for when to use this tool (viewing feedback on a specific ticket). However, it does not explicitly mention alternatives or when not to use it, so it misses the top tier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a linked mock GitHub Issue without inventing missing logs or context.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| issue_id | Yes | |
| replayed | Yes | |
| ticket_id | Yes | |
| issue_number | Yes | |
| idempotency_key | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (idempotentHint=true, destructiveHint=false), the description adds meaningful disclosure: the issue is a 'mock' entity and missing logs/context must not be fabricated. This is relevant behavioral context not captured in annotations or schema.
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?
A single 12-word sentence is perfectly concise and front-loads the core action. Every word earns its place; there is no filler or redundant restatement of 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?
The annotations and output schema cover safety, idempotency, and return shape, so the description can be minimal. However, it leaves unclear what 'linked' refers to and gives no context for selecting this over sibling tools, making it adequate but not fully 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?
The description provides almost no parameter-specific guidance; only the phrase about not inventing logs/context hints at optional fields. With schema description coverage at 0%, it does not compensate for the nine properties defined in the nested request object.
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 the specific verb 'Create' with a clear resource 'linked mock GitHub Issue', distinguishing this tool from sibling ticket management and feedback tools. The title 'Create a developer bug report' reinforces the action without ambiguity.
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 state when to use this tool instead of alternatives such as tickets_add_reply or feedback_add. It gives a constraint ('without inventing missing logs or context') but no explicit context or exclusions for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a local create/update draft that cannot bypass human review.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
| Name | Required | Description |
|---|---|---|
| path | Yes | |
| draft_id | Yes | |
| replayed | Yes | |
| ticket_id | Yes | |
| review_status | No | |
| idempotency_key | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds the valuable behavioral detail that the draft is local and cannot bypass human review, clarifying it will not directly publish or update knowledge articles.
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, front-loaded sentence with no redundant words. It conveys the core purpose and a critical constraint efficiently.
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?
Despite having a complex nested request with nine properties, the description offers no context about the draft lifecycle, how to fill the parameters, or what happens after creation. The 'local' and 'human review' hints are useful, but the description is far too minimal for the tool's 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?
Schema description coverage is 0%, but the description provides no information about the request object's fields such as ticket_id, solution_steps, recommended_action, or idempotency_key. The agent must rely solely on field names and constraints, which is insufficient for correct invocation.
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 creates a local create/update draft, distinguishing it from read-only siblings like knowledge_search and knowledge_get_article. The key constraint 'cannot bypass human review' makes the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'cannot bypass human review' implies the tool is for drafts that require approval, but the description does not explicitly state when to use it over alternatives or mention any exclusions. Usage context is only implied, not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one published knowledge article by its stable ID.
| Name | Required | Description | Default |
|---|---|---|---|
| article_id | Yes |
| Name | Required | Description |
|---|---|---|
| body | Yes | |
| path | Yes | |
| title | Yes | |
| category | Yes | |
| keywords | Yes | |
| article_id | Yes | |
| exclusions | No | |
| applicability | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares the operation as read-only, so the description need not restate that. It adds the valuable behavioral detail that only published articles are accessible and that the ID is stable, but it does not go further (e.g., error behavior, permissions). This is sufficient but not rich, similar to the get_calls example.
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 of nine words, perfectly front-loaded with the action and object. Every word adds value: 'published' and 'stable ID' are meaningful constraints. There is zero redundancy or waste.
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?
This is a simple one-parameter read operation with a provided output schema and read-only annotation. The description adequately captures the essential behavior (reading a specific published article by ID) and constraints. No additional return-value explanation is needed because the output schema exists. The tool is simple enough that the description 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 description coverage is 0%, so the description carries the full burden for parameter meaning. The description clarifies that 'article_id' is a 'stable ID', which helps distinguish it as an identifier rather than a search query. However, it lacks format examples or additional context beyond what the schema's name and length constraints already imply.
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 the specific verb 'Read' and identifies the resource as a 'knowledge article' with the constraints 'published' and 'by its stable ID'. This clearly distinguishes it from sibling tools like knowledge_search (which searches) and knowledge_create_draft (which creates).
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 used when you have the stable ID of a published article, but it does not explicitly mention when to use it over alternatives such as knowledge_search for discovery or knowledge_create_draft for creating. The usage context is clear but lacks explicit exclusions or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search published Markdown articles by title, keywords and body tokens.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| category | No |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| query | Yes | |
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only (readOnlyHint=true) and closed-world (openWorldHint=false). The description adds meaningful context by specifying that the search is limited to published articles and matches on title, keywords, and body tokens, which goes beyond the annotations and clarifies what the agent can 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 a single, tightly written sentence that immediately conveys the tool's purpose. No filler or redundant content, making it highly efficient 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 tool's simplicity, the presence of an output schema, and read-only annotations, the description is fairly complete. It covers the search scope (published articles, matching fields) but omits details like result ordering or pagination, which are likely covered by the output schema. Sufficient for a search tool of this 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?
The input schema has three parameters with 0% description coverage, so the description must compensate. It provides useful semantics for the 'query' parameter (searching by title, keywords, body tokens) but does not explain 'limit' or 'category'. This is partial compensation; the agent can infer limit/category defaults and enums from 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 'Search published Markdown articles by title, keywords and body tokens' clearly identifies the action (search), resource (published Markdown articles), and search scope. It distinguishes itself from sibling tools like knowledge_get_article, which retrieves a specific article, and knowledge_create_draft, which creates content.
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 finding articles but does not explicitly contrast it with alternatives such as knowledge_get_article or mention when to use search vs. retrieval. There is no 'when to use' or 'when not to use' guidance, leaving the context implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a concise L2 escalation into the mock Telegram outbox.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
| Name | Required | Description |
|---|---|---|
| replayed | Yes | |
| ticket_id | Yes | |
| message_id | Yes | |
| destination | Yes | |
| idempotency_key | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the useful context that this writes to a 'mock' outbox, indicating it's a simulated integration. Annotations already indicate idempotent and non-destructive, so the description adds the mock detail beyond structured data.
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 concise sentence, front-loaded with the action, 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 tool with a complex nested request object and minimal annotations, the description is too sparse. It doesn't explain the purpose of L2 escalation, the meaning of 'mock', or how the output is returned, leaving the agent to infer from field names alone.
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 zero description coverage, and the description mentions no parameter details. Field names like ticket_id and summary are self-explanatory, but the description fails to explain the request structure or semantics of idempotency_key, priority, or facts.
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 writes an L2 escalation to a mock Telegram outbox, with a specific verb ('Write') and resource ('Telegram outbox'). It distinguishes from sibling tools that manage tickets, knowledge, GitHub bugs, and feedback, as this is for Telegram notifications.
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 use this tool versus alternatives like tickets_add_reply or github_create_bug. The description implies use for L2 escalation but doesn't explicitly state prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a local mock reply and either wait for the user or close the ticket.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | ||
| ticket_id | Yes | ||
| close_ticket | No | ||
| idempotency_key | Yes |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| replayed | Yes | |
| ticket_id | Yes | |
| idempotency_key | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and destructiveHint=false. The description adds valuable context beyond annotations by clarifying that the reply is a 'local mock' and that it either waits for the user or closes the ticket. No contradictions with annotations.
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 is front-loaded and free of filler. Every word contributes to conveying the tool's purpose and behavior.
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 simple parameters, the description is mostly adequate. However, the lack of parameter-level guidance—especially for idempotency_key—and the ambiguous 'local mock' phrase leave room for misinterpretation about whether the reply is actually sent or only stored locally.
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 must compensate. It hints at the close_ticket behavior ('or close the ticket') and implicitly references message/ticket_id, but it completely omits idempotency_key. The required idempotency_key's purpose and constraints are left unexplained, which is a significant gap for a required parameter.
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 specific action ('Add a local mock reply') and resource ('to a ticket'), distinguishing it from sibling tools like tickets_list_new or tickets_change_status. The wait-or-close behavior further differentiates this tool's scope.
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 when replying to a ticket, but does not explicitly state when to use this tool versus alternatives such as tickets_change_status or tickets_update_classification. No exclusions or alternative references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change status in the local overlay; the public MockAPI remains untouched.
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| ticket_id | Yes | ||
| idempotency_key | Yes |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| replayed | Yes | |
| ticket_id | Yes | |
| idempotency_key | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint true and destructiveHint false. The description adds valuable context by specifying that the change occurs in the local overlay and that the public MockAPI is untouched, providing insight into the mutation's side effects. This goes beyond the annotations without contradicting them.
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 verb and resource. Every word earns its place, with no filler or repetition. The two clauses deliver the essential action and scope efficiently.
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 meaningful annotations, the description adds the key behavioral distinction (local overlay vs. public API) that is not captured elsewhere. It is sufficient for a simple mutation tool, though it could benefit from a brief note on when to use it or what the idempotency key is for.
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 only references 'status' indirectly via the action, providing no additional meaning for ticket_id or idempotency_key. The idempotency key's purpose and the expected format of ticket_id remain undocumented, leaving the agent to infer from parameter names alone.
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 specific action ('change status') and identifies the resource scope ('local overlay'), distinguishing it from sibling tools like tickets_update_classification (which changes classifications) and tickets_add_reply (which adds messages). The added clarification that the public MockAPI remains untouched further differentiates it from tools that affect the public API.
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 local status changes but does not explicitly state when to use this tool over alternatives or mention exclusions. It clarifies that the public API is unaffected, which gives some contextual guidance, but it lacks direct comparisons to siblings or explicit 'use this when' phrasing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one source ticket with local agent classification, replies and status overlay.
| Name | Required | Description | Default |
|---|---|---|---|
| ticket_id | Yes |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| replies | No | |
| subject | Yes | |
| requester | Yes | |
| ticket_id | Yes | |
| created_at | Yes | |
| updated_at | Yes | |
| description | Yes | |
| agent_category | No | |
| agent_priority | No | |
| source_category | Yes | |
| source_priority | Yes | |
| classification_confidence | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, covering the safety profile. The description adds context about the returned data (classification, replies, status overlay) but does not disclose other behavioral traits such as authorization requirements, rate limits, or the meaning of 'status overlay'. This is acceptable given the annotation coverage.
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, directly front-loaded with the verb and resource, and contains no filler. Every word adds meaningful detail.
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 a single required parameter, a read-only annotation, and an output schema present, the description is sufficient for basic use. It highlights the key components of the return value, though it does not explain any preconditions or edge cases. Given the simplicity of the tool, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. However, it does not explicitly describe the 'ticket_id' parameter beyond the schema's title and constraints. The phrase 'one source ticket' hints at the target but adds no meaningful semantics beyond the parameter name itself.
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 specific verb ('Get') and resource ('one source ticket'), and enumerates the included details (local agent classification, replies, status overlay). This clearly distinguishes it from sibling tools like tickets_list_new, which lists new tickets, and tickets_update_classification, which modifies.
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 a single existing ticket by ID, but does not explicitly state when to use it versus alternatives. No exclusions or alternative tool mentions are provided, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tickets whose effective status is Новая, oldest first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of new tickets to return. |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| tickets | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the read-only nature is disclosed. The description adds value beyond annotations by explaining the 'effective status' nuance and the 'oldest first' ordering, which provides useful behavioral context not present in the schema or annotations.
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 concise sentence with no redundant words. It front-loads the primary action and includes the key filter and ordering, making it highly scannable.
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-only list tool with an output schema, one optional parameter, and read-only annotations, the description provides all necessary context: what it lists, the filter, and the ordering. No critical gaps remain.
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% for the single parameter (limit), and the description adds no additional meaning beyond what the schema already states. The baseline of 3 applies because the schema carries the full semantic weight.
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 ('List'), resource ('tickets'), a precise filter ('effective status is Новая'), and ordering ('oldest first'). This clearly distinguishes it from siblings like tickets_get (which likely retrieves a single ticket) and mutation tools like tickets_change_status.
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 implies when to use this tool (when you need a list of new tickets), but it does not explicitly contrast it with alternatives or state when not to use it. The context is inferred from the description and sibling tool names, and there is no exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Persist agent classification locally without rewriting source labels.
| Name | Required | Description | Default |
|---|---|---|---|
| category | Yes | ||
| priority | Yes | ||
| ticket_id | Yes | ||
| confidence | Yes | ||
| idempotency_key | Yes |
| Name | Required | Description |
|---|---|---|
| category | Yes | |
| priority | Yes | |
| replayed | Yes | |
| ticket_id | Yes | |
| confidence | Yes | |
| idempotency_key | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover idempotency and non-destructiveness. The description adds useful behavioral context by specifying that persistence is local and does not rewrite source labels, which goes beyond the structured annotations. No contradiction detected.
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 that front-loads the action and key constraints. Every word earns its place, with no repetition of schema or annotation 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?
Given the schema has enums and annotations cover idempotency and safety, the description is adequate for a simple local persistence operation. However, it leaves out the purpose of idempotency_key and confidence, which an agent might need to invoke correctly in edge cases. Output schema exists, so return values need not be described.
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 provides no parameter-level detail. The enum values for category and priority give some implicit meaning, but confidence and idempotency_key are unexplained. The tool requires 5 parameters, so this is a significant gap that the description should have compensated for.
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 action (persist) and resource (agent classification), with an important qualifier (locally, without rewriting source labels) that distinguishes it from other ticket operations like tickets_change_status or tickets_add_reply.
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 when to use this tool (when you need to persist agent classification locally without altering source labels) but does not explicitly name alternatives or provide exclusion criteria. It gives contextual guidance but lacks explicit 'use instead of' statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct action within its domain: ticket management, knowledge lookup, notification, bug creation, and feedback. The descriptions clearly differentiate overlapping concepts like tickets_add_reply vs feedback_add and update_classification vs change_status.
Tools largely follow a domain_verb_noun pattern (tickets_add_reply, knowledge_get_article, github_create_bug). Minor exceptions like feedback_add/feedback_list (implicit object) and tickets_list_new (adjective instead of noun) create slight inconsistency but remain predictable.
The 12 tools cover a well-scoped support agent workflow: ticket triage, knowledge access, escalation, bug reporting, and feedback. The count is within the ideal range and each tool serves a clear purpose.
Core ticket operations are covered, but there is no way to list tickets by status other than 'new', which prevents the agent from resuming work on in-progress or waiting tickets. Knowledge draft creation exists without management (list/update), leaving an incomplete workflow.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Build and manage AI-native customer support agents from Claude or any MCP client.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/infernaltiger/ai-l1-support-agent'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
