veryfront 0.1.140 → 0.1.142

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

package/src/cli/mcp/tools.ts

@@ -35,18 +35,24 @@ export function setServerStartTime(time: number): void {
 
 const getErrorsInput = z.object({
   type: z.enum(["compile", "runtime", "bundle", "hmr", "module"]).optional().describe(
-    "Filter by error type",
+    "Filter by error type. Example: 'compile'. Omit to return all types.",
+  ),
+  file: z.string().optional().describe(
+    "Filter by file path. Example: 'app/page.tsx'. Omit to return errors from all files.",
+  ),
+  limit: z.number().optional().default(50).describe(
+    "Maximum number of errors to return. Defaults to 50.",
   ),
-  file: z.string().optional().describe("Filter by file path"),
-  limit: z.number().optional().default(50).describe("Maximum number of errors to return"),
 });
 
 type GetErrorsInput = z.infer<typeof getErrorsInput>;
 
 export const vfGetErrors: MCPTool<GetErrorsInput, DevError[]> = {
   name: "vf_get_errors",
+  title: "Get Errors",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "Get compilation, runtime, and build errors from the dev server. Use this to debug issues with your code.",
+    "Use this when you need to check for compilation, runtime, bundle, HMR, or module errors in the dev server. Returns error details including file path, line number, and message. Do not use for server logs — use vf_get_logs instead.",
   inputSchema: getErrorsInput,
   execute: async (input) => {
     const errors = getErrorCollector().getAll({
@@ -60,21 +66,31 @@ export const vfGetErrors: MCPTool<GetErrorsInput, DevError[]> = {
 };
 
 const getLogsInput = z.object({
-  level: z.enum(["debug", "info", "warn", "error"]).optional().describe("Filter by log level"),
+  level: z.enum(["debug", "info", "warn", "error"]).optional().describe(
+    "Filter by log level. Example: 'error'. Omit to return all levels.",
+  ),
   source: z.string().optional().describe(
-    "Filter by log source (e.g., 'server', 'hmr', 'transform')",
+    "Filter by log source. Example: 'server', 'hmr', 'transform'. Omit to return all sources.",
+  ),
+  pattern: z.string().optional().describe(
+    "Filter by pattern (case-insensitive substring match). Example: 'timeout'.",
+  ),
+  limit: z.number().optional().default(100).describe(
+    "Maximum number of log entries to return. Defaults to 100.",
+  ),
+  since: z.number().optional().describe(
+    "Only return logs after this Unix timestamp in milliseconds.",
   ),
-  pattern: z.string().optional().describe("Filter by pattern (case-insensitive substring match)"),
-  limit: z.number().optional().default(100).describe("Maximum number of log entries to return"),
-  since: z.number().optional().describe("Only return logs after this timestamp"),
 });
 
 type GetLogsInput = z.infer<typeof getLogsInput>;
 
 export const vfGetLogs: MCPTool<GetLogsInput, LogEntry[]> = {
   name: "vf_get_logs",
+  title: "Get Logs",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "Get recent server logs. Use this to understand what the server is doing and debug runtime issues.",
+    "Use this when you need to inspect server logs to understand runtime behavior or debug request handling. Returns log entries with timestamp, level, source, and message. Do not use for build/compile errors — use vf_get_errors instead.",
   inputSchema: getLogsInput,
   execute: async (input) => {
     return getLogBuffer().query({
@@ -89,7 +105,7 @@ export const vfGetLogs: MCPTool<GetLogsInput, LogEntry[]> = {
 
 const clearCacheInput = z.object({
   type: z.enum(["all", "modules", "mdx"]).optional().default("all").describe(
-    "Type of cache to clear",
+    "Type of cache to clear. Example: 'modules'. Defaults to 'all'.",
   ),
 });
 
@@ -102,8 +118,15 @@ interface ClearCacheOutput {
 
 export const vfClearCache: MCPTool<ClearCacheInput, ClearCacheOutput> = {
   name: "vf_clear_cache",
+  title: "Clear Cache",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   description:
-    "Clear module and build caches. Use this when changes aren't being reflected or to force a rebuild.",
+    "Use this when the dev server shows stale modules or MDX content. Returns the list of cleared cache directories. Do not use to fix code errors — those require code changes.",
   inputSchema: clearCacheInput,
   execute: async (input) => {
     const fs = createFileSystem();
@@ -143,7 +166,10 @@ export function createVfGetStatus(
 ): MCPTool<GetStatusInput, ServerStatus> {
   return {
     name: "vf_get_status",
-    description: "Get the current status of the dev server including error counts and uptime.",
+    title: "Server Status",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description:
+      "Use this when you need a quick summary of the dev server's uptime, error counts, and warning counts. Note: always reports running=true when the MCP server is reachable. Do not use for detailed error info — use vf_get_errors instead.",
     inputSchema: getStatusInput,
     execute: async () => {
       const errors = getErrorCollector();
@@ -167,9 +193,11 @@ export function createVfGetStatus(
 export const vfGetStatus = createVfGetStatus();
 
 const clearErrorsInput = z.object({
-  file: z.string().optional().describe("Clear errors for a specific file only"),
+  file: z.string().optional().describe(
+    "Clear errors for a specific file only. Example: 'app/page.tsx'. Omit to clear all files.",
+  ),
   type: z.enum(["compile", "runtime", "bundle", "hmr", "module"]).optional().describe(
-    "Clear errors of a specific type only",
+    "Clear errors of a specific type only. Example: 'compile'. Omit to clear all types.",
   ),
 });
 
@@ -181,7 +209,15 @@ interface ClearErrorsOutput {
 
 export const vfClearErrors: MCPTool<ClearErrorsInput, ClearErrorsOutput> = {
   name: "vf_clear_errors",
-  description: "Clear errors from the error collector. Useful after fixing issues.",
+  title: "Clear Errors",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  description:
+    "Use this when you need to clear accumulated errors from the error collector, optionally filtering by file or type. Returns the number of cleared errors. Do not use for viewing errors — use vf_get_errors instead.",
   inputSchema: clearErrorsInput,
   execute: async (input) => {
     const collector = getErrorCollector();

package/src/deno.js

@@ -1,6 +1,6 @@
 export default {
   "name": "veryfront",
-  "version": "0.1.140",
+  "version": "0.1.142",
   "license": "Apache-2.0",
   "nodeModulesDir": "auto",
   "exclude": [

package/src/src/agent/runtime/index.ts

@@ -406,7 +406,7 @@ export class AgentRuntime {
           logger.error("Agent stream error", { error });
           sendSSE(controller, encoder, {
             type: "error",
-            error: "An internal error occurred",
+            error: error instanceof Error ? error.message : String(error),
           });
           closeSSEStream(controller);
         } finally {

package/src/src/agent/runtime/tool-helpers.ts

@@ -11,6 +11,7 @@ import { executeTool, toolRegistry } from "../../tool/index.js";
 import { toolToProviderDefinition } from "../../tool/registry.js";
 import { SKILL_TOOL_IDS } from "../../skill/types.js";
 import { serverLogger } from "../../utils/index.js";
+import { createError, toError } from "../../errors/veryfront-error.js";
 import {
   executeRemoteIntegrationTool,
   isRemoteIntegrationTool,
@@ -71,6 +72,52 @@ export function isDynamicTool(name: string): boolean {
 // deno-lint-ignore no-explicit-any -- generic erasure: accepts Tool with any input/output types
 export type ToolConfigEntry = Tool<any, any> | boolean;
 
+function formatAvailableToolNames(names: Iterable<string>): string {
+  const sorted = [...new Set(names)].sort();
+  return sorted.length > 0 ? sorted.join(", ") : "(none)";
+}
+
+function throwUnknownConfiguredToolsError(
+  unknownToolNames: string[],
+  availableLocalToolNames: Iterable<string>,
+  availableRemoteToolNames: Iterable<string>,
+): never {
+  const unknownList = unknownToolNames.sort().join(", ");
+  const availableNames = formatAvailableToolNames([
+    ...availableLocalToolNames,
+    ...availableRemoteToolNames,
+  ]);
+
+  throw toError(
+    createError({
+      type: "agent",
+      message:
+        `Unknown tool reference${unknownToolNames.length === 1 ? "" : "s"}: ${unknownList}. ` +
+        `Tool names must exactly match tool({ id: "..." }). Available tools: ${availableNames}`,
+    }),
+  );
+}
+
+async function getRemoteToolDefinitions(options?: {
+  includeIntegrationTools?: boolean;
+  allowedRemoteToolNames?: string[];
+}): Promise<ToolDefinition[]> {
+  if (options?.includeIntegrationTools === false) {
+    return [];
+  }
+
+  try {
+    const { getRemoteIntegrationToolDefinitions } = await import(
+      "../../integrations/remote-tools.js"
+    );
+    return (await getRemoteIntegrationToolDefinitions()).filter((def) =>
+      !options?.allowedRemoteToolNames || options.allowedRemoteToolNames.includes(def.name)
+    );
+  } catch {
+    return [];
+  }
+}
+
 export function resolveConfiguredTool(
   toolsConfig: true | Record<string, ToolConfigEntry> | undefined,
   toolName: string,
@@ -179,32 +226,35 @@ export async function getAvailableTools(
     });
 
     // Append remote integration tools (per-request, project-scoped)
-    if (options?.includeIntegrationTools !== false) {
-      try {
-        const { getRemoteIntegrationToolDefinitions } = await import(
-          "../../integrations/remote-tools.js"
-        );
-        const remoteDefs = (await getRemoteIntegrationToolDefinitions()).filter((def) =>
-          !options?.allowedRemoteToolNames || options.allowedRemoteToolNames.includes(def.name)
-        );
-        for (const def of remoteDefs) {
-          logToolDefinition(def.name, def);
-        }
-        tools.push(...remoteDefs);
-      } catch {
-        // Integration tools unavailable — non-fatal
-      }
+    const remoteDefs = await getRemoteToolDefinitions(options);
+    for (const def of remoteDefs) {
+      logToolDefinition(def.name, def);
     }
+    tools.push(...remoteDefs);
 
     return tools;
   }
 
   const tools: ToolDefinition[] = [];
+  const remoteDefs = await getRemoteToolDefinitions(options);
+  const remoteToolNames = new Set(remoteDefs.map((def) => def.name));
+  const explicitlyRequestedRemoteToolNames = new Set<string>();
+  const unresolvedConfiguredToolNames: string[] = [];
 
   for (const [name, entry] of Object.entries(toolsConfig)) {
     if (entry === true) {
       const tool = toolRegistry.get(name);
-      if (tool) addToolDefinition(tools, name, tool);
+      if (tool) {
+        addToolDefinition(tools, name, tool);
+        continue;
+      }
+
+      if (remoteToolNames.has(name)) {
+        explicitlyRequestedRemoteToolNames.add(name);
+        continue;
+      }
+
+      unresolvedConfiguredToolNames.push(name);
       continue;
     }
 
@@ -213,28 +263,28 @@ export async function getAvailableTools(
     }
   }
 
-  // Also append remote integration tools for explicit-object configs.
-  // The internal streaming path converts `tools: true` to an explicit object
-  // from the local registry, so remote tools would be missed without this.
-  if (options?.includeIntegrationTools !== false) {
-    try {
-      const { getRemoteIntegrationToolDefinitions } = await import(
-        "../../integrations/remote-tools.js"
-      );
-      const remoteDefs = (await getRemoteIntegrationToolDefinitions()).filter((def) =>
-        !options?.allowedRemoteToolNames || options.allowedRemoteToolNames.includes(def.name)
-      );
-      for (const def of remoteDefs) {
-        // Skip if already present (e.g., explicitly configured by name)
-        if (!tools.some((t) => t.name === def.name)) {
-          logToolDefinition(def.name, def);
-          tools.push(def);
-        }
-      }
-    } catch {
-      // Integration tools unavailable — non-fatal
+  // Explicit-object configs should only expose remote definitions that were
+  // explicitly requested, except for the internal runtime path that expands
+  // `tools: true` into an explicit local-tool map and passes the remote allowlist.
+  const remoteDefsToAppend = explicitlyRequestedRemoteToolNames.size > 0
+    ? remoteDefs.filter((def) => explicitlyRequestedRemoteToolNames.has(def.name))
+    : remoteDefs.filter((def) => options?.allowedRemoteToolNames?.includes(def.name));
+
+  for (const def of remoteDefsToAppend) {
+    // Skip if already present (e.g., explicitly configured by name)
+    if (!tools.some((t) => t.name === def.name)) {
+      logToolDefinition(def.name, def);
+      tools.push(def);
     }
   }
 
+  if (unresolvedConfiguredToolNames.length > 0) {
+    throwUnknownConfiguredToolsError(
+      unresolvedConfiguredToolNames,
+      toolRegistry.getAll().keys(),
+      remoteToolNames,
+    );
+  }
+
   return tools;
 }

package/src/src/internal-agents/run-stream.ts

@@ -17,8 +17,10 @@ import {
 } from "./ag-ui-sse.js";
 import { AgentRunCancelledError, type AgentRunSessionManager } from "./session-manager.js";
 import type { RuntimeRunAgentInput } from "./schema.js";
+import { serverLogger } from "../utils/index.js";
 
 const anyObjectSchema = z.record(z.string(), z.unknown());
+const logger = serverLogger.component("internal-agent-run-stream");
 
 type RuntimeFilteredAgent = Agent & {
   config: Agent["config"] & {
@@ -230,6 +232,14 @@ export async function createRuntimeAgentStreamResponse(
   agent: Agent,
   deps: RuntimeAgentStreamExecutionDeps,
 ): Promise<dntShim.Response> {
+  logger.info("Starting internal agent runtime stream", {
+    runId: input.runId,
+    threadId: input.threadId,
+    agentId: input.agentId,
+    messageCount: input.messages.length,
+    toolCount: input.tools.length,
+    contextCount: input.context.length,
+  });
   const abortSignal = deps.sessionManager.startRun({
     runId: input.runId,
     threadId: input.threadId,
@@ -272,8 +282,19 @@ export async function createRuntimeAgentStreamResponse(
       undefined,
       abortSignal,
     );
+    logger.info("Internal agent runtime stream attached", {
+      runId: input.runId,
+      threadId: input.threadId,
+      agentId: input.agentId,
+    });
   } catch (error) {
     deps.sessionManager.failRun(input.runId);
+    logger.error("Internal agent runtime stream setup failed", {
+      runId: input.runId,
+      threadId: input.threadId,
+      agentId: input.agentId,
+      error: error instanceof Error ? error.message : String(error),
+    });
     throw error;
   }
 
@@ -306,6 +327,11 @@ export async function createRuntimeAgentStreamResponse(
 
       const abortHandler = () => {
         aborted = true;
+        logger.warn("Internal agent runtime stream aborted", {
+          runId: input.runId,
+          threadId: input.threadId,
+          agentId: input.agentId,
+        });
         reader.cancel(new AgentRunCancelledError()).catch(() => {});
       };
 
@@ -324,6 +350,11 @@ export async function createRuntimeAgentStreamResponse(
           throwIfAborted();
 
           if (done) {
+            logger.info("Internal agent runtime stream reader completed", {
+              runId: input.runId,
+              threadId: input.threadId,
+              agentId: input.agentId,
+            });
             break;
           }
 
@@ -353,15 +384,35 @@ export async function createRuntimeAgentStreamResponse(
           enqueueIfAttached(mappedEvent.event, mappedEvent.payload);
         }
         deps.sessionManager.completeRun(input.runId);
+        logger.info("Internal agent runtime stream finalized", {
+          runId: input.runId,
+          threadId: input.threadId,
+          agentId: input.agentId,
+          sawVisibleOutput: state.sawVisibleOutput,
+          sawTerminalError: state.sawTerminalError,
+          finishReason: state.metadata.finishReason,
+        });
       } catch (error) {
         if (error instanceof AgentRunCancelledError) {
           deps.sessionManager.cancelRun(input.runId);
+          logger.warn("Internal agent runtime stream cancelled", {
+            runId: input.runId,
+            threadId: input.threadId,
+            agentId: input.agentId,
+            error: error.message,
+          });
           enqueueIfAttached("RunError", {
             code: "CANCELLED",
             message: error.message,
           });
         } else {
           deps.sessionManager.failRun(input.runId);
+          logger.error("Internal agent runtime stream failed", {
+            runId: input.runId,
+            threadId: input.threadId,
+            agentId: input.agentId,
+            error: error instanceof Error ? error.message : String(error),
+          });
           enqueueIfAttached("RunError", {
             code: "RUNTIME_ERROR",
             message: error instanceof Error ? error.message : String(error),
@@ -372,10 +423,21 @@ export async function createRuntimeAgentStreamResponse(
         if (clientAttached) {
           controller.close();
         }
+        logger.debug("Internal agent runtime stream response closed", {
+          runId: input.runId,
+          threadId: input.threadId,
+          agentId: input.agentId,
+          clientAttached,
+        });
       }
     },
     cancel() {
       clientAttached = false;
+      logger.info("Internal agent runtime client detached", {
+        runId: input.runId,
+        threadId: input.threadId,
+        agentId: input.agentId,
+      });
       return Promise.resolve();
     },
   });

package/src/src/issues/mcp.ts

@@ -53,8 +53,11 @@ type IssuesCreateInput = z.infer<typeof issuesCreateInput>;
 
 const issuesCreate: MCPTool<IssuesCreateInput, Issue> = {
   name: "issues_create",
-  description: "Create a new issue, task, or plan as a markdown file. " +
-    "Use prefix 'TASK' for small work items, 'PLAN' for proposals/RFCs, 'ISSUE' for bugs/features.",
+  title: "Create Issue",
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+  description: "Use this when you need to create a new issue, task, or plan as a markdown file. " +
+    "Use prefix 'TASK' for small work items, 'PLAN' for proposals/RFCs, 'ISSUE' for bugs/features. " +
+    "Returns the created issue. Do not use for updating — use issues_update instead.",
   inputSchema: issuesCreateInput,
   execute: async (input) => {
     const manager = getManager(input.projectDir);
@@ -81,7 +84,10 @@ type IssuesGetInput = z.infer<typeof issuesGetInput>;
 
 const issuesGet: MCPTool<IssuesGetInput, Issue | null> = {
   name: "issues_get",
-  description: "Get a specific issue by ID. Returns null if not found.",
+  title: "Get Issue",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  description:
+    "Use this when you need to retrieve a specific issue by its ID. Returns the issue or null if not found. Do not use for listing — use issues_list instead.",
   inputSchema: issuesGetInput,
   execute: async (input) => {
     const manager = getManager(input.projectDir);
@@ -107,8 +113,16 @@ type IssuesUpdateInput = z.infer<typeof issuesUpdateInput>;
 
 const issuesUpdate: MCPTool<IssuesUpdateInput, Issue | null> = {
   name: "issues_update",
-  description: "Update an existing issue. Only provided fields are updated. " +
-    "Returns the updated issue or null if not found.",
+  title: "Update Issue",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  description:
+    "Use this when you need to modify an existing issue. Only provided fields are updated. " +
+    "Returns the updated issue or null if not found. Do not use to close — use issues_close instead.",
   inputSchema: issuesUpdateInput,
   execute: async (input) => {
     const manager = getManager(input.projectDir);
@@ -153,8 +167,10 @@ interface IssuesListOutput {
 
 const issuesList: MCPTool<IssuesListInput, IssuesListOutput> = {
   name: "issues_list",
-  description: "List issues with filtering and sorting. " +
-    "Returns matching issues and total count.",
+  title: "List Issues",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  description: "Use this when you need to find issues matching criteria. " +
+    "Returns matching issues and total count. Do not use to get a single known issue — use issues_get instead.",
   inputSchema: issuesListInput,
   execute: async (input) => {
     const manager = getManager(input.projectDir);
@@ -183,7 +199,15 @@ type IssuesCloseInput = z.infer<typeof issuesCloseInput>;
 
 const issuesClose: MCPTool<IssuesCloseInput, Issue | null> = {
   name: "issues_close",
-  description: "Close an issue. Returns the updated issue or null if not found.",
+  title: "Close Issue",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  description:
+    "Use this when you need to close an issue. Returns the updated issue or null if not found. Do not use to delete — use issues_delete instead.",
   inputSchema: issuesCloseInput,
   execute: async (input) => {
     const manager = getManager(input.projectDir);
@@ -207,8 +231,17 @@ interface IssuesDeleteOutput {
 
 const issuesDelete: MCPTool<IssuesDeleteInput, IssuesDeleteOutput> = {
   name: "issues_delete",
-  description: "Permanently delete an issue file. " +
-    "Use with caution - this cannot be undone.",
+  title: "Delete Issue",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  description:
+    "Use this when you need to permanently delete an issue. Returns {deleted: true/false}. " +
+    "WARNING: this is irreversible and cannot be undone. Prefer issues_close unless permanent deletion is explicitly requested. " +
+    "Do not use to close — use issues_close instead.",
   inputSchema: issuesDeleteInput,
   execute: async (input) => {
     const manager = getManager(input.projectDir);

package/src/src/mcp/index.ts

@@ -24,7 +24,13 @@
 import "../../_dnt.polyfills.js";
 
 
-export type { MCPServerConfig, MCPStats, MCPTool } from "./types.js";
+export type {
+  MCPServerConfig,
+  MCPStats,
+  MCPTool,
+  ToolAnnotations,
+  ToolListEntry,
+} from "./types.js";
 
 export {
   clearMCPRegistry,