Background
/improve cycle 126's api_surface_audit of docs/api-surface/mcp-tools.txt (36 tools) found 4 outliers breaking the registry's dominant noun + operation pattern:
| Current tool |
Suggested replacement |
get_active_project |
project with operation: get_active |
list_projects |
project with operation: list |
select_project |
project with operation: select |
validate_all_projects |
project with operation: validate_all |
Every other tool in the 32+ remaining inventory follows the pattern of one noun-based tool with an operation enum inside the input schema:
dsl → validate, inspect_entity, lint, analyze, fidelity, export_frontend_specstory → get, coverage, scope_fidelitydb → status, verify- ...
The 4 project-* tools are the only ones that hoist the verb into the tool name. Inconsistent shape → 4 extra tools in the registry, 4 extra agent-discoverability surface to remember, 4 extra entries in the consolidated tools list.
Proposal
Consolidate into one project tool:
{
"name": "project",
"description": "Manage the active project and walk the project list.",
"inputSchema": {
"properties": {
"operation": {
"type": "string",
"enum": ["list", "get_active", "select", "validate_all"],
},
# plus operation-specific args (project_name for select, etc.)
},
"required": ["operation"],
},
}Blast radius
- 4 entries in
dazzle.mcp.server.tools_consolidated.get_all_consolidated_tools() → 1 entry
- 4 handlers → 1 dispatch handler with op-routing (mirror the
dsl / story tool pattern)
- Drift gate
tests/unit/test_api_surface_drift.py regenerates on dazzle inspect-api mcp-tools --write
- CHANGELOG entry under Changed + Removed
Cross-cuts: any agent / CLAUDE.md / docs that names these tools by their current name needs to be updated. Grep shows they're documented in the MCP tools section of .claude/CLAUDE.md (line 102 of the section lists bootstrap, spec_analyze, user_management, user_profile, llm — the project ones aren't listed there, so doc surface is small).
Sequencing
Single PR. The 4-into-1 collapse is mechanical. Tests for each operation can mirror the existing pattern for dsl/story MCP tools.
Discovered by
/improve cycle 126 framework-ux lane, api_surface_audit sub-strategy. The cycle walked all 36 entries against the audit's standard lens (naming, required-vs-optional, type choice, default, granularity, removal). API-004 is the only proposal worth filing from this surface — the other 32 tools' shapes are acceptable. See dev_docs/api-surface-audit-log.md for the cycle's full notes.
This issue is pre-1.0 cleanup — the kind of breaking shape change that's cheap now and expensive after 1.0. Companion to #1069 which covers the DSL-construct rename pass; same spirit, different surface.
Background
/improvecycle 126'sapi_surface_auditofdocs/api-surface/mcp-tools.txt(36 tools) found 4 outliers breaking the registry's dominantnoun + operationpattern:get_active_projectprojectwithoperation: get_activelist_projectsprojectwithoperation: listselect_projectprojectwithoperation: selectvalidate_all_projectsprojectwithoperation: validate_allEvery other tool in the 32+ remaining inventory follows the pattern of one noun-based tool with an
operationenum inside the input schema:dsl→validate,inspect_entity,lint,analyze,fidelity,export_frontend_specstory→get,coverage,scope_fidelitydb→status,verifyThe 4 project-* tools are the only ones that hoist the verb into the tool name. Inconsistent shape → 4 extra tools in the registry, 4 extra agent-discoverability surface to remember, 4 extra entries in the consolidated tools list.
Proposal
Consolidate into one
projecttool:{ "name": "project", "description": "Manage the active project and walk the project list.", "inputSchema": { "properties": { "operation": { "type": "string", "enum": ["list", "get_active", "select", "validate_all"], }, # plus operation-specific args (project_name for select, etc.) }, "required": ["operation"], }, }Blast radius
dazzle.mcp.server.tools_consolidated.get_all_consolidated_tools()→ 1 entrydsl/storytool pattern)tests/unit/test_api_surface_drift.pyregenerates ondazzle inspect-api mcp-tools --writeCross-cuts: any agent / CLAUDE.md / docs that names these tools by their current name needs to be updated. Grep shows they're documented in the MCP tools section of
.claude/CLAUDE.md(line 102 of the section listsbootstrap,spec_analyze,user_management,user_profile,llm— the project ones aren't listed there, so doc surface is small).Sequencing
Single PR. The 4-into-1 collapse is mechanical. Tests for each operation can mirror the existing pattern for
dsl/storyMCP tools.Discovered by
/improvecycle 126 framework-ux lane,api_surface_auditsub-strategy. The cycle walked all 36 entries against the audit's standard lens (naming, required-vs-optional, type choice, default, granularity, removal). API-004 is the only proposal worth filing from this surface — the other 32 tools' shapes are acceptable. Seedev_docs/api-surface-audit-log.mdfor the cycle's full notes.This issue is pre-1.0 cleanup — the kind of breaking shape change that's cheap now and expensive after 1.0. Companion to #1069 which covers the DSL-construct rename pass; same spirit, different surface.