Многоразовые роли и навыки SDLC-агентов на этапе сборки, предоставляемые через Model Context Protocol (MCP), для любого проекта, ориентированного на GitHub и использующего ИИ-ассистентов.
Это инструментарий времени сборки для того, как поставляется программное обеспечение — определения ролей агентов (Product Analyst, Solution Architect, Code Reviewer и т. д.) и общие чек-листы для ревью (ревью PR, ревью архитектуры, least-privilege для IAM, проектирование eval-сценариев, ...). Это не зависимость времени выполнения какого-либо продукта; потребляющим репозиториям это нужно только пока ИИ-агент кодинга выполняет работу по SDLC.
Этот пакет был извлечён (с историей git) из support-ticket-triage-assistant, где он был впервые создан и использовался как эталонная реализация. Теперь он также обслуживает supportrouter-aws. Извлечение устранило хрупкую связь между репозиториями, когда второй проект напрямую указывал на virtualenv и путь к папке первого проекта.
Related MCP server: speckitmcp
9 агентов: product-analyst, solution-architect, implementation-planner, test-eval-designer, code-reviewer, refactor-reviewer, documentation-agent, release-manager, dependency-upgrade-agent.
31 навык: общие SDLC-чек-листы (pr-code-review, architecture-review, github-backlog-creation, release-readiness-review, application-security-review, dependency-supply-chain-review, cicd-pipeline-review, api-contract-review, incident-postmortem-review, ...) плюс технические чек-листы для конкретных стеков (cdk-stack-review, cloud-infra-review, iam-least-privilege-review, bedrock-guardrails-review, dynamodb-data-model-review, fastapi-service-review, frontend-accessibility-review, llm-as-judge-rubric-design, eval-scenario-design, synthetic-data-design, knowledge-graph-modeling-review, graph-rag-retrieval-review, ...).
Полный индекс см. в enterprise_sdlc_mcp/catalog/manifest.yaml.
Каждый навык объявляет тег applies_when, чтобы потребляющий проект мог определить, какие из них действительно релевантны для него, независимо от фиксированного списка ролей агентов used_by:
Тег | Значение |
| Общие SDLC-рекомендации — релевантны для любого проекта независимо от стека. |
| Релевантно только если проект предоставляет API-поверхность (REST/GraphQL/RPC), независимо от фреймворка. |
| Релевантно только если у проекта есть фронтенд/UI-поверхность. |
| Релевантно только если проект предоставляет облачные/инфраструктурные ресурсы (любой провайдер). |
| Релевантно только если сам продукт использует LLM во время выполнения (а не просто создан с помощью ИИ-агента кодинга). |
| Релевантно только если основное хранилище данных проекта — property graph / knowledge graph. |
| Релевантно только если проект извлекает данные из графовой БД для обоснования ответов, сгенерированных LLM (нативный для графов поиск, в отличие от документного/векторного поиска). |
| Релевантно только после внедрения этой конкретной технологии — см. собственный файл навыка для примечания «применяется только если/когда внедрено». |
list_skills() возвращает applies_when для каждой записи, чтобы инструменты (или агент) могли фильтровать то, что важно для данного проекта.
Каждый агент также объявляет машиночитаемый блок permissions — структурированное дополнение к разделу «Code-Modify Permission» в его собственном markdown — с уровнем code_modify (none / scoped / conditional) и списком разрешённых write_paths. list_agents() возвращает это, чтобы инструменты (pre-merge hook, CI-гейт) могли проверить фактически изменённые файлы PR на соответствие тому, что должна была затрагивать авторская роль, вместо того чтобы полагаться на чтение прозы. Передайте manifest_path в list_agents(), чтобы получить write_paths, разрешённые относительно реального проекта, а не сырые плейсхолдеры {{project.*}}.
Markdown каталога использует плейсхолдеры {{project.*}}, которые разрешаются во время обслуживания из собственного манифеста sdlc.project.yaml каждого потребляющего репозитория — детерминированная подстановка строк, без участия LLM. См. enterprise_sdlc_mcp/catalog/manifest_keys.yaml для полного, протестированного справочника всех ключей, которые может использовать каталог (какие ключи обязательны для любого проекта, а какие нужны только для навыка с тегом конкретного стека).
Предназначен для установки в режиме editable, из локального соседнего checkout, в собственный virtualenv каждого потребляющего проекта — никогда не ссылаться на другие репозитории по пути.
# from the consuming project's own repo, with its own .venv active
git clone https://github.com/raghuram-chittibomma/enterprise-sdlc-mcp.git ../enterprise-sdlc-mcp
pip install -e ../enterprise-sdlc-mcpНачинаете новый проект? Скопируйте templates/new-project/ в корень репозитория вместо того, чтобы собирать это вручную — он поставляется с заполненным sdlc.project.yaml, AGENTS.md, .cursor/mcp.json, скелетом docs/00_project–docs/03_operations, на который указывает каждый ключ основного документа, заглушкой оверлея .skills/ и шаблонами PR/issue + CI workflow в .github/. Это та же структура папок, к которой вручную пришли support-ticket-triage-assistant и supportrouter-aws, теперь закреплённая, чтобы новый репозиторий получал её бесплатно. См. templates/new-project/README.md для чек-листа.
Добавляете это в существующий репозиторий? Добавьте манифест sdlc.project.yaml в корень потребляющего репозитория (см. tests/fixtures/sdlc.project.yaml для примера формы) и включите сервер в .cursor/mcp.json потребляющего репозитория:
{
"mcpServers": {
"enterprise-sdlc": {
"command": "C:\\absolute\\path\\to\\consuming-project\\.venv\\Scripts\\python.exe",
"args": ["-m", "enterprise_sdlc_mcp.server"],
"env": {
"SDLC_PROJECT_MANIFEST": "C:\\absolute\\path\\to\\consuming-project\\sdlc.project.yaml"
}
}
}
}Используйте абсолютные пути как для command, так и для SDLC_PROJECT_MANIFEST. Относительный command (например, .venv/Scripts/python.exe) ненадёжно разрешается относительно корня рабочей области в Cursor на Windows — он может молча откатиться к глобальному интерпретатору из PATH, на котором этот пакет не установлен, и завершиться с ModuleNotFoundError. Абсолютные пути полностью устраняют эту неоднозначность. (На Linux/macOS используйте .venv/bin/python; та же оговорка об относительных путях может не применяться, но абсолютные пути всё равно безопаснее по умолчанию.)
Никаких трюков с PYTHONPATH не нужно, как только пакет установлен через pip в собственный venv этого проекта — просто укажите command на интерпретатор этого venv.
Уже установили это где-то и просто хотите получить новую версию? См. ROLLOUT.md для чек-листа обновления, а не повторяйте первичную настройку.
Ключи sdlc.project.yaml, используемые основными (always-уровня) агентами/навыками — определите их независимо от стека:
display_name, repo_root, docs.architecture, docs.data_model, docs.test_strategy, docs.product_brief, docs.orchestrator_brief, docs.project_charter, docs.release_notes, docs.runbook, paths.source, paths.tests, paths.evals, paths.project_skills, milestone.current, extensions.
Несколько ключей являются условными — нужны только если вы вызываете конкретный навык с тегом стека, который их читает (например, paths.infra для cdk-stack-review, docs.eval_strategy для llm-as-judge-rubric-design). См. enterprise_sdlc_mcp/catalog/manifest_keys.yaml для полного, протестированного списка с описаниями и указанием, к какому именно навыку относится каждый условный ключ.
Нерезрешённый плейсхолдер — отсутствующий ключ манифеста, на который ссылается навык, который вы действительно вызываете, — это реальный пробел: он пропускает буквальный текст {{project.x}} в разрешённый вывод вместо того, чтобы громко завершиться ошибкой. Вызовите инструмент validate_manifest для вашего собственного sdlc.project.yaml, чтобы проверить, какие основные/условные ключи отсутствуют, до того как это произойдёт. tests/test_manifest_keys.py отдельно защищает от изменений каталога, вводящих недокументированный ключ.
Инструмент | Описание |
| ID агентов каталога, заголовки, исходный файл и |
| Разрешённый markdown роли агента для проекта |
| ID навыков каталога, заголовки и теги |
| Разрешённый чек-лист навыка для проекта |
| Доменные навыки из собственного пути оверлея проекта |
| Чтение локального файла навыка-оверлея проекта |
| Разобранный манифест проекта |
| Сообщает, какие основные/условные ключи |
Промпт | Использование |
| Запуск субагента Code Reviewer с разрешённой ролью + навыком |
| Запуск прохода ревью Solution Architect / Refactor Reviewer |
| Общий: запуск любого ID агента с любым списком ID навыков через запятую и свободным текстовым контекстом — используйте это вместо добавления новой жёстко заданной функции промпта для каждой пары |
Ресурсы также доступны по адресам enterprise-sdlc://catalog/manifest, enterprise-sdlc://agents/{id} и enterprise-sdlc://skills/{id}.
В MCP нет понятия хуков — сервер не может регистрировать перехватчики жизненного цикла так, как он регистрирует инструменты/промпты/ресурсы (см. .cursor/hooks.json для того, чем на самом деле являются хуки Cursor: локальные скрипты, запускаемые по событиям beforeShellExecution/afterFileEdit/и т. д., распространяемые через систему контроля версий, MDM или панель управления командой Enterprise — никогда через MCP).
Этот репозиторий поставляет один хук уровня проекта — в .cursor/hooks.json (и продублированный в templates/new-project/.cursor/): beforeShellExecution помечает gh pr merge и запрашивает подтверждение, что обязательное независимое ревью (get_agent("code-reviewer") + get_skill("pr-code-review")) действительно состоялось, поскольку этот шаг в противном случае обеспечивается только тем, кто помнит прочитать AGENTS.md/этот README. Это напоминание, а не жёсткая блокировка — он не может проверить, что ревью реально выполнялось, только спросить.
Это намеренно единственный хук, поставляемый здесь. Более широкие защитные хуки (защита от деструктивных git-команд, защита от опасных shell-команд, защита от утечки секретов) — хорошая идея, но они относятся к уровню пользователя (~/.cursor/hooks.json), а не к уровню проекта — это личные страховочные сети, которые должны действовать во всех репозиториях, с которыми вы работаете, а не то, во что каждый проект-потребитель должен отдельно opt-in.
pip install -e ".[dev]"
ruff check .
pytestЗакрыт пробел в покрытии, обнаруженный при онбординге первого проекта-потребителя graph/Graph-RAG: в каталоге не было ничего, что рассматривало бы моделирование property-graph данных или нативные для графа способы извлечения, хотя postgresql-schema-review/dynamodb-data-model-review покрывают аналогичное для своих стеков.
Добавлен knowledge-graph-modeling-review — минимальность сущностей/связей, отсутствие сохраняемых производных связей (аналог избегания избыточных колонок в моделировании графа), стратегия идентичности на основе natural key, поля происхождения данных и документация кардинальности/направленности. Используется Solution Architect; тег graph.
Добавлен graph-rag-retrieval-review — ограничения глубины обхода/разветвления, цитируемые идентификаторы извлечённых путей, валидация динамически генерируемых запросов (например, text-to-Cypher) перед выполнением, а также жёсткое правило, что сгенерированные ответы утверждают только те связи, которые реально присутствуют в извлечённом подграфе. Дополняет (не заменяет) rag-retrieval-design-review — так же, как fastapi-service-review дополняет api-contract-review. Используется Solution Architect; тег graph-rag.
Добавлены теги graph и graph-rag в таблицу тегов applies_when каталога.
Новый агент не добавлен — оба пробела закрываются чек-листами для существующей роли Solution Architect, а не отсутствующей ролью.
Добавлен первый Cursor-хук в этот репозиторий после установления (см. раздел «Hooks» выше), что MCP и хуки — это разные механизмы: сервер каталога не может передать определения хуков клиенту, поэтому это должно было поставляться как реальный .cursor/hooks.json, а не как новый код MCP-сервера.
Добавлены .cursor/hooks.json + .cursor/hooks/pr_merge_gate.py: хук beforeShellExecution, который запрашивает подтверждение перед выполнением gh pr merge, напоминая тому, кто выполняет merge, что требование независимого ревью (get_agent("code-reviewer") + get_skill("pr-code-review")) уже должно быть выполнено. Продублирован в templates/new-project/.cursor/, чтобы новые репозитории-потребители получали его бесплатно.
Добавлен tests/test_hooks.py, который запускает обе копии скрипта хука как реальные подпроцессы (соответствуя собственному контракту Cursor «JSON через stdin/stdout») и проверяет, что hooks.json указывает на реально существующий скрипт.
Также исправлены два пункта списка, отображавшихся пустыми, появившиеся в документации каркаса 0.6.0 (пункт нумерованного/маркированного списка, всё содержимое которого было HTML-комментарием, отображался на GitHub как пустой маркер списка) в AGENTS.md, PROJECT_CHARTER.md и AI_ORCHESTRATOR_BRIEF.md.
Закрыт пробел «создания каркаса нового проекта»: раньше нигде не было зафиксировано, как должна выглядеть структура папок нового репозитория-потребителя, поэтому validate_manifest мог сообщить, что манифест полностью валиден, в то время как каждый объявленный в нём путь docs.* указывал на файл, который никогда не был создан.
Добавлен templates/new-project/ — стартовый набор, который новый репозиторий копирует целиком: заполненный sdlc.project.yaml (основные ключи предзаполнены, условные ключи закомментированы с пояснениями), AGENTS.md, .cursor/mcp.json, скелет docs/00_project–docs/03_operations (по одному стартовому файлу на каждый основной ключ docs.*, плюс примечание о конвенции ADR в docs/01_architecture/DECISIONS/), заглушка проектного оверлея .skills/ и шаблоны .github/ (шаблон PR, шаблоны issue story/feature_task/bug_report, соответствующие иерархии Story→Task из навыка github-backlog-creation, и CI-воркфлоу ruff+pytest).
Это кодифицирует, а не изобретает конвенцию: она совпадает со структурой папок, к которой support-ticket-triage-assistant и supportrouter-aws уже пришли вручную — разница в том, что третьему проекту больше не придётся восстанавливать её методом обратного проектирования из существующего потребителя.
Добавлен tests/test_new_project_template.py, который валит CI, если поставляемый шаблон когда-либо отклонится от контракта основных ключей из manifest_keys.yaml, или если путь docs.* в манифесте шаблона перестанет указывать на реальный файл в каркасе.
Обновлён раздел «Установка в проект-потребитель»: новые проекты теперь сначала направляются к каркасу, а затем к ручным шагам первичной настройки.
Учтена обратная связь от внешнего ревью по двум наиболее приоритетным оставшимся пробелам: в основном навыке ревью PR не было реальной строгости ревью, а разрешения на изменение кода существовали только в виде прозы.
Переписан pr-code-review.md с чек-листа соответствия процессу из 6 пунктов на содержательное ревью корректности: модель серьёзности Blocker/Major/Minor, обязательное правило доказательств (цитировать файл+строку, приводить фрагмент проблемного кода — неподтверждённое утверждение не является замечанием), чек-лист корректности (крайние случаи, обработка ошибок, конкурентность, освобождение ресурсов, обработка сбоев внешних вызовов) и явный ## Output Format с всегда отображаемым путём «None.», чтобы чистый PR фиксировался как реальный результат, а не подразумевался молчанием. Прежний чек-лист процесса сохранён отдельным разделом.
Обновлены Outputs/Allowed Actions в code-reviewer.md в соответствии с этим: замечания помечаются серьёзностью с цитируемыми доказательствами, а вердикт (Approve/Request Changes) всегда явный.
Добавлен структурированный блок permissions (code_modify: none/scoped/conditional, плюс allowlist write_paths) каждому агенту в manifest.yaml — наряду с, а не вместо, существующего прозаического раздела «Code-Modify Permission» каждого агента. list_agents() теперь возвращает его и может разрешать write_paths относительно реального манифеста проекта, если он передан, чтобы CI-гейт или pre-merge хук могли сверять изменённые файлы PR с тем, к чему реально должна прикасаться авторская роль.
Добавлен test_every_agent_declares_well_formed_permissions в tests/test_catalog_consistency.py, проверяющий форму code_modify/write_paths (например, у none должен быть пустой allowlist; у scoped/conditional — непустой).
Намеренно не распространяли конвенцию серьёзности/доказательств/формата вывода на остальные 15+ навыков ревью — пока ограничились отмеченным наиболее приоритетным файлом; стоит вернуться к этому отдельным проходом.
Завершает пункты P2 дорожной карты ужесточения плюс два ранее незапланированных пункта пробелов.
Добавлен dependency-upgrade-agent — 9-я роль агента, которая планирует и выполняет обновления зависимостей/версий рантайма как отдельный отслеживаемый рабочий процесс (отличается от refactor-reviewer, который сфокусирован на структуре, и от dependency-supply-chain-review, который является чек-листом ревью, а не исполнительной ролью).
Добавлены incident-postmortem-review (безобвинительные постмортемы, первопричина против сопутствующих факторов, отслеживаемые follow-up), frontend-accessibility-review (управляемость с клавиатуры, alt-текст, контраст, воспринимаемое скринридером состояние) и cloud-infra-review (вендор-нейтральный инфраструктурный базовый уровень поверх AWS-специфичного cdk-stack-review, который теперь также помечен тегом infra).
Добавлен инструмент validate_manifest, который сообщает, каких основных/условных ключей {{project.*}} не хватает в собственном манифесте проекта, вместо того чтобы обнаруживать пробел только когда плейсхолдер протекает в живой промпт.
Добавлен универсальный промпт launch_role (id агента + разделённые запятыми id навыков + свободный текстовый контекст), чтобы новые пары агент/навык не требовали новых захардкоженных функций промптов в server.py. Два существующих удобных промпта не изменены.
Добавлен tests/test_catalog_consistency.py, который валит CI, если список used_by навыка в manifest.yaml и его собственная строка «Used by:» в markdown когда-либо разойдутся, или если used_by ссылается на несуществующий id агента.
Добавлены теги applies_when: frontend и infra.
Добавлен ROLLOUT.md — версионно-независимый чек-лист для обновления установки enterprise-sdlc-mcp в репозитории-потребителе (или онбординга нового), поскольку этот шаг раньше нигде не был задокументирован.
Закрыты самые крупные пробелы покрытия, выявленные в ревью ужесточения — области, релевантные практически любому проекту-потребителю, в отличие от AWS/LLM-специфичных навыков, уже присутствующих в каталоге.
Добавлен application-security-review — облачно/стек-агностичный чек-лист секретов, валидации ввода, аутентификации/авторизации и утечек ошибок (дополняет AWS-специфичные iam-least-privilege-review / bedrock-guardrails-review).
Добавлен dependency-supply-chain-review — пининг lockfile, триаж CVE, лицензионная соответствие и ревью PR от Dependabot/Renovate. Раньше ни один навык этого не покрывал.
Добавлен cicd-pipeline-review — вендор-нейтральный чек-лист здоровья пайплайна (обязательные проверки, секреты в CI, кэширование, обработка флаки-проверок), независимый от AWS-специфичного инфраструктурного фокуса cdk-stack-review.
Добавлен api-contract-review — универсальный чек-лист контракта REST/GraphQL, не привязанный к фреймворку; fastapi-service-review теперь помечен как его FastAPI-специфичное дополнение (applies_when: [fastapi, api]).
Все четыре используются существующими агентами Solution Architect и Code Reviewer (плюс Release Manager для cicd-pipeline-review) — новая роль агента не добавлена.
Добавлен тег applies_when: api для навыков, которые применимы только когда проект предоставляет API-поверхность.
Проход ужесточения, сфокусированный на том, чтобы каталог оставался по-настоящему переиспользуемым для несвязанных проектов, а не только для двух текущих потребителей. Никакие id агентов/навыков, пути файлов или ключи манифеста не были удалены или переименованы — существующие репозитории-потребители не затронуты обновлением.
Удалены детали, специфичные для проекта-источника (доменный язык support-ticket-triage, захардкоженные ссылки ADR-004/ADR-005) из dynamodb-data-model-review, iam-least-privilege-review, eval-scenario-design, architecture-review, synthetic-data-design, observability-dashboard-review, bedrock-guardrails-review, cdk-stack-review, llm-as-judge-rubric-design и prompt-caching-review, чтобы они читались как по-настоящему универсальные (или по-настоящему универсальные для своего стека) рекомендации, а не как архитектура одного проекта, поданная как универсальное правило.
«Main Orchestrator» — ранее неопределённый, предполагаемый существующим актор, упоминавшийся в 7 файлах агентов/навыков — обобщён до «координирующего агента (или человека, ведущего сессию)».
Каждому навыку в manifest.yaml добавлен тег applies_when (always или тег стека, например aws / dynamodb / bedrock / langgraph / rag / fastapi / postgresql / llm-product), теперь возвращаемый list_skills().
Полный контракт плейсхолдеров {{project.*}} задокументирован в catalog/manifest_keys.yaml (обязательные против условных ключей и какой навык требует каждый условный).
tests/fixtures/sdlc.project.yaml расширен для определения каждого документированного ключа, и добавлен tests/test_manifest_keys.py, который валит CI, если файл каталога когда-либо ссылается на недокументированный плейсхолдер или если любой файл каталога не резолвится чисто против фикстурного манифеста.
MIT — см. LICENSE.
Return resolved agent role markdown for the given project manifest.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | ||
| manifest_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It hints at processing with 'resolved' but does not disclose side effects, permissions, error behavior, or the optional manifest_path behavior. There is no contradiction with annotations since none exist.
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 sentence with no redundant wording, efficiently conveying the core action and result. It is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks context about what 'resolved' means, the relationship between agent_id and manifest_path, and when to use this tool. The output schema covers return structure, but key selection and behavioral information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain either parameter. While the schema defines agent_id as required and manifest_path as optional, the description's reference to 'given project manifest' is ambiguous relative to optional manifest_path. No additional parameter semantics are provided.
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 ('Return') and identifies the resource ('resolved agent role markdown') and context ('for the given project manifest'). This distinguishes it from sibling listing tools like list_agents, though it does not explicitly name 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?
No guidance is provided on when to use this tool versus siblings such as list_agents or get_project_manifest. The description only states what it returns, not the circumstances for its use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return parsed project manifest used for placeholder resolution.
| Name | Required | Description | Default |
|---|---|---|---|
| manifest_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It does not state whether the operation is read-only, what happens if the manifest path is invalid, or whether side effects exist. The word 'Return' suggests safety but is not explicit.
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 sentence efficiently conveys the tool's purpose, with the verb and resource front-loaded. 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?
Despite having an output schema, the description fails to explain the optional parameter's behavior or any error handling, making it incomplete for an agent to invoke the tool correctly without guessing.
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. However, it does not mention the 'manifest_path' parameter, what it controls, or what happens when it is null. The parameter name is somewhat self-explanatory, but the description adds no meaningful value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a parsed project manifest used for placeholder resolution. This is a specific verb+resource and naturally distinguishes from sibling tools that focus on agents, skills, and project skills.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance about when to use this tool versus alternatives. It implies a purpose (placeholder resolution) but lacks any statement of context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a project-local overlay skill (domain-specific checklists).
| Name | Required | Description | Default |
|---|---|---|---|
| manifest_path | No | ||
| skill_filename | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. The 'Read' verb clearly signals a non-mutating operation, but it does not disclose behavior on missing files, whether the overlay merges with global skills, or error conditions. It is minimal yet acceptable for a simple read tool.
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 sentence, front-loaded with the action verb, with no redundant or extraneous content. Every word contributes to 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?
While the tool is simple and an output schema exists, the description is incomplete for invocation because it does not explain the parameters at all, especially manifest_path. This leaves a critical gap in the agent's ability to use 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?
Schema description coverage is 0%, and the description provides zero semantic support for the parameters (skill_filename, manifest_path). It mentions neither parameter nor hints at their roles, so the agent cannot infer meaning beyond the property names themselves.
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 ('Read') and resource ('project-local overlay skill') with a clarifying parenthetical about domain-specific checklists. The 'project-local' qualifier distinguishes it from sibling get_skill, making 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 description implies its use for project-local skills, but it does not explicitly contrast with get_skill or provide when-not-to-use guidance. It lacks direct alternatives or exclusions, though the intent is inferable from the naming.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return resolved skill checklist markdown for the given project manifest.
| Name | Required | Description | Default |
|---|---|---|---|
| skill_id | Yes | ||
| manifest_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It only states the return value and offers no insight into side effects, error conditions, permissions, or the meaning of 'resolved'. As a read operation, it fails to explicitly state that it is non-mutating or what inputs affect the resolution.
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, well-structured sentence that immediately states the action and object. It contains no filler or redundancy, and all words contribute to understanding the tool's 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?
While the output schema exists and covers return value structure, the description lacks essential context about how the skill_id and manifest_path interact, what resolution entails, and when to choose this over the many sibling tools. The tool is simple, but the description leaves notable gaps in operational context.
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% and the description does not explain either parameter. 'skill_id' is never mentioned, and 'manifest_path' is only alluded to via 'for the given project manifest'. The description fails to compensate for the schema's lack of documentation, leaving the agent to infer parameter purposes from 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 uses a specific verb ('Return') and identifies the resource ('resolved skill checklist markdown') and context ('for the given project manifest'). This makes the tool's purpose clear and distinguishes it from siblings like list_skills or get_project_manifest, though it doesn't explicitly contrast with get_project_skill.
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 usage context is provided. The description does not mention when to use this tool versus alternatives such as get_project_skill or list_project_skills, nor does it state any prerequisites or exclusions. The implied use case (need a resolved checklist) is present but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List enterprise catalog build-time agent roles.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. The verb 'List' clearly conveys a read-only operation, but no additional behavioral context such as return format, pagination, or authorization is disclosed. The description is minimal, providing only the basic action and resource.
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 that is immediately understandable. It is front-loaded with the verb and resource, and contains no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with zero parameters and an output schema available, the description is sufficient to understand the tool's purpose. The output schema covers return values, and the simple nature of the operation does not require extensive context. Minor gaps exist in usage guidance but that is addressed separately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100%, so there are no parameter details to clarify. The description adds context about the type of agents listed, which is meaningful. Baseline for 0 params is 4, and the description does not detract from that.
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' with a clear resource 'enterprise catalog build-time agent roles', distinguishing it from sibling tools like get_agent (singular) and list_skills (different resource). The scope is well-defined.
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 listing all agent roles, but it does not explicitly mention when to use this tool versus alternatives such as get_agent for a specific agent. No when-not-to-use or alternative guidance is provided, leaving the guidance 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.
List markdown skill filenames in the project overlay (.skills/ by default).
| Name | Required | Description | Default |
|---|---|---|---|
| manifest_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does state that it lists filenames only (not contents) and indicates the default path, but it does not mention edge cases like missing manifests, recursion, or whether only .md files are returned. For a simple read-only list tool, this is minimally adequate.
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, front-loaded with the action and resource, and contains no filler. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and there is only one optional parameter, the description covers the core purpose and scope. However, it lacks explicit usage guidance relative to sibling tools and doesn't fully explain the manifest_path parameter, so it is not complete enough for seamless tool selection in a broader context.
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 one parameter (manifest_path) with no description and 0% schema coverage. The description indirectly explains the default behavior of the parameter ('.skills/ by default') but does not explicitly state that manifest_path overrides this default. This adds some meaning but leaves the parameter's role implicit.
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') and resource ('markdown skill filenames in the project overlay'), clearly distinguishing it from siblings like list_skills or get_skill by scoping to the project overlay. The default path (.skills/) adds helpful specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear that this tool operates on the project overlay, which implies a distinction from global skill listing. However, it does not explicitly state when to use this over list_skills or when not to use it, and no alternative tools are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List enterprise catalog SDLC skills/checklists.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It implies a read-only operation via 'List' but does not state whether it returns all items, supports pagination, or any side effects. This is minimal but not misleading, so a 2 is appropriate.
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 that front-loads the verb and resource. It contains no fluff or redundant information, earning a perfect score for conciseness.
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 tool is simple (no parameters, straightforward list operation) and an output schema exists, so detailed return value explanation is unnecessary. The phrase 'enterprise catalog' provides essential scope context relative to sibling tools, making the description complete enough for this use case.
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 parameters, so there is no parameter information to add. Per the rubric, a baseline of 4 applies for tools with no parameters, as the description cannot add value beyond what the schema already communicates.
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 specifies the action ('List') and the resource ('enterprise catalog SDLC skills/checklists'). It distinguishes itself from sibling tools like list_project_skills by emphasizing 'enterprise catalog', indicating a global scope rather than project-specific.
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 by the phrase 'enterprise catalog' versus project-specific skills, but there is no explicit guidance on when to use this tool instead of alternatives like list_project_skills or get_skill. No when-to-use or when-not-to-use instructions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_agentget_project_manifestget_project_skillget_skilllist_agentslist_project_skillslist_skillsScored across 7 tools
Each tool targets a distinct resource (catalog agents, catalog skills, project skills, manifest), but list_skills vs list_project_skills and get_skill vs get_project_skill could be confused if descriptions are not read closely. The clear qualifiers reduce ambiguity.
All tools follow the consistent list_<plural>/get_<singular> pattern, with project-scoped variants prefixed by project_. This is a uniform, predictable naming convention.
7 tools is well-scoped for a read-only catalog server covering agents, skills, project overlays, and manifest resolution. No tool feels redundant or missing.
The tool surface covers the full lifecycle for this domain: listing and getting catalog agents, catalog skills, project-local skills, plus the manifest. No obvious dead ends for the server's stated purpose.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Team docs served to AI agents over MCP - search, Markdown reads, version pinning, read audit.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Roadmap, tasks, releases and user feedback your coding agent reads and writes over MCP.
