feat(mcp): Add tool annotations for improved LLM tool understanding

Add `readOnlyHint` and `destructiveHint` annotations to all 15 MCP tools
to help AI/LLM agents better understand the safety characteristics of
each tool:

Read-only tools (10):
- searchDocsTool - Search documentation
- listOrgsTool - List organizations
- listProjectsTool - List projects
- getCurrentWorker - Get current worker info
- listRunsTool - List runs
- getRunDetailsTool - Get run details
- waitForRunToCompleteTool - Wait for run completion
- listDeploysTool - List deployments
- listPreviewBranchesTool - List preview branches

Destructive tools (5):
- createProjectInOrgTool - Creates a new project
- initializeProjectTool - Initializes a project
- triggerTaskTool - Triggers task execution
- cancelRunTool - Cancels a running task
- deployTool - Deploys code to environment

These annotations follow the MCP specification and help AI agents
make informed decisions about which tools require user confirmation
before execution.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: web-flow

packages/cli-v3/src/mcp/tools.ts

@@ -39,7 +39,11 @@ export function registerTools(context: McpContext) {
     context.server.registerTool(
       tool.name,
       {
-        annotations: { title: tool.title },
+        annotations: {
+          title: tool.title,
+          readOnlyHint: tool.readOnlyHint,
+          destructiveHint: tool.destructiveHint,
+        },
         description: tool.description,
         inputSchema: tool.inputSchema,
       },

packages/cli-v3/src/mcp/tools/deploys.ts

@@ -14,6 +14,8 @@ export const deployTool = {
   name: toolsMetadata.deploy.name,
   title: toolsMetadata.deploy.title,
   description: toolsMetadata.deploy.description,
+  readOnlyHint: false,
+  destructiveHint: true,
   inputSchema: DeployInput.shape,
   handler: toolHandler(DeployInput.shape, async (input, { ctx, createProgressTracker, _meta }) => {
     ctx.logger?.log("calling deploy", { input });
@@ -114,6 +116,8 @@ export const listDeploysTool = {
   name: toolsMetadata.list_deploys.name,
   title: toolsMetadata.list_deploys.title,
   description: toolsMetadata.list_deploys.description,
+  readOnlyHint: true,
+  destructiveHint: false,
   inputSchema: ListDeploysInput.shape,
   handler: toolHandler(ListDeploysInput.shape, async (input, { ctx }) => {
     ctx.logger?.log("calling list_deploys", { input });

packages/cli-v3/src/mcp/tools/docs.ts

@@ -7,6 +7,8 @@ export const searchDocsTool = {
   name: toolsMetadata.search_docs.name,
   title: toolsMetadata.search_docs.title,
   description: toolsMetadata.search_docs.description,
+  readOnlyHint: true,
+  destructiveHint: false,
   inputSchema: {
     query: z.string(),
   },

packages/cli-v3/src/mcp/tools/orgs.ts

@@ -11,6 +11,8 @@ export const listOrgsTool = {
   name: toolsMetadata.list_orgs.name,
   title: toolsMetadata.list_orgs.title,
   description: toolsMetadata.list_orgs.description,
+  readOnlyHint: true,
+  destructiveHint: false,
   inputSchema: {},
   handler: async (input: unknown, { ctx }: ToolMeta): Promise<CallToolResult> => {
     ctx.logger?.log("calling list_orgs", { input });
@@ -39,6 +41,8 @@ export const listProjectsTool = {
   name: toolsMetadata.list_projects.name,
   title: toolsMetadata.list_projects.title,
   description: toolsMetadata.list_projects.description,
+  readOnlyHint: true,
+  destructiveHint: false,
   inputSchema: {},
   handler: async (input: unknown, { ctx }: ToolMeta): Promise<CallToolResult> => {
     ctx.logger?.log("calling list_projects", { input });
@@ -107,6 +111,8 @@ export const createProjectInOrgTool = {
   name: toolsMetadata.create_project_in_org.name,
   title: toolsMetadata.create_project_in_org.title,
   description: toolsMetadata.create_project_in_org.description,
+  readOnlyHint: false,
+  destructiveHint: true,
   inputSchema: CreateProjectInOrgInput.shape,
   handler: toolHandler(CreateProjectInOrgInput.shape, async (input, { ctx }) => {
     ctx.logger?.log("calling create_project_in_org", { input });
@@ -137,6 +143,8 @@ export const initializeProjectTool = {
   name: toolsMetadata.initialize_project.name,
   title: toolsMetadata.initialize_project.title,
   description: toolsMetadata.initialize_project.description,
+  readOnlyHint: false,
+  destructiveHint: true,
   inputSchema: InitializeProjectInput.shape,
   handler: toolHandler(InitializeProjectInput.shape, async (input, { ctx }) => {
     ctx.logger?.log("calling initialize_project", { input });

packages/cli-v3/src/mcp/tools/previewBranches.ts

@@ -7,6 +7,8 @@ export const listPreviewBranchesTool = {
   name: toolsMetadata.list_preview_branches.name,
   title: toolsMetadata.list_preview_branches.title,
   description: toolsMetadata.list_preview_branches.description,
+  readOnlyHint: true,
+  destructiveHint: false,
   inputSchema: ListPreviewBranchesInput.shape,
   handler: toolHandler(ListPreviewBranchesInput.shape, async (input, { ctx }) => {
     ctx.logger?.log("calling list_preview_branches", { input });

packages/cli-v3/src/mcp/tools/runs.ts

@@ -8,6 +8,8 @@ export const getRunDetailsTool = {
   name: toolsMetadata.get_run_details.name,
   title: toolsMetadata.get_run_details.title,
   description: toolsMetadata.get_run_details.description,
+  readOnlyHint: true,
+  destructiveHint: false,
   inputSchema: GetRunDetailsInput.shape,
   handler: toolHandler(GetRunDetailsInput.shape, async (input, { ctx }) => {
     ctx.logger?.log("calling get_run_details", { input });
@@ -65,6 +67,8 @@ export const waitForRunToCompleteTool = {
   name: toolsMetadata.wait_for_run_to_complete.name,
   title: toolsMetadata.wait_for_run_to_complete.title,
   description: toolsMetadata.wait_for_run_to_complete.description,
+  readOnlyHint: true,
+  destructiveHint: false,
   inputSchema: CommonRunsInput.shape,
   handler: toolHandler(CommonRunsInput.shape, async (input, { ctx, signal }) => {
     ctx.logger?.log("calling wait_for_run_to_complete", { input });
@@ -118,6 +122,8 @@ export const cancelRunTool = {
   name: toolsMetadata.cancel_run.name,
   title: toolsMetadata.cancel_run.title,
   description: toolsMetadata.cancel_run.description,
+  readOnlyHint: false,
+  destructiveHint: true,
   inputSchema: CommonRunsInput.shape,
   handler: toolHandler(CommonRunsInput.shape, async (input, { ctx }) => {
     ctx.logger?.log("calling cancel_run", { input });
@@ -158,6 +164,8 @@ export const listRunsTool = {
   name: toolsMetadata.list_runs.name,
   title: toolsMetadata.list_runs.title,
   description: toolsMetadata.list_runs.description,
+  readOnlyHint: true,
+  destructiveHint: false,
   inputSchema: ListRunsInput.shape,
   handler: toolHandler(ListRunsInput.shape, async (input, { ctx }) => {
     ctx.logger?.log("calling list_runs", { input });

packages/cli-v3/src/mcp/tools/tasks.ts

@@ -7,6 +7,8 @@ export const getCurrentWorker = {
   name: toolsMetadata.get_current_worker.name,
   title: toolsMetadata.get_current_worker.title,
   description: toolsMetadata.get_current_worker.description,
+  readOnlyHint: true,
+  destructiveHint: false,
   inputSchema: CommonProjectsInput.shape,
   handler: toolHandler(CommonProjectsInput.shape, async (input, { ctx }) => {
     ctx.logger?.log("calling get_current_worker", { input });
@@ -86,6 +88,8 @@ export const triggerTaskTool = {
   name: toolsMetadata.trigger_task.name,
   title: toolsMetadata.trigger_task.title,
   description: toolsMetadata.trigger_task.description,
+  readOnlyHint: false,
+  destructiveHint: true,
   inputSchema: TriggerTaskInput.shape,
   handler: toolHandler(TriggerTaskInput.shape, async (input, { ctx }) => {
     ctx.logger?.log("calling trigger_task", { input });