DollhouseMCP

# PersonaTools Removal Plan - Multi-Agent Coordination **Date**: August 19, 2025 - 4:30 PM **Orchestrator**: Opus **Issue**: #633 - PersonaTools Partial Removal **Objective**: Remove 9 redundant PersonaTools, keep 5 export/import tools ## Executive Summary We will remove 9 redundant PersonaTools that have exact ElementTools equivalents, while keeping 5 export/import/share tools that provide unique functionality not yet available in ElementTools. This reduces tool count from 51 to 42 tools and simplifies the API. ## Tools Analysis ### 🔴 Tools to REMOVE (9 tools) These tools have **EXACT** ElementTools equivalents and are redundant: | PersonaTool | ElementTool Equivalent | Rationale for Removal | |-------------|------------------------|----------------------| | `list_personas` | `list_elements(type: "personas")` | Direct 1:1 mapping, no functionality loss | | `activate_persona` | `activate_element(name, type: "personas")` | ElementTools supports all element types including personas | | `get_active_persona` | `get_active_elements(type: "personas")` | Same functionality, unified interface | | `deactivate_persona` | `deactivate_element(name, type: "personas")` | Redundant with element system | | `get_persona_details` | `get_element_details(name, type: "personas")` | Identical functionality | | `reload_personas` | `reload_elements(type: "personas")` | Same operation, type-specific | | `create_persona` | `create_element(type: "personas", ...)` | ElementTools has full creation support | | `edit_persona` | `edit_element(name, type: "personas", ...)` | Complete editing functionality exists | | `validate_persona` | `validate_element(name, type: "personas")` | Validation logic identical | ### ✅ Tools to KEEP (5 tools) These tools provide **UNIQUE** functionality not available in ElementTools: | PersonaTool | Unique Functionality | Why Keep | |------------|---------------------|----------| | `export_persona` | Export single persona to JSON | No element export in ElementTools | | `export_all_personas` | Bulk export with filtering | Unique batch operation | | `import_persona` | Import from file/JSON string | No element import in ElementTools | | `share_persona` | Generate shareable URLs | Unique sharing mechanism | | `import_from_url` | Import from shared URLs | Complements share_persona | ## Multi-Agent Coordination Plan ### Coordination Document All agents will use: `COORDINATION_PERSONA_TOOLS_REMOVAL.md` ### Agent Assignments #### Agent 1: Dependency Scanner (Sonnet) **Label**: [AGENT-1-SCANNER] **Mission**: Map all dependencies and usage patterns **Tasks**: 1. Scan for direct tool name references in code 2. Identify test dependencies 3. Map server method calls vs tool calls 4. Document all import statements 5. Check for hardcoded tool names in strings #### Agent 2: Code Surgeon (Sonnet) **Label**: [AGENT-2-SURGEON] **Mission**: Perform surgical removal of 9 tools **Tasks**: 1. Remove 9 tool definitions from PersonaTools.ts 2. Keep 5 export/import tools intact 3. Update function to return only 5 tools 4. Preserve all server methods (they're still used) 5. Update any imports/exports #### Agent 3: Test Validator (Sonnet) **Label**: [AGENT-3-VALIDATOR] **Mission**: Ensure no test breakage **Tasks**: 1. Run full test suite before changes 2. Identify tests using removed tools 3. Update tests to use ElementTools equivalents 4. Verify export/import tools still work 5. Confirm 100% test pass rate #### Agent 4: Documentation Updater (Sonnet) **Label**: [AGENT-4-DOCS] **Mission**: Update all documentation **Tasks**: 1. Update README.md tool count (51 → 42) 2. Update API_REFERENCE.md 3. Create migration guide section 4. Update examples to use ElementTools 5. Document kept export/import tools #### Agent 5: Integration Tester (Sonnet) **Label**: [AGENT-5-INTEGRATION] **Mission**: Verify complete system integration **Tasks**: 1. Test ElementTools with personas type 2. Verify export/import still functional 3. Check tool registration in ServerSetup 4. Test with Claude Desktop simulation 5. Verify no runtime errors ## Implementation Phases ### Phase 1: Analysis & Preparation (30 min) - Agent 1 scans all dependencies - Create backup branch - Document current state ### Phase 2: Code Removal (45 min) - Agent 2 removes 9 tool definitions - Keep export/import tools intact - Update exports and registrations ### Phase 3: Test Updates (45 min) - Agent 3 updates affected tests - Verify all tests pass - Check coverage maintained ### Phase 4: Documentation (30 min) - Agent 4 updates all docs - Create migration guide - Update tool counts ### Phase 5: Integration Testing (30 min) - Agent 5 runs full integration tests - Verify with mock Claude Desktop - Confirm no regressions ## Risk Mitigation ### Identified Risks 1. **Test Dependencies** - **Risk**: Tests directly calling removed tools - **Mitigation**: Tests use server methods, not tool names - **Action**: Agent 3 will verify and update if needed 2. **Documentation References** - **Risk**: Many docs reference old tools - **Mitigation**: Comprehensive doc update by Agent 4 - **Action**: Search and replace with migration notes 3. **Security Test Dependencies** - **Risk**: Security tests use create_persona, edit_persona - **Mitigation**: These call server methods, not tools - **Action**: Verify server.createPersona() still works 4. **Export/Import Breakage** - **Risk**: Accidentally removing needed functionality - **Mitigation**: Keep 5 tools explicitly marked - **Action**: Agent 5 tests all export/import paths ## Success Criteria - [ ] 9 PersonaTools removed from codebase - [ ] 5 export/import tools remain functional - [ ] All tests pass (100% rate) - [ ] Tool count updated (51 → 42) - [ ] Migration guide complete - [ ] No runtime errors - [ ] ElementTools handle all persona operations - [ ] Export/import functionality preserved ## Code Structure Analysis ### Current PersonaTools.ts Structure ```typescript export function getPersonaTools(server: IToolHandler): Array<{ tool: ToolDefinition; handler: any }> { return [ // REMOVE: Basic management (9 tools) { tool: { name: "list_personas" }, handler: () => server.listPersonas() }, { tool: { name: "activate_persona" }, handler: (args) => server.activatePersona(args.persona) }, // ... 7 more to remove // KEEP: Export/Import (5 tools) { tool: { name: "export_persona" }, handler: (args) => server.exportPersona(args.persona) }, { tool: { name: "export_all_personas" }, handler: (args) => server.exportAllPersonas(args.includeDefaults) }, { tool: { name: "import_persona" }, handler: (args) => server.importPersona(args.source, args.overwrite) }, { tool: { name: "share_persona" }, handler: (args) => server.sharePersona(args.persona, args.expiryDays) }, { tool: { name: "import_from_url" }, handler: (args) => server.importFromUrl(args.url, args.overwrite) } ]; } ``` ### After Removal Structure ```typescript export function getPersonaExportImportTools(server: IToolHandler): Array<{ tool: ToolDefinition; handler: any }> { return [ // Only export/import tools remain (5 tools) { tool: { name: "export_persona" }, ... }, { tool: { name: "export_all_personas" }, ... }, { tool: { name: "import_persona" }, ... }, { tool: { name: "share_persona" }, ... }, { tool: { name: "import_from_url" }, ... } ]; } ``` ## Migration Guide for Users ### For Each Removed Tool ```typescript // OLD: Using PersonaTools list_personas() activate_persona("creative-writer") get_active_persona() deactivate_persona() // NEW: Using ElementTools list_elements(type: "personas") activate_element(name: "creative-writer", type: "personas") get_active_elements(type: "personas") deactivate_element(name: "creative-writer", type: "personas") ``` ### Export/Import Still Work ```typescript // These remain unchanged export_persona("creative-writer") import_persona("./my-persona.json") share_persona("creative-writer", 7) ``` ## Timeline - **Total Estimated Time**: 3 hours - **Agents Running**: Parallel where possible - **Checkpoints**: After each phase - **Rollback Plan**: Git stash ready ## Notes for Orchestrator (Opus) 1. **Maintain backward compatibility** for server methods 2. **Don't remove server.createPersona()** etc - they're used internally 3. **Focus on MCP tool definitions** only 4. **Keep detailed logs** in coordination document 5. **Test incrementally** - don't wait until end --- **Ready to Execute**: This plan provides clear, bite-sized tasks for each agent with specific responsibilities and success criteria.