ss-tools/.ai/reports/axiom_mcp_tools_evaluation.md

Axiom MCP Tools Evaluation Report

Общее резюме (Executive Summary)

В ходе тестирования поверхности Axiom MCP-инструментов были проверены основные категории: Query/Search, Semantic Health & Audit, AST/Semantic Patching, Workspace Management и Validation/Command execution. Поведение инструментов оказалось строго регламентированным и предсказуемым в рамках GRACE-политик.

Самые сильные стороны:

1. Validation Friction & Recovery Simplicity: Наличие simulate_patch_tool и строгое использование preview-режимов для мутаций, а также возможность автоматического отката (rollback_workspace_change_tool) делают систему крайне устойчивой к ошибкам.
2. Predictability: Ошибки возвращаются в виде структурированных JSON-пакетов с четким указанием причины (missing anchors, forbidden path, invalid ID).

Самые проблемные места (Ограничения):

1. Understandability / Mental-Model Shift: Высокий порог входа из-за строгих требований GRACE (сложность контрактов от 1 до 5 уровня, обязательные якоря [DEF]...[/DEF]). Привычные паттерны (shell writes) заблокированы.
2. Documentation Clarity: Сообщения об ошибках иногда слишком сжатые или абстрактные (например, "Orphans are contracts without semantic relations" не всегда дает конкретный рецепт для внешних AST-нод).

---

Таблица оценок инструментов (Scale 1-5, где 5 - отлично)

Tool Category	Tools Evaluated	Understandability	Predictability	Mental-Model Shift	Consistency	Doc Clarity	Error Quality	Validation Friction	Recovery Simplicity
Query & Semantic Search	search_contracts, find_contract, query_workspace_semantics, get_semantic_context	4	5	3	5	4	5	5 (Low)	N/A (Read-only)
Audit & Health	workspace_semantic_health, audit_contracts, audit_belief_protocol, diff_contract_semantics	4	5	3	5	4	4	4 (Low)	N/A (Read-only)
AST & Semantic Mutators	patch_contract, guarded_patch_contract, wrap_node_in_contract, rename_semantic_tag	3	4	2 (High shift)	5	4	4	2 (High - strict)	5 (Easy undo)
Workspace & File Ops	create_workspace_file, patch_workspace_file, manage_workspace_path, scaffold_workspace_module	5	5	4	5	5	5	3 (Moderate)	5
Validation & Recovery	run_workspace_command, summarize_workspace_change, rollback_workspace_change, rebuild_workspace_semantic_index	4	5	5 (Native)	5	5	5	5 (Low)	5

---

Детализированные заметки по категориям

1. Read / Search / Audit (Read-Only Tools)

• Фактическое поведение: Быстрое извлечение связей контрактов и AST-деревьев. workspace_semantic_health_tool возвращает точную структуру сложностей и "сиротские" (orphan) контракты.
• Ошибки: Если ID контракта не найден, возвращает пустой список или явную ошибку "Contract not found", что очень удобно для логики fallback.
• Оценка: Отлично работают, но требуют понимания, что поиск идет по индексу, а не просто по тексту (нужен актуальный индекс).

2. Mutation & Patching (Dangerous Tools)

• Фактическое поведение: Перед мутациями обязательно нужно понимать контекст (согласно Mental-Model Shift). Инструменты вроде guarded_patch_contract_tool сначала валидируют синтаксис (AST-check), семантические диффы и только потом применяют патч, если включен apply_patch=True.
• Строгость валидации: Крайне высокая. Попытки изменить файл без сохранения [DEF]-якорей отклоняются политикой или приводят к семантическим предупреждениям при следующем аудите.
• Recovery: Любая успешная мутация записывается в checkpoint (.axiom/checkpoints). Отмена через rollback_workspace_change_tool происходит атомарно.

3. Command Execution & Policy

• Фактическое поведение: run_workspace_command_tool работает в песочнице (bwrap). Запись вне .axiom/temp успешно пресекается политикой (Read-Only shell).
• Ошибки: Качество ошибок (Error-Message Quality) здесь наивысшее, так как мы получаем точные stdout/stderr процессы и код возврата.

Вывод

Поверхность Axiom MCP спроектирована с приоритетом на восстанавливаемость (Recovery) и предсказуемость (Predictability). Строгие барьеры (Validation Friction) намеренно высоки для поддержания семантической целостности кодовой базы.