feat: Add tool annotations for improved LLM tool understanding (#1543)

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: triepod-ai <noreply@github.com>
Co-authored-by: Ralph Khreish <35776126+Crunchyman-ralph@users.noreply.github.com>
Co-authored-by: triepod-ai <199543909+triepod-ai@users.noreply.github.com>

.changeset/tool-annotations.md

@@ -0,0 +1,7 @@
+---
+"task-master-ai": patch
+---
+
+feat: Add tool annotations for improved LLM tool understanding
+
+Added MCP tool annotations (readOnlyHint, destructiveHint, title) to all 12 tools to help LLMs better understand tool behavior and make safer decisions about tool execution.

apps/mcp/src/tools/autopilot/abort.tool.ts

@@ -25,6 +25,10 @@ export function registerAutopilotAbortTool(server: FastMCP) {
 		description:
 			'Abort the current TDD workflow and clean up workflow state. This will remove the workflow state file but will NOT delete the git branch or any code changes.',
 		parameters: AbortSchema,
+		annotations: {
+			title: 'Abort Autopilot Workflow',
+			destructiveHint: true
+		},
 		execute: withToolContext(
 			'autopilot-abort',
 			async (args: AbortArgs, { log, tmCore }: ToolContext) => {

apps/mcp/src/tools/autopilot/commit.tool.ts

@@ -36,6 +36,10 @@ export function registerAutopilotCommitTool(server: FastMCP) {
 		description:
 			'Create a git commit with automatic staging, message generation, and metadata embedding. Generates appropriate commit messages based on subtask context and TDD phase.',
 		parameters: CommitSchema,
+		annotations: {
+			title: 'Commit Autopilot Changes',
+			destructiveHint: true
+		},
 		execute: withToolContext(
 			'autopilot-commit',
 			async (args: CommitArgs, { log, tmCore }: ToolContext) => {

apps/mcp/src/tools/autopilot/complete.tool.ts

@@ -33,6 +33,10 @@ export function registerAutopilotCompleteTool(server: FastMCP) {
 		description:
 			'Complete the current TDD phase (RED or GREEN) with test result validation. RED phase: expects failures (if 0 failures, feature is already implemented and subtask auto-completes). GREEN phase: expects all tests passing. For COMMIT phase, use autopilot_commit instead.',
 		parameters: CompletePhaseSchema,
+		annotations: {
+			title: 'Complete Autopilot Phase',
+			destructiveHint: true
+		},
 		execute: withToolContext(
 			'autopilot-complete-phase',
 			async (args: CompletePhaseArgs, { log, tmCore }: ToolContext) => {

apps/mcp/src/tools/autopilot/finalize.tool.ts

@@ -25,6 +25,10 @@ export function registerAutopilotFinalizeTool(server: FastMCP) {
 		description:
 			'Finalize and complete the workflow. Validates that all changes are committed and working tree is clean before marking workflow as complete.',
 		parameters: FinalizeSchema,
+		annotations: {
+			title: 'Finalize Autopilot Workflow',
+			destructiveHint: true
+		},
 		execute: withToolContext(
 			'autopilot-finalize',
 			async (args: FinalizeArgs, { log, tmCore }: ToolContext) => {

apps/mcp/src/tools/autopilot/next.tool.ts

@@ -25,6 +25,10 @@ export function registerAutopilotNextTool(server: FastMCP) {
 		description:
 			'Get the next action to perform in the TDD workflow. Returns detailed context about what needs to be done next, including the current phase, subtask, and expected actions.',
 		parameters: NextActionSchema,
+		annotations: {
+			title: 'Get Next Autopilot Action',
+			readOnlyHint: true
+		},
 		execute: withToolContext(
 			'autopilot-next',
 			async (args: NextActionArgs, { log, tmCore }: ToolContext) => {

apps/mcp/src/tools/autopilot/resume.tool.ts

@@ -25,6 +25,10 @@ export function registerAutopilotResumeTool(server: FastMCP) {
 		description:
 			'Resume a previously started TDD workflow from saved state. Restores the workflow state machine and continues from where it left off.',
 		parameters: ResumeWorkflowSchema,
+		annotations: {
+			title: 'Resume Autopilot Workflow',
+			readOnlyHint: true
+		},
 		execute: withToolContext(
 			'autopilot-resume',
 			async (args: ResumeWorkflowArgs, { log, tmCore }: ToolContext) => {

apps/mcp/src/tools/autopilot/start.tool.ts

@@ -39,6 +39,10 @@ export function registerAutopilotStartTool(server: FastMCP) {
 		description:
 			'Initialize and start a new TDD workflow for a task. Creates a git branch and sets up the workflow state machine.',
 		parameters: StartWorkflowSchema,
+		annotations: {
+			title: 'Start Autopilot Workflow',
+			destructiveHint: true
+		},
 		execute: withToolContext(
 			'autopilot-start',
 			async (args: StartWorkflowArgs, { log, tmCore }: ToolContext) => {

apps/mcp/src/tools/autopilot/status.tool.ts

@@ -25,6 +25,10 @@ export function registerAutopilotStatusTool(server: FastMCP) {
 		description:
 			'Get comprehensive workflow status including current phase, progress, subtask details, and activity history.',
 		parameters: StatusSchema,
+		annotations: {
+			title: 'Get Autopilot Status',
+			readOnlyHint: true
+		},
 		execute: withToolContext(
 			'autopilot-status',
 			async (args: StatusArgs, { log, tmCore }: ToolContext) => {

apps/mcp/src/tools/tasks/generate.tool.ts

@@ -33,6 +33,10 @@ export function registerGenerateTool(server: FastMCP) {
 		description:
 			'Generates individual task files in tasks/ directory based on tasks.json. Only works with local file storage.',
 		parameters: GenerateSchema,
+		annotations: {
+			title: 'Generate Task Files',
+			destructiveHint: true
+		},
 		execute: withToolContext(
 			'generate',
 			async (args: GenerateArgs, { log, tmCore }: ToolContext) => {

apps/mcp/src/tools/tasks/get-task.tool.ts

@@ -38,6 +38,10 @@ export function registerGetTaskTool(server: FastMCP) {
 		name: 'get_task',
 		description: 'Get detailed information about a specific task',
 		parameters: GetTaskSchema,
+		annotations: {
+			title: 'Get Task',
+			readOnlyHint: true
+		},
 		execute: withToolContext(
 			'get-task',
 			async (args: GetTaskArgs, { log, tmCore }: ToolContext) => {

apps/mcp/src/tools/tasks/get-tasks.tool.ts

@@ -40,6 +40,10 @@ export function registerGetTasksTool(server: FastMCP) {
 		description:
 			'Get all tasks from Task Master, optionally filtering by status and including subtasks.',
 		parameters: GetTasksSchema,
+		annotations: {
+			title: 'Get Tasks',
+			readOnlyHint: true
+		},
 		execute: withToolContext(
 			'get-tasks',
 			async (args: GetTasksArgs, { log, tmCore }: ToolContext) => {

apps/mcp/src/tools/tasks/set-task-status.tool.ts

@@ -34,6 +34,10 @@ export function registerSetTaskStatusTool(server: FastMCP) {
 		name: 'set_task_status',
 		description: 'Set the status of one or more tasks or subtasks.',
 		parameters: SetTaskStatusSchema,
+		annotations: {
+			title: 'Set Task Status',
+			destructiveHint: true
+		},
 		execute: withToolContext(
 			'set-task-status',
 			async (args: SetTaskStatusArgs, { log, tmCore }: ToolContext) => {

mcp-server/src/tools/add-dependency.js

@@ -33,6 +33,10 @@ export function registerAddDependencyTool(server) {
 				.describe('The directory of the project. Must be an absolute path.'),
 			tag: z.string().optional().describe('Tag context to operate on')
 		}),
+		annotations: {
+			title: 'Add Dependency',
+			destructiveHint: true
+		},
 		execute: withToolContext(
 			'add-dependency',
 			async (args, { log, session }) => {

mcp-server/src/tools/add-subtask.js

@@ -62,6 +62,10 @@ export function registerAddSubtaskTool(server) {
 				.describe('The directory of the project. Must be an absolute path.'),
 			tag: z.string().optional().describe('Tag context to operate on')
 		}),
+		annotations: {
+			title: 'Add Subtask',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				const resolvedTag = resolveTag({

mcp-server/src/tools/add-tag.js

@@ -50,6 +50,10 @@ export function registerAddTagTool(server) {
 				.string()
 				.describe('The directory of the project. Must be an absolute path.')
 		}),
+		annotations: {
+			title: 'Add Tag',
+			destructiveHint: false
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(`Starting add-tag with args: ${JSON.stringify(args)}`);

mcp-server/src/tools/add-task.js

@@ -65,6 +65,10 @@ export function registerAddTaskTool(server) {
 				.optional()
 				.describe('Whether to use research capabilities for task creation')
 		}),
+		annotations: {
+			title: 'Add Task',
+			destructiveHint: false
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(`Starting add-task with args: ${JSON.stringify(args)}`);

mcp-server/src/tools/analyze.js

@@ -75,6 +75,10 @@ export function registerAnalyzeProjectComplexityTool(server) {
 				.describe('The directory of the project. Must be an absolute path.'),
 			tag: z.string().optional().describe('Tag context to operate on')
 		}),
+		annotations: {
+			title: 'Analyze Project Complexity',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			const toolName = 'analyze_project_complexity'; // Define tool name for logging
 

mcp-server/src/tools/clear-subtasks.js

@@ -39,6 +39,10 @@ export function registerClearSubtasksTool(server) {
 				message: "Either 'id' or 'all' parameter must be provided",
 				path: ['id', 'all']
 			}),
+		annotations: {
+			title: 'Clear Subtasks',
+			destructiveHint: true
+		},
 		execute: withToolContext('clear-subtasks', async (args, context) => {
 			try {
 				context.log.info(

mcp-server/src/tools/complexity-report.js

@@ -33,6 +33,10 @@ export function registerComplexityReportTool(server) {
 				.string()
 				.describe('The directory of the project. Must be an absolute path.')
 		}),
+		annotations: {
+			title: 'Complexity Report',
+			readOnlyHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(

mcp-server/src/tools/copy-tag.js

@@ -36,6 +36,10 @@ export function registerCopyTagTool(server) {
 				.string()
 				.describe('The directory of the project. Must be an absolute path.')
 		}),
+		annotations: {
+			title: 'Copy Tag',
+			destructiveHint: false
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(`Starting copy-tag with args: ${JSON.stringify(args)}`);

mcp-server/src/tools/delete-tag.js

@@ -34,6 +34,10 @@ export function registerDeleteTagTool(server) {
 				.string()
 				.describe('The directory of the project. Must be an absolute path.')
 		}),
+		annotations: {
+			title: 'Delete Tag',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(`Starting delete-tag with args: ${JSON.stringify(args)}`);

mcp-server/src/tools/expand-all.js

@@ -64,6 +64,10 @@ export function registerExpandAllTool(server) {
 				),
 			tag: z.string().optional().describe('Tag context to operate on')
 		}),
+		annotations: {
+			title: 'Expand All Tasks',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(

mcp-server/src/tools/expand-task.js

@@ -52,6 +52,10 @@ export function registerExpandTaskTool(server) {
 				.describe('Force expansion even if subtasks exist'),
 			tag: z.string().optional().describe('Tag context to operate on')
 		}),
+		annotations: {
+			title: 'Expand Task',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(`Starting expand-task with args: ${JSON.stringify(args)}`);

mcp-server/src/tools/fix-dependencies.js

@@ -24,6 +24,10 @@ export function registerFixDependenciesTool(server) {
 				.describe('The directory of the project. Must be an absolute path.'),
 			tag: z.string().optional().describe('Tag context to operate on')
 		}),
+		annotations: {
+			title: 'Fix Dependencies',
+			destructiveHint: true
+		},
 		execute: withToolContext('fix-dependencies', async (args, context) => {
 			try {
 				context.log.info(

mcp-server/src/tools/get-operation-status.js

@@ -15,6 +15,10 @@ export function registerGetOperationStatusTool(server, asyncManager) {
 		parameters: z.object({
 			operationId: z.string().describe('The ID of the operation to check.')
 		}),
+		annotations: {
+			title: 'Get Operation Status',
+			readOnlyHint: true
+		},
 		execute: async (args, { log }) => {
 			try {
 				const { operationId } = args;

mcp-server/src/tools/initialize-project.js

@@ -56,6 +56,10 @@ export function registerInitializeProjectTool(server) {
 					`List of rule profiles to include at initialization. If omitted, defaults to Cursor profile only. Available options: ${RULE_PROFILES.join(', ')}`
 				)
 		}),
+		annotations: {
+			title: 'Initialize Project',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, context) => {
 			const { log } = context;
 			const session = context.session;

mcp-server/src/tools/list-tags.js

@@ -33,6 +33,10 @@ export function registerListTagsTool(server) {
 				.string()
 				.describe('The directory of the project. Must be an absolute path.')
 		}),
+		annotations: {
+			title: 'List Tags',
+			readOnlyHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(`Starting list-tags with args: ${JSON.stringify(args)}`);

mcp-server/src/tools/models.js

@@ -79,6 +79,10 @@ export function registerModelsTool(server) {
 					'Custom base URL for providers that support it (e.g., https://api.example.com/v1).'
 				)
 		}),
+		annotations: {
+			title: 'Models',
+			destructiveHint: true
+		},
 		execute: withToolContext('models', async (args, context) => {
 			try {
 				context.log.info(

mcp-server/src/tools/move-task.js

@@ -54,6 +54,10 @@ export function registerMoveTaskTool(server) {
 				.optional()
 				.describe('Break cross-tag dependencies during move')
 		}),
+		annotations: {
+			title: 'Move Task',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				// Check if this is a cross-tag move

mcp-server/src/tools/next-task.js

@@ -38,6 +38,10 @@ export function registerNextTaskTool(server) {
 				.describe('The directory of the project. Must be an absolute path.'),
 			tag: z.string().optional().describe('Tag context to operate on')
 		}),
+		annotations: {
+			title: 'Next Task',
+			readOnlyHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(`Finding next task with args: ${JSON.stringify(args)}`);

mcp-server/src/tools/parse-prd.js

@@ -65,6 +65,10 @@ export function registerParsePRDTool(server) {
 				.optional()
 				.describe('Append generated tasks to existing file.')
 		}),
+		annotations: {
+			title: 'Parse PRD',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(
 			async (args, { log, session, reportProgress }) => {
 				try {

mcp-server/src/tools/remove-dependency.js

@@ -31,6 +31,10 @@ export function registerRemoveDependencyTool(server) {
 				.describe('The directory of the project. Must be an absolute path.'),
 			tag: z.string().optional().describe('Tag context to operate on')
 		}),
+		annotations: {
+			title: 'Remove Dependency',
+			destructiveHint: true
+		},
 		execute: withToolContext('remove-dependency', async (args, context) => {
 			try {
 				const resolvedTag = resolveTag({

mcp-server/src/tools/remove-subtask.js

@@ -48,6 +48,10 @@ export function registerRemoveSubtaskTool(server) {
 				.describe('The directory of the project. Must be an absolute path.'),
 			tag: z.string().optional().describe('Tag context to operate on')
 		}),
+		annotations: {
+			title: 'Remove Subtask',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				const resolvedTag = resolveTag({

mcp-server/src/tools/remove-task.js

@@ -42,6 +42,10 @@ export function registerRemoveTaskTool(server) {
 					'Specify which tag context to operate on. Defaults to the current active tag.'
 				)
 		}),
+		annotations: {
+			title: 'Remove Task',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(`Removing task(s) with ID(s): ${args.id}`);

mcp-server/src/tools/rename-tag.js

@@ -31,6 +31,10 @@ export function registerRenameTagTool(server) {
 				.string()
 				.describe('The directory of the project. Must be an absolute path.')
 		}),
+		annotations: {
+			title: 'Rename Tag',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(`Starting rename-tag with args: ${JSON.stringify(args)}`);

mcp-server/src/tools/research.js

@@ -66,6 +66,11 @@ export function registerResearchTool(server) {
 				.describe('The directory of the project. Must be an absolute path.'),
 			tag: z.string().optional().describe('Tag context to operate on')
 		}),
+		annotations: {
+			title: 'Research',
+			destructiveHint: true,
+			openWorldHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				const resolvedTag = resolveTag({

mcp-server/src/tools/response-language.js

@@ -22,6 +22,10 @@ export function registerResponseLanguageTool(server) {
 					'The new response language to set. like "中文" "English" or "español".'
 				)
 		}),
+		annotations: {
+			title: 'Response Language',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(

mcp-server/src/tools/rules.js

@@ -43,6 +43,10 @@ export function registerRulesTool(server) {
 					'DANGEROUS: Force removal even if it would leave no rule profiles. Only use if you are absolutely certain.'
 				)
 		}),
+		annotations: {
+			title: 'Rules',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(

mcp-server/src/tools/scope-down.js

@@ -50,6 +50,10 @@ export function registerScopeDownTool(server) {
 				.optional()
 				.describe('Whether to use research capabilities for scoping')
 		}),
+		annotations: {
+			title: 'Scope Down Task',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(`Starting scope-down with args: ${JSON.stringify(args)}`);

mcp-server/src/tools/scope-up.js

@@ -50,6 +50,10 @@ export function registerScopeUpTool(server) {
 				.optional()
 				.describe('Whether to use research capabilities for scoping')
 		}),
+		annotations: {
+			title: 'Scope Up Task',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(`Starting scope-up with args: ${JSON.stringify(args)}`);

mcp-server/src/tools/set-task-status.js

@@ -51,6 +51,10 @@ export function registerSetTaskStatusTool(server) {
 				.describe('The directory of the project. Must be an absolute path.'),
 			tag: z.string().optional().describe('Optional tag context to operate on')
 		}),
+		annotations: {
+			title: 'Set Task Status',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(

mcp-server/src/tools/update-subtask.js

@@ -38,6 +38,10 @@ export function registerUpdateSubtaskTool(server) {
 				.describe('The directory of the project. Must be an absolute path.'),
 			tag: z.string().optional().describe('Tag context to operate on')
 		}),
+		annotations: {
+			title: 'Update Subtask',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			const toolName = 'update_subtask';
 

mcp-server/src/tools/update-task.js

@@ -47,6 +47,10 @@ export function registerUpdateTaskTool(server) {
 				.describe('The directory of the project. Must be an absolute path.'),
 			tag: z.string().optional().describe('Tag context to operate on')
 		}),
+		annotations: {
+			title: 'Update Task',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			const toolName = 'update_task';
 			try {

mcp-server/src/tools/update.js

@@ -47,6 +47,10 @@ export function registerUpdateTool(server) {
 				),
 			tag: z.string().optional().describe('Tag context to operate on')
 		}),
+		annotations: {
+			title: 'Update Tasks',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			const toolName = 'update';
 			const { from, prompt, research, file, projectRoot, tag } = args;

mcp-server/src/tools/use-tag.js

@@ -30,6 +30,10 @@ export function registerUseTagTool(server) {
 				.string()
 				.describe('The directory of the project. Must be an absolute path.')
 		}),
+		annotations: {
+			title: 'Use Tag',
+			destructiveHint: true
+		},
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
 				log.info(`Starting use-tag with args: ${JSON.stringify(args)}`);

mcp-server/src/tools/validate-dependencies.js

@@ -25,6 +25,10 @@ export function registerValidateDependenciesTool(server) {
 				.describe('The directory of the project. Must be an absolute path.'),
 			tag: z.string().optional().describe('Tag context to operate on')
 		}),
+		annotations: {
+			title: 'Validate Dependencies',
+			readOnlyHint: true
+		},
 		execute: withToolContext(
 			'validate-dependencies',
 			async (args, { log, session }) => {