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>

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) => {