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.