@anton.andrusenko/shopify-mcp-admin 0.1.0 → 0.3.0

package/dist/index.js

@@ -10,8 +10,11 @@ import { z } from "zod";
 var configSchema = z.object({
   // Required - store identity
   SHOPIFY_STORE_URL: z.string().min(1, "SHOPIFY_STORE_URL is required").regex(/\.myshopify\.com$/, "Must be a valid myshopify.com domain"),
-  // Required - authentication
-  SHOPIFY_ACCESS_TOKEN: z.string().min(1, "SHOPIFY_ACCESS_TOKEN is required"),
+  // Authentication Option 1: Legacy Custom App (static token)
+  SHOPIFY_ACCESS_TOKEN: z.string().optional(),
+  // Authentication Option 2: Dev Dashboard (OAuth 2.0 client credentials)
+  SHOPIFY_CLIENT_ID: z.string().optional(),
+  SHOPIFY_CLIENT_SECRET: z.string().optional(),
   // Optional with defaults
   SHOPIFY_API_VERSION: z.string().default("2025-10"),
   DEBUG: z.string().optional(),
@@ -19,8 +22,52 @@ var configSchema = z.object({
   PORT: z.string().default("3000").transform(Number),
   // Transport selection (AC-2.2.6, AC-2.2.7)
   // Default: stdio for Claude Desktop compatibility
-  TRANSPORT: z.enum(["stdio", "http"]).default("stdio")
-});
+  TRANSPORT: z.enum(["stdio", "http"]).default("stdio"),
+  // Store info cache TTL (milliseconds)
+  // Default: 5 minutes (300000ms) - configurable for performance tuning
+  STORE_INFO_CACHE_TTL_MS: z.string().optional().default("300000").transform(Number).describe("Cache TTL for store info in milliseconds (default: 5 minutes)")
+}).refine(
+  (data) => {
+    const hasLegacyAuth = !!data.SHOPIFY_ACCESS_TOKEN;
+    const hasClientId = !!data.SHOPIFY_CLIENT_ID;
+    const hasClientSecret = !!data.SHOPIFY_CLIENT_SECRET;
+    const hasClientCredentials = hasClientId && hasClientSecret;
+    return hasLegacyAuth || hasClientCredentials;
+  },
+  {
+    message: "Authentication required: Provide either SHOPIFY_ACCESS_TOKEN (legacy) OR both SHOPIFY_CLIENT_ID and SHOPIFY_CLIENT_SECRET (Dev Dashboard)"
+  }
+).refine(
+  (data) => {
+    const hasClientId = !!data.SHOPIFY_CLIENT_ID;
+    const hasClientSecret = !!data.SHOPIFY_CLIENT_SECRET;
+    if (hasClientId && !hasClientSecret) {
+      return false;
+    }
+    return true;
+  },
+  {
+    message: "Incomplete client credentials: SHOPIFY_CLIENT_SECRET is required when SHOPIFY_CLIENT_ID is provided"
+  }
+).refine(
+  (data) => {
+    const hasClientId = !!data.SHOPIFY_CLIENT_ID;
+    const hasClientSecret = !!data.SHOPIFY_CLIENT_SECRET;
+    if (hasClientSecret && !hasClientId) {
+      return false;
+    }
+    return true;
+  },
+  {
+    message: "Incomplete client credentials: SHOPIFY_CLIENT_ID is required when SHOPIFY_CLIENT_SECRET is provided"
+  }
+);
+function getAuthMode(config) {
+  if (config.SHOPIFY_ACCESS_TOKEN) {
+    return "token";
+  }
+  return "client_credentials";
+}
 function isDebugEnabled(debugValue) {
   if (!debugValue) return false;
   const normalized = debugValue.toLowerCase().trim();
@@ -54,8 +101,10 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 // src/utils/logger.ts
 var SANITIZATION_PATTERNS = [
   { pattern: /shpat_[a-zA-Z0-9]+/g, replacement: "[REDACTED]" },
-  { pattern: /Bearer\s+[a-zA-Z0-9]+/g, replacement: "Bearer [REDACTED]" },
-  { pattern: /access_token[=:]\s*[a-zA-Z0-9]+/gi, replacement: "access_token=[REDACTED]" }
+  { pattern: /shpua_[a-zA-Z0-9]+/g, replacement: "[REDACTED]" },
+  { pattern: /Bearer\s+[a-zA-Z0-9_-]+/g, replacement: "Bearer [REDACTED]" },
+  { pattern: /access_token[=:]\s*[a-zA-Z0-9_-]+/gi, replacement: "access_token=[REDACTED]" },
+  { pattern: /client_secret[=:]\s*[a-zA-Z0-9_-]+/gi, replacement: "client_secret=[REDACTED]" }
 ];
 function sanitizeLogMessage(message) {
   let result = message;
@@ -313,6 +362,283 @@ async function withRateLimit(operation, context, config = DEFAULT_RATE_LIMIT_CON
 // src/shopify/client.ts
 import "@shopify/shopify-api/adapters/node";
 import { shopifyApi } from "@shopify/shopify-api";
+
+// src/utils/errors.ts
+var sanitizeErrorMessage = sanitizeLogMessage;
+var ToolError = class _ToolError extends Error {
+  /** AI-friendly suggestion for error recovery */
+  suggestion;
+  /**
+   * Create a new ToolError
+   *
+   * @param message - The error message describing what went wrong
+   * @param suggestion - A helpful suggestion for how to resolve the error
+   */
+  constructor(message, suggestion) {
+    super(message);
+    this.name = "ToolError";
+    this.suggestion = suggestion;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _ToolError);
+    }
+  }
+};
+function extractErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  return "Unknown error";
+}
+function createToolError(error, suggestion) {
+  const message = extractErrorMessage(error);
+  const safeMessage = sanitizeErrorMessage(message);
+  const safeSuggestion = sanitizeErrorMessage(suggestion);
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: `Error: ${safeMessage}
+
+Suggestion: ${safeSuggestion}`
+      }
+    ]
+  };
+}
+function safeStringify2(data) {
+  try {
+    const seen = /* @__PURE__ */ new WeakSet();
+    return JSON.stringify(
+      data,
+      (_key, value) => {
+        if (typeof value === "object" && value !== null) {
+          if (seen.has(value)) {
+            return "[Circular]";
+          }
+          seen.add(value);
+        }
+        return value;
+      },
+      2
+    );
+  } catch {
+    return "[Unable to stringify]";
+  }
+}
+function createToolSuccess(data) {
+  const text = safeStringify2(data);
+  return {
+    content: [
+      {
+        type: "text",
+        text
+      }
+    ],
+    structuredContent: data
+  };
+}
+
+// src/shopify/token-manager.ts
+var TokenManager = class _TokenManager {
+  config;
+  cachedToken = null;
+  refreshPromise = null;
+  /**
+   * Refresh buffer: 5 minutes before expiry
+   *
+   * Tokens are refreshed when within this window of expiration
+   * to ensure requests don't fail due to token expiry mid-request.
+   */
+  static REFRESH_BUFFER_MS = 5 * 60 * 1e3;
+  /**
+   * Create a new TokenManager instance
+   *
+   * @param config - Configuration containing store URL and OAuth credentials
+   */
+  constructor(config) {
+    this.config = config;
+    log.debug("TokenManager initialized", { storeUrl: config.storeUrl });
+  }
+  /**
+   * Get a valid access token
+   *
+   * Returns a cached token if valid and not expiring soon.
+   * Automatically fetches a new token if:
+   * - No token is cached
+   * - Cached token is within 5 minutes of expiration
+   *
+   * Concurrent calls are deduplicated - only one OAuth request
+   * is made even if multiple callers request a token simultaneously.
+   *
+   * @returns Promise resolving to a valid access token string
+   * @throws ToolError if token acquisition fails
+   */
+  async getAccessToken() {
+    if (this.refreshPromise) {
+      log.debug("Token refresh in progress, waiting...");
+      return this.refreshPromise;
+    }
+    if (this.cachedToken && !this.needsRefresh()) {
+      log.debug("Using cached token");
+      return this.cachedToken.accessToken;
+    }
+    log.debug("Fetching new OAuth token");
+    this.refreshPromise = this.fetchNewToken().then((token) => {
+      this.cachedToken = token;
+      log.debug("Token cached successfully", {
+        expiresIn: Math.round((token.expiresAt - Date.now()) / 1e3)
+      });
+      return token.accessToken;
+    }).finally(() => {
+      this.refreshPromise = null;
+    });
+    return this.refreshPromise;
+  }
+  /**
+   * Fetch a new token from Shopify OAuth endpoint
+   *
+   * Implements OAuth 2.0 client credentials grant flow:
+   * - POST to /admin/oauth/access_token
+   * - Content-Type: application/x-www-form-urlencoded
+   * - Body: grant_type, client_id, client_secret
+   *
+   * @returns Promise resolving to cached token with expiry
+   * @throws ToolError on OAuth failure (401, 400, network error)
+   * @private
+   */
+  async fetchNewToken() {
+    const tokenEndpoint = this.buildTokenEndpoint();
+    try {
+      const response = await fetch(tokenEndpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded"
+        },
+        body: new URLSearchParams({
+          grant_type: "client_credentials",
+          client_id: this.config.clientId,
+          client_secret: this.config.clientSecret
+        })
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw this.handleOAuthError(response.status, errorText);
+      }
+      const data = await response.json();
+      if (!data.access_token) {
+        throw new ToolError(
+          "Invalid OAuth response: missing access_token",
+          "This may be a temporary Shopify API issue. Try again in a few minutes."
+        );
+      }
+      const expiresAt = Date.now() + data.expires_in * 1e3;
+      return {
+        accessToken: data.access_token,
+        expiresAt
+      };
+    } catch (error) {
+      if (error instanceof ToolError) {
+        throw error;
+      }
+      const message = error instanceof Error ? error.message : "Unknown error";
+      throw new ToolError(
+        `OAuth token request failed: ${message}`,
+        "Check your network connection and ensure SHOPIFY_CLIENT_ID and SHOPIFY_CLIENT_SECRET are correct."
+      );
+    }
+  }
+  /**
+   * Build the OAuth token endpoint URL
+   *
+   * @returns Full URL to the Shopify OAuth token endpoint
+   * @private
+   */
+  buildTokenEndpoint() {
+    const storeUrl = this.config.storeUrl.includes("://") ? this.config.storeUrl : `https://${this.config.storeUrl}`;
+    const baseUrl = storeUrl.replace(/\/$/, "");
+    return `${baseUrl}/admin/oauth/access_token`;
+  }
+  /**
+   * Check if the cached token needs to be refreshed
+   *
+   * Returns true if:
+   * - No token is cached
+   * - Token expires within REFRESH_BUFFER_MS (5 minutes)
+   *
+   * @returns true if token should be refreshed
+   * @private
+   */
+  needsRefresh() {
+    if (!this.cachedToken) {
+      return true;
+    }
+    const refreshThreshold = Date.now() + _TokenManager.REFRESH_BUFFER_MS;
+    return refreshThreshold >= this.cachedToken.expiresAt;
+  }
+  /**
+   * Handle OAuth error responses
+   *
+   * Creates appropriate ToolError with actionable suggestions
+   * based on HTTP status code.
+   *
+   * @param status - HTTP status code
+   * @param responseText - Error response body
+   * @returns ToolError with appropriate message and suggestion
+   * @private
+   */
+  handleOAuthError(status, responseText) {
+    switch (status) {
+      case 401:
+        return new ToolError(
+          "OAuth authentication failed (HTTP 401)",
+          "Verify that SHOPIFY_CLIENT_ID and SHOPIFY_CLIENT_SECRET are correct. Ensure the app has the required scopes configured in the Dev Dashboard."
+        );
+      case 400:
+        return new ToolError(
+          "OAuth bad request (HTTP 400)",
+          "The OAuth request parameters are invalid. Ensure SHOPIFY_CLIENT_ID and SHOPIFY_CLIENT_SECRET are set correctly and the app is properly configured in the Dev Dashboard."
+        );
+      case 403:
+        return new ToolError(
+          "OAuth forbidden (HTTP 403)",
+          "The app may not have permission to access this store. Ensure the app is installed on the store and has the required access scopes."
+        );
+      case 404:
+        return new ToolError(
+          "OAuth endpoint not found (HTTP 404)",
+          `Verify SHOPIFY_STORE_URL is correct and includes the .myshopify.com domain. Current value appears incorrect. Received: ${responseText.slice(0, 100)}`
+        );
+      case 429:
+        return new ToolError(
+          "OAuth rate limited (HTTP 429)",
+          "Too many token requests. Wait a few minutes before trying again."
+        );
+      default:
+        return new ToolError(
+          `OAuth request failed (HTTP ${status})`,
+          `Unexpected error from Shopify OAuth endpoint. Response: ${responseText.slice(0, 200)}`
+        );
+    }
+  }
+  /**
+   * Clear the cached token
+   *
+   * Use this for:
+   * - Testing: Reset state between tests
+   * - Error recovery: Force new token after auth failures
+   *
+   * The next call to getAccessToken() will fetch a new token.
+   */
+  clearCache() {
+    this.cachedToken = null;
+    log.debug("Token cache cleared");
+  }
+};
+
+// src/shopify/client.ts
 var DEFAULT_API_VERSION = "2025-10";
 var SHOP_QUERY = `
   query {
@@ -322,6 +648,7 @@ var SHOP_QUERY = `
   }
 `;
 var _defaultClient = null;
+var _tokenManager = null;
 async function verifyConnectivity(client) {
   const response = await client.graphql.request(SHOP_QUERY);
   if (response.errors && response.errors.length > 0) {
@@ -377,18 +704,59 @@ async function createShopifyClient(credentials, options = {}) {
   }
   return client;
 }
+async function createClientWithTokenRefresh(credentials, tokenManager) {
+  const baseClient = buildClient(credentials);
+  let currentToken = credentials.accessToken;
+  return {
+    ...baseClient,
+    graphql: {
+      request: async (query, options) => {
+        const token = await tokenManager.getAccessToken();
+        if (token !== currentToken) {
+          log.debug("Token refreshed, updating client credentials");
+          currentToken = token;
+          credentials.accessToken = token;
+          const refreshedClient = buildClient(credentials);
+          return refreshedClient.graphql.request(query, options);
+        }
+        return baseClient.graphql.request(query, options);
+      }
+    }
+  };
+}
 async function getShopifyClient() {
   if (_defaultClient !== null) {
     return _defaultClient;
   }
   const config = getConfig();
-  const credentials = {
-    storeUrl: config.SHOPIFY_STORE_URL,
-    accessToken: config.SHOPIFY_ACCESS_TOKEN,
-    apiVersion: config.SHOPIFY_API_VERSION
-  };
+  const authMode = getAuthMode(config);
+  log.info(`Initializing Shopify client with auth mode: ${authMode}`);
   try {
-    const client = await createShopifyClient(credentials);
+    if (authMode === "token") {
+      const credentials2 = {
+        storeUrl: config.SHOPIFY_STORE_URL,
+        accessToken: config.SHOPIFY_ACCESS_TOKEN,
+        apiVersion: config.SHOPIFY_API_VERSION
+      };
+      const client2 = await createShopifyClient(credentials2);
+      _defaultClient = client2;
+      return _defaultClient;
+    }
+    log.debug("Creating TokenManager for client_credentials auth");
+    _tokenManager = new TokenManager({
+      storeUrl: config.SHOPIFY_STORE_URL,
+      clientId: config.SHOPIFY_CLIENT_ID,
+      clientSecret: config.SHOPIFY_CLIENT_SECRET
+    });
+    const initialToken = await _tokenManager.getAccessToken();
+    log.debug("Initial OAuth token acquired successfully");
+    const credentials = {
+      storeUrl: config.SHOPIFY_STORE_URL,
+      accessToken: initialToken,
+      apiVersion: config.SHOPIFY_API_VERSION
+    };
+    const client = await createClientWithTokenRefresh(credentials, _tokenManager);
+    await verifyConnectivity(client);
     _defaultClient = client;
     return _defaultClient;
   } catch (error) {
@@ -571,7 +939,7 @@ function transformShopResponse(shop) {
 async function getStoreInfo() {
   const now = Date.now();
   const config = getConfig();
-  const ttl = "STORE_INFO_CACHE_TTL_MS" in config ? config.STORE_INFO_CACHE_TTL_MS ?? DEFAULT_CACHE_TTL_MS : DEFAULT_CACHE_TTL_MS;
+  const ttl = config.STORE_INFO_CACHE_TTL_MS ?? DEFAULT_CACHE_TTL_MS;
   if (_cachedStoreInfo && now - _cacheTimestamp < ttl) {
     log.debug("Returning cached store info");
     return _cachedStoreInfo;
@@ -598,6 +966,42 @@ async function getStoreInfo() {
 var require2 = createRequire(import.meta.url);
 var packageJson = require2("../package.json");
 var SERVER_NAME = "shopify-mcp-admin";
+var SERVER_INSTRUCTIONS = `This MCP server provides access to a Shopify store's Admin API.
+
+KEY CONCEPTS:
+- Products contain variants; each variant has its own price, SKU, and inventory
+- Inventory is tracked per variant AND per location (multi-location stores)
+- Metafields store custom data using namespace/key pairs
+- Collections organize products for navigation and SEO
+- All IDs use Shopify GID format: "gid://shopify/Product/123"
+
+RESOURCE TYPES & GID FORMATS:
+- Products: gid://shopify/Product/{id}
+- Variants: gid://shopify/ProductVariant/{id}
+- Collections: gid://shopify/Collection/{id}
+- Images: gid://shopify/MediaImage/{id}
+- Pages: gid://shopify/Page/{id}
+- Blogs: gid://shopify/Blog/{id}
+- Articles: gid://shopify/Article/{id}
+- Redirects: gid://shopify/UrlRedirect/{id}
+- InventoryItems: gid://shopify/InventoryItem/{id}
+- Locations: gid://shopify/Location/{id}
+
+BEST PRACTICES:
+- Always verify product/variant IDs using get-product before updates
+- Use list-low-inventory to proactively identify stock issues
+- When updating SEO, consider updating URL redirects
+- For bulk operations, prefer bulk tools when available
+- Use metafields to store custom SEO data (JSON-LD, Open Graph)
+
+RATE LIMITS:
+- Shopify GraphQL has cost-based rate limiting (~50 points/sec)
+- Large queries may retry automatically with exponential backoff
+- Rate limit errors include helpful retry suggestions
+
+WORKFLOW HINTS:
+- Tool descriptions include **Prerequisites:** and **Follow-ups:** for multi-step operations
+- Check tool category and relationships for semantic grouping`;
 function getServerVersion() {
   return packageJson.version;
 }
@@ -613,9 +1017,13 @@ function createServer() {
       capabilities: {
         tools: {},
         // Enable tools capability (AC-2.1.4)
-        resources: {}
+        resources: {},
         // Enable resources capability (AC-2.1.4)
-      }
+        logging: {}
+        // Enable logging capability (AC-9.5.1.2)
+      },
+      instructions: SERVER_INSTRUCTIONS
+      // Provide Shopify context to AI agents (AC-9.5.1.1)
     }
   );
   return server;
@@ -1967,86 +2375,23 @@ function createSingleTenantContext(client, shopDomain) {
   };
 }
 
-// src/utils/errors.ts
-var sanitizeErrorMessage = sanitizeLogMessage;
-var ToolError = class _ToolError extends Error {
-  /** AI-friendly suggestion for error recovery */
-  suggestion;
-  /**
-   * Create a new ToolError
-   *
-   * @param message - The error message describing what went wrong
-   * @param suggestion - A helpful suggestion for how to resolve the error
-   */
-  constructor(message, suggestion) {
-    super(message);
-    this.name = "ToolError";
-    this.suggestion = suggestion;
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, _ToolError);
-    }
-  }
-};
-function extractErrorMessage(error) {
-  if (error instanceof Error) {
-    return error.message;
-  }
-  if (typeof error === "string") {
-    return error;
-  }
-  return "Unknown error";
-}
-function createToolError(error, suggestion) {
-  const message = extractErrorMessage(error);
-  const safeMessage = sanitizeErrorMessage(message);
-  const safeSuggestion = sanitizeErrorMessage(suggestion);
-  return {
-    isError: true,
-    content: [
-      {
-        type: "text",
-        text: `Error: ${safeMessage}
-
-Suggestion: ${safeSuggestion}`
-      }
-    ]
-  };
-}
-function safeStringify2(data) {
-  try {
-    const seen = /* @__PURE__ */ new WeakSet();
-    return JSON.stringify(
-      data,
-      (_key, value) => {
-        if (typeof value === "object" && value !== null) {
-          if (seen.has(value)) {
-            return "[Circular]";
-          }
-          seen.add(value);
-        }
-        return value;
-      },
-      2
-    );
-  } catch {
-    return "[Unable to stringify]";
-  }
-}
-function createToolSuccess(data) {
-  const text = safeStringify2(data);
+// src/tools/registration.ts
+var KEBAB_CASE_REGEX = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+function deriveDefaultAnnotations(name) {
+  const isReadOnly = name.startsWith("get-") || name.startsWith("list-");
+  const isDestructive = name.startsWith("delete-");
+  const isCreate = name.startsWith("create-");
   return {
-    content: [
-      {
-        type: "text",
-        text
-      }
-    ],
-    structuredContent: data
+    readOnlyHint: isReadOnly,
+    destructiveHint: isDestructive,
+    // create-* is NOT idempotent (each call creates new resource)
+    // delete-* is NOT idempotent (second call fails - resource gone)
+    // update-*, set-*, add-*, remove-*, reorder-* ARE idempotent
+    idempotentHint: !isCreate && !isDestructive,
+    // All our tools interact with Shopify API
+    openWorldHint: true
   };
 }
-
-// src/tools/registration.ts
-var KEBAB_CASE_REGEX = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 var registeredTools = /* @__PURE__ */ new Map();
 function validateToolName(name) {
   if (!name || name.trim() === "") {
@@ -2106,7 +2451,7 @@ function wrapToolHandler(toolName, schema, handler) {
   };
 }
 function registerTool(definition, handler, options = {}) {
-  const { name, title, description, inputSchema: inputSchema41 } = definition;
+  const { name, title, description, inputSchema: inputSchema41, annotations } = definition;
   try {
     if (!options.skipNameValidation) {
       validateToolName(name);
@@ -2116,13 +2461,20 @@ function registerTool(definition, handler, options = {}) {
     }
     const jsonSchema = convertZodToJsonSchema(inputSchema41);
     const wrappedHandler = wrapToolHandler(name, inputSchema41, handler);
+    const finalAnnotations = {
+      ...deriveDefaultAnnotations(name),
+      ...annotations,
+      // Use definition title as fallback for annotation title
+      title: annotations?.title ?? title
+    };
     const registeredTool = {
       name,
       title,
       description,
       inputSchema: jsonSchema,
       zodSchema: inputSchema41,
-      handler: wrappedHandler
+      handler: wrappedHandler,
+      annotations: finalAnnotations
     };
     registeredTools.set(name, registeredTool);
     log.debug(`Registered tool: ${name}`);
@@ -2141,7 +2493,8 @@ function getRegisteredTools() {
   return Array.from(registeredTools.values()).map((tool) => ({
     name: tool.name,
     description: `${tool.title}: ${tool.description}`,
-    inputSchema: tool.inputSchema
+    inputSchema: tool.inputSchema,
+    annotations: tool.annotations
   }));
 }
 function getToolByName(name) {
@@ -2161,7 +2514,7 @@ function registerContextAwareTool(definition, handler, options = {}) {
 }
 
 // src/tools/add-product-image.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 
 // src/shopify/mutations.ts
 var PRODUCT_CREATE_MUTATION = `
@@ -2801,22 +3154,41 @@ async function addProductImage(productId, input) {
   };
 }
 
+// src/tools/validators.ts
+import { z as z2 } from "zod";
+var GID_PATTERN = /^gid:\/\/shopify\/[A-Za-z]+\/\d+$/;
+function gidSchema(resourceType) {
+  const pattern = resourceType ? new RegExp(`^gid://shopify/${resourceType}/\\d+$`) : GID_PATTERN;
+  const example = resourceType ? `gid://shopify/${resourceType}/123456789` : "gid://shopify/Product/123456789";
+  return z2.string().regex(pattern, `Must be a valid Shopify GID (e.g., ${example})`).describe(`Shopify Global ID (format: ${example})`);
+}
+var productIdSchema = gidSchema("Product");
+var variantIdSchema = gidSchema("ProductVariant");
+var collectionIdSchema = gidSchema("Collection");
+var imageIdSchema = gidSchema("MediaImage");
+var pageIdSchema = gidSchema("Page");
+var blogIdSchema = gidSchema("Blog");
+var articleIdSchema = gidSchema("Article");
+var redirectIdSchema = gidSchema("UrlRedirect");
+var inventoryItemIdSchema = gidSchema("InventoryItem");
+var locationIdSchema = gidSchema("Location");
+
 // src/tools/add-product-image.ts
-var inputSchema = z2.object({
-  productId: z2.string().min(1).describe(
+var inputSchema = z3.object({
+  productId: productIdSchema.describe(
     'Shopify product GID (e.g., "gid://shopify/Product/123"). Required. Use list-products to find product IDs.'
   ),
-  url: z2.string().url().describe(
+  url: z3.string().url().describe(
     "Publicly accessible image URL. Shopify will fetch and host the image. Required. Supported formats: JPEG, PNG, GIF, WEBP."
   ),
-  altText: z2.string().optional().describe(
+  altText: z3.string().optional().describe(
     "Alt text for accessibility and SEO. Describes the image for screen readers. Recommended for better accessibility and search rankings."
   )
 });
-var outputSchema = z2.object({
-  id: z2.string().describe('Image GID (e.g., "gid://shopify/MediaImage/123")'),
-  url: z2.string().describe("Shopify CDN URL for the image"),
-  altText: z2.string().nullable().describe("Alt text for the image")
+var outputSchema = z3.object({
+  id: z3.string().describe('Image GID (e.g., "gid://shopify/MediaImage/123")'),
+  url: z3.string().describe("Shopify CDN URL for the image"),
+  altText: z3.string().nullable().describe("Alt text for the image")
 });
 var handleAddProductImage = async (context, params) => {
   log.debug(`Adding image to product on shop: ${context.shopDomain}`);
@@ -2874,6 +3246,14 @@ function registerAddProductImageTool() {
         relatedTools: ["get-product", "update-product-image"],
         prerequisites: ["create-product"],
         followUps: ["update-product-image", "reorder-product-images"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        // Adding same URL creates duplicate images!
+        openWorldHint: true
       }
     },
     handleAddProductImage
@@ -2881,7 +3261,7 @@ function registerAddProductImageTool() {
 }
 
 // src/tools/add-products-to-collection.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
 // src/shopify/collections.ts
 var GET_COLLECTION_QUERY = `
@@ -3282,18 +3662,18 @@ async function removeProductsFromCollection(collectionId, productIds) {
 }
 
 // src/tools/add-products-to-collection.ts
-var inputSchema2 = z3.object({
-  collectionId: z3.string().min(1).describe(
+var inputSchema2 = z4.object({
+  collectionId: collectionIdSchema.describe(
     'Collection GID (e.g., "gid://shopify/Collection/123"). Use list-collections to find valid collection IDs.'
   ),
-  productIds: z3.array(z3.string().min(1)).min(1).max(250).describe(
+  productIds: z4.array(productIdSchema).min(1).max(250).describe(
     'Array of product GIDs to add (e.g., ["gid://shopify/Product/123", "gid://shopify/Product/456"]). Maximum 250 products per call. Use list-products to find valid product IDs.'
   )
 });
-var outputSchema2 = z3.object({
-  collectionId: z3.string().describe("Collection GID"),
-  productsCount: z3.number().describe("Total number of products now in the collection"),
-  addedCount: z3.number().describe("Number of products added in this operation")
+var outputSchema2 = z4.object({
+  collectionId: z4.string().describe("Collection GID"),
+  productsCount: z4.number().describe("Total number of products now in the collection"),
+  addedCount: z4.number().describe("Number of products added in this operation")
 });
 var handleAddProductsToCollection = async (context, params) => {
   log.debug(
@@ -3337,6 +3717,14 @@ function registerAddProductsToCollectionTool() {
         relatedTools: ["remove-products-from-collection", "list-products"],
         prerequisites: ["create-collection", "list-products"],
         followUps: ["get-collection"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        // Adding same products is idempotent (no-op)
+        openWorldHint: true
       }
     },
     handleAddProductsToCollection
@@ -3344,7 +3732,7 @@ function registerAddProductsToCollectionTool() {
 }
 
 // src/tools/create-article.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 
 // src/shopify/blogs.ts
 var LIST_BLOGS_QUERY = `
@@ -3850,51 +4238,51 @@ async function deleteArticle(articleId) {
 }
 
 // src/tools/create-article.ts
-var inputSchema3 = z4.object({
-  blogId: z4.string().describe(
+var inputSchema3 = z5.object({
+  blogId: blogIdSchema.describe(
     'The blog ID to create the article in (required). Must be a valid Shopify GID format. Example: "gid://shopify/Blog/12345". Use list-blogs to find blog IDs.'
   ),
-  title: z4.string().min(1).describe(
+  title: z5.string().min(1).describe(
     "The title of the article (required). This will be displayed as the article heading. Example: 'How to Use Our Products', '10 Tips for Beginners'."
   ),
-  authorName: z4.string().min(1).describe(
+  authorName: z5.string().min(1).describe(
     "The name of the article author (required). This is displayed on the article. Example: 'John Doe', 'Marketing Team'."
   ),
-  body: z4.string().optional().describe(
+  body: z5.string().optional().describe(
     "The HTML body content of the article. Supports HTML markup for formatting. Example: '<h2>Introduction</h2><p>Welcome to our guide...</p>'"
   ),
-  summary: z4.string().optional().describe(
+  summary: z5.string().optional().describe(
     "A summary or excerpt of the article. Used for previews on blog listing pages. Can include HTML markup."
   ),
-  tags: z4.array(z4.string()).optional().describe(
+  tags: z5.array(z5.string()).optional().describe(
     "Tags for categorization. Helps organize articles and improve discoverability. Example: ['guide', 'tutorial', 'beginner']."
   ),
-  image: z4.object({
-    url: z4.string().url().describe("The URL of the featured image"),
-    altText: z4.string().optional().describe("Alt text for accessibility")
+  image: z5.object({
+    url: z5.string().url().describe("The URL of the featured image"),
+    altText: z5.string().optional().describe("Alt text for accessibility")
   }).optional().describe("Featured image for the article."),
-  isPublished: z4.boolean().optional().describe(
+  isPublished: z5.boolean().optional().describe(
     "Whether the article should be visible on the storefront. Defaults to false (unpublished). Set to true to make the article immediately visible."
   ),
-  publishDate: z4.string().optional().describe(
+  publishDate: z5.string().optional().describe(
     "The date and time when the article should become visible (ISO 8601 format). Example: '2024-01-15T10:00:00Z'. If not set and isPublished is true, publishes immediately."
   ),
-  handle: z4.string().optional().describe(
+  handle: z5.string().optional().describe(
     "The URL handle/slug for the article. If not provided, it will be auto-generated from the title. Example: 'how-to-use-our-products' would create URL /blogs/blog-handle/how-to-use-our-products."
   ),
-  templateSuffix: z4.string().optional().describe(
+  templateSuffix: z5.string().optional().describe(
     "The suffix of the Liquid template used to render the article. For example, 'featured' would use the template 'article.featured.liquid'."
   )
 });
-var outputSchema3 = z4.object({
-  id: z4.string().describe('Created article GID (e.g., "gid://shopify/Article/123")'),
-  title: z4.string().describe("Article title"),
-  handle: z4.string().describe("URL handle/slug"),
-  blog: z4.object({
-    id: z4.string().describe("Parent blog GID"),
-    title: z4.string().describe("Parent blog title")
+var outputSchema3 = z5.object({
+  id: z5.string().describe('Created article GID (e.g., "gid://shopify/Article/123")'),
+  title: z5.string().describe("Article title"),
+  handle: z5.string().describe("URL handle/slug"),
+  blog: z5.object({
+    id: z5.string().describe("Parent blog GID"),
+    title: z5.string().describe("Parent blog title")
   }),
-  isPublished: z4.boolean().describe("Whether article is visible on storefront")
+  isPublished: z5.boolean().describe("Whether article is visible on storefront")
 });
 var handleCreateArticle = async (context, params) => {
   log.debug(`Creating article on shop: ${context.shopDomain}`);
@@ -3950,6 +4338,14 @@ function registerCreateArticleTool() {
         relatedTools: ["list-blogs", "list-articles", "update-article"],
         prerequisites: ["list-blogs"],
         followUps: ["list-articles", "update-article"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        // create-* tools are NOT idempotent
+        openWorldHint: true
       }
     },
     handleCreateArticle
@@ -3957,26 +4353,26 @@ function registerCreateArticleTool() {
 }
 
 // src/tools/create-blog.ts
-import { z as z5 } from "zod";
-var inputSchema4 = z5.object({
-  title: z5.string().min(1).describe(
+import { z as z6 } from "zod";
+var inputSchema4 = z6.object({
+  title: z6.string().min(1).describe(
     "The title of the blog (required). This will be displayed as the blog heading. Example: 'Company News', 'Product Guides', 'Industry Insights'."
   ),
-  handle: z5.string().optional().describe(
+  handle: z6.string().optional().describe(
     "The URL handle/slug for the blog. If not provided, it will be auto-generated from the title. Example: 'news' would create URL /blogs/news."
   ),
-  commentPolicy: z5.enum(["CLOSED", "MODERATE", "OPEN"]).optional().describe(
+  commentPolicy: z6.enum(["CLOSED", "MODERATE", "OPEN"]).optional().describe(
     "Comment moderation policy for the blog. CLOSED: Comments disabled. MODERATE: Comments require approval. OPEN: Comments appear immediately. Defaults to MODERATE if not specified."
   ),
-  templateSuffix: z5.string().optional().describe(
+  templateSuffix: z6.string().optional().describe(
     "The suffix of the Liquid template used to render the blog. For example, 'news' would use the template 'blog.news.liquid'."
   )
 });
-var outputSchema4 = z5.object({
-  id: z5.string().describe('Created blog GID (e.g., "gid://shopify/Blog/123")'),
-  title: z5.string().describe("Blog title"),
-  handle: z5.string().describe("URL handle/slug"),
-  commentPolicy: z5.enum(["CLOSED", "MODERATE", "OPEN"]).describe("Comment moderation policy")
+var outputSchema4 = z6.object({
+  id: z6.string().describe('Created blog GID (e.g., "gid://shopify/Blog/123")'),
+  title: z6.string().describe("Blog title"),
+  handle: z6.string().describe("URL handle/slug"),
+  commentPolicy: z6.enum(["CLOSED", "MODERATE", "OPEN"]).describe("Comment moderation policy")
 });
 var handleCreateBlog = async (context, params) => {
   log.debug(`Creating blog on shop: ${context.shopDomain}`);
@@ -4018,6 +4414,14 @@ function registerCreateBlogTool() {
       relationships: {
         relatedTools: ["list-blogs", "update-blog", "create-article"],
         followUps: ["create-article", "list-blogs"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        // create-* tools are NOT idempotent
+        openWorldHint: true
       }
     },
     handleCreateBlog
@@ -4025,20 +4429,20 @@ function registerCreateBlogTool() {
 }
 
 // src/tools/create-collection.ts
-import { z as z6 } from "zod";
-var inputSchema5 = z6.object({
-  title: z6.string().min(1).describe("Collection title (required). This will be displayed to customers."),
-  handle: z6.string().optional().describe(
+import { z as z7 } from "zod";
+var inputSchema5 = z7.object({
+  title: z7.string().min(1).describe("Collection title (required). This will be displayed to customers."),
+  handle: z7.string().optional().describe(
     'URL handle/slug for the collection (e.g., "summer-sale"). Auto-generated from title if not provided.'
   ),
-  descriptionHtml: z6.string().optional().describe(
+  descriptionHtml: z7.string().optional().describe(
     "Collection description with HTML formatting. Displayed on collection pages in the store."
   ),
-  seo: z6.object({
-    title: z6.string().optional().describe("SEO title for search engines"),
-    description: z6.string().optional().describe("SEO meta description for search engines")
+  seo: z7.object({
+    title: z7.string().optional().describe("SEO title for search engines"),
+    description: z7.string().optional().describe("SEO meta description for search engines")
   }).optional().describe("SEO metadata to optimize collection visibility in search results"),
-  sortOrder: z6.enum([
+  sortOrder: z7.enum([
     "ALPHA_ASC",
     "ALPHA_DESC",
     "BEST_SELLING",
@@ -4050,18 +4454,18 @@ var inputSchema5 = z6.object({
   ]).optional().describe(
     "How products are sorted within the collection. Options: ALPHA_ASC (A-Z), ALPHA_DESC (Z-A), BEST_SELLING, CREATED (oldest first), CREATED_DESC (newest first), MANUAL, PRICE_ASC (low to high), PRICE_DESC (high to low)"
   ),
-  image: z6.object({
-    src: z6.string().url().describe("Publicly accessible image URL"),
-    altText: z6.string().optional().describe("Alt text for accessibility and SEO")
+  image: z7.object({
+    src: z7.string().url().describe("Publicly accessible image URL"),
+    altText: z7.string().optional().describe("Alt text for accessibility and SEO")
   }).optional().describe("Collection image displayed on collection pages"),
-  templateSuffix: z6.string().optional().describe(
+  templateSuffix: z7.string().optional().describe(
     'Liquid template suffix for custom collection templates. For example, "featured" uses collection.featured.liquid'
   )
 });
-var outputSchema5 = z6.object({
-  id: z6.string().describe('Created collection GID (e.g., "gid://shopify/Collection/123")'),
-  title: z6.string().describe("Collection title"),
-  handle: z6.string().describe("Collection URL handle")
+var outputSchema5 = z7.object({
+  id: z7.string().describe('Created collection GID (e.g., "gid://shopify/Collection/123")'),
+  title: z7.string().describe("Collection title"),
+  handle: z7.string().describe("Collection URL handle")
 });
 var handleCreateCollection = async (context, params) => {
   log.debug(`Creating collection on shop: ${context.shopDomain}`);
@@ -4100,6 +4504,14 @@ function registerCreateCollectionTool() {
       relationships: {
         relatedTools: ["list-collections", "get-collection"],
         followUps: ["add-products-to-collection", "update-collection"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        // Each call creates a new collection
+        openWorldHint: true
       }
     },
     handleCreateCollection
@@ -4107,7 +4519,7 @@ function registerCreateCollectionTool() {
 }
 
 // src/tools/create-page.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 
 // src/shopify/pages.ts
 var PAGE_QUERY = `
@@ -4389,28 +4801,28 @@ async function deletePage(pageId) {
 }
 
 // src/tools/create-page.ts
-var inputSchema6 = z7.object({
-  title: z7.string().min(1).describe(
+var inputSchema6 = z8.object({
+  title: z8.string().min(1).describe(
     "The title of the page (required). This will be displayed as the page heading. Example: 'About Us', 'Contact', 'Privacy Policy'."
   ),
-  body: z7.string().optional().describe(
+  body: z8.string().optional().describe(
     "The HTML body content of the page. Supports HTML markup for formatting. Example: '<h1>About Our Company</h1><p>We are a great company.</p>'"
   ),
-  handle: z7.string().optional().describe(
+  handle: z8.string().optional().describe(
     "The URL handle/slug for the page. If not provided, it will be auto-generated from the title. Example: 'about-us' would create URL /pages/about-us."
   ),
-  isPublished: z7.boolean().optional().describe(
+  isPublished: z8.boolean().optional().describe(
     "Whether the page should be visible on the storefront. Defaults to false (unpublished). Set to true to make the page immediately visible."
   ),
-  templateSuffix: z7.string().optional().describe(
+  templateSuffix: z8.string().optional().describe(
     "The suffix of the Liquid template used to render the page. For example, 'contact' would use the template 'page.contact.liquid'."
   )
 });
-var outputSchema6 = z7.object({
-  id: z7.string().describe('Created page GID (e.g., "gid://shopify/Page/123")'),
-  title: z7.string().describe("Page title"),
-  handle: z7.string().describe("URL handle/slug"),
-  isPublished: z7.boolean().describe("Whether page is visible on storefront")
+var outputSchema6 = z8.object({
+  id: z8.string().describe('Created page GID (e.g., "gid://shopify/Page/123")'),
+  title: z8.string().describe("Page title"),
+  handle: z8.string().describe("URL handle/slug"),
+  isPublished: z8.boolean().describe("Whether page is visible on storefront")
 });
 var handleCreatePage = async (context, params) => {
   log.debug(`Creating page on shop: ${context.shopDomain}`);
@@ -4453,6 +4865,14 @@ function registerCreatePageTool() {
       relationships: {
         relatedTools: ["list-pages", "get-page", "update-page"],
         followUps: ["get-page", "update-page"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        // create-* tools are NOT idempotent
+        openWorldHint: true
       }
     },
     handleCreatePage
@@ -4460,78 +4880,78 @@ function registerCreatePageTool() {
 }
 
 // src/tools/create-product.ts
-import { z as z8 } from "zod";
-var inputSchema7 = z8.object({
+import { z as z9 } from "zod";
+var inputSchema7 = z9.object({
   // Required field
-  title: z8.string().min(1, "title is required").describe('Product title (required). Example: "Premium Cotton T-Shirt"'),
+  title: z9.string().min(1, "title is required").describe('Product title (required). Example: "Premium Cotton T-Shirt"'),
   // Optional core fields
-  description: z8.string().optional().describe('Product description (HTML supported). Example: "<p>Soft cotton t-shirt.</p>"'),
-  vendor: z8.string().optional().describe('Product vendor/brand name. Example: "Acme Corp"'),
-  productType: z8.string().optional().describe('Product type for categorization. Example: "T-Shirts"'),
-  tags: z8.array(z8.string()).optional().describe('Tags for search and filtering. Example: ["summer", "cotton", "casual"]'),
-  status: z8.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).optional().default("DRAFT").describe(
+  description: z9.string().optional().describe('Product description (HTML supported). Example: "<p>Soft cotton t-shirt.</p>"'),
+  vendor: z9.string().optional().describe('Product vendor/brand name. Example: "Acme Corp"'),
+  productType: z9.string().optional().describe('Product type for categorization. Example: "T-Shirts"'),
+  tags: z9.array(z9.string()).optional().describe('Tags for search and filtering. Example: ["summer", "cotton", "casual"]'),
+  status: z9.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).optional().default("DRAFT").describe(
     "Product status: ACTIVE (visible), DRAFT (hidden), ARCHIVED (hidden). Default: DRAFT"
   ),
   // SEO metadata
-  seo: z8.object({
-    title: z8.string().optional().describe("SEO title for search engine results"),
-    description: z8.string().optional().describe("SEO meta description for search engines")
+  seo: z9.object({
+    title: z9.string().optional().describe("SEO title for search engine results"),
+    description: z9.string().optional().describe("SEO meta description for search engines")
   }).optional().describe(
     "SEO metadata for search engine optimization. If not provided, Shopify uses product title/description."
   ),
   // Variants
-  variants: z8.array(
-    z8.object({
-      price: z8.string().describe('Variant price as decimal string. Example: "29.99"'),
-      compareAtPrice: z8.string().optional().describe('Original price for sale display. Example: "39.99"'),
-      sku: z8.string().optional().describe('Stock keeping unit. Example: "SHIRT-001-RED-M"'),
-      barcode: z8.string().optional().describe("Barcode (UPC, EAN, etc.)"),
-      inventoryQuantity: z8.number().int().min(0).optional().describe("Initial inventory quantity (note: may require separate inventory API)"),
-      options: z8.array(z8.string()).optional().describe('Variant options. Example: ["Red", "Medium"]')
+  variants: z9.array(
+    z9.object({
+      price: z9.string().describe('Variant price as decimal string. Example: "29.99"'),
+      compareAtPrice: z9.string().optional().describe('Original price for sale display. Example: "39.99"'),
+      sku: z9.string().optional().describe('Stock keeping unit. Example: "SHIRT-001-RED-M"'),
+      barcode: z9.string().optional().describe("Barcode (UPC, EAN, etc.)"),
+      inventoryQuantity: z9.number().int().min(0).optional().describe("Initial inventory quantity (note: may require separate inventory API)"),
+      options: z9.array(z9.string()).optional().describe('Variant options. Example: ["Red", "Medium"]')
     })
   ).optional().describe("Product variants. If not provided, a default variant is created."),
   // Images
-  images: z8.array(
-    z8.object({
-      url: z8.string().url("Invalid image URL format").describe("Publicly accessible image URL"),
-      altText: z8.string().optional().describe("Alt text for accessibility")
+  images: z9.array(
+    z9.object({
+      url: z9.string().url("Invalid image URL format").describe("Publicly accessible image URL"),
+      altText: z9.string().optional().describe("Alt text for accessibility")
     })
   ).optional().describe("Product images. Shopify fetches images from URLs.")
 });
-var outputSchema7 = z8.object({
-  id: z8.string().describe('Product GID (e.g., "gid://shopify/Product/123")'),
-  title: z8.string().describe("Product title"),
-  handle: z8.string().describe("URL handle/slug"),
-  description: z8.string().nullable().describe("Product description (HTML)"),
-  vendor: z8.string().describe("Vendor/brand name"),
-  productType: z8.string().describe("Product type"),
-  status: z8.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).describe("Product status"),
-  tags: z8.array(z8.string()).describe("Product tags"),
-  seo: z8.object({
-    title: z8.string().nullable().describe("SEO title for search engines"),
-    description: z8.string().nullable().describe("SEO description/meta description")
+var outputSchema7 = z9.object({
+  id: z9.string().describe('Product GID (e.g., "gid://shopify/Product/123")'),
+  title: z9.string().describe("Product title"),
+  handle: z9.string().describe("URL handle/slug"),
+  description: z9.string().nullable().describe("Product description (HTML)"),
+  vendor: z9.string().describe("Vendor/brand name"),
+  productType: z9.string().describe("Product type"),
+  status: z9.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).describe("Product status"),
+  tags: z9.array(z9.string()).describe("Product tags"),
+  seo: z9.object({
+    title: z9.string().nullable().describe("SEO title for search engines"),
+    description: z9.string().nullable().describe("SEO description/meta description")
   }).describe("SEO metadata for search engine optimization"),
-  createdAt: z8.string().describe("Creation timestamp (ISO 8601)"),
-  updatedAt: z8.string().describe("Last update timestamp (ISO 8601)"),
-  variants: z8.array(
-    z8.object({
-      id: z8.string().describe("Variant GID"),
-      title: z8.string().describe("Variant title"),
-      price: z8.string().describe("Price"),
-      compareAtPrice: z8.string().nullable().describe("Compare at price"),
-      sku: z8.string().nullable().describe("SKU"),
-      barcode: z8.string().nullable().describe("Barcode"),
-      inventoryQuantity: z8.number().nullable().describe("Inventory quantity")
+  createdAt: z9.string().describe("Creation timestamp (ISO 8601)"),
+  updatedAt: z9.string().describe("Last update timestamp (ISO 8601)"),
+  variants: z9.array(
+    z9.object({
+      id: z9.string().describe("Variant GID"),
+      title: z9.string().describe("Variant title"),
+      price: z9.string().describe("Price"),
+      compareAtPrice: z9.string().nullable().describe("Compare at price"),
+      sku: z9.string().nullable().describe("SKU"),
+      barcode: z9.string().nullable().describe("Barcode"),
+      inventoryQuantity: z9.number().nullable().describe("Inventory quantity")
     })
   ).describe("Product variants"),
-  images: z8.array(
-    z8.object({
-      id: z8.string().describe("Image GID"),
-      url: z8.string().describe("Image URL"),
-      altText: z8.string().nullable().describe("Alt text")
+  images: z9.array(
+    z9.object({
+      id: z9.string().describe("Image GID"),
+      url: z9.string().describe("Image URL"),
+      altText: z9.string().nullable().describe("Alt text")
     })
   ).describe("Product images"),
-  totalInventory: z8.number().describe("Total inventory across variants")
+  totalInventory: z9.number().describe("Total inventory across variants")
 });
 var handleCreateProduct = async (context, params) => {
   log.debug(`Creating product on shop: ${context.shopDomain}`);
@@ -4574,6 +4994,14 @@ function registerCreateProductTool() {
         relatedTools: ["get-product", "update-product", "list-products"],
         followUps: ["add-product-image", "set-product-metafields", "add-products-to-collection"],
         alternatives: ["update-product"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        // Each call creates a new product
+        openWorldHint: true
       }
     },
     handleCreateProduct
@@ -4581,7 +5009,7 @@ function registerCreateProductTool() {
 }
 
 // src/tools/create-redirect.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 
 // src/shopify/redirects.ts
 var URL_REDIRECT_CREATE_MUTATION = `
@@ -4729,20 +5157,20 @@ async function deleteRedirect(redirectId) {
 }
 
 // src/tools/create-redirect.ts
-var inputSchema8 = z9.object({
-  path: z9.string().min(1).refine((val) => val.startsWith("/"), {
+var inputSchema8 = z10.object({
+  path: z10.string().min(1).refine((val) => val.startsWith("/"), {
     message: "Path must start with '/' (e.g., '/old-product-url')"
   }).describe(
     "The source path to redirect FROM. Must start with '/'. Example: '/old-product-url' or '/collections/old-collection'."
   ),
-  target: z9.string().min(1).describe(
+  target: z10.string().min(1).describe(
     "The destination URL to redirect TO. Can be relative ('/new-product-url') or absolute ('https://example.com/page')."
   )
 });
-var outputSchema8 = z9.object({
-  id: z9.string().describe('Created redirect GID (e.g., "gid://shopify/UrlRedirect/123")'),
-  path: z9.string().describe("Source path that will redirect"),
-  target: z9.string().describe("Target URL visitors will be redirected to")
+var outputSchema8 = z10.object({
+  id: z10.string().describe('Created redirect GID (e.g., "gid://shopify/UrlRedirect/123")'),
+  path: z10.string().describe("Source path that will redirect"),
+  target: z10.string().describe("Target URL visitors will be redirected to")
 });
 var handleCreateRedirect = async (context, params) => {
   log.debug(`Creating redirect on shop: ${context.shopDomain}`);
@@ -4783,6 +5211,14 @@ function registerCreateRedirectTool() {
       relationships: {
         relatedTools: ["list-redirects", "delete-redirect"],
         followUps: ["list-redirects"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        // Each call creates a new redirect (duplicate path fails)
+        openWorldHint: true
       }
     },
     handleCreateRedirect
@@ -4790,15 +5226,15 @@ function registerCreateRedirectTool() {
 }
 
 // src/tools/delete-article.ts
-import { z as z10 } from "zod";
-var inputSchema9 = z10.object({
-  id: z10.string().describe(
+import { z as z11 } from "zod";
+var inputSchema9 = z11.object({
+  id: articleIdSchema.describe(
     'The article ID to delete (required). Must be a valid Shopify GID format. Example: "gid://shopify/Article/12345". Use list-articles to find article IDs. This action cannot be undone - consider using update-article to unpublish instead.'
   )
 });
-var outputSchema9 = z10.object({
-  success: z10.boolean().describe("Whether the deletion was successful"),
-  deletedArticleId: z10.string().describe("The ID of the deleted article")
+var outputSchema9 = z11.object({
+  success: z11.boolean().describe("Whether the deletion was successful"),
+  deletedArticleId: z11.string().describe("The ID of the deleted article")
 });
 var handleDeleteArticle = async (context, params) => {
   log.debug(`Deleting article on shop: ${context.shopDomain}`);
@@ -4839,6 +5275,14 @@ function registerDeleteArticleTool() {
         relatedTools: ["list-articles", "update-article"],
         prerequisites: ["list-articles"],
         alternatives: ["update-article"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        // delete-* tools are NOT idempotent
+        openWorldHint: true
       }
     },
     handleDeleteArticle
@@ -4846,15 +5290,15 @@ function registerDeleteArticleTool() {
 }
 
 // src/tools/delete-blog.ts
-import { z as z11 } from "zod";
-var inputSchema10 = z11.object({
-  id: z11.string().describe(
+import { z as z12 } from "zod";
+var inputSchema10 = z12.object({
+  id: blogIdSchema.describe(
     'The blog ID to delete (required). Must be a valid Shopify GID format. Example: "gid://shopify/Blog/12345". Use list-blogs to find blog IDs. WARNING: Deleting a blog also deletes ALL articles within it.'
   )
 });
-var outputSchema10 = z11.object({
-  success: z11.boolean().describe("Whether the deletion was successful"),
-  deletedBlogId: z11.string().describe("The ID of the deleted blog")
+var outputSchema10 = z12.object({
+  success: z12.boolean().describe("Whether the deletion was successful"),
+  deletedBlogId: z12.string().describe("The ID of the deleted blog")
 });
 var handleDeleteBlog = async (context, params) => {
   log.debug(`Deleting blog on shop: ${context.shopDomain}`);
@@ -4894,6 +5338,14 @@ function registerDeleteBlogTool() {
       relationships: {
         relatedTools: ["list-blogs", "list-articles"],
         prerequisites: ["list-blogs"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        // delete-* tools are NOT idempotent
+        openWorldHint: true
       }
     },
     handleDeleteBlog
@@ -4901,14 +5353,14 @@ function registerDeleteBlogTool() {
 }
 
 // src/tools/delete-collection.ts
-import { z as z12 } from "zod";
-var inputSchema11 = z12.object({
-  collectionId: z12.string().min(1).describe(
+import { z as z13 } from "zod";
+var inputSchema11 = z13.object({
+  collectionId: collectionIdSchema.describe(
     'Collection ID to delete (GID format, e.g., "gid://shopify/Collection/123"). Use list-collections or get-collection to find collection IDs.'
   )
 });
-var outputSchema11 = z12.object({
-  deletedCollectionId: z12.string().describe("The GID of the deleted collection")
+var outputSchema11 = z13.object({
+  deletedCollectionId: z13.string().describe("The GID of the deleted collection")
 });
 var handleDeleteCollection = async (context, params) => {
   log.debug(`Deleting collection on shop: ${context.shopDomain}`);
@@ -4945,6 +5397,15 @@ function registerDeleteCollectionTool() {
       relationships: {
         relatedTools: ["list-collections"],
         prerequisites: ["get-collection"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        // Permanently deletes collection
+        idempotentHint: false,
+        // Second call fails (already deleted)
+        openWorldHint: true
       }
     },
     handleDeleteCollection
@@ -4952,15 +5413,15 @@ function registerDeleteCollectionTool() {
 }
 
 // src/tools/delete-page.ts
-import { z as z13 } from "zod";
-var inputSchema12 = z13.object({
-  id: z13.string().min(1).describe(
+import { z as z14 } from "zod";
+var inputSchema12 = z14.object({
+  id: pageIdSchema.describe(
     'The page ID to delete (required). Must be a valid Shopify GID format. Example: "gid://shopify/Page/123456789". Use list-pages to find page IDs. WARNING: This action is permanent and cannot be undone.'
   )
 });
-var outputSchema12 = z13.object({
-  success: z13.boolean().describe("Whether the deletion was successful"),
-  deletedPageId: z13.string().describe("The ID of the deleted page")
+var outputSchema12 = z14.object({
+  success: z14.boolean().describe("Whether the deletion was successful"),
+  deletedPageId: z14.string().describe("The ID of the deleted page")
 });
 var handleDeletePage = async (context, params) => {
   log.debug(`Deleting page on shop: ${context.shopDomain}`);
@@ -5001,6 +5462,14 @@ function registerDeletePageTool() {
         relatedTools: ["get-page", "list-pages"],
         prerequisites: ["get-page"],
         alternatives: ["update-page"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        // delete-* tools are NOT idempotent
+        openWorldHint: true
       }
     },
     handleDeletePage
@@ -5008,7 +5477,7 @@ function registerDeletePageTool() {
 }
 
 // src/tools/delete-product-image.ts
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 var FILE_DELETE_MUTATION = `
   mutation FileDelete($fileIds: [ID!]!) {
     fileDelete(fileIds: $fileIds) {
@@ -5020,14 +5489,14 @@ var FILE_DELETE_MUTATION = `
     }
   }
 `;
-var inputSchema13 = z14.object({
-  imageId: z14.string().min(1).describe(
+var inputSchema13 = z15.object({
+  imageId: imageIdSchema.describe(
     'Shopify image GID to delete (e.g., "gid://shopify/MediaImage/123"). Required. Use get-product to find image IDs in the images array.'
   )
 });
-var outputSchema13 = z14.object({
-  success: z14.boolean().describe("Whether the deletion was successful"),
-  deletedImageId: z14.string().describe("ID of the deleted image")
+var outputSchema13 = z15.object({
+  success: z15.boolean().describe("Whether the deletion was successful"),
+  deletedImageId: z15.string().describe("ID of the deleted image")
 });
 var handleDeleteProductImage = async (context, params) => {
   log.debug(`Deleting image on shop: ${context.shopDomain}`);
@@ -5085,6 +5554,15 @@ function registerDeleteProductImageTool() {
       relationships: {
         relatedTools: ["get-product", "add-product-image"],
         prerequisites: ["get-product"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        // Permanently deletes image from Shopify CDN
+        idempotentHint: false,
+        // Second call fails (already deleted)
+        openWorldHint: true
       }
     },
     handleDeleteProductImage
@@ -5092,7 +5570,7 @@ function registerDeleteProductImageTool() {
 }
 
 // src/tools/delete-product-metafields.ts
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 
 // src/shopify/metafields.ts
 var GET_PRODUCT_METAFIELDS_QUERY = `
@@ -5271,28 +5749,28 @@ async function deleteProductMetafields(productId, identifiers) {
 }
 
 // src/tools/delete-product-metafields.ts
-var metafieldIdentifierSchema = z15.object({
-  namespace: z15.string().min(1).describe('Metafield namespace (e.g., "custom", "seo"). Must match existing metafield.'),
-  key: z15.string().min(1).describe('Metafield key (e.g., "color_hex"). Must match existing metafield.')
+var metafieldIdentifierSchema = z16.object({
+  namespace: z16.string().min(1).describe('Metafield namespace (e.g., "custom", "seo"). Must match existing metafield.'),
+  key: z16.string().min(1).describe('Metafield key (e.g., "color_hex"). Must match existing metafield.')
 });
-var inputSchema14 = z15.object({
-  productId: z15.string().min(1).describe(
+var inputSchema14 = z16.object({
+  productId: productIdSchema.describe(
     'Shopify product ID (GID format, e.g., "gid://shopify/Product/123"). Use get-product or list-products to find product IDs.'
   ),
-  identifiers: z15.array(metafieldIdentifierSchema).min(1, "At least one metafield identifier is required").describe(
+  identifiers: z16.array(metafieldIdentifierSchema).min(1, "At least one metafield identifier is required").describe(
     "Array of metafield identifiers to delete. Each identifier must have namespace and key. Use get-product-metafields first to verify which metafields exist."
   )
 });
-var outputSchema14 = z15.object({
-  success: z15.boolean().describe("Whether the operation succeeded"),
-  deletedMetafields: z15.array(
-    z15.object({
-      ownerId: z15.string().describe("Product GID that owned the metafield"),
-      namespace: z15.string().describe("Namespace of deleted metafield"),
-      key: z15.string().describe("Key of deleted metafield")
+var outputSchema14 = z16.object({
+  success: z16.boolean().describe("Whether the operation succeeded"),
+  deletedMetafields: z16.array(
+    z16.object({
+      ownerId: z16.string().describe("Product GID that owned the metafield"),
+      namespace: z16.string().describe("Namespace of deleted metafield"),
+      key: z16.string().describe("Key of deleted metafield")
     })
   ).describe("Identifiers of successfully deleted metafields"),
-  deletedCount: z15.number().describe("Number of metafields deleted")
+  deletedCount: z16.number().describe("Number of metafields deleted")
 });
 var handleDeleteProductMetafields = async (context, params) => {
   log.debug(
@@ -5329,6 +5807,15 @@ function registerDeleteProductMetafieldsTool() {
       relationships: {
         relatedTools: ["get-product-metafields"],
         prerequisites: ["get-product-metafields"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        // Partial data deletion - cannot be recovered
+        idempotentHint: false,
+        // Second call fails (already deleted)
+        openWorldHint: true
       }
     },
     handleDeleteProductMetafields
@@ -5336,13 +5823,15 @@ function registerDeleteProductMetafieldsTool() {
 }
 
 // src/tools/delete-product.ts
-import { z as z16 } from "zod";
-var inputSchema15 = z16.object({
-  id: z16.string().min(1).describe('Shopify product ID (GID format, e.g., "gid://shopify/Product/123"). Required.')
+import { z as z17 } from "zod";
+var inputSchema15 = z17.object({
+  id: productIdSchema.describe(
+    'Shopify product ID (GID format, e.g., "gid://shopify/Product/123"). Required.'
+  )
 });
-var outputSchema15 = z16.object({
-  deletedProductId: z16.string().describe("The ID of the deleted product"),
-  title: z16.string().describe("The title of the deleted product (for confirmation)")
+var outputSchema15 = z17.object({
+  deletedProductId: z17.string().describe("The ID of the deleted product"),
+  title: z17.string().describe("The title of the deleted product (for confirmation)")
 });
 var handleDeleteProduct = async (context, params) => {
   log.debug(`Deleting product on shop: ${context.shopDomain}`);
@@ -5391,6 +5880,15 @@ function registerDeleteProductTool() {
       relationships: {
         relatedTools: ["list-products"],
         prerequisites: ["get-product"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        // Permanently deletes product
+        idempotentHint: false,
+        // Second call fails (already deleted)
+        openWorldHint: true
       }
     },
     handleDeleteProduct
@@ -5398,15 +5896,15 @@ function registerDeleteProductTool() {
 }
 
 // src/tools/delete-redirect.ts
-import { z as z17 } from "zod";
-var inputSchema16 = z17.object({
-  id: z17.string().min(1).describe(
+import { z as z18 } from "zod";
+var inputSchema16 = z18.object({
+  id: redirectIdSchema.describe(
     'Shopify redirect GID (e.g., "gid://shopify/UrlRedirect/123"). Use list-redirects to find redirect IDs.'
   )
 });
-var outputSchema16 = z17.object({
-  success: z17.boolean().describe("Whether the deletion succeeded"),
-  deletedRedirectId: z17.string().describe("ID of the deleted redirect")
+var outputSchema16 = z18.object({
+  success: z18.boolean().describe("Whether the deletion succeeded"),
+  deletedRedirectId: z18.string().describe("ID of the deleted redirect")
 });
 var handleDeleteRedirect = async (context, params) => {
   log.debug(`Deleting redirect on shop: ${context.shopDomain}`);
@@ -5455,6 +5953,15 @@ function registerDeleteRedirectTool() {
       relationships: {
         relatedTools: ["create-redirect"],
         prerequisites: ["list-redirects"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        // Permanently removes redirect - can hurt SEO
+        idempotentHint: false,
+        // Second call fails (already deleted)
+        openWorldHint: true
       }
     },
     handleDeleteRedirect
@@ -5462,7 +5969,7 @@ function registerDeleteRedirectTool() {
 }
 
 // src/tools/get-bulk-inventory.ts
-import { z as z18 } from "zod";
+import { z as z19 } from "zod";
 
 // src/shopify/inventory.ts
 var GET_INVENTORY_ITEM_QUERY = `
@@ -6033,46 +6540,46 @@ async function getBulkInventory(options) {
 }
 
 // src/tools/get-bulk-inventory.ts
-var inputSchema17 = z18.object({
-  productIds: z18.array(z18.string()).min(1, { message: "productIds array cannot be empty" }).max(50, { message: "Maximum 50 product IDs allowed per request" }).describe(
+var inputSchema17 = z19.object({
+  productIds: z19.array(productIdSchema).min(1, { message: "productIds array cannot be empty" }).max(50, { message: "Maximum 50 product IDs allowed per request" }).describe(
     'Array of Shopify product IDs (e.g., ["gid://shopify/Product/123", "gid://shopify/Product/456"]). Maximum 50 products per request. Get product IDs from list-products or search.'
   ),
-  includeVariants: z18.boolean().default(true).describe(
+  includeVariants: z19.boolean().default(true).describe(
     "Include per-variant inventory breakdown. Default: true. Set to false for faster response with only product totals."
   ),
-  locationId: z18.string().optional().describe(
+  locationId: locationIdSchema.optional().describe(
     'Optional location ID to filter inventory (e.g., "gid://shopify/Location/789"). If not provided, returns total inventory across all locations.'
   )
 });
-var outputSchema17 = z18.object({
-  products: z18.array(
-    z18.object({
-      productId: z18.string().describe("Product GID"),
-      productTitle: z18.string().describe("Product title"),
-      totalInventory: z18.number().describe("Total inventory across all variants"),
-      variants: z18.array(
-        z18.object({
-          variantId: z18.string().describe("Variant GID"),
-          variantTitle: z18.string().describe('Variant title (e.g., "Red / Large")'),
-          sku: z18.string().nullable().describe("SKU (Stock Keeping Unit)"),
-          inventoryItemId: z18.string().describe("Inventory item GID"),
-          available: z18.number().describe("Available quantity"),
-          locations: z18.array(
-            z18.object({
-              locationId: z18.string().describe("Location GID"),
-              locationName: z18.string().describe("Human-readable location name"),
-              available: z18.number().describe("Available quantity at this location")
+var outputSchema17 = z19.object({
+  products: z19.array(
+    z19.object({
+      productId: z19.string().describe("Product GID"),
+      productTitle: z19.string().describe("Product title"),
+      totalInventory: z19.number().describe("Total inventory across all variants"),
+      variants: z19.array(
+        z19.object({
+          variantId: z19.string().describe("Variant GID"),
+          variantTitle: z19.string().describe('Variant title (e.g., "Red / Large")'),
+          sku: z19.string().nullable().describe("SKU (Stock Keeping Unit)"),
+          inventoryItemId: z19.string().describe("Inventory item GID"),
+          available: z19.number().describe("Available quantity"),
+          locations: z19.array(
+            z19.object({
+              locationId: z19.string().describe("Location GID"),
+              locationName: z19.string().describe("Human-readable location name"),
+              available: z19.number().describe("Available quantity at this location")
             })
           ).optional().describe("Per-location inventory breakdown")
         })
       ).optional().describe("Variant details (if includeVariants=true)")
     })
   ).describe("Products with inventory data"),
-  notFound: z18.array(z18.string()).describe("Product IDs that were not found in the store"),
-  summary: z18.object({
-    productsQueried: z18.number().describe("Total number of product IDs provided"),
-    productsFound: z18.number().describe("Number of products found in the store"),
-    totalInventory: z18.number().describe("Sum of inventory across all found products")
+  notFound: z19.array(z19.string()).describe("Product IDs that were not found in the store"),
+  summary: z19.object({
+    productsQueried: z19.number().describe("Total number of product IDs provided"),
+    productsFound: z19.number().describe("Number of products found in the store"),
+    totalInventory: z19.number().describe("Sum of inventory across all found products")
   }).describe("Summary statistics")
 });
 var handleGetBulkInventory = async (context, params) => {
@@ -6112,6 +6619,13 @@ function registerGetBulkInventoryTool() {
         prerequisites: ["list-products"],
         followUps: ["update-inventory", "get-inventory"],
         alternatives: ["get-inventory"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleGetBulkInventory
@@ -6119,30 +6633,30 @@ function registerGetBulkInventoryTool() {
 }
 
 // src/tools/get-collection.ts
-import { z as z19 } from "zod";
-var inputSchema18 = z19.object({
-  collectionId: z19.string().min(1).describe(
+import { z as z20 } from "zod";
+var inputSchema18 = z20.object({
+  collectionId: collectionIdSchema.describe(
     'Collection ID (GID format, e.g., "gid://shopify/Collection/123"). Use list-collections to find collection IDs.'
   )
 });
-var outputSchema18 = z19.object({
-  id: z19.string().describe("Collection GID"),
-  title: z19.string().describe("Collection title"),
-  handle: z19.string().describe("URL handle/slug"),
-  description: z19.string().describe("Plain text description"),
-  descriptionHtml: z19.string().describe("HTML description"),
-  seo: z19.object({
-    title: z19.string().nullable().describe("SEO title"),
-    description: z19.string().nullable().describe("SEO description")
+var outputSchema18 = z20.object({
+  id: z20.string().describe("Collection GID"),
+  title: z20.string().describe("Collection title"),
+  handle: z20.string().describe("URL handle/slug"),
+  description: z20.string().describe("Plain text description"),
+  descriptionHtml: z20.string().describe("HTML description"),
+  seo: z20.object({
+    title: z20.string().nullable().describe("SEO title"),
+    description: z20.string().nullable().describe("SEO description")
   }),
-  image: z19.object({
-    id: z19.string().describe("Image GID"),
-    url: z19.string().describe("Image URL"),
-    altText: z19.string().nullable().describe("Alt text")
+  image: z20.object({
+    id: z20.string().describe("Image GID"),
+    url: z20.string().describe("Image URL"),
+    altText: z20.string().nullable().describe("Alt text")
   }).nullable(),
-  sortOrder: z19.string().describe("Product sort order within collection"),
-  productsCount: z19.number().describe("Number of products in collection"),
-  updatedAt: z19.string().describe("Last update timestamp (ISO 8601)")
+  sortOrder: z20.string().describe("Product sort order within collection"),
+  productsCount: z20.number().describe("Number of products in collection"),
+  updatedAt: z20.string().describe("Last update timestamp (ISO 8601)")
 });
 var handleGetCollection = async (context, params) => {
   log.debug(`Getting collection on shop: ${context.shopDomain}`);
@@ -6169,6 +6683,13 @@ function registerGetCollectionTool() {
       relationships: {
         relatedTools: ["list-collections"],
         followUps: ["update-collection", "delete-collection", "add-products-to-collection"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleGetCollection
@@ -6176,37 +6697,37 @@ function registerGetCollectionTool() {
 }
 
 // src/tools/get-inventory.ts
-import { z as z20 } from "zod";
-var inputSchema19 = z20.object({
-  variantId: z20.string().optional().describe(
+import { z as z21 } from "zod";
+var inputSchema19 = z21.object({
+  variantId: variantIdSchema.optional().describe(
     'The Shopify product variant ID (e.g., "gid://shopify/ProductVariant/123"). Use this when you have a variant ID from a product query (get-product or list-products).'
   ),
-  inventoryItemId: z20.string().optional().describe(
+  inventoryItemId: inventoryItemIdSchema.optional().describe(
     'The Shopify inventory item ID (e.g., "gid://shopify/InventoryItem/456"). Use this if you already have the inventory item ID from a previous query.'
   ),
-  locationId: z20.string().optional().describe(
+  locationId: locationIdSchema.optional().describe(
     'Optional location ID to filter results (e.g., "gid://shopify/Location/789"). If not provided, returns inventory at all locations.'
   )
 }).refine((data) => data.variantId || data.inventoryItemId, {
   message: "Either variantId or inventoryItemId must be provided"
 });
-var outputSchema19 = z20.object({
-  inventoryItemId: z20.string().describe("Inventory item GID"),
-  variantId: z20.string().describe("Product variant GID"),
-  variantTitle: z20.string().describe('Variant title (e.g., "Red / Large")'),
-  productId: z20.string().describe("Product GID"),
-  productTitle: z20.string().describe("Product title"),
-  sku: z20.string().nullable().describe("SKU (Stock Keeping Unit)"),
-  tracked: z20.boolean().describe("Whether inventory tracking is enabled for this item"),
-  totalAvailable: z20.number().describe("Total available quantity across all locations"),
-  locations: z20.array(
-    z20.object({
-      locationId: z20.string().describe("Location GID"),
-      locationName: z20.string().describe("Human-readable location name"),
-      isActive: z20.boolean().describe("Whether the location is active"),
-      available: z20.number().describe("Quantity available for sale"),
-      onHand: z20.number().describe("Physical quantity on hand"),
-      committed: z20.number().describe("Quantity committed to orders")
+var outputSchema19 = z21.object({
+  inventoryItemId: z21.string().describe("Inventory item GID"),
+  variantId: z21.string().describe("Product variant GID"),
+  variantTitle: z21.string().describe('Variant title (e.g., "Red / Large")'),
+  productId: z21.string().describe("Product GID"),
+  productTitle: z21.string().describe("Product title"),
+  sku: z21.string().nullable().describe("SKU (Stock Keeping Unit)"),
+  tracked: z21.boolean().describe("Whether inventory tracking is enabled for this item"),
+  totalAvailable: z21.number().describe("Total available quantity across all locations"),
+  locations: z21.array(
+    z21.object({
+      locationId: z21.string().describe("Location GID"),
+      locationName: z21.string().describe("Human-readable location name"),
+      isActive: z21.boolean().describe("Whether the location is active"),
+      available: z21.number().describe("Quantity available for sale"),
+      onHand: z21.number().describe("Physical quantity on hand"),
+      committed: z21.number().describe("Quantity committed to orders")
     })
   ).describe("Inventory levels by location")
 });
@@ -6280,6 +6801,13 @@ function registerGetInventoryTool() {
         ],
         prerequisites: ["get-product", "list-products"],
         followUps: ["update-inventory"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleGetInventory
@@ -6287,23 +6815,23 @@ function registerGetInventoryTool() {
 }
 
 // src/tools/get-page.ts
-import { z as z21 } from "zod";
-var inputSchema20 = z21.object({
-  id: z21.string().min(1).describe(
+import { z as z22 } from "zod";
+var inputSchema20 = z22.object({
+  id: pageIdSchema.describe(
     'The page ID to retrieve. Must be a valid Shopify GID format. Example: "gid://shopify/Page/123456789". Use list-pages to find page IDs.'
   )
 });
-var outputSchema20 = z21.object({
-  id: z21.string().describe("Page GID"),
-  title: z21.string().describe("Page title"),
-  handle: z21.string().describe("URL handle/slug"),
-  body: z21.string().describe("HTML body content"),
-  bodySummary: z21.string().describe("Plain text summary (first 150 chars)"),
-  isPublished: z21.boolean().describe("Whether page is visible on storefront"),
-  publishedAt: z21.string().nullable().describe("ISO timestamp when published"),
-  templateSuffix: z21.string().nullable().describe("Custom template suffix"),
-  createdAt: z21.string().describe("ISO timestamp of creation"),
-  updatedAt: z21.string().describe("ISO timestamp of last update")
+var outputSchema20 = z22.object({
+  id: z22.string().describe("Page GID"),
+  title: z22.string().describe("Page title"),
+  handle: z22.string().describe("URL handle/slug"),
+  body: z22.string().describe("HTML body content"),
+  bodySummary: z22.string().describe("Plain text summary (first 150 chars)"),
+  isPublished: z22.boolean().describe("Whether page is visible on storefront"),
+  publishedAt: z22.string().nullable().describe("ISO timestamp when published"),
+  templateSuffix: z22.string().nullable().describe("Custom template suffix"),
+  createdAt: z22.string().describe("ISO timestamp of creation"),
+  updatedAt: z22.string().describe("ISO timestamp of last update")
 });
 var handleGetPage = async (context, params) => {
   log.debug(`Getting page on shop: ${context.shopDomain}`);
@@ -6330,6 +6858,13 @@ function registerGetPageTool() {
         relatedTools: ["list-pages", "update-page", "delete-page"],
         prerequisites: ["list-pages"],
         followUps: ["update-page", "delete-page"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleGetPage
@@ -6337,27 +6872,27 @@ function registerGetPageTool() {
 }
 
 // src/tools/get-product-metafields.ts
-import { z as z22 } from "zod";
-var inputSchema21 = z22.object({
-  productId: z22.string().min(1).describe(
+import { z as z23 } from "zod";
+var inputSchema21 = z23.object({
+  productId: productIdSchema.describe(
     'Shopify product ID (GID format, e.g., "gid://shopify/Product/123"). Use get-product or list-products to find product IDs.'
   ),
-  namespace: z22.string().optional().describe(
+  namespace: z23.string().optional().describe(
     'Filter metafields by namespace (e.g., "custom", "seo", "my_app"). If not provided, returns metafields from all namespaces.'
   ),
-  keys: z22.array(z22.string()).optional().describe(
+  keys: z23.array(z23.string()).optional().describe(
     'Filter by specific metafield keys within the namespace (e.g., ["color", "size"]). Requires namespace to be specified for meaningful filtering.'
   )
 });
-var outputSchema21 = z22.array(
-  z22.object({
-    id: z22.string().describe('Metafield GID (e.g., "gid://shopify/Metafield/123")'),
-    namespace: z22.string().describe("Metafield namespace (grouping identifier)"),
-    key: z22.string().describe("Metafield key (field name)"),
-    value: z22.string().describe("Metafield value (the stored data)"),
-    type: z22.string().describe('Metafield type (e.g., "single_line_text_field", "json", "number_integer")'),
-    createdAt: z22.string().describe("Creation timestamp (ISO 8601)"),
-    updatedAt: z22.string().describe("Last update timestamp (ISO 8601)")
+var outputSchema21 = z23.array(
+  z23.object({
+    id: z23.string().describe('Metafield GID (e.g., "gid://shopify/Metafield/123")'),
+    namespace: z23.string().describe("Metafield namespace (grouping identifier)"),
+    key: z23.string().describe("Metafield key (field name)"),
+    value: z23.string().describe("Metafield value (the stored data)"),
+    type: z23.string().describe('Metafield type (e.g., "single_line_text_field", "json", "number_integer")'),
+    createdAt: z23.string().describe("Creation timestamp (ISO 8601)"),
+    updatedAt: z23.string().describe("Last update timestamp (ISO 8601)")
   })
 );
 var handleGetProductMetafields = async (context, params) => {
@@ -6390,6 +6925,13 @@ function registerGetProductMetafieldsTool() {
         relatedTools: ["get-product", "set-product-metafields"],
         prerequisites: ["get-product"],
         followUps: ["set-product-metafields", "delete-product-metafields"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleGetProductMetafields
@@ -6397,51 +6939,51 @@ function registerGetProductMetafieldsTool() {
 }
 
 // src/tools/get-product.ts
-import { z as z23 } from "zod";
-var inputSchema22 = z23.object({
-  id: z23.string().optional().describe(
+import { z as z24 } from "zod";
+var inputSchema22 = z24.object({
+  id: productIdSchema.optional().describe(
     'Shopify product ID (GID format, e.g., "gid://shopify/Product/123"). Use either id or handle.'
   ),
-  handle: z23.string().optional().describe(
+  handle: z24.string().optional().describe(
     'Product URL handle/slug (e.g., "premium-cotton-t-shirt"). Use either id or handle.'
   )
 }).refine((data) => data.id || data.handle, {
   message: "Either id or handle must be provided"
 });
-var outputSchema22 = z23.object({
-  id: z23.string().describe('Product GID (e.g., "gid://shopify/Product/123")'),
-  title: z23.string().describe("Product title"),
-  handle: z23.string().describe("URL handle/slug"),
-  description: z23.string().nullable().describe("Product description (HTML)"),
-  vendor: z23.string().describe("Vendor/brand name"),
-  productType: z23.string().describe("Product type"),
-  status: z23.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).describe("Product status"),
-  tags: z23.array(z23.string()).describe("Product tags"),
-  seo: z23.object({
-    title: z23.string().nullable().describe("SEO title for search engines"),
-    description: z23.string().nullable().describe("SEO description/meta description")
+var outputSchema22 = z24.object({
+  id: z24.string().describe('Product GID (e.g., "gid://shopify/Product/123")'),
+  title: z24.string().describe("Product title"),
+  handle: z24.string().describe("URL handle/slug"),
+  description: z24.string().nullable().describe("Product description (HTML)"),
+  vendor: z24.string().describe("Vendor/brand name"),
+  productType: z24.string().describe("Product type"),
+  status: z24.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).describe("Product status"),
+  tags: z24.array(z24.string()).describe("Product tags"),
+  seo: z24.object({
+    title: z24.string().nullable().describe("SEO title for search engines"),
+    description: z24.string().nullable().describe("SEO description/meta description")
   }).describe("SEO metadata for search engine optimization"),
-  createdAt: z23.string().describe("Creation timestamp (ISO 8601)"),
-  updatedAt: z23.string().describe("Last update timestamp (ISO 8601)"),
-  variants: z23.array(
-    z23.object({
-      id: z23.string().describe("Variant GID"),
-      title: z23.string().describe("Variant title"),
-      price: z23.string().describe("Price"),
-      compareAtPrice: z23.string().nullable().describe("Compare at price"),
-      sku: z23.string().nullable().describe("SKU"),
-      barcode: z23.string().nullable().describe("Barcode"),
-      inventoryQuantity: z23.number().nullable().describe("Inventory quantity")
+  createdAt: z24.string().describe("Creation timestamp (ISO 8601)"),
+  updatedAt: z24.string().describe("Last update timestamp (ISO 8601)"),
+  variants: z24.array(
+    z24.object({
+      id: z24.string().describe("Variant GID"),
+      title: z24.string().describe("Variant title"),
+      price: z24.string().describe("Price"),
+      compareAtPrice: z24.string().nullable().describe("Compare at price"),
+      sku: z24.string().nullable().describe("SKU"),
+      barcode: z24.string().nullable().describe("Barcode"),
+      inventoryQuantity: z24.number().nullable().describe("Inventory quantity")
     })
   ).describe("Product variants"),
-  images: z23.array(
-    z23.object({
-      id: z23.string().describe("Image GID"),
-      url: z23.string().describe("Image URL"),
-      altText: z23.string().nullable().describe("Alt text")
+  images: z24.array(
+    z24.object({
+      id: z24.string().describe("Image GID"),
+      url: z24.string().describe("Image URL"),
+      altText: z24.string().nullable().describe("Alt text")
     })
   ).describe("Product images"),
-  totalInventory: z23.number().describe("Total inventory across variants")
+  totalInventory: z24.number().describe("Total inventory across variants")
 });
 var handleGetProduct = async (context, params) => {
   log.debug(`Getting product on shop: ${context.shopDomain}`);
@@ -6492,6 +7034,13 @@ function registerGetProductTool() {
           "add-product-image",
           "get-product-metafields"
         ]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleGetProduct
@@ -6499,36 +7048,36 @@ function registerGetProductTool() {
 }
 
 // src/tools/list-articles.ts
-import { z as z24 } from "zod";
-var inputSchema23 = z24.object({
-  first: z24.number().int().min(1).max(50).optional().default(10).describe("Number of articles to return (1-50). Defaults to 10."),
-  cursor: z24.string().optional().describe(
+import { z as z25 } from "zod";
+var inputSchema23 = z25.object({
+  first: z25.number().int().min(1).max(50).optional().default(10).describe("Number of articles to return (1-50). Defaults to 10."),
+  cursor: z25.string().optional().describe(
     "Pagination cursor from a previous response. Use the endCursor from the previous response to get the next page of results."
   ),
-  query: z24.string().optional().describe(
+  query: z25.string().optional().describe(
     "Search query to filter articles. Supports Shopify search syntax. Examples: 'title:Guide', 'tag:tutorial', 'blog_id:123456789'."
   ),
-  blogId: z24.string().optional().describe(
+  blogId: z25.string().optional().describe(
     'Filter articles by blog ID. Provide the numeric ID (not the full GID) to filter. Example: To filter blog "gid://shopify/Blog/123456", pass blogId as "123456".'
   ),
-  sortKey: z24.enum(["ID", "TITLE", "UPDATED_AT", "PUBLISHED_AT", "AUTHOR", "BLOG_TITLE"]).optional().describe("Sort order for results. Defaults to ID.")
+  sortKey: z25.enum(["ID", "TITLE", "UPDATED_AT", "PUBLISHED_AT", "AUTHOR", "BLOG_TITLE"]).optional().describe("Sort order for results. Defaults to ID.")
 });
-var outputSchema23 = z24.object({
-  articles: z24.array(
-    z24.object({
-      id: z24.string().describe("Article GID"),
-      title: z24.string().describe("Article title"),
-      handle: z24.string().describe("URL handle/slug"),
-      blog: z24.object({
-        id: z24.string().describe("Parent blog GID"),
-        title: z24.string().describe("Parent blog title")
+var outputSchema23 = z25.object({
+  articles: z25.array(
+    z25.object({
+      id: z25.string().describe("Article GID"),
+      title: z25.string().describe("Article title"),
+      handle: z25.string().describe("URL handle/slug"),
+      blog: z25.object({
+        id: z25.string().describe("Parent blog GID"),
+        title: z25.string().describe("Parent blog title")
       }),
-      isPublished: z24.boolean().describe("Whether article is visible on storefront"),
-      publishedAt: z24.string().nullable().describe("ISO timestamp when published")
+      isPublished: z25.boolean().describe("Whether article is visible on storefront"),
+      publishedAt: z25.string().nullable().describe("ISO timestamp when published")
     })
   ),
-  hasNextPage: z24.boolean().describe("Whether more articles are available"),
-  endCursor: z24.string().nullable().describe("Cursor for next page pagination")
+  hasNextPage: z25.boolean().describe("Whether more articles are available"),
+  endCursor: z25.string().nullable().describe("Cursor for next page pagination")
 });
 var handleListArticles = async (context, params) => {
   log.debug(`Listing articles on shop: ${context.shopDomain}`);
@@ -6578,6 +7127,13 @@ function registerListArticlesTool() {
       relationships: {
         relatedTools: ["list-blogs", "create-article", "update-article"],
         followUps: ["update-article", "delete-article", "create-article"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleListArticles
@@ -6585,29 +7141,29 @@ function registerListArticlesTool() {
 }
 
 // src/tools/list-blogs.ts
-import { z as z25 } from "zod";
-var inputSchema24 = z25.object({
-  first: z25.number().int().min(1).max(50).optional().default(10).describe("Number of blogs to return (1-50). Defaults to 10."),
-  cursor: z25.string().optional().describe(
+import { z as z26 } from "zod";
+var inputSchema24 = z26.object({
+  first: z26.number().int().min(1).max(50).optional().default(10).describe("Number of blogs to return (1-50). Defaults to 10."),
+  cursor: z26.string().optional().describe(
     "Pagination cursor from a previous response. Use the endCursor from the previous response to get the next page of results."
   ),
-  query: z25.string().optional().describe(
+  query: z26.string().optional().describe(
     "Search query to filter blogs. Supports Shopify search syntax. Examples: 'title:News', 'handle:company-blog'."
   ),
-  sortKey: z25.enum(["ID", "TITLE", "UPDATED_AT"]).optional().describe("Sort order for results. Defaults to ID.")
+  sortKey: z26.enum(["ID", "TITLE", "UPDATED_AT"]).optional().describe("Sort order for results. Defaults to ID.")
 });
-var outputSchema24 = z25.object({
-  blogs: z25.array(
-    z25.object({
-      id: z25.string().describe("Blog GID"),
-      title: z25.string().describe("Blog title"),
-      handle: z25.string().describe("URL handle/slug"),
-      commentPolicy: z25.enum(["CLOSED", "MODERATE", "OPEN"]).describe("Comment moderation policy"),
-      articlesCount: z25.number().describe("Number of articles in the blog")
+var outputSchema24 = z26.object({
+  blogs: z26.array(
+    z26.object({
+      id: z26.string().describe("Blog GID"),
+      title: z26.string().describe("Blog title"),
+      handle: z26.string().describe("URL handle/slug"),
+      commentPolicy: z26.enum(["CLOSED", "MODERATE", "OPEN"]).describe("Comment moderation policy"),
+      articlesCount: z26.number().describe("Number of articles in the blog")
     })
   ),
-  hasNextPage: z25.boolean().describe("Whether more blogs are available"),
-  endCursor: z25.string().nullable().describe("Cursor for next page pagination")
+  hasNextPage: z26.boolean().describe("Whether more blogs are available"),
+  endCursor: z26.string().nullable().describe("Cursor for next page pagination")
 });
 var handleListBlogs = async (context, params) => {
   log.debug(`Listing blogs on shop: ${context.shopDomain}`);
@@ -6651,6 +7207,13 @@ function registerListBlogsTool() {
       relationships: {
         relatedTools: ["create-blog", "update-blog", "list-articles"],
         followUps: ["create-article", "update-blog", "create-blog"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleListBlogs
@@ -6658,40 +7221,40 @@ function registerListBlogsTool() {
 }
 
 // src/tools/list-collections.ts
-import { z as z26 } from "zod";
-var inputSchema25 = z26.object({
-  first: z26.number().int().min(1).max(50).optional().default(10).describe("Number of collections to return (1-50). Default: 10"),
-  after: z26.string().optional().describe(
+import { z as z27 } from "zod";
+var inputSchema25 = z27.object({
+  first: z27.number().int().min(1).max(50).optional().default(10).describe("Number of collections to return (1-50). Default: 10"),
+  after: z27.string().optional().describe(
     "Pagination cursor from previous response. Use the endCursor value from the previous page to get the next page of results."
   ),
-  query: z26.string().optional().describe(
+  query: z27.string().optional().describe(
     'Search query to filter collections. Searches across collection titles and handles. Example: "summer" finds collections with "summer" in the title or handle.'
   ),
-  sortKey: z26.enum(["TITLE", "UPDATED_AT", "ID", "RELEVANCE"]).optional().describe(
+  sortKey: z27.enum(["TITLE", "UPDATED_AT", "ID", "RELEVANCE"]).optional().describe(
     "Sort collections by: TITLE (alphabetical), UPDATED_AT (most recently updated first), ID (by collection ID), or RELEVANCE (best match when using query filter)"
   )
 });
-var outputSchema25 = z26.object({
-  collections: z26.array(
-    z26.object({
-      id: z26.string().describe("Collection GID"),
-      title: z26.string().describe("Collection title"),
-      handle: z26.string().describe("URL handle"),
-      seo: z26.object({
-        title: z26.string().nullable().describe("SEO title"),
-        description: z26.string().nullable().describe("SEO description")
+var outputSchema25 = z27.object({
+  collections: z27.array(
+    z27.object({
+      id: z27.string().describe("Collection GID"),
+      title: z27.string().describe("Collection title"),
+      handle: z27.string().describe("URL handle"),
+      seo: z27.object({
+        title: z27.string().nullable().describe("SEO title"),
+        description: z27.string().nullable().describe("SEO description")
       }),
-      productsCount: z26.number().describe("Number of products in collection")
+      productsCount: z27.number().describe("Number of products in collection")
     })
   ),
-  pageInfo: z26.object({
-    hasNextPage: z26.boolean().describe("Whether more pages exist"),
-    endCursor: z26.string().nullable().describe("Cursor for next page")
+  pageInfo: z27.object({
+    hasNextPage: z27.boolean().describe("Whether more pages exist"),
+    endCursor: z27.string().nullable().describe("Cursor for next page")
   }),
-  summary: z26.object({
-    totalReturned: z26.number().describe("Number of collections in this response"),
-    hasMore: z26.boolean().describe("Whether more collections are available"),
-    hint: z26.string().describe("Suggestion for next action")
+  summary: z27.object({
+    totalReturned: z27.number().describe("Number of collections in this response"),
+    hasMore: z27.boolean().describe("Whether more collections are available"),
+    hint: z27.string().describe("Suggestion for next action")
   }).describe("AI-friendly summary for context management")
 });
 var handleListCollections = async (context, params) => {
@@ -6725,6 +7288,13 @@ function registerListCollectionsTool() {
       relationships: {
         relatedTools: ["get-collection"],
         followUps: ["get-collection", "update-collection", "add-products-to-collection"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleListCollections
@@ -6732,47 +7302,47 @@ function registerListCollectionsTool() {
 }
 
 // src/tools/list-low-inventory.ts
-import { z as z27 } from "zod";
-var inputSchema26 = z27.object({
-  threshold: z27.number().int().min(0).default(10).describe(
+import { z as z28 } from "zod";
+var inputSchema26 = z28.object({
+  threshold: z28.number().int().min(0).default(10).describe(
     "Products with total inventory at or below this number will be included. Default: 10. Use 0 to find only out-of-stock products."
   ),
-  includeZero: z27.boolean().default(true).describe(
+  includeZero: z28.boolean().default(true).describe(
     "Include products with zero inventory. Default: true. Set to false to see only low-stock (not out-of-stock) products."
   ),
-  status: z27.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).optional().describe(
+  status: z28.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).optional().describe(
     "Filter by product status. Default: ACTIVE. Use DRAFT to check pre-launch products, ARCHIVED for historical."
   ),
-  first: z27.number().int().min(1).max(100).default(50).describe("Number of products to return per page. Default: 50, max: 100."),
-  after: z27.string().optional().describe("Pagination cursor from previous response. Use pageInfo.endCursor to get next page.")
+  first: z28.number().int().min(1).max(100).default(50).describe("Number of products to return per page. Default: 50, max: 100."),
+  after: z28.string().optional().describe("Pagination cursor from previous response. Use pageInfo.endCursor to get next page.")
 });
-var outputSchema26 = z27.object({
-  products: z27.array(
-    z27.object({
-      productId: z27.string().describe('Product GID (e.g., "gid://shopify/Product/123")'),
-      productTitle: z27.string().describe("Product title"),
-      status: z27.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).describe("Product status"),
-      totalInventory: z27.number().describe("Total inventory across all variants"),
-      isOutOfStock: z27.boolean().describe("True if total inventory is zero"),
-      variants: z27.array(
-        z27.object({
-          variantId: z27.string().describe("Variant GID"),
-          variantTitle: z27.string().describe('Variant title (e.g., "Red / Large")'),
-          sku: z27.string().nullable().describe("SKU (Stock Keeping Unit)"),
-          inventoryItemId: z27.string().describe("Inventory item GID"),
-          available: z27.number().describe("Available quantity for sale")
+var outputSchema26 = z28.object({
+  products: z28.array(
+    z28.object({
+      productId: z28.string().describe('Product GID (e.g., "gid://shopify/Product/123")'),
+      productTitle: z28.string().describe("Product title"),
+      status: z28.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).describe("Product status"),
+      totalInventory: z28.number().describe("Total inventory across all variants"),
+      isOutOfStock: z28.boolean().describe("True if total inventory is zero"),
+      variants: z28.array(
+        z28.object({
+          variantId: z28.string().describe("Variant GID"),
+          variantTitle: z28.string().describe('Variant title (e.g., "Red / Large")'),
+          sku: z28.string().nullable().describe("SKU (Stock Keeping Unit)"),
+          inventoryItemId: z28.string().describe("Inventory item GID"),
+          available: z28.number().describe("Available quantity for sale")
         })
       ).describe("Variant breakdown with inventory")
     })
   ).describe("Products with low inventory, sorted by total inventory ascending"),
-  pageInfo: z27.object({
-    hasNextPage: z27.boolean().describe("Whether more products exist after this page"),
-    endCursor: z27.string().nullable().describe('Cursor for the last item - use as "after" to get next page')
+  pageInfo: z28.object({
+    hasNextPage: z28.boolean().describe("Whether more products exist after this page"),
+    endCursor: z28.string().nullable().describe('Cursor for the last item - use as "after" to get next page')
   }).describe("Pagination information"),
-  summary: z27.object({
-    totalProducts: z27.number().describe("Number of products in this response"),
-    outOfStockCount: z27.number().describe("Number of products with zero inventory"),
-    lowStockCount: z27.number().describe("Number of products with inventory > 0 but below threshold")
+  summary: z28.object({
+    totalProducts: z28.number().describe("Number of products in this response"),
+    outOfStockCount: z28.number().describe("Number of products with zero inventory"),
+    lowStockCount: z28.number().describe("Number of products with inventory > 0 but below threshold")
   }).describe("Summary statistics")
 });
 var handleListLowInventory = async (context, params) => {
@@ -6802,6 +7372,13 @@ function registerListLowInventoryTool() {
       relationships: {
         relatedTools: ["get-inventory", "update-inventory", "get-bulk-inventory"],
         followUps: ["get-inventory", "update-inventory"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleListLowInventory
@@ -6809,31 +7386,31 @@ function registerListLowInventoryTool() {
 }
 
 // src/tools/list-pages.ts
-import { z as z28 } from "zod";
-var inputSchema27 = z28.object({
-  first: z28.number().int().min(1).max(50).optional().describe(
+import { z as z29 } from "zod";
+var inputSchema27 = z29.object({
+  first: z29.number().int().min(1).max(50).optional().describe(
     "Number of pages to return per request. Default: 10, Maximum: 50. Use pagination (cursor) to retrieve more results."
   ),
-  cursor: z28.string().optional().describe(
+  cursor: z29.string().optional().describe(
     "Pagination cursor from a previous list-pages response (endCursor). Use this to get the next page of results."
   ),
-  query: z28.string().optional().describe(
+  query: z29.string().optional().describe(
     "Search query to filter pages. Supports Shopify search syntax. Examples: 'title:About', 'handle:contact', 'created_at:>2024-01-01'."
   ),
-  sortKey: z28.enum(["ID", "TITLE", "UPDATED_AT", "PUBLISHED_AT"]).optional().describe("Field to sort pages by. Options: ID (default), TITLE, UPDATED_AT, PUBLISHED_AT.")
+  sortKey: z29.enum(["ID", "TITLE", "UPDATED_AT", "PUBLISHED_AT"]).optional().describe("Field to sort pages by. Options: ID (default), TITLE, UPDATED_AT, PUBLISHED_AT.")
 });
-var outputSchema27 = z28.object({
-  pages: z28.array(
-    z28.object({
-      id: z28.string().describe("Page GID"),
-      title: z28.string().describe("Page title"),
-      handle: z28.string().describe("URL handle/slug"),
-      isPublished: z28.boolean().describe("Whether page is visible"),
-      updatedAt: z28.string().describe("ISO timestamp of last update")
+var outputSchema27 = z29.object({
+  pages: z29.array(
+    z29.object({
+      id: z29.string().describe("Page GID"),
+      title: z29.string().describe("Page title"),
+      handle: z29.string().describe("URL handle/slug"),
+      isPublished: z29.boolean().describe("Whether page is visible"),
+      updatedAt: z29.string().describe("ISO timestamp of last update")
     })
   ),
-  hasNextPage: z28.boolean().describe("Whether more pages exist"),
-  endCursor: z28.string().nullable().describe("Cursor for next page of results")
+  hasNextPage: z29.boolean().describe("Whether more pages exist"),
+  endCursor: z29.string().nullable().describe("Cursor for next page of results")
 });
 var handleListPages = async (context, params) => {
   log.debug(`Listing pages on shop: ${context.shopDomain}`);
@@ -6865,6 +7442,13 @@ function registerListPagesTool() {
       relationships: {
         relatedTools: ["get-page", "create-page"],
         followUps: ["get-page", "update-page", "create-page"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleListPages
@@ -6872,46 +7456,46 @@ function registerListPagesTool() {
 }
 
 // src/tools/list-products.ts
-import { z as z29 } from "zod";
-var inputSchema28 = z29.object({
-  first: z29.number().int().min(1).max(50).optional().describe("Number of products to return (1-50). Default: 10"),
-  after: z29.string().optional().describe("Pagination cursor from previous response's endCursor. Omit for first page."),
-  query: z29.string().optional().describe(
+import { z as z30 } from "zod";
+var inputSchema28 = z30.object({
+  first: z30.number().int().min(1).max(50).optional().describe("Number of products to return (1-50). Default: 10"),
+  after: z30.string().optional().describe("Pagination cursor from previous response's endCursor. Omit for first page."),
+  query: z30.string().optional().describe(
     'Search query for title, description, tags. Example: "summer dress", "organic cotton"'
   ),
-  status: z29.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).optional().describe(
+  status: z30.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).optional().describe(
     "Filter by product status. ACTIVE = published, DRAFT = not published, ARCHIVED = hidden"
   ),
-  vendor: z29.string().optional().describe('Filter by exact vendor name. Example: "Acme Corp", "Nike"'),
-  productType: z29.string().optional().describe('Filter by exact product type. Example: "T-Shirts", "Shoes"'),
-  sortBy: z29.enum(["TITLE", "CREATED_AT", "UPDATED_AT", "INVENTORY_TOTAL"]).optional().describe("Sort field. TITLE, CREATED_AT (default), UPDATED_AT, or INVENTORY_TOTAL"),
-  sortOrder: z29.enum(["ASC", "DESC"]).optional().describe("Sort direction. ASC (default) for ascending, DESC for descending")
+  vendor: z30.string().optional().describe('Filter by exact vendor name. Example: "Acme Corp", "Nike"'),
+  productType: z30.string().optional().describe('Filter by exact product type. Example: "T-Shirts", "Shoes"'),
+  sortBy: z30.enum(["TITLE", "CREATED_AT", "UPDATED_AT", "INVENTORY_TOTAL"]).optional().describe("Sort field. TITLE, CREATED_AT (default), UPDATED_AT, or INVENTORY_TOTAL"),
+  sortOrder: z30.enum(["ASC", "DESC"]).optional().describe("Sort direction. ASC (default) for ascending, DESC for descending")
 });
-var outputSchema28 = z29.object({
-  products: z29.array(
-    z29.object({
-      id: z29.string().describe('Product GID (e.g., "gid://shopify/Product/123")'),
-      title: z29.string().describe("Product title"),
-      handle: z29.string().describe("URL handle/slug"),
-      status: z29.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).describe("Product status"),
-      vendor: z29.string().describe("Vendor/brand name"),
-      productType: z29.string().describe("Product type"),
-      totalInventory: z29.number().describe("Total inventory across all variants"),
-      primaryVariantPrice: z29.string().describe('Price of the first variant (e.g., "29.99")'),
-      imageUrl: z29.string().nullable().describe("First image URL or null if no images")
+var outputSchema28 = z30.object({
+  products: z30.array(
+    z30.object({
+      id: z30.string().describe('Product GID (e.g., "gid://shopify/Product/123")'),
+      title: z30.string().describe("Product title"),
+      handle: z30.string().describe("URL handle/slug"),
+      status: z30.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).describe("Product status"),
+      vendor: z30.string().describe("Vendor/brand name"),
+      productType: z30.string().describe("Product type"),
+      totalInventory: z30.number().describe("Total inventory across all variants"),
+      primaryVariantPrice: z30.string().describe('Price of the first variant (e.g., "29.99")'),
+      imageUrl: z30.string().nullable().describe("First image URL or null if no images")
     })
   ).describe("Array of product summaries"),
-  pageInfo: z29.object({
-    hasNextPage: z29.boolean().describe("Whether more products exist after this page"),
-    hasPreviousPage: z29.boolean().describe("Whether products exist before this page"),
-    startCursor: z29.string().nullable().describe("Cursor for the first item in this page"),
-    endCursor: z29.string().nullable().describe('Cursor for the last item - use as "after" to get next page')
+  pageInfo: z30.object({
+    hasNextPage: z30.boolean().describe("Whether more products exist after this page"),
+    hasPreviousPage: z30.boolean().describe("Whether products exist before this page"),
+    startCursor: z30.string().nullable().describe("Cursor for the first item in this page"),
+    endCursor: z30.string().nullable().describe('Cursor for the last item - use as "after" to get next page')
   }).describe("Pagination information"),
-  totalCount: z29.number().describe("Number of products returned in this page"),
-  summary: z29.object({
-    totalReturned: z29.number().describe("Number of products in this response"),
-    hasMore: z29.boolean().describe("Whether more products are available"),
-    hint: z29.string().describe("Suggestion for next action")
+  totalCount: z30.number().describe("Number of products returned in this page"),
+  summary: z30.object({
+    totalReturned: z30.number().describe("Number of products in this response"),
+    hasMore: z30.boolean().describe("Whether more products are available"),
+    hint: z30.string().describe("Suggestion for next action")
   }).describe("AI-friendly summary for context management")
 });
 var handleListProducts = async (context, params) => {
@@ -6952,6 +7536,13 @@ function registerListProductsTool() {
       relationships: {
         relatedTools: ["get-product"],
         followUps: ["get-product", "update-product", "delete-product"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleListProducts
@@ -6959,30 +7550,30 @@ function registerListProductsTool() {
 }
 
 // src/tools/list-redirects.ts
-import { z as z30 } from "zod";
-var inputSchema29 = z30.object({
-  first: z30.number().int().min(1).max(50).optional().default(10).describe("Number of redirects to return (1-50, default: 10)."),
-  cursor: z30.string().optional().describe(
+import { z as z31 } from "zod";
+var inputSchema29 = z31.object({
+  first: z31.number().int().min(1).max(50).optional().default(10).describe("Number of redirects to return (1-50, default: 10)."),
+  cursor: z31.string().optional().describe(
     "Pagination cursor from previous response (endCursor). Use this to fetch the next page of results."
   ),
-  query: z30.string().optional().describe(
+  query: z31.string().optional().describe(
     "Search filter. Supports 'path:' and 'target:' prefixes. Examples: 'path:/old-' to find redirects starting with /old-, 'target:/products/' to find redirects pointing to /products/."
   )
 });
-var outputSchema29 = z30.object({
-  redirects: z30.array(
-    z30.object({
-      id: z30.string().describe("Redirect GID"),
-      path: z30.string().describe("Source path"),
-      target: z30.string().describe("Target URL")
+var outputSchema29 = z31.object({
+  redirects: z31.array(
+    z31.object({
+      id: z31.string().describe("Redirect GID"),
+      path: z31.string().describe("Source path"),
+      target: z31.string().describe("Target URL")
     })
   ),
-  hasNextPage: z30.boolean().describe("Whether more results exist"),
-  endCursor: z30.string().nullable().describe("Cursor for fetching next page"),
-  summary: z30.object({
-    totalReturned: z30.number().describe("Number of redirects in this response"),
-    hasMore: z30.boolean().describe("Whether more redirects are available"),
-    hint: z30.string().describe("Suggestion for next action")
+  hasNextPage: z31.boolean().describe("Whether more results exist"),
+  endCursor: z31.string().nullable().describe("Cursor for fetching next page"),
+  summary: z31.object({
+    totalReturned: z31.number().describe("Number of redirects in this response"),
+    hasMore: z31.boolean().describe("Whether more redirects are available"),
+    hint: z31.string().describe("Suggestion for next action")
   }).describe("AI-friendly summary for context management")
 });
 var handleListRedirects = async (context, params) => {
@@ -7027,6 +7618,13 @@ function registerListRedirectsTool() {
       relationships: {
         relatedTools: ["create-redirect"],
         followUps: ["delete-redirect"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleListRedirects
@@ -7034,18 +7632,18 @@ function registerListRedirectsTool() {
 }
 
 // src/tools/remove-products-from-collection.ts
-import { z as z31 } from "zod";
-var inputSchema30 = z31.object({
-  collectionId: z31.string().min(1).describe(
+import { z as z32 } from "zod";
+var inputSchema30 = z32.object({
+  collectionId: collectionIdSchema.describe(
     'Collection GID (e.g., "gid://shopify/Collection/123"). Use list-collections to find valid collection IDs.'
   ),
-  productIds: z31.array(z31.string().min(1)).min(1).max(250).describe(
+  productIds: z32.array(productIdSchema).min(1).max(250).describe(
     'Array of product GIDs to remove (e.g., ["gid://shopify/Product/123", "gid://shopify/Product/456"]). Maximum 250 products per call. Use list-products to find valid product IDs.'
   )
 });
-var outputSchema30 = z31.object({
-  success: z31.boolean().describe("Whether the operation succeeded"),
-  removedCount: z31.number().describe("Number of products removed from the collection")
+var outputSchema30 = z32.object({
+  success: z32.boolean().describe("Whether the operation succeeded"),
+  removedCount: z32.number().describe("Number of products removed from the collection")
 });
 var handleRemoveProductsFromCollection = async (context, params) => {
   log.debug(
@@ -7082,6 +7680,15 @@ function registerRemoveProductsFromCollectionTool() {
       relationships: {
         relatedTools: ["add-products-to-collection", "get-collection"],
         prerequisites: ["get-collection"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        // Does not delete products, just removes from collection
+        idempotentHint: true,
+        // Removing already-removed products is idempotent
+        openWorldHint: true
       }
     },
     handleRemoveProductsFromCollection
@@ -7089,7 +7696,7 @@ function registerRemoveProductsFromCollectionTool() {
 }
 
 // src/tools/reorder-product-images.ts
-import { z as z32 } from "zod";
+import { z as z33 } from "zod";
 var PRODUCT_REORDER_MEDIA_MUTATION = `
   mutation ProductReorderMedia($id: ID!, $moves: [MoveInput!]!) {
     productReorderMedia(id: $id, moves: $moves) {
@@ -7104,23 +7711,23 @@ var PRODUCT_REORDER_MEDIA_MUTATION = `
     }
   }
 `;
-var moveSchema = z32.object({
-  id: z32.string().min(1).describe('Image GID to move (e.g., "gid://shopify/MediaImage/123")'),
-  newPosition: z32.number().int().min(0).describe("Zero-based target position. Position 0 is the featured image.")
+var moveSchema = z33.object({
+  id: imageIdSchema.describe('Image GID to move (e.g., "gid://shopify/MediaImage/123")'),
+  newPosition: z33.number().int().min(0).describe("Zero-based target position. Position 0 is the featured image.")
 });
-var inputSchema31 = z32.object({
-  productId: z32.string().min(1).describe(
+var inputSchema31 = z33.object({
+  productId: productIdSchema.describe(
     'Shopify product GID (e.g., "gid://shopify/Product/123"). Required. Use list-products to find product IDs.'
   ),
-  moves: z32.array(moveSchema).min(1).describe(
+  moves: z33.array(moveSchema).min(1).describe(
     "Array of move operations. Each move specifies an image ID and its new position. Only include images whose position is actually changing. Positions are 0-indexed (position 0 is the featured/hero image)."
   )
 });
-var outputSchema31 = z32.object({
-  success: z32.boolean().describe("Whether the reorder operation was initiated successfully"),
-  jobId: z32.string().nullable().describe("Background job ID for tracking (may be null if processed immediately)"),
-  jobDone: z32.boolean().describe("Whether the job completed immediately"),
-  message: z32.string().describe("Human-readable message describing the result")
+var outputSchema31 = z33.object({
+  success: z33.boolean().describe("Whether the reorder operation was initiated successfully"),
+  jobId: z33.string().nullable().describe("Background job ID for tracking (may be null if processed immediately)"),
+  jobDone: z33.boolean().describe("Whether the job completed immediately"),
+  message: z33.string().describe("Human-readable message describing the result")
 });
 var handleReorderProductImages = async (context, params) => {
   log.debug(`Reordering images on shop: ${context.shopDomain}`);
@@ -7195,6 +7802,14 @@ function registerReorderProductImagesTool() {
       relationships: {
         relatedTools: ["add-product-image", "update-product-image"],
         prerequisites: ["get-product"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        // Same order produces same result
+        openWorldHint: true
       }
     },
     handleReorderProductImages
@@ -7202,45 +7817,45 @@ function registerReorderProductImagesTool() {
 }
 
 // src/tools/set-product-metafields.ts
-import { z as z33 } from "zod";
+import { z as z34 } from "zod";
 var MAX_METAFIELDS_PER_CALL = 25;
-var metafieldInputSchema = z33.object({
-  namespace: z33.string().min(1).describe(
+var metafieldInputSchema = z34.object({
+  namespace: z34.string().min(1).describe(
     'Metafield namespace (grouping identifier, e.g., "custom", "seo", "my_app"). Use consistent namespaces to organize related metafields.'
   ),
-  key: z33.string().min(1).describe(
+  key: z34.string().min(1).describe(
     'Metafield key (field name, e.g., "color_hex", "schema_markup"). Keys should be lowercase with underscores, unique within a namespace.'
   ),
-  value: z33.string().describe("The value to store. All values are stored as strings; JSON should be stringified."),
-  type: z33.string().min(1).describe(
+  value: z34.string().describe("The value to store. All values are stored as strings; JSON should be stringified."),
+  type: z34.string().min(1).describe(
     'Metafield type. Required for creating new metafields. Common types: "single_line_text_field" (short text), "multi_line_text_field" (long text), "number_integer", "number_decimal", "boolean", "json", "url", "date", "date_time".'
   )
 });
-var inputSchema32 = z33.object({
-  productId: z33.string().min(1).describe(
+var inputSchema32 = z34.object({
+  productId: productIdSchema.describe(
     'Shopify product ID (GID format, e.g., "gid://shopify/Product/123"). Use get-product or list-products to find product IDs.'
   ),
-  metafields: z33.array(metafieldInputSchema).min(1, "At least one metafield is required").max(
+  metafields: z34.array(metafieldInputSchema).min(1, "At least one metafield is required").max(
     MAX_METAFIELDS_PER_CALL,
     `Maximum ${MAX_METAFIELDS_PER_CALL} metafields per call. Split into multiple calls for larger batches.`
   ).describe(
     `Array of metafields to create or update (max ${MAX_METAFIELDS_PER_CALL} per call). Existing metafields with matching namespace+key are updated; new ones are created.`
   )
 });
-var outputSchema32 = z33.object({
-  success: z33.boolean().describe("Whether the operation succeeded"),
-  metafields: z33.array(
-    z33.object({
-      id: z33.string().describe("Metafield GID"),
-      namespace: z33.string().describe("Metafield namespace"),
-      key: z33.string().describe("Metafield key"),
-      value: z33.string().describe("Metafield value"),
-      type: z33.string().describe("Metafield type"),
-      createdAt: z33.string().describe("Creation timestamp (ISO 8601)"),
-      updatedAt: z33.string().describe("Last update timestamp (ISO 8601)")
+var outputSchema32 = z34.object({
+  success: z34.boolean().describe("Whether the operation succeeded"),
+  metafields: z34.array(
+    z34.object({
+      id: z34.string().describe("Metafield GID"),
+      namespace: z34.string().describe("Metafield namespace"),
+      key: z34.string().describe("Metafield key"),
+      value: z34.string().describe("Metafield value"),
+      type: z34.string().describe("Metafield type"),
+      createdAt: z34.string().describe("Creation timestamp (ISO 8601)"),
+      updatedAt: z34.string().describe("Last update timestamp (ISO 8601)")
     })
   ).describe("Created or updated metafields"),
-  count: z33.number().describe("Number of metafields processed")
+  count: z34.number().describe("Number of metafields processed")
 });
 var handleSetProductMetafields = async (context, params) => {
   log.debug(
@@ -7284,6 +7899,14 @@ function registerSetProductMetafieldsTool() {
         relatedTools: ["get-product", "get-product-metafields"],
         prerequisites: ["get-product"],
         followUps: ["get-product-metafields"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        // Same values produce same result
+        openWorldHint: true
       }
     },
     handleSetProductMetafields
@@ -7291,47 +7914,47 @@ function registerSetProductMetafieldsTool() {
 }
 
 // src/tools/update-article.ts
-import { z as z34 } from "zod";
-var inputSchema33 = z34.object({
-  id: z34.string().describe(
+import { z as z35 } from "zod";
+var inputSchema33 = z35.object({
+  id: articleIdSchema.describe(
     'The article ID to update (required). Must be a valid Shopify GID format. Example: "gid://shopify/Article/12345". Use list-articles to find article IDs.'
   ),
-  title: z34.string().optional().describe("The new title for the article. Only provided if changing the title."),
-  authorName: z34.string().optional().describe("The new author name for the article."),
-  body: z34.string().optional().describe("The new HTML body content of the article. Supports HTML markup for formatting."),
-  summary: z34.string().optional().describe("A summary or excerpt of the article."),
-  tags: z34.array(z34.string()).optional().describe(
+  title: z35.string().optional().describe("The new title for the article. Only provided if changing the title."),
+  authorName: z35.string().optional().describe("The new author name for the article."),
+  body: z35.string().optional().describe("The new HTML body content of the article. Supports HTML markup for formatting."),
+  summary: z35.string().optional().describe("A summary or excerpt of the article."),
+  tags: z35.array(z35.string()).optional().describe(
     "New tags for categorization. This replaces all existing tags. Example: ['guide', 'tutorial', 'beginner']."
   ),
-  image: z34.object({
-    url: z34.string().url().describe("The URL of the featured image"),
-    altText: z34.string().optional().describe("Alt text for accessibility")
+  image: z35.object({
+    url: z35.string().url().describe("The URL of the featured image"),
+    altText: z35.string().optional().describe("Alt text for accessibility")
   }).optional().describe("Featured image for the article."),
-  isPublished: z34.boolean().optional().describe(
+  isPublished: z35.boolean().optional().describe(
     "Whether the article should be visible on the storefront. Set to true to publish, false to unpublish."
   ),
-  publishDate: z34.string().optional().describe(
+  publishDate: z35.string().optional().describe(
     "The date and time when the article should become visible (ISO 8601 format). Example: '2024-01-15T10:00:00Z'."
   ),
-  handle: z34.string().optional().describe(
+  handle: z35.string().optional().describe(
     "The new URL handle/slug for the article. Set redirectNewHandle to true to automatically redirect the old URL to the new one."
   ),
-  templateSuffix: z34.string().optional().describe(
+  templateSuffix: z35.string().optional().describe(
     "The suffix of the Liquid template used to render the article. For example, 'featured' would use the template 'article.featured.liquid'."
   ),
-  redirectNewHandle: z34.boolean().optional().describe(
+  redirectNewHandle: z35.boolean().optional().describe(
     "Whether to automatically redirect the old URL to the new handle. Set to true when changing the handle to preserve SEO and existing links."
   )
 });
-var outputSchema33 = z34.object({
-  id: z34.string().describe("Updated article GID"),
-  title: z34.string().describe("Article title"),
-  handle: z34.string().describe("URL handle/slug"),
-  blog: z34.object({
-    id: z34.string().describe("Parent blog GID"),
-    title: z34.string().describe("Parent blog title")
+var outputSchema33 = z35.object({
+  id: z35.string().describe("Updated article GID"),
+  title: z35.string().describe("Article title"),
+  handle: z35.string().describe("URL handle/slug"),
+  blog: z35.object({
+    id: z35.string().describe("Parent blog GID"),
+    title: z35.string().describe("Parent blog title")
   }),
-  isPublished: z34.boolean().describe("Whether article is visible on storefront")
+  isPublished: z35.boolean().describe("Whether article is visible on storefront")
 });
 var handleUpdateArticle = async (context, params) => {
   log.debug(`Updating article on shop: ${context.shopDomain}`);
@@ -7387,6 +8010,13 @@ function registerUpdateArticleTool() {
         relatedTools: ["list-articles", "create-article", "delete-article"],
         prerequisites: ["list-articles"],
         followUps: ["list-articles"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleUpdateArticle
@@ -7394,30 +8024,30 @@ function registerUpdateArticleTool() {
 }
 
 // src/tools/update-blog.ts
-import { z as z35 } from "zod";
-var inputSchema34 = z35.object({
-  id: z35.string().describe(
+import { z as z36 } from "zod";
+var inputSchema34 = z36.object({
+  id: blogIdSchema.describe(
     'The blog ID to update (required). Must be a valid Shopify GID format. Example: "gid://shopify/Blog/12345". Use list-blogs to find blog IDs.'
   ),
-  title: z35.string().optional().describe("The new title for the blog. Only provided if changing the title."),
-  handle: z35.string().optional().describe(
+  title: z36.string().optional().describe("The new title for the blog. Only provided if changing the title."),
+  handle: z36.string().optional().describe(
     "The new URL handle/slug for the blog. Set redirectNewHandle to true to automatically redirect the old URL to the new one."
   ),
-  commentPolicy: z35.enum(["CLOSED", "MODERATE", "OPEN"]).optional().describe(
+  commentPolicy: z36.enum(["CLOSED", "MODERATE", "OPEN"]).optional().describe(
     "Comment moderation policy for the blog. CLOSED: Comments disabled. MODERATE: Comments require approval. OPEN: Comments appear immediately."
   ),
-  templateSuffix: z35.string().optional().describe(
+  templateSuffix: z36.string().optional().describe(
     "The suffix of the Liquid template used to render the blog. For example, 'news' would use the template 'blog.news.liquid'."
   ),
-  redirectNewHandle: z35.boolean().optional().describe(
+  redirectNewHandle: z36.boolean().optional().describe(
     "Whether to automatically redirect the old URL to the new handle. Set to true when changing the handle to preserve SEO and existing links."
   )
 });
-var outputSchema34 = z35.object({
-  id: z35.string().describe("Updated blog GID"),
-  title: z35.string().describe("Blog title"),
-  handle: z35.string().describe("URL handle/slug"),
-  commentPolicy: z35.enum(["CLOSED", "MODERATE", "OPEN"]).describe("Comment moderation policy")
+var outputSchema34 = z36.object({
+  id: z36.string().describe("Updated blog GID"),
+  title: z36.string().describe("Blog title"),
+  handle: z36.string().describe("URL handle/slug"),
+  commentPolicy: z36.enum(["CLOSED", "MODERATE", "OPEN"]).describe("Comment moderation policy")
 });
 var handleUpdateBlog = async (context, params) => {
   log.debug(`Updating blog on shop: ${context.shopDomain}`);
@@ -7467,6 +8097,13 @@ function registerUpdateBlogTool() {
         relatedTools: ["list-blogs", "create-blog", "delete-blog"],
         prerequisites: ["list-blogs"],
         followUps: ["list-blogs"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleUpdateBlog
@@ -7474,21 +8111,21 @@ function registerUpdateBlogTool() {
 }
 
 // src/tools/update-collection.ts
-import { z as z36 } from "zod";
-var inputSchema35 = z36.object({
-  collectionId: z36.string().min(1).describe(
+import { z as z37 } from "zod";
+var inputSchema35 = z37.object({
+  collectionId: collectionIdSchema.describe(
     'Collection ID to update (GID format, e.g., "gid://shopify/Collection/123"). Use list-collections or get-collection to find collection IDs.'
   ),
-  title: z36.string().min(1).optional().describe("New collection title"),
-  handle: z36.string().optional().describe(
+  title: z37.string().min(1).optional().describe("New collection title"),
+  handle: z37.string().optional().describe(
     "New URL handle/slug. When changing, set redirectNewHandle: true to create automatic redirect from the old URL."
   ),
-  descriptionHtml: z36.string().optional().describe("New HTML description"),
-  seo: z36.object({
-    title: z36.string().optional().describe("New SEO title"),
-    description: z36.string().optional().describe("New SEO meta description")
+  descriptionHtml: z37.string().optional().describe("New HTML description"),
+  seo: z37.object({
+    title: z37.string().optional().describe("New SEO title"),
+    description: z37.string().optional().describe("New SEO meta description")
   }).optional().describe("Updated SEO metadata"),
-  sortOrder: z36.enum([
+  sortOrder: z37.enum([
     "ALPHA_ASC",
     "ALPHA_DESC",
     "BEST_SELLING",
@@ -7498,19 +8135,19 @@ var inputSchema35 = z36.object({
     "PRICE_ASC",
     "PRICE_DESC"
   ]).optional().describe("New product sort order within collection"),
-  image: z36.object({
-    src: z36.string().url().describe("New image URL (publicly accessible)"),
-    altText: z36.string().optional().describe("New alt text for accessibility")
+  image: z37.object({
+    src: z37.string().url().describe("New image URL (publicly accessible)"),
+    altText: z37.string().optional().describe("New alt text for accessibility")
   }).optional().describe("New collection image"),
-  templateSuffix: z36.string().optional().describe("New Liquid template suffix"),
-  redirectNewHandle: z36.boolean().optional().describe(
+  templateSuffix: z37.string().optional().describe("New Liquid template suffix"),
+  redirectNewHandle: z37.boolean().optional().describe(
     "When changing the handle, set to true to create an automatic URL redirect from the old handle to the new one. Important for SEO to preserve link equity."
   )
 });
-var outputSchema35 = z36.object({
-  id: z36.string().describe("Updated collection GID"),
-  title: z36.string().describe("Collection title"),
-  handle: z36.string().describe("Collection URL handle")
+var outputSchema35 = z37.object({
+  id: z37.string().describe("Updated collection GID"),
+  title: z37.string().describe("Collection title"),
+  handle: z37.string().describe("Collection URL handle")
 });
 var handleUpdateCollection = async (context, params) => {
   log.debug(`Updating collection on shop: ${context.shopDomain}`);
@@ -7557,6 +8194,14 @@ function registerUpdateCollectionTool() {
         relatedTools: ["get-collection", "list-collections"],
         prerequisites: ["get-collection"],
         followUps: ["add-products-to-collection", "remove-products-from-collection"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        // Same update produces same result
+        openWorldHint: true
       }
     },
     handleUpdateCollection
@@ -7564,8 +8209,8 @@ function registerUpdateCollectionTool() {
 }
 
 // src/tools/update-inventory.ts
-import { z as z37 } from "zod";
-var inventoryReasonEnum = z37.enum([
+import { z as z38 } from "zod";
+var inventoryReasonEnum = z38.enum([
   "correction",
   "cycle_count_available",
   "damaged",
@@ -7584,20 +8229,20 @@ var inventoryReasonEnum = z37.enum([
   "safety_stock",
   "shrinkage"
 ]);
-var inputSchema36 = z37.object({
-  inventoryItemId: z37.string().min(1).describe(
+var inputSchema36 = z38.object({
+  inventoryItemId: inventoryItemIdSchema.describe(
     'The Shopify inventory item ID (e.g., "gid://shopify/InventoryItem/456"). Get this from get-inventory tool or from get-product response.'
   ),
-  locationId: z37.string().min(1).describe(
+  locationId: locationIdSchema.describe(
     'The location ID where inventory should be updated (e.g., "gid://shopify/Location/789"). Get this from get-inventory tool.'
   ),
-  setQuantity: z37.number().int().min(0).optional().describe(
+  setQuantity: z38.number().int().min(0).optional().describe(
     "Set inventory to this exact quantity. Example: 100. Use for absolute stock counts after physical inventory. Cannot be used together with adjustQuantity."
   ),
-  adjustQuantity: z37.number().int().optional().describe(
+  adjustQuantity: z38.number().int().optional().describe(
     "Adjust inventory by this amount. Positive to add, negative to subtract. Example: -5 to reduce by 5, +10 to add 10. Use for incremental changes. Cannot be used together with setQuantity."
   ),
-  name: z37.enum(["available", "on_hand"]).optional().default("available").describe(
+  name: z38.enum(["available", "on_hand"]).optional().default("available").describe(
     'Which quantity to modify. "available" (default) for sellable stock, "on_hand" for physical count.'
   ),
   reason: inventoryReasonEnum.optional().default("correction").describe(
@@ -7608,16 +8253,16 @@ var inputSchema36 = z37.object({
 }).refine((data) => !(data.setQuantity !== void 0 && data.adjustQuantity !== void 0), {
   message: "Cannot provide both setQuantity and adjustQuantity. Choose one."
 });
-var outputSchema36 = z37.object({
-  success: z37.boolean().describe("Whether the operation succeeded"),
-  inventoryItemId: z37.string().describe("Inventory item GID"),
-  locationId: z37.string().describe("Location GID where inventory was updated"),
-  locationName: z37.string().describe("Human-readable location name"),
-  previousQuantity: z37.number().describe("Quantity before the change"),
-  newQuantity: z37.number().describe("Quantity after the change"),
-  delta: z37.number().describe("The actual change applied (positive or negative)"),
-  name: z37.string().describe("Which quantity was modified (available or on_hand)"),
-  reason: z37.string().describe("Reason for the adjustment")
+var outputSchema36 = z38.object({
+  success: z38.boolean().describe("Whether the operation succeeded"),
+  inventoryItemId: z38.string().describe("Inventory item GID"),
+  locationId: z38.string().describe("Location GID where inventory was updated"),
+  locationName: z38.string().describe("Human-readable location name"),
+  previousQuantity: z38.number().describe("Quantity before the change"),
+  newQuantity: z38.number().describe("Quantity after the change"),
+  delta: z38.number().describe("The actual change applied (positive or negative)"),
+  name: z38.string().describe("Which quantity was modified (available or on_hand)"),
+  reason: z38.string().describe("Reason for the adjustment")
 });
 var handleUpdateInventory = async (context, params) => {
   log.debug(`Updating inventory on shop: ${context.shopDomain}`);
@@ -7698,6 +8343,13 @@ function registerUpdateInventoryTool() {
         relatedTools: ["get-inventory", "get-bulk-inventory", "list-low-inventory"],
         prerequisites: ["get-inventory"],
         followUps: ["get-inventory"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleUpdateInventory
@@ -7705,33 +8357,33 @@ function registerUpdateInventoryTool() {
 }
 
 // src/tools/update-page.ts
-import { z as z38 } from "zod";
-var inputSchema37 = z38.object({
-  id: z38.string().min(1).describe(
+import { z as z39 } from "zod";
+var inputSchema37 = z39.object({
+  id: pageIdSchema.describe(
     'The page ID to update (required). Must be a valid Shopify GID format. Example: "gid://shopify/Page/123456789". Use list-pages to find page IDs.'
   ),
-  title: z38.string().optional().describe("The new title for the page. Only provide if you want to change it."),
-  body: z38.string().optional().describe(
+  title: z39.string().optional().describe("The new title for the page. Only provide if you want to change it."),
+  body: z39.string().optional().describe(
     "The new HTML body content for the page. Supports HTML markup. Only provide if you want to change it."
   ),
-  handle: z38.string().optional().describe(
+  handle: z39.string().optional().describe(
     "The new URL handle/slug for the page. Only provide if you want to change the URL. Consider setting redirectNewHandle to true when changing handles."
   ),
-  isPublished: z38.boolean().optional().describe(
+  isPublished: z39.boolean().optional().describe(
     "Whether the page should be visible on the storefront. Set to true to publish, false to unpublish."
   ),
-  templateSuffix: z38.string().optional().describe(
+  templateSuffix: z39.string().optional().describe(
     "The suffix of the Liquid template used to render the page. Set to empty string to use the default template."
   ),
-  redirectNewHandle: z38.boolean().optional().describe(
+  redirectNewHandle: z39.boolean().optional().describe(
     "Whether to create a redirect from the old handle to the new handle when changing handles. Recommended to preserve SEO value when changing page URLs."
   )
 });
-var outputSchema37 = z38.object({
-  id: z38.string().describe("Updated page GID"),
-  title: z38.string().describe("Page title"),
-  handle: z38.string().describe("URL handle/slug"),
-  isPublished: z38.boolean().describe("Whether page is visible on storefront")
+var outputSchema37 = z39.object({
+  id: z39.string().describe("Updated page GID"),
+  title: z39.string().describe("Page title"),
+  handle: z39.string().describe("URL handle/slug"),
+  isPublished: z39.boolean().describe("Whether page is visible on storefront")
 });
 var handleUpdatePage = async (context, params) => {
   log.debug(`Updating page on shop: ${context.shopDomain}`);
@@ -7782,6 +8434,13 @@ function registerUpdatePageTool() {
         relatedTools: ["get-page", "list-pages"],
         prerequisites: ["get-page"],
         followUps: ["get-page"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
     },
     handleUpdatePage
@@ -7789,7 +8448,7 @@ function registerUpdatePageTool() {
 }
 
 // src/tools/update-product-image.ts
-import { z as z39 } from "zod";
+import { z as z40 } from "zod";
 var FILE_UPDATE_MUTATION = `
   mutation FileUpdate($files: [FileUpdateInput!]!) {
     fileUpdate(files: $files) {
@@ -7809,18 +8468,18 @@ var FILE_UPDATE_MUTATION = `
     }
   }
 `;
-var inputSchema38 = z39.object({
-  imageId: z39.string().min(1).describe(
+var inputSchema38 = z40.object({
+  imageId: imageIdSchema.describe(
     'Shopify image GID (e.g., "gid://shopify/MediaImage/123"). Required. Use get-product to find image IDs in the media field.'
   ),
-  altText: z39.string().describe(
+  altText: z40.string().describe(
     "New alt text for the image. Pass an empty string to clear the alt text. Alt text describes the image for screen readers and helps search engines understand image content."
   )
 });
-var outputSchema38 = z39.object({
-  id: z39.string().describe('Image GID (e.g., "gid://shopify/MediaImage/123")'),
-  url: z39.string().nullable().describe("Shopify CDN URL for the image"),
-  altText: z39.string().nullable().describe("Updated alt text for the image")
+var outputSchema38 = z40.object({
+  id: z40.string().describe('Image GID (e.g., "gid://shopify/MediaImage/123")'),
+  url: z40.string().nullable().describe("Shopify CDN URL for the image"),
+  altText: z40.string().nullable().describe("Updated alt text for the image")
 });
 var handleUpdateProductImage = async (context, params) => {
   log.debug(`Updating image alt text on shop: ${context.shopDomain}`);
@@ -7887,6 +8546,14 @@ function registerUpdateProductImageTool() {
         relatedTools: ["reorder-product-images", "add-product-image"],
         prerequisites: ["add-product-image"],
         followUps: ["reorder-product-images"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        // Same alt text update produces same result
+        openWorldHint: true
       }
     },
     handleUpdateProductImage
@@ -7894,19 +8561,19 @@ function registerUpdateProductImageTool() {
 }
 
 // src/tools/update-product-variant.ts
-import { z as z40 } from "zod";
-var inputSchema39 = z40.object({
-  productId: z40.string().min(1).describe(
+import { z as z41 } from "zod";
+var inputSchema39 = z41.object({
+  productId: productIdSchema.describe(
     'Shopify product GID (e.g., "gid://shopify/Product/123"). Required. Use get-product to find the product ID containing the variant.'
   ),
-  id: z40.string().min(1).describe(
+  id: variantIdSchema.describe(
     'Shopify variant GID (e.g., "gid://shopify/ProductVariant/456"). Required. Use get-product to find variant IDs for a product.'
   ),
-  price: z40.string().optional().describe('New variant price as decimal string (e.g., "29.99")'),
-  compareAtPrice: z40.string().nullable().optional().describe(
+  price: z41.string().optional().describe('New variant price as decimal string (e.g., "29.99")'),
+  compareAtPrice: z41.string().nullable().optional().describe(
     'Original price for sale display (e.g., "39.99"). When set higher than price, Shopify shows strikethrough pricing. Set to null to remove the compare at price.'
   ),
-  barcode: z40.string().nullable().optional().describe("Barcode (UPC, EAN, ISBN, etc.). Set to null to remove.")
+  barcode: z41.string().nullable().optional().describe("Barcode (UPC, EAN, ISBN, etc.). Set to null to remove.")
 }).refine(
   (data) => {
     const { productId: _productId, id: _id, ...updateFields } = data;
@@ -7914,14 +8581,14 @@ var inputSchema39 = z40.object({
   },
   { message: "At least one field to update must be provided (price, compareAtPrice, or barcode)" }
 );
-var outputSchema39 = z40.object({
-  id: z40.string().describe('Variant GID (e.g., "gid://shopify/ProductVariant/123")'),
-  title: z40.string().describe('Variant title (e.g., "Red / Medium")'),
-  price: z40.string().describe("Current price as decimal string"),
-  compareAtPrice: z40.string().nullable().describe("Compare at price for sale display"),
-  sku: z40.string().nullable().describe("Stock keeping unit"),
-  barcode: z40.string().nullable().describe("Barcode (UPC, EAN, etc.)"),
-  inventoryQuantity: z40.number().nullable().describe("Available inventory quantity")
+var outputSchema39 = z41.object({
+  id: z41.string().describe('Variant GID (e.g., "gid://shopify/ProductVariant/123")'),
+  title: z41.string().describe('Variant title (e.g., "Red / Medium")'),
+  price: z41.string().describe("Current price as decimal string"),
+  compareAtPrice: z41.string().nullable().describe("Compare at price for sale display"),
+  sku: z41.string().nullable().describe("Stock keeping unit"),
+  barcode: z41.string().nullable().describe("Barcode (UPC, EAN, etc.)"),
+  inventoryQuantity: z41.number().nullable().describe("Available inventory quantity")
 });
 var handleUpdateProductVariant = async (context, params) => {
   log.debug(`Updating product variant on shop: ${context.shopDomain}`);
@@ -7957,6 +8624,14 @@ function registerUpdateProductVariantTool() {
       relationships: {
         relatedTools: ["get-product", "get-inventory"],
         prerequisites: ["get-product"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        // Same update produces same result
+        openWorldHint: true
       }
     },
     handleUpdateProductVariant
@@ -7964,23 +8639,25 @@ function registerUpdateProductVariantTool() {
 }
 
 // src/tools/update-product.ts
-import { z as z41 } from "zod";
-var inputSchema40 = z41.object({
-  id: z41.string().min(1).describe('Shopify product ID (GID format, e.g., "gid://shopify/Product/123"). Required.'),
-  title: z41.string().min(1).optional().describe("New product title"),
-  description: z41.string().optional().describe("New product description (HTML supported)"),
-  vendor: z41.string().optional().describe("New product vendor/brand name"),
-  productType: z41.string().optional().describe("New product type for categorization"),
-  tags: z41.array(z41.string()).optional().describe("New tags (replaces existing tags)"),
-  status: z41.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).optional().describe("New product status: ACTIVE (visible), DRAFT (hidden), ARCHIVED (hidden)"),
-  seo: z41.object({
-    title: z41.string().optional().describe("SEO title for search engine results"),
-    description: z41.string().optional().describe("SEO meta description for search engines")
+import { z as z42 } from "zod";
+var inputSchema40 = z42.object({
+  id: productIdSchema.describe(
+    'Shopify product ID (GID format, e.g., "gid://shopify/Product/123"). Required.'
+  ),
+  title: z42.string().min(1).optional().describe("New product title"),
+  description: z42.string().optional().describe("New product description (HTML supported)"),
+  vendor: z42.string().optional().describe("New product vendor/brand name"),
+  productType: z42.string().optional().describe("New product type for categorization"),
+  tags: z42.array(z42.string()).optional().describe("New tags (replaces existing tags)"),
+  status: z42.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).optional().describe("New product status: ACTIVE (visible), DRAFT (hidden), ARCHIVED (hidden)"),
+  seo: z42.object({
+    title: z42.string().optional().describe("SEO title for search engine results"),
+    description: z42.string().optional().describe("SEO meta description for search engines")
   }).optional().describe("SEO metadata for search engine optimization"),
-  handle: z41.string().optional().describe(
+  handle: z42.string().optional().describe(
     'New URL handle/slug (e.g., "my-product"). Use with redirectNewHandle for URL changes.'
   ),
-  redirectNewHandle: z41.boolean().optional().describe(
+  redirectNewHandle: z42.boolean().optional().describe(
     "If true, creates automatic redirect from old handle to new handle. Use when changing handle."
   )
 }).refine(
@@ -7990,40 +8667,40 @@ var inputSchema40 = z41.object({
   },
   { message: "At least one field to update must be provided" }
 );
-var outputSchema40 = z41.object({
-  id: z41.string().describe('Product GID (e.g., "gid://shopify/Product/123")'),
-  title: z41.string().describe("Product title"),
-  handle: z41.string().describe("URL handle/slug"),
-  description: z41.string().nullable().describe("Product description (HTML)"),
-  vendor: z41.string().describe("Vendor/brand name"),
-  productType: z41.string().describe("Product type"),
-  status: z41.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).describe("Product status"),
-  tags: z41.array(z41.string()).describe("Product tags"),
-  seo: z41.object({
-    title: z41.string().nullable().describe("SEO title for search engines"),
-    description: z41.string().nullable().describe("SEO description/meta description")
+var outputSchema40 = z42.object({
+  id: z42.string().describe('Product GID (e.g., "gid://shopify/Product/123")'),
+  title: z42.string().describe("Product title"),
+  handle: z42.string().describe("URL handle/slug"),
+  description: z42.string().nullable().describe("Product description (HTML)"),
+  vendor: z42.string().describe("Vendor/brand name"),
+  productType: z42.string().describe("Product type"),
+  status: z42.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).describe("Product status"),
+  tags: z42.array(z42.string()).describe("Product tags"),
+  seo: z42.object({
+    title: z42.string().nullable().describe("SEO title for search engines"),
+    description: z42.string().nullable().describe("SEO description/meta description")
   }).describe("SEO metadata for search engine optimization"),
-  createdAt: z41.string().describe("Creation timestamp (ISO 8601)"),
-  updatedAt: z41.string().describe("Last update timestamp (ISO 8601)"),
-  variants: z41.array(
-    z41.object({
-      id: z41.string().describe("Variant GID"),
-      title: z41.string().describe("Variant title"),
-      price: z41.string().describe("Price"),
-      compareAtPrice: z41.string().nullable().describe("Compare at price"),
-      sku: z41.string().nullable().describe("SKU"),
-      barcode: z41.string().nullable().describe("Barcode"),
-      inventoryQuantity: z41.number().nullable().describe("Inventory quantity")
+  createdAt: z42.string().describe("Creation timestamp (ISO 8601)"),
+  updatedAt: z42.string().describe("Last update timestamp (ISO 8601)"),
+  variants: z42.array(
+    z42.object({
+      id: z42.string().describe("Variant GID"),
+      title: z42.string().describe("Variant title"),
+      price: z42.string().describe("Price"),
+      compareAtPrice: z42.string().nullable().describe("Compare at price"),
+      sku: z42.string().nullable().describe("SKU"),
+      barcode: z42.string().nullable().describe("Barcode"),
+      inventoryQuantity: z42.number().nullable().describe("Inventory quantity")
     })
   ).describe("Product variants"),
-  images: z41.array(
-    z41.object({
-      id: z41.string().describe("Image GID"),
-      url: z41.string().describe("Image URL"),
-      altText: z41.string().nullable().describe("Alt text")
+  images: z42.array(
+    z42.object({
+      id: z42.string().describe("Image GID"),
+      url: z42.string().describe("Image URL"),
+      altText: z42.string().nullable().describe("Alt text")
     })
   ).describe("Product images"),
-  totalInventory: z41.number().describe("Total inventory across variants")
+  totalInventory: z42.number().describe("Total inventory across variants")
 });
 var handleUpdateProduct = async (context, params) => {
   log.debug(`Updating product on shop: ${context.shopDomain}`);
@@ -8060,6 +8737,14 @@ function registerUpdateProductTool() {
         relatedTools: ["list-products", "get-product"],
         prerequisites: ["get-product"],
         followUps: ["add-product-image", "set-product-metafields"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        // Same update produces same result
+        openWorldHint: true
       }
     },
     handleUpdateProduct
@@ -8075,7 +8760,9 @@ function setupToolHandlers(server) {
       tools: tools.map((tool) => ({
         name: tool.name,
         description: tool.description,
-        inputSchema: tool.inputSchema
+        inputSchema: tool.inputSchema,
+        // Include MCP tool annotations (Epic 9.5 - MCP Best Practices)
+        annotations: tool.annotations
       }))
     };
   });