veryfront 0.1.140 → 0.1.142

package/src/cli/mcp/jsonrpc.ts

@@ -43,6 +43,18 @@ export const JSONRPC_ERRORS = {
   INTERNAL_ERROR: -32603,
 } as const;
 
+/**
+ * Error with a JSON-RPC error code attached.
+ * Preserves stack traces unlike throwing plain objects.
+ */
+export class JsonRpcError extends Error {
+  readonly code: number;
+  constructor(code: number, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
 /**
  * Create a JSON-RPC parse error response
  */
@@ -70,15 +82,71 @@ export function successResponse(id: string | number | undefined, result: unknown
 export function errorResponse(
   id: string | number | undefined,
   e: unknown,
-  code = JSONRPC_ERRORS.INTERNAL_ERROR,
+  code?: number,
 ): JSONRPCResponse {
+  const errorCode = typeof e === "object" && e !== null && "code" in e
+    ? (e as { code: unknown }).code
+    : undefined;
+  const resolvedCode = code ??
+    (typeof errorCode === "number" ? errorCode : JSONRPC_ERRORS.INTERNAL_ERROR);
+  const message = e instanceof Error
+    ? e.message
+    : typeof e === "object" && e !== null && "message" in e
+    ? String((e as { message: unknown }).message)
+    : String(e);
   return {
     jsonrpc: "2.0",
     id,
-    error: {
-      code,
-      message: e instanceof Error ? e.message : String(e),
+    error: { code: resolvedCode, message },
+  };
+}
+
+/**
+ * Supported MCP protocol versions (newest first).
+ * Shared across all CLI MCP servers so the version list is maintained in one place.
+ */
+export const MCP_SUPPORTED_VERSIONS: [string, ...string[]] = ["2025-11-25", "2024-11-05"];
+
+/**
+ * Safely extract a record from unknown params (mirrors src/mcp toParamsRecord).
+ */
+export function toParamsRecord(params: unknown): Record<string, unknown> {
+  if (params && typeof params === "object" && !Array.isArray(params)) {
+    return params as Record<string, unknown>;
+  }
+  return {};
+}
+
+/**
+ * Negotiate MCP protocol version: echo the client's version if supported,
+ * otherwise fall back to the newest supported version.
+ */
+export function negotiateVersion(params: unknown): string {
+  const p = toParamsRecord(params);
+  const requested = typeof p.protocolVersion === "string" ? p.protocolVersion : undefined;
+  return requested && MCP_SUPPORTED_VERSIONS.includes(requested)
+    ? requested
+    : MCP_SUPPORTED_VERSIONS[0];
+}
+
+/**
+ * Build a complete MCP initialize result with negotiated version,
+ * capabilities, serverInfo, and instructions.
+ */
+export function buildInitializeResult(
+  params: unknown,
+  serverInfo: { name: string; title: string; version: string; description: string },
+  instructions: string,
+): Record<string, unknown> {
+  return {
+    protocolVersion: negotiateVersion(params),
+    capabilities: {
+      tools: { listChanged: true },
+      resources: { listChanged: true },
+      prompts: { listChanged: true },
     },
+    serverInfo,
+    instructions,
   };
 }
 

package/src/cli/mcp/remote-file-tools.ts

@@ -200,6 +200,8 @@ interface RemoteListFilesOutput {
 
 export const vfRemoteListFiles: MCPTool<RemoteListFilesInput, RemoteListFilesOutput> = {
   name: "vf_remote_list_files",
+  title: "List Remote Files",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
     "List files in a remote Veryfront project. Returns file paths, types, and sizes. Use this to explore a project's structure.",
   inputSchema: remoteListFilesInput,
@@ -249,6 +251,8 @@ interface RemoteGetFileOutput {
 
 export const vfRemoteGetFile: MCPTool<RemoteGetFileInput, RemoteGetFileOutput> = {
   name: "vf_remote_get_file",
+  title: "Get Remote File",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
     "Read the content of a file from a remote Veryfront project. Always use this before modifying a file.",
   inputSchema: remoteGetFileInput,
@@ -296,6 +300,13 @@ interface RemoteUpdateFileOutput {
 
 export const vfRemoteUpdateFile: MCPTool<RemoteUpdateFileInput, RemoteUpdateFileOutput> = {
   name: "vf_remote_update_file",
+  title: "Update Remote File",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   description:
     "Create or update a file in a remote Veryfront project. Always read the file first before updating to understand its current state.",
   inputSchema: remoteUpdateFileInput,
@@ -341,6 +352,13 @@ interface RemoteDeleteFileOutput {
 
 export const vfRemoteDeleteFile: MCPTool<RemoteDeleteFileInput, RemoteDeleteFileOutput> = {
   name: "vf_remote_delete_file",
+  title: "Delete Remote File",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   description: "Delete a file from a remote Veryfront project.",
   inputSchema: remoteDeleteFileInput,
   execute: async (input) => {
@@ -378,6 +396,8 @@ interface RemoteSearchFilesOutput {
 
 export const vfRemoteSearchFiles: MCPTool<RemoteSearchFilesInput, RemoteSearchFilesOutput> = {
   name: "vf_remote_search_files",
+  title: "Search Remote Files",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
     "Search for text patterns within file contents in a remote Veryfront project. Supports regex and glob patterns.",
   inputSchema: remoteSearchFilesInput,
@@ -430,6 +450,8 @@ interface RemoteMoveFileOutput {
 
 export const vfRemoteMoveFile: MCPTool<RemoteMoveFileInput, RemoteMoveFileOutput> = {
   name: "vf_remote_move_file",
+  title: "Move Remote File",
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   description: "Move or rename a file in a remote Veryfront project.",
   inputSchema: remoteMoveFileInput,
   execute: async (input) => {
@@ -477,6 +499,8 @@ interface RemoteListBranchesOutput {
 
 export const vfRemoteListBranches: MCPTool<RemoteListBranchesInput, RemoteListBranchesOutput> = {
   name: "vf_remote_list_branches",
+  title: "List Remote Branches",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description: "List branches in a remote Veryfront project.",
   inputSchema: remoteListBranchesInput,
   execute: async (input) => {
@@ -514,6 +538,8 @@ interface RemoteCreateBranchOutput {
 
 export const vfRemoteCreateBranch: MCPTool<RemoteCreateBranchInput, RemoteCreateBranchOutput> = {
   name: "vf_remote_create_branch",
+  title: "Create Remote Branch",
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   description:
     "Create a new branch in a remote Veryfront project. Branch from main by default, or specify a base branch.",
   inputSchema: remoteCreateBranchInput,
@@ -552,6 +578,8 @@ interface RemoteMergeBranchOutput {
 
 export const vfRemoteMergeBranch: MCPTool<RemoteMergeBranchInput, RemoteMergeBranchOutput> = {
   name: "vf_remote_merge_branch",
+  title: "Merge Remote Branch",
+  annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
   description: "Merge a branch into the target branch (or main if not specified).",
   inputSchema: remoteMergeBranchInput,
   execute: async (input) => {
@@ -596,6 +624,13 @@ interface RemoteDeleteBranchOutput {
 
 export const vfRemoteDeleteBranch: MCPTool<RemoteDeleteBranchInput, RemoteDeleteBranchOutput> = {
   name: "vf_remote_delete_branch",
+  title: "Delete Remote Branch",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   description: "Delete a branch from a remote Veryfront project.",
   inputSchema: remoteDeleteBranchInput,
   execute: async (input) => {
@@ -633,6 +668,8 @@ interface RemoteCreateProjectOutput {
 
 export const vfRemoteCreateProject: MCPTool<RemoteCreateProjectInput, RemoteCreateProjectOutput> = {
   name: "vf_remote_create_project",
+  title: "Create Remote Project",
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   description: "Create a new Veryfront project. Returns the project details including ID and slug.",
   inputSchema: remoteCreateProjectInput,
   execute: async (input) => {
@@ -671,6 +708,8 @@ interface RemoteCloneProjectOutput {
 
 export const vfRemoteCloneProject: MCPTool<RemoteCloneProjectInput, RemoteCloneProjectOutput> = {
   name: "vf_remote_clone_project",
+  title: "Clone Remote Project",
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   description:
     "Clone a Veryfront project by creating a new project and copying all files from the source.",
   inputSchema: remoteCloneProjectInput,

package/src/cli/mcp/server.ts

@@ -13,11 +13,14 @@ import { createHttpServer, type HttpServer } from "../../src/platform/compat/htt
 import type { StdinReader } from "../../src/platform/index.js";
 import { withSpan } from "../../src/observability/tracing/otlp-setup.js";
 import { createIssuesManager } from "../../src/issues/index.js";
+import type { ToolListEntry } from "../../src/mcp/index.js";
 import { getErrorCollector, getLogBuffer } from "../../src/observability/index.js";
 import { allTools, getTool, setServerStartTime } from "./tools.js";
 import { startStdioJsonRpc } from "./stdio.js";
 import {
+  buildInitializeResult,
   errorResponse,
+  JsonRpcError,
   type JSONRPCRequest,
   JSONRPCRequestSchema,
   type JSONRPCResponse,
@@ -121,6 +124,17 @@ export class MCPDevServer {
 
       if (req.method === "OPTIONS") return new dntShim.Response(null, { status: 204, headers });
 
+      if (origin && !isAllowedOrigin) {
+        return new dntShim.Response(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            id: null,
+            error: { code: -32600, message: "Forbidden: Origin not allowed" },
+          }),
+          { status: 403, headers },
+        );
+      }
+
       if (url.pathname !== "/mcp") {
         return new dntShim.Response(JSON.stringify({ error: "Not found. MCP endpoint is at /mcp" }), {
           status: 404,
@@ -168,6 +182,8 @@ export class MCPDevServer {
     switch (method) {
       case "initialize":
         return Promise.resolve(this.handleInitialize(params));
+      case "notifications/initialized":
+        return Promise.resolve({});
       case "tools/list":
         return Promise.resolve(this.handleToolsList());
       case "tools/call":
@@ -185,53 +201,70 @@ export class MCPDevServer {
     }
   }
 
-  private handleInitialize(_params: unknown): unknown {
-    return {
-      protocolVersion: "2024-11-05",
-      capabilities: {
-        tools: {},
-        resources: {},
-        prompts: {},
+  private handleInitialize(params: unknown): unknown {
+    return buildInitializeResult(
+      params,
+      {
+        name: this.config.serverName ?? "veryfront-dev",
+        title: "Veryfront Dev MCP Server",
+        version: this.config.serverVersion ?? "1.0.0",
+        description:
+          "Veryfront development server tools for real-time errors, logs, HMR, and scaffolding",
       },
-      serverInfo: {
-        name: this.config.serverName,
-        version: this.config.serverVersion,
-      },
-    };
+      "Veryfront dev MCP server provides development tools. Use vf_get_errors to check for code errors, vf_get_logs for server logs, and vf_trigger_hmr for hot module reload.",
+    );
   }
 
-  private handleToolsList(): unknown {
+  private handleToolsList(): { tools: ToolListEntry[] } {
     return {
-      tools: allTools.map((tool) => ({
-        name: tool.name,
-        description: tool.description,
-        inputSchema: this.zodToJsonSchema(tool.inputSchema),
-      })),
+      tools: allTools.map((tool) => {
+        const entry: ToolListEntry = {
+          name: tool.name,
+          description: tool.description,
+          inputSchema: this.zodToJsonSchema(tool.inputSchema),
+        };
+        if (tool.title) entry.title = tool.title;
+        if (tool.annotations) entry.annotations = tool.annotations;
+        return entry;
+      }),
     };
   }
 
   private handleToolsCall(params: unknown): Promise<unknown> {
-    const { name, arguments: args } = ToolsCallParamsSchema.parse(params);
+    const { name: toolName, arguments: args } = ToolsCallParamsSchema.parse(params);
+
+    const tool = getTool(toolName);
+    if (!tool) {
+      throw new JsonRpcError(-32602, `Unknown tool: ${toolName}`);
+    }
+
+    let input: unknown;
+    try {
+      input = tool.inputSchema.parse(args ?? {});
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new JsonRpcError(-32602, `Invalid arguments for tool ${toolName}: ${message}`);
+    }
 
     return withSpan(
       "cli.mcp.handleToolsCall",
       async () => {
-        const tool = getTool(name);
-        if (!tool) throw new Error(`Unknown tool: ${name}`);
-
-        const input = tool.inputSchema.parse(args ?? {});
-        const result = await tool.execute(input);
+        try {
+          const result = await tool.execute(input);
 
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(result, null, 2),
-            },
-          ],
-        };
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            isError: false,
+          };
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{ type: "text", text: message }],
+            isError: true,
+          };
+        }
       },
-      { "mcp.tool.name": name },
+      { "mcp.tool.name": toolName },
     );
   }
 

package/src/cli/mcp/standalone.ts

@@ -11,7 +11,9 @@ import type { StdinReader } from "../../src/platform/index.js";
 import { DevServerClient } from "./dev-server-client.js";
 import { startStdioJsonRpc } from "./stdio.js";
 import {
+  buildInitializeResult,
   errorResponse,
+  JsonRpcError,
   type JSONRPCRequest,
   JSONRPCRequestSchema,
   type JSONRPCResponse,
@@ -79,11 +81,16 @@ export class StandaloneMCPServer {
   private dispatchMethod(method: string, params: unknown): Promise<unknown> {
     switch (method) {
       case "initialize":
-        return Promise.resolve({
-          protocolVersion: "2024-11-05",
-          capabilities: { tools: {}, resources: {}, prompts: {} },
-          serverInfo: { name: "veryfront-mcp", version: "1.0.0" },
-        });
+        return Promise.resolve(buildInitializeResult(
+          params,
+          {
+            name: "veryfront-mcp",
+            title: "Veryfront Standalone MCP Server",
+            version: "1.0.0",
+            description: "Veryfront standalone MCP server for CLI-based development tools",
+          },
+          "Veryfront standalone MCP server provides development tools. Use vf_get_errors to check for code errors, vf_get_logs for server logs, and vf_get_status for dev server health.",
+        ));
       case "notifications/initialized":
         return Promise.resolve({});
       case "tools/list":
@@ -110,13 +117,24 @@ export class StandaloneMCPServer {
   }
 
   private async handleToolsCall(params: unknown): Promise<unknown> {
-    const { name, arguments: args } = ToolsCallParamsSchema.parse(params);
+    const { name: toolName, arguments: args } = ToolsCallParamsSchema.parse(params);
 
-    const tool = this.tools.find((t) => t.name === name);
-    if (!tool) throw new Error(`Unknown tool: ${name}`);
+    const tool = this.tools.find((t) => t.name === toolName);
+    if (!tool) throw new JsonRpcError(-32602, `Unknown tool: ${toolName}`);
 
-    const result = await tool.execute(args ?? {});
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    try {
+      const result = await tool.execute(args ?? {});
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        isError: false,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        content: [{ type: "text", text: message }],
+        isError: true,
+      };
+    }
   }
 
   private handleResourcesList(): unknown {

package/src/cli/mcp/tools/catalog-tools.ts

@@ -334,8 +334,10 @@ type ListExamplesInput = z.infer<typeof listExamplesInput>;
 
 export const vfListExamples: MCPTool<ListExamplesInput, ExampleInfo[]> = {
   name: "vf_list_examples",
+  title: "List Examples",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "List example projects that demonstrate Veryfront features. Use these as references or starting points for new projects.",
+    "Use this when you need to browse example projects that demonstrate Veryfront features and integrations. Returns an array of example info with name, description, and category. Do not use for project templates — use vf_list_templates instead.",
   inputSchema: listExamplesInput,
   execute: () => Promise.resolve(EXAMPLES),
 };
@@ -350,8 +352,10 @@ type ListTemplatesInput = z.infer<typeof listTemplatesInput>;
 
 export const vfListTemplates: MCPTool<ListTemplatesInput, TemplateInfo[]> = {
   name: "vf_list_templates",
+  title: "List Templates",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true }, // openWorldHint: templates come from remote catalog API
   description:
-    "List available project templates. Use this to help users choose the right starting point for their project.",
+    "Use this when you need to list available project templates for creating new projects. Returns an array of template info with name and description. Do not use for example projects — use vf_list_examples instead.",
   inputSchema: listTemplatesInput,
   execute: () => Promise.resolve(TEMPLATES),
 };
@@ -372,8 +376,10 @@ type ListIntegrationsInput = z.infer<typeof listIntegrationsInput>;
 
 export const vfListIntegrations: MCPTool<ListIntegrationsInput, IntegrationInfo[]> = {
   name: "vf_list_integrations",
+  title: "List Integrations",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "List available service integrations (Gmail, Slack, GitHub, etc.). These can be added to AI projects to give agents access to external services.",
+    "Use this when you need to list available service integrations (Gmail, Slack, GitHub, etc.) that can be added to AI projects. Returns an array of integration info with name, category, and description. Do not use for adding integrations to a project — use vf_create_project with the integrations parameter instead.",
   inputSchema: listIntegrationsInput,
   execute: (input) => {
     const { category } = input;
@@ -392,8 +398,10 @@ type ListUsecasesInput = z.infer<typeof listUsecasesInput>;
 
 export const vfListUsecases: MCPTool<ListUsecasesInput, UsecaseInfo[]> = {
   name: "vf_list_usecases",
+  title: "List Use Cases",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "List pre-configured use-case templates. Each includes recommended integrations and UI layout for common scenarios.",
+    "Use this when you need to browse pre-configured use-case templates with recommended integrations and UI layouts. Returns an array of use-case info with name, integrations, and layout. Do not use for raw templates — use vf_list_templates instead.",
   inputSchema: listUsecasesInput,
   execute: () => Promise.resolve(USECASES),
 };
@@ -438,8 +446,10 @@ interface CreateProjectResult {
 
 export const vfCreateProject: MCPTool<CreateProjectInput, CreateProjectResult> = {
   name: "vf_create_project",
+  title: "Create Project",
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   description:
-    "Create a new Veryfront project from a template. This is the MCP equivalent of 'veryfront init'. Returns the project directory and next steps.",
+    "Use this when you need to create a new Veryfront project from a template. Returns the project directory and next steps. Do not use for scaffolding individual files — use vf_scaffold instead.",
   inputSchema: createProjectInput,
   execute: (input) =>
     withSpan(

package/src/cli/mcp/tools/cicd-tools.ts

@@ -8,6 +8,8 @@ const getPipelineStatusInput = z.object({
 
 const vfGetPipelineStatus: MCPTool = {
   name: "vf_get_pipeline_status",
+  title: "Pipeline Status",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description: "Get the current build/deploy pipeline state for a project environment.",
   inputSchema: getPipelineStatusInput,
   execute: async (input: { projectSlug: string; environment: string }) => {
@@ -27,6 +29,8 @@ const getDeployHistoryInput = z.object({
 
 const vfGetDeployHistory: MCPTool = {
   name: "vf_get_deploy_history",
+  title: "Deploy History",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description: "List recent deployments with status, version, URL, and timestamp.",
   inputSchema: getDeployHistoryInput,
   execute: async (input: { projectSlug: string; limit: number }) => {
@@ -45,6 +49,8 @@ const getBuildLogsInput = z.object({
 
 const vfGetBuildLogs: MCPTool = {
   name: "vf_get_build_logs",
+  title: "Build Logs",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description: "Get build logs from an active or recent build/deployment.",
   inputSchema: getBuildLogsInput,
   execute: async (input: { projectSlug: string; deployId?: string }) => {
@@ -64,6 +70,8 @@ const triggerDeployInput = z.object({
 
 const vfTriggerDeploy: MCPTool = {
   name: "vf_trigger_deploy",
+  title: "Trigger Deploy",
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   description:
     "Trigger a deployment to an environment. Returns a deployment ID for status tracking.",
   inputSchema: triggerDeployInput,

package/src/cli/mcp/tools/dev-tools.ts

@@ -20,7 +20,7 @@ const hotReloadInput = z.object({
   file: z
     .string()
     .optional()
-    .describe("Specific file to trigger reload for (optional - reloads all if not specified)"),
+    .describe("Specific file to trigger reload for. Example: 'app/page.tsx'. Omit to reload all."),
 });
 
 type HotReloadInput = z.infer<typeof hotReloadInput>;
@@ -32,8 +32,15 @@ interface HotReloadResult {
 
 export const vfHotReload: MCPTool<HotReloadInput, HotReloadResult> = {
   name: "vf_hot_reload",
+  title: "Hot Reload",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   description:
-    "Trigger a hot reload of the dev server. Use after making changes to see them instantly.",
+    "Use this when you need to signal that a hot reload should occur. Note: currently a no-op stub that returns success without triggering an actual reload. For file-level HMR that sends a WebSocket update, use vf_trigger_hmr instead.",
   inputSchema: hotReloadInput,
   execute: () =>
     Promise.resolve({
@@ -72,8 +79,10 @@ interface DebugContextResult {
 
 export const vfGetDebugContext: MCPTool<GetDebugContextInput, DebugContextResult> = {
   name: "vf_get_debug_context",
+  title: "Debug Context",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "Get the current server context including project info, environment, and mode. Useful for debugging server configuration issues.",
+    "Use this when you need the dev server's debug context including project slug, environment, request context mode, and multi-project configuration. Returns project info and server mode. Do not use for error details — use vf_get_errors instead.",
   inputSchema: getDebugContextInput,
   execute: (input) =>
     withSpan(
@@ -114,7 +123,7 @@ export const vfGetDebugContext: MCPTool<GetDebugContextInput, DebugContextResult
 // ============================================================================
 
 const triggerHmrInput = z.object({
-  path: z.string().describe("File path that changed (e.g., 'app/page.tsx')"),
+  path: z.string().describe("File path that changed. Example: 'app/page.tsx'."),
   port: z.number().int().min(1).max(65535).optional().default(8080).describe(
     "Dev server port (defaults to 8080)",
   ),
@@ -129,8 +138,15 @@ interface TriggerHmrResult {
 
 export const vfTriggerHmr: MCPTool<TriggerHmrInput, TriggerHmrResult> = {
   name: "vf_trigger_hmr",
+  title: "Trigger HMR",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   description:
-    "Trigger Hot Module Replacement for a specific file. The browser will update without a full reload.",
+    "Use this when you need to force an HMR update for a specific file path. Sends a WebSocket reload notification to connected browsers. Returns success status and active listener count. Do not use if no browser is connected — check vf_get_flywheel_status first.",
   inputSchema: triggerHmrInput,
   execute: (input) => {
     const metrics = ReloadNotifier.getMetrics();
@@ -156,7 +172,7 @@ export const vfTriggerHmr: MCPTool<TriggerHmrInput, TriggerHmrResult> = {
 
 const previewRouteInput = z.object({
   route: z.string().startsWith("/", "Route must start with /").describe(
-    "Route path to preview (e.g., '/', '/dashboard', '/api/users')",
+    "Route path to preview. Example: '/', '/dashboard', '/api/users'.",
   ),
   port: z.number().int().min(1).max(65535).optional().default(8080).describe(
     "Dev server port (defaults to 8080)",
@@ -165,7 +181,9 @@ const previewRouteInput = z.object({
     .enum(["html", "json", "status"])
     .optional()
     .default("status")
-    .describe("Output format: html (full page), json (API response), status (just HTTP status)"),
+    .describe(
+      "Output format: 'html' for full page, 'json' for API response, 'status' for just HTTP status. Defaults to 'status'.",
+    ),
 });
 
 type PreviewRouteInput = z.infer<typeof previewRouteInput>;
@@ -182,8 +200,10 @@ interface PreviewRouteResult {
 
 export const vfPreviewRoute: MCPTool<PreviewRouteInput, PreviewRouteResult> = {
   name: "vf_preview_route",
+  title: "Preview Route",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "Preview a route by making a request to the dev server. Returns the rendered output, HTTP status, and render time. Perfect for testing changes instantly.",
+    "Use this when you need to test-render a route and inspect the response. Returns rendered output, HTTP status, and render time. Note: API routes may have side effects. Do not use for listing routes — use vf_list_routes instead.",
   inputSchema: previewRouteInput,
   execute: (input) =>
     withSpan(
@@ -263,8 +283,10 @@ interface WaitForReadyResult {
 
 export const vfWaitForReady: MCPTool<WaitForReadyInput, WaitForReadyResult> = {
   name: "vf_wait_for_ready",
+  title: "Wait for Ready",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "Wait for the server to be ready by polling the health endpoint. Use this after starting the server to ensure it's accepting requests.",
+    "Use this when you need to wait for the dev server to become ready after restart. Polls the health endpoint until responsive. Returns success status and elapsed time. Do not use for error counts or uptime — use vf_get_status instead.",
   inputSchema: waitForReadyInput,
   execute: (input) =>
     withSpan(
@@ -351,8 +373,10 @@ interface FlywheelStatus {
 
 export const vfGetFlywheelStatus: MCPTool<GetFlywheelStatusInput, FlywheelStatus> = {
   name: "vf_get_flywheel_status",
+  title: "Flywheel Status",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "Get aggregated status for the development flywheel. Shows server state, error counts, log summary, and HMR status in one view.",
+    "Use this when you need a comprehensive status overview combining server health, error counts, and HMR statistics. Returns server status, error/log counts, and HMR metrics in one response. Do not use for detailed error or log content — use vf_get_errors or vf_get_logs instead.",
   inputSchema: getFlywheelStatusInput,
   execute: (input) =>
     withSpan(

package/src/cli/mcp/tools/introspection-tools.ts

@@ -11,8 +11,10 @@ const getSchemaInput = z.object({
 
 const vfGetSchema: MCPTool = {
   name: "vf_get_schema",
+  title: "Get CLI Schema",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "Get the CLI command schema for discovering available commands, arguments, and flags.",
+    "Use this when you need to discover available CLI commands, their arguments, and flags. Returns the command schema as JSON. Do not use for project info — use vf_get_project_info instead.",
   inputSchema: getSchemaInput,
   execute: async (input: { command?: string; category?: string }) => {
     if (input.command) {
@@ -26,7 +28,10 @@ const getProjectInfoInput = z.object({});
 
 const vfGetProjectInfo: MCPTool = {
   name: "vf_get_project_info",
-  description: "Get project metadata including project slug, version, and environment.",
+  title: "Get Project Info",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  description:
+    "Use this when you need project metadata including project slug, version, and environment. Returns slug, version, and environment config. Do not use for CLI commands — use vf_get_schema instead.",
   inputSchema: getProjectInfoInput,
   execute: async () => {
     const { getEnvironmentConfig } = await import("../../../src/config/index.js");