feat: change default MCP tool tier from 'all' to 'core' (#1490)

Author: Crunchyman-ralph

.taskmaster/CLAUDE.md

@@ -91,6 +91,7 @@ Task Master provides an MCP server that Claude Code can connect to. Configure in
       "command": "npx",
       "args": ["-y", "task-master-ai"],
       "env": {
+        "TASK_MASTER_TOOLS": "core",
         "ANTHROPIC_API_KEY": "your_key_here",
         "PERPLEXITY_API_KEY": "your_key_here",
         "OPENAI_API_KEY": "OPENAI_API_KEY_HERE",
@@ -106,6 +107,24 @@ Task Master provides an MCP server that Claude Code can connect to. Configure in
 }
 ```
 
+### MCP Tool Tiers
+
+Task Master uses tiered tool loading to optimize context window usage:
+
+| Tier | Tools | Use Case |
+|------|-------|----------|
+| `core` | 7 | Minimal daily workflow tools (default) |
+| `standard` | 14 | Common task management |
+| `all` | 44+ | Full suite with research, autopilot, dependencies |
+
+**Core tools (7):** `get_tasks`, `next_task`, `get_task`, `set_task_status`, `update_subtask`, `parse_prd`, `expand_task`
+
+**Standard adds (7 more):** `initialize_project`, `analyze_project_complexity`, `expand_all`, `add_subtask`, `remove_task`, `add_task`, `complexity_report`
+
+**All tier adds:** Dependency management, tag management, research, autopilot TDD workflow, scope up/down, models, rules
+
+**To upgrade tiers:** Change `TASK_MASTER_TOOLS` in `.mcp.json` from `"core"` to `"standard"` or `"all"` and restart the MCP connection.
+
 ### Essential MCP Tools
 
 ```javascript

apps/docs/capabilities/mcp.mdx

@@ -19,27 +19,7 @@ To optimize LLM context usage, you can control which Task Master MCP tools are l
 
 ### Configuration Modes
 
-#### All Tools (Default)
-Loads all 36 available tools. Use when you need full Task Master functionality.
-
-```json
-{
-  "mcpServers": {
-    "task-master-ai": {
-      "command": "npx",
-      "args": ["-y", "task-master-ai"],
-      "env": {
-        "TASK_MASTER_TOOLS": "all",
-        "ANTHROPIC_API_KEY": "your_key_here"
-      }
-    }
-  }
-}
-```
-
-If `TASK_MASTER_TOOLS` is not set, all tools are loaded by default.
-
-#### Core Tools (Lean Mode)
+#### Core Tools (Default, Lean Mode)
 Loads only 7 essential tools for daily development. Ideal for minimal context usage.
 
 **Core tools included:**
@@ -66,7 +46,7 @@ Loads only 7 essential tools for daily development. Ideal for minimal context us
 }
 ```
 
-You can also use `"lean"` as an alias for `"core"`.
+You can also use `"lean"` as an alias for `"core"`. If `TASK_MASTER_TOOLS` is not set, core tools are loaded by default.
 
 #### Standard Tools
 Loads 15 commonly used tools. Balances functionality with context efficiency.
@@ -114,9 +94,27 @@ Specify exactly which tools to load using a comma-separated list. Tool names are
 }
 ```
 
+#### All Tools
+Loads all 36 available tools. Use when you need full Task Master functionality.
+
+```json
+{
+  "mcpServers": {
+    "task-master-ai": {
+      "command": "npx",
+      "args": ["-y", "task-master-ai"],
+      "env": {
+        "TASK_MASTER_TOOLS": "all",
+        "ANTHROPIC_API_KEY": "your_key_here"
+      }
+    }
+  }
+}
+```
+
 ### Choosing the Right Configuration
 
-- **Use `core`/`lean`**: When working with basic task management workflows or when context limits are strict
+- **Use `core`/`lean`**: Default setting, ideal for basic task management workflows or when context limits are strict
 - **Use `standard`**: For most development workflows that include task creation and analysis
 - **Use `all`**: When you need full functionality including tag management, dependencies, and advanced features
 - **Use custom list**: When you have specific tool requirements or want to experiment with minimal sets

apps/docs/getting-started/quick-start/configuration-quick.mdx

@@ -41,9 +41,9 @@ For MCP/Cursor usage: Configure keys in the env section of your .cursor/mcp.json
 **Optimize Context Usage**: You can control which Task Master MCP tools are loaded using the `TASK_MASTER_TOOLS` environment variable. This helps reduce LLM context usage by only loading the tools you need.
 
 Options:
-- `all` (default) - All 36 tools
+- `core` or `lean` (default) - 7 essential tools
 - `standard` - 15 commonly used tools
-- `core` or `lean` - 7 essential tools
+- `all` - All 36 tools
 
 Example:
 ```json

assets/AGENTS.md

@@ -92,6 +92,7 @@ Task Master provides an MCP server that Claude Code can connect to. Configure in
       "command": "npx",
       "args": ["-y", "task-master-ai"],
       "env": {
+        "TASK_MASTER_TOOLS": "core",
         "ANTHROPIC_API_KEY": "your_key_here",
         "PERPLEXITY_API_KEY": "your_key_here",
         "OPENAI_API_KEY": "OPENAI_API_KEY_HERE",
@@ -107,6 +108,18 @@ Task Master provides an MCP server that Claude Code can connect to. Configure in
 }
 ```
 
+### MCP Tool Tiers
+
+Default: `core` (7 tools). Set via `TASK_MASTER_TOOLS` env var.
+
+| Tier | Count | Tools |
+|------|-------|-------|
+| `core` | 7 | `get_tasks`, `next_task`, `get_task`, `set_task_status`, `update_subtask`, `parse_prd`, `expand_task` |
+| `standard` | 14 | core + `initialize_project`, `analyze_project_complexity`, `expand_all`, `add_subtask`, `remove_task`, `add_task`, `complexity_report` |
+| `all` | 44+ | standard + dependencies, tags, research, autopilot, scoping, models, rules |
+
+**Upgrade when tool unavailable:** Edit MCP config, change `TASK_MASTER_TOOLS` from `"core"` to `"standard"` or `"all"`, restart MCP.
+
 ### Essential MCP Tools
 
 ```javascript

assets/rules/taskmaster.mdc

@@ -555,4 +555,18 @@ Environment variables are used **only** for sensitive API keys related to AI pro
 
 ---
 
+## MCP Tool Tiers
+
+Default: `core` (7 tools). Set via `TASK_MASTER_TOOLS` env var in MCP config.
+
+| Tier | Count | Tools |
+|------|-------|-------|
+| `core` | 7 | `get_tasks`, `next_task`, `get_task`, `set_task_status`, `update_subtask`, `parse_prd`, `expand_task` |
+| `standard` | 14 | core + `initialize_project`, `analyze_project_complexity`, `expand_all`, `add_subtask`, `remove_task`, `add_task`, `complexity_report` |
+| `all` | 44+ | standard + dependencies, tags, research, autopilot, scoping, models, rules |
+
+**Upgrade when tool unavailable:** Edit MCP config (`.cursor/mcp.json`, `.mcp.json`, or `.vscode/mcp.json`), change `TASK_MASTER_TOOLS` from `"core"` to `"standard"` or `"all"`, restart MCP.
+
+---
+
 For details on how these commands fit into the development process, see the [Development Workflow Guide](mdc:.cursor/rules/dev_workflow.mdc).

docs/configuration.md

@@ -70,21 +70,20 @@ The `TASK_MASTER_TOOLS` environment variable controls which tools are loaded by
 
 #### Configuration Options
 
-- **`all`** (default): Loads all 36 available tools (~21,000 tokens)
-  - Best for: Users who need the complete feature set
-  - Use when: Working with complex projects requiring all Task Master features
-  - Backward compatibility: This is the default to maintain compatibility with existing installations
+- **`core`** (default, or `lean`): Loads 7 essential tools (~5,000 tokens, 70% reduction)
+  - Best for: Daily development with minimal token overhead
+  - Tools included: `get_tasks`, `next_task`, `get_task`, `set_task_status`, `update_subtask`, `parse_prd`, `expand_task`
+  - Use when: Working in large contexts where token usage is critical
+  - Note: "lean" is an alias for "core" (same tools)
 
 - **`standard`**: Loads 15 commonly used tools (~10,000 tokens, 50% reduction)
   - Best for: Regular task management workflows
   - Tools included: All core tools plus project initialization, complexity analysis, task generation, and more
   - Use when: You need a balanced set of features with reduced token usage
 
-- **`core`** (or `lean`): Loads 7 essential tools (~5,000 tokens, 70% reduction)
-  - Best for: Daily development with minimal token overhead
-  - Tools included: `get_tasks`, `next_task`, `get_task`, `set_task_status`, `update_subtask`, `parse_prd`, `expand_task`
-  - Use when: Working in large contexts where token usage is critical
-  - Note: "lean" is an alias for "core" (same tools, token estimate and recommended use). You can refer to it as either "core" or "lean" when configuring.
+- **`all`**: Loads all 36 available tools (~21,000 tokens)
+  - Best for: Users who need the complete feature set
+  - Use when: Working with complex projects requiring all Task Master features
 
 - **Custom list**: Comma-separated list of specific tool names
   - Best for: Specialized workflows requiring specific tools
@@ -124,7 +123,7 @@ The `TASK_MASTER_TOOLS` environment variable controls which tools are loaded by
 
 #### Tool Loading Behavior
 
-- When `TASK_MASTER_TOOLS` is unset or empty, the system defaults to `"all"`
+- When `TASK_MASTER_TOOLS` is unset or empty, the system defaults to `"core"`
 - Invalid tool names in a user-specified list are ignored (a warning is emitted for each)
 - If every tool name in a custom list is invalid, the system falls back to `"all"`
 - Tool names are case-insensitive (e.g., `"CORE"`, `"core"`, and `"Core"` are treated identically)

mcp-server/src/tools/index.js

@@ -15,14 +15,14 @@ import {
 
 /**
  * Helper function to safely read and normalize the TASK_MASTER_TOOLS environment variable
- * @returns {string} The tools configuration string, defaults to 'all'
+ * @returns {string} The tools configuration string, defaults to 'core'
  */
 export function getToolsConfiguration() {
 	const rawValue = process.env.TASK_MASTER_TOOLS;
 
 	if (!rawValue || rawValue.trim() === '') {
-		logger.debug('No TASK_MASTER_TOOLS env var found, defaulting to "all"');
-		return 'all';
+		logger.debug('No TASK_MASTER_TOOLS env var found, defaulting to "core"');
+		return 'core';
 	}
 
 	const normalizedValue = rawValue.trim();
@@ -37,7 +37,7 @@ export function getToolsConfiguration() {
  * @param {string} toolMode - The tool mode configuration (defaults to 'all')
  * @returns {Object} Object containing registered tools, failed tools, and normalized mode
  */
-export function registerTaskMasterTools(server, toolMode = 'all') {
+export function registerTaskMasterTools(server, toolMode = 'core') {
 	const registeredTools = [];
 	const failedTools = [];
 

package-lock.json

@@ -42,11 +42,15 @@ export function setupMCPConfiguration(projectRoot, mcpConfigPath) {
 	log('info', `Setting up MCP configuration at ${mcpPath}...`);
 
 	// New MCP config to be added - references the installed package
+	// TASK_MASTER_TOOLS: "core" loads essential daily workflow tools (7 tools, default)
+	// Options: "core" (7 essential tools), "standard" (14 common tools), "all" (44+ tools)
+	// See agent rules for tool tier details and how to upgrade if needed
 	const newMCPServer = {
 		'task-master-ai': {
 			command: 'npx',
 			args: ['-y', 'task-master-ai'],
 			env: {
+				TASK_MASTER_TOOLS: 'core',
 				ANTHROPIC_API_KEY: 'YOUR_ANTHROPIC_API_KEY_HERE',
 				PERPLEXITY_API_KEY: 'YOUR_PERPLEXITY_API_KEY_HERE',
 				OPENAI_API_KEY: 'YOUR_OPENAI_KEY_HERE',
@@ -158,7 +162,7 @@ export function removeTaskMasterMCPConfiguration(projectRoot, mcpConfigPath) {
 
 	const mcpPath = path.join(projectRoot, mcpConfigPath);
 
-	let result = {
+	const result = {
 		success: false,
 		removed: false,
 		deleted: false,