Scaffold a new MCP tool — stub in platform/interfaces/tools/, backend_api facade, test stub. Usage: /add-tool [tool_name]
Add a new MCP tool end-to-end: service logic, backend API facade, interface wrapper, and a test stub. Keeps the contract consistent with the rest of the tool surface.
$ARGUMENTS = {tool_name} in snake_case (e.g. list_frozen_models, compare_ingest_logs).
If the tool name is missing, ask. Do not invent one.
Decide placement.
platform/interfaces/tools/ the tool belongs in (e.g. admin.py, knowledge.py, patterns.py, lifecycle.py).Check for a backend facade. Most tools go through platform/interfaces/backend_api.py as a translation layer. Read it — if there's a pattern for this tool's shape, follow it.
Scaffold the service logic first (not the tool wrapper).
platform/model_registry.py, knowledge/store/..., intelligence/...).Scaffold the backend API facade in backend_api.py.
ApiResult (or the module's existing envelope shape).Scaffold the MCP tool wrapper in the chosen tools/*.py module.
_helpers._api_result_to_json for success/error translation.@mcp.tool() + @tool_handler.Add a test stub in tests/platform/interfaces/tools/test_<module>.py:
ToolError caseUpdate .claude/settings.json permissions.allow list to include mcp__xppatlas__{tool_name} so users don't get permission prompts the first time they call it. Ask before committing this change.
Update CHANGELOG.md + TASKS.md as part of the phase this work belongs to.
tools/__init__.py (or wherever registration happens) if the module uses explicit registration