MCP Tool Mastery

Master the 80+ MCP tools available in the GoodVibes plugin. This skill teaches you when and how to use each tool for maximum effectiveness.

THE LAW: Tool-First Development

This is non-negotiable. Violating these rules means you're not doing your job.

Before ANY Task

# 1. ALWAYS check tool schema first
mcp-cli info plugin_goodvibes_goodvibes-tools/<tool_name>

# 2. THEN make the call
mcp-cli call plugin_goodvibes_goodvibes-tools/<tool_name> '{"param": "value"}'

The Golden Rules

1. Never skip mcp-cli info - Schemas are tool-specific. Your assumptions are wrong.
2. Never do manually what a tool can do - If a tool exists, use it.
3. Skills contain expertise you lack - Load them to become an expert.
4. Tools provide current information - Your training data is outdated.

---

Quick Reference: Tool Selection by Task

Starting Any Task

| First Action | Tool | Command | |--------------|------|---------| | Understand project | detect_stack | mcp-cli call .../detect_stack '{}' | | Find relevant skills | recommend_skills | mcp-cli call .../recommend_skills '{"task": "..."}' | | Check for issues | project_issues | mcp-cli call .../project_issues '{}' |

Before Writing Code

| Task | Tool | Why | |------|------|-----| | Follow patterns | scan_patterns | Match existing code style | | Understand types | get_schema | Know the interfaces | | Check conventions | get_conventions | Follow project standards |

During Code Navigation

| Need | Tool | Use Case | |------|------|----------| | Find definition | go_to_definition | Jump to where symbol is defined | | Find usages | find_references | See all places symbol is used | | Find implementations | get_implementations | Find concrete implementations of interface | | Search symbols | workspace_symbols | Find symbols by name across codebase | | Understand hierarchy | get_type_hierarchy | See inheritance chain |

Before Editing Code

| Task | Tool | Mandatory? | |------|------|------------| | Check patterns | scan_patterns | Yes | | Preview errors | validate_edits_preview | Recommended | | Check if safe to delete | safe_delete_check | Before deletion | | Find affected tests | find_tests_for_file | Yes |

After Editing Code

| Task | Tool | When | |------|------|------| | Type check | check_types | After TypeScript changes | | Get diagnostics | get_diagnostics | For file-level issues | | Run smoke test | run_smoke_test | Before committing |

Debugging

| Problem | Tool | What It Does | |---------|------|--------------| | Stack trace | parse_error_stack | Parse and explain errors | | Type error | explain_type_error | Explain TypeScript errors | | Find dead code | find_dead_code | Identify unused code | | Check circular deps | find_circular_deps | Find dependency cycles |

Security & Quality

| Concern | Tool | Use | |---------|------|-----| | Secrets in code | scan_for_secrets | Find exposed credentials | | Env config | get_env_config | Understand environment setup | | Permissions | check_permissions | Verify file/dir permissions |

---

Complete Tool Catalog

Discovery & Search (6 tools)

| Tool | Purpose | When to Use | |------|---------|-------------| | search_skills | Find skills by keyword | Starting new domain task | | search_agents | Find agents by capability | Need specialized help | | search_tools | Find tools by function | Looking for specific capability | | recommend_skills | AI-powered skill suggestions | Before any complex task | | get_skill_content | Load skill into context | After finding relevant skill | | get_agent_content | Read agent definition | Understanding agent capabilities |

Dependencies & Stack (6 tools)

| Tool | Purpose | When to Use | |------|---------|-------------| | skill_dependencies | Find skill prerequisites | Before loading skills | | detect_stack | Identify project technologies | First action in new project | | check_versions | Verify package versions | Debugging version issues | | scan_patterns | Find code patterns in project | Before writing similar code | | analyze_dependencies | Deep dependency analysis | Understanding dep structure | | find_circular_deps | Detect circular dependencies | Before refactoring |

Documentation & Schema (5 tools)

| Tool | Purpose | When to Use | |------|---------|-------------| | fetch_docs | Get library documentation | Need API reference | | get_schema | Get type/interface schemas | Before working with types | | read_config | Read configuration files | Understanding project config | | get_database_schema | Get DB schema info | Before database work | | get_api_routes | Map API endpoints | Understanding API structure |

Quality & Testing (7 tools)

| Tool | Purpose | When to Use | |------|---------|-------------| | validate_implementation | Check code meets specs | After implementation | | run_smoke_test | Quick validation test | Before committing | | check_types | TypeScript type checking | After any TS changes | | project_issues | Find project problems | Start of any task | | find_tests_for_file | Find related tests | Before modifying code | | get_test_coverage | Get coverage metrics | Before writing tests | | suggest_test_cases | AI test suggestions | When adding tests |

Scaffolding (3 tools)

| Tool | Purpose | When to Use | |------|---------|-------------| | scaffold_project | Generate project structure | Starting new project | | list_templates | Show available templates | Choosing scaffold template | | plugin_status | Check plugin health | Debugging plugin issues |

LSP/Code Intelligence (18 tools)

Navigation: | Tool | Purpose | |------|---------| | find_references | Find all symbol usages | | go_to_definition | Jump to symbol definition | | get_implementations | Find interface implementations | | get_call_hierarchy | See call relationships | | get_document_symbols | List symbols in file | | workspace_symbols | Search symbols globally |

Analysis: | Tool | Purpose | |------|---------| | get_symbol_info | Get symbol documentation | | get_signature_help | Get function signatures | | get_diagnostics | Get file diagnostics | | get_type_hierarchy | See inheritance chain | | get_inlay_hints | See inferred types | | get_api_surface | Map public API |

Refactoring: | Tool | Purpose | |------|---------| | rename_symbol | Safely rename symbols | | get_code_actions | Get available fixes | | apply_code_action | Apply a code fix | | find_dead_code | Find unused code | | safe_delete_check | Verify safe deletion | | validate_edits_preview | Preview edit errors |

Error Analysis & Security (5 tools)

| Tool | Purpose | When to Use | |------|---------|-------------| | parse_error_stack | Parse stack traces | Debugging errors | | explain_type_error | Explain TS errors | Complex type errors | | scan_for_secrets | Find exposed secrets | Before commits, in reviews | | get_env_config | Get env configuration | Working with env vars | | check_permissions | Check file permissions | Deployment issues |

Code Analysis & Diff (3 tools)

| Tool | Purpose | When to Use | |------|---------|-------------| | get_conventions | Get project conventions | Before writing code | | detect_breaking_changes | Find breaking changes | Before API changes | | semantic_diff | Semantic code comparison | Reviewing changes |

Framework-Specific (3 tools)

| Tool | Purpose | When to Use | |------|---------|-------------| | get_react_component_tree | Map React components | Frontend work | | get_prisma_operations | Get Prisma operations | Database work | | analyze_bundle | Analyze bundle size | Performance work |

Runtime & Frontend Tools (15+ tools)

| Tool | Purpose | |------|---------| | start_dev_server | Start development server | | health_monitor | Monitor server health | | watch_for_errors | Watch for runtime errors | | browser_automation | Automate browser actions | | verify_runtime_behavior | Verify runtime behavior | | lighthouse_audit | Run Lighthouse audit | | visual_regression | Visual regression testing | | analyze_responsive_breakpoints | Check responsive design | | trace_component_state | Trace React state | | analyze_render_triggers | Find render causes | | analyze_layout_hierarchy | Analyze CSS layout | | diagnose_overflow | Debug overflow issues | | get_accessibility_tree | Get a11y tree | | get_sizing_strategy | Analyze sizing | | analyze_event_flow | Trace events | | analyze_tailwind_conflicts | Find CSS conflicts |

Advanced Operations (10+ tools)

| Tool | Purpose | |------|---------| | retry_with_learning | Retry with error learning | | resolve_merge_conflict | Help resolve conflicts | | atomic_multi_edit | Atomic multi-file edits | | auto_rollback | Automatic rollback | | validate_api_contract | Validate API contracts | | profile_function | Profile performance | | log_analyzer | Analyze logs | | generate_types | Generate TypeScript types | | identify_tech_debt | Find technical debt |

---

Tool Invocation Patterns

Pattern 1: Schema Check First (MANDATORY)

# WRONG - Never do this
mcp-cli call plugin_goodvibes_goodvibes-tools/detect_stack '{}'

# CORRECT - Always check schema first
mcp-cli info plugin_goodvibes_goodvibes-tools/detect_stack
# Read the schema output
mcp-cli call plugin_goodvibes_goodvibes-tools/detect_stack '{}'

Pattern 2: Parallel Info Calls

When using multiple tools, check all schemas first:

# Check all schemas in parallel
mcp-cli info plugin_goodvibes_goodvibes-tools/detect_stack
mcp-cli info plugin_goodvibes_goodvibes-tools/scan_patterns
mcp-cli info plugin_goodvibes_goodvibes-tools/project_issues

# Then make calls
mcp-cli call plugin_goodvibes_goodvibes-tools/detect_stack '{}'
mcp-cli call plugin_goodvibes_goodvibes-tools/project_issues '{}'

Pattern 3: Skill Loading Workflow

# 1. Find relevant skills
mcp-cli info plugin_goodvibes_goodvibes-tools/recommend_skills
mcp-cli call plugin_goodvibes_goodvibes-tools/recommend_skills '{"task": "implement authentication"}'

# 2. Load the recommended skill
mcp-cli info plugin_goodvibes_goodvibes-tools/get_skill_content
mcp-cli call plugin_goodvibes_goodvibes-tools/get_skill_content '{"skill_path": "webdev/authentication/clerk"}'

Pattern 4: Pre-Edit Validation

# Before making edits, validate they won't cause errors
mcp-cli info plugin_goodvibes_goodvibes-tools/validate_edits_preview
mcp-cli call plugin_goodvibes_goodvibes-tools/validate_edits_preview '{"file": "src/auth.ts", "changes": "..."}'

Pattern 5: Safe Deletion

# Before deleting any symbol, verify it's safe
mcp-cli info plugin_goodvibes_goodvibes-tools/safe_delete_check
mcp-cli call plugin_goodvibes_goodvibes-tools/safe_delete_check '{"symbol": "oldFunction", "file": "src/utils.ts"}'

---

Agent-Specific Tool Recommendations

Backend Engineer Priority Tools

1. get_database_schema - Always before DB work
2. get_api_routes - Understand existing API
3. get_prisma_operations - When using Prisma
4. get_implementations - Find service implementations
5. validate_api_contract - Before API changes

Frontend Architect Priority Tools

1. get_react_component_tree - Understand component hierarchy
2. analyze_bundle - Check bundle impact
3. analyze_tailwind_conflicts - Find CSS issues
4. get_accessibility_tree - Check a11y
5. analyze_responsive_breakpoints - Verify responsive design

Test Engineer Priority Tools

1. find_tests_for_file - Find existing tests
2. get_test_coverage - Understand coverage gaps
3. suggest_test_cases - Get test suggestions
4. validate_edits_preview - Verify test code compiles
5. run_smoke_test - Quick validation

Code Architect Priority Tools

1. find_circular_deps - Detect dependency cycles
2. find_dead_code - Identify unused code
3. get_api_surface - Understand public APIs
4. detect_breaking_changes - Before refactoring
5. get_type_hierarchy - Understand class relationships

DevOps Deployer Priority Tools

1. analyze_bundle - Check bundle size
2. scan_for_secrets - Find exposed credentials
3. get_env_config - Understand env setup
4. check_permissions - Verify file permissions
5. run_smoke_test - Pre-deployment validation

---

Troubleshooting

Tool Not Found

# List all available tools
mcp-cli tools

# Search for tools by keyword
mcp-cli grep "database"

Schema Mismatch

# Always re-check schema if call fails
mcp-cli info plugin_goodvibes_goodvibes-tools/<tool>

Tool Returns Error

1. Check schema matches your call
2. Verify required parameters
3. Check parameter types (strings vs objects)
4. Use stdin for complex JSON:

mcp-cli call plugin_goodvibes_goodvibes-tools/<tool> - <<'EOF'
{
  "complex": {
    "nested": "value"
  }
}
EOF

---

Checklist: Am I Using Tools Correctly?

Before any task:

• [ ] Did I run detect_stack?
• [ ] Did I check project_issues?
• [ ] Did I search for relevant skills?

Before editing:

• [ ] Did I run scan_patterns?
• [ ] Did I check find_tests_for_file?
• [ ] Did I use validate_edits_preview?

After editing:

• [ ] Did I run check_types?
• [ ] Did I run get_diagnostics?

Before deletion:

• [ ] Did I run safe_delete_check?
• [ ] Did I verify with find_references?

If you answered "no" to any of these, GO BACK AND USE THE TOOL.