veryfront 0.1.141 → 0.1.142

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");

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

@@ -37,8 +37,10 @@ type ListRoutesInput = z.infer<typeof listRoutesInput>;
 
 export const vfListRoutes: MCPTool<ListRoutesInput, RouteInfo[]> = {
   name: "vf_list_routes",
+  title: "List Routes",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "Discover all routes in the project. Returns pages, API routes, layouts, and special routes. Use this to understand the project structure before making changes.",
+    "Use this when you need to discover all routes in the project including pages, API routes, layouts, error, loading, and not-found routes. Returns an array of route info with path, type, and file. Do not use for rendering a route — use vf_preview_route instead.",
   inputSchema: listRoutesInput,
   execute: (input) =>
     withSpan(
@@ -142,8 +144,10 @@ async function getProjectName(projectDir: string, fs: FileSystem): Promise<strin
 
 export const vfGetProjectContext: MCPTool<GetProjectContextInput, ProjectContext> = {
   name: "vf_get_project_context",
+  title: "Project Context",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "Get deep understanding of the project structure, conventions, and capabilities. Use this at the start of any coding session to understand the project before making changes.",
+    "Use this when you need to understand the project structure, conventions, and capabilities at the start of a coding session. Also returns route information. Do not use for detailed per-route rendering — use vf_preview_route instead.",
   inputSchema: getProjectContextInput,
   execute: (input) =>
     withSpan(
@@ -219,8 +223,10 @@ function toRelativePath(absolutePath: string, projectDir: string): string {
 
 export const vfGetComponentTree: MCPTool<GetComponentTreeInput, ComponentTreeResult> = {
   name: "vf_get_component_tree",
+  title: "Component Tree",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "Analyze the component hierarchy for a route. Shows layouts, providers, and components that render on this route. Helps understand the rendering structure.",
+    "Use this when you need to analyze the component hierarchy for a specific route including layouts, providers, and nested components. Returns the component tree structure. Do not use for listing all routes — use vf_list_routes instead.",
   inputSchema: getComponentTreeInput,
   execute: (input) =>
     withSpan(
@@ -375,8 +381,10 @@ async function scanForProjects(
 
 export const vfListLocalProjects: MCPTool<ListLocalProjectsInput, LocalProjectInfo[]> = {
   name: "vf_list_local_projects",
+  title: "List Local Projects",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "Discover Veryfront projects on the local filesystem. Scans for veryfront.config.ts files and returns project info including template type and integrations.",
+    "Use this when you need to discover Veryfront projects on the local filesystem by scanning for veryfront.config.ts files. Returns project info including template type and integrations. Do not use for project structure details — use vf_get_project_context instead.",
   inputSchema: listLocalProjectsInput,
   execute: (input) =>
     withSpan(

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

@@ -209,8 +209,10 @@ const SCAFFOLD_CONFIGS: Record<ScaffoldType, ScaffoldConfig> = {
 
 export const vfScaffold: MCPTool<ScaffoldInput, ScaffoldResult> = {
   name: "vf_scaffold",
+  title: "Scaffold Code",
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   description:
-    "Generate new entities (pages, API routes, layouts, components, AI tools, agents, prompts) with proper conventions. This is the recommended way to create new files in a Veryfront project.",
+    "Use this when you need to generate new pages, API routes, layouts, components, AI tools, agents, or prompts with proper Veryfront conventions. Returns the created file path and content. May overwrite existing files at the target path. Do not use for creating entire projects — use vf_create_project instead.",
   inputSchema: scaffoldInput,
   execute: (input) =>
     withSpan(
@@ -400,8 +402,10 @@ const CONVENTIONS: Record<string, Convention> = {
 
 export const vfGetConventions: MCPTool<GetConventionsInput, Convention[]> = {
   name: "vf_get_conventions",
+  title: "Get Conventions",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "Get Veryfront coding conventions and best practices. Use this as guardrails when writing code to ensure consistency with the project standards.",
+    "Use this when you need Veryfront coding conventions and best practices for routing, API, components, AI, or styling. Do not use for project structure — use vf_get_project_context instead.",
   inputSchema: getConventionsInput,
   execute: (input) => {
     if (input.topic === "all") return Promise.resolve(Object.values(CONVENTIONS));

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

@@ -91,8 +91,10 @@ interface GetSkillsResult {
 
 export const vfGetSkills: MCPTool<GetSkillsInput, GetSkillsResult> = {
   name: "vf_get_skills",
+  title: "Get Skills",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "Discover available Agent Skills for Veryfront development. Skills provide procedural knowledge for using MCP tools effectively. Call without name param to list all skills, or with name to get full skill content.",
+    "Use this when you need to discover available Agent Skills or load a specific skill's procedural knowledge. Returns skill names and descriptions, or full skill content when name is provided. Do not use for skill reference docs — use vf_get_skill_reference instead.",
   inputSchema: getSkillsInput,
   execute: (input) =>
     withSpan(
@@ -168,8 +170,10 @@ interface GetSkillReferenceResult {
 
 export const vfGetSkillReference: MCPTool<GetSkillReferenceInput, GetSkillReferenceResult> = {
   name: "vf_get_skill_reference",
+  title: "Get Skill Reference",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "Get a specific reference document from a skill. Use this to load detailed documentation on demand.",
+    "Use this when you need to load a specific reference document from a skill. Returns the document content as text. Do not use for skill discovery — use vf_get_skills instead.",
   inputSchema: getSkillReferenceInput,
   execute: async (input) => {
     const fs = getFs();