MCP Tool Preferences

When MCP tools are available, ALWAYS prefer them over CLI equivalents unless the user explicitly requests CLI usage.

Mandatory Requirements

Requirement	Rule	Rationale
MCP First	MUST prefer MCP tools over CLI equivalents when available	Consistent behavior
Pre-Flight Checks	MUST complete pre-flight requirements before operations	Proper initialization
Error Reporting	MUST report MCP tool failures clearly before trying CLI	User awareness
Auth Verification	MUST verify authentication before resource operations	Prevent auth failures
Structured Output	MUST use MCP for structured data retrieval	Avoid parsing text

Prohibited Patterns

Pattern	Prohibition	Alternative
CLI Over MCP	NEVER use CLI when equivalent MCP tool exists	Use MCP tool
Silent CLI Fallback	NEVER silently switch from MCP to CLI on failure	Report error, ask user
Assumed Executables	NEVER assume psql, gh, az are installed	Use MCP equivalents
Python Path Assumption	NEVER assume python command works	Use get_python_executable_details
Skip Pre-Flight	NEVER skip pre-flight checks for database/cloud ops	Complete all required steps

Why MCP Tools First

• Authentication handled: MCP connections manage credentials; CLI may require separate auth
• Structured output: MCP returns typed data; CLI requires parsing text
• User may not have CLI installed: psql, gh, az, kubectl are not guaranteed
• Consistency: Same tool = same behavior across sessions

Tool Preference Matrix

Task	PREFER (MCP)	AVOID (CLI)
PostgreSQL queries	pgsql_connect, pgsql_query, pgsql_modify	psql
PostgreSQL schema	pgsql_db_context, pgsql_visualize_schema	pg_dump, \d commands
GitHub PR details	github-pull-request_activePullRequest	gh pr view
GitHub issues	github-pull-request_issue_fetch	gh issue view
GitHub search	github-pull-request_formSearchQuery + doSearch	gh search
Azure resources	azure_resources-query_azure_resource_graph	az resource list
Azure auth	azure_auth-get_auth_context	az account show
Python environment	configure_python_environment	Assume python works
Python packages	install_python_packages	pip install directly
Git changes	get_changed_files	git diff (use for complex diffs)
File search	file_search, grep_search, semantic_search	find, grep
Code navigation	list_code_usages	grep for symbol names

Pre-Flight Requirements

Before PostgreSQL Operations

1. MUST call pgsql_list_servers to discover available connections
2. MUST call pgsql_connect to establish connection
3. MUST call pgsql_db_context before modifications to understand schema

Before Python Operations

1. MUST call configure_python_environment first
2. MUST use get_python_executable_details to get correct invocation
3. Do NOT assume python or python3 is the correct command

Before GitHub Operations

1. For current PR: MUST call github-pull-request_activePullRequest first
2. For searches: MUST call github-pull-request_formSearchQuery before doSearch
3. For issue details: Use github-pull-request_issue_fetch with issue number

Before Azure Operations

1. MUST call azure_development-recommend_custom_modes for Azure-related requests
2. For resource queries: Use azure_resources-query_azure_resource_graph
3. Check auth context with azure_auth-get_auth_context if access issues arise

When CLI Is Appropriate

Use terminal commands when:

• User explicitly requests CLI (e.g., "run gh pr create")
• No MCP equivalent exists for the operation
• MCP tool fails and CLI is a documented fallback
• Operation requires interactive input that MCP cannot handle
• Running build/test commands (npm test, make build, etc.)

Prohibited Patterns

Do NOT:

• Run psql when pgsql_* tools are available
• Run gh pr view when github-pull-request_activePullRequest exists
• Run az commands for resource queries when ARG tools are available
• Assume Python executable path without checking environment tools
• Use grep for code symbol search when list_code_usages fits better

Error Recovery

If an MCP tool fails:

1. Report the error clearly to the user
2. Check if authentication/connection is the issue
3. Offer CLI as explicit fallback: "The MCP tool failed. Would you like me to try using the CLI instead?"
4. Do NOT silently switch to CLI

Tool Discovery

If unsure whether an MCP tool exists:

1. Check the tools available in current context
2. Prefer tools with structured parameters over freeform CLI
3. When in doubt, ask: "I can do this via [MCP tool] or [CLI]. Which do you prefer?"