@anton.andrusenko/shopify-mcp-admin 0.2.0 → 0.4.0

package/dist/index.js

@@ -22,7 +22,10 @@ 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;
@@ -936,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;
@@ -963,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;
 }
@@ -978,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;
@@ -2334,6 +2377,21 @@ function createSingleTenantContext(client, shopDomain) {
 
 // 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 {
+    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
+  };
+}
 var registeredTools = /* @__PURE__ */ new Map();
 function validateToolName(name) {
   if (!name || name.trim() === "") {
@@ -2393,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: inputSchema46, annotations } = definition;
   try {
     if (!options.skipNameValidation) {
       validateToolName(name);
@@ -2401,15 +2459,22 @@ function registerTool(definition, handler, options = {}) {
     if (registeredTools.has(name)) {
       throw new Error(`Tool "${name}" is already registered. Tool names must be unique.`);
     }
-    const jsonSchema = convertZodToJsonSchema(inputSchema41);
-    const wrappedHandler = wrapToolHandler(name, inputSchema41, handler);
+    const jsonSchema = convertZodToJsonSchema(inputSchema46);
+    const wrappedHandler = wrapToolHandler(name, inputSchema46, 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
+      zodSchema: inputSchema46,
+      handler: wrappedHandler,
+      annotations: finalAnnotations
     };
     registeredTools.set(name, registeredTool);
     log.debug(`Registered tool: ${name}`);
@@ -2428,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) {
@@ -2448,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 = `
@@ -3088,22 +3154,42 @@ 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");
+var marketIdSchema = gidSchema("Market");
+
 // 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}`);
@@ -3161,6 +3247,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
@@ -3168,7 +3262,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 = `
@@ -3569,18 +3663,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(
@@ -3624,6 +3718,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
@@ -3631,7 +3733,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 = `
@@ -4137,51 +4239,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}`);
@@ -4237,6 +4339,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
@@ -4244,26 +4354,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}`);
@@ -4305,6 +4415,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
@@ -4312,20 +4430,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",
@@ -4337,18 +4455,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}`);
@@ -4387,14 +4505,352 @@ 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
   );
 }
 
+// src/tools/create-market.ts
+import { z as z8 } from "zod";
+
+// src/shopify/markets.ts
+var LIST_MARKETS_QUERY = `
+query Markets($first: Int!, $after: String) {
+  markets(first: $first, after: $after) {
+    nodes {
+      id
+      name
+      handle
+      enabled
+      status
+      type
+      currencySettings {
+        baseCurrency { currencyCode }
+        localCurrencies
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+}
+`;
+var GET_MARKET_QUERY = `
+query Market($id: ID!) {
+  market(id: $id) {
+    id
+    name
+    handle
+    enabled
+    status
+    type
+    currencySettings {
+      baseCurrency { currencyCode currencyName }
+      localCurrencies
+    }
+    webPresences(first: 10) {
+      nodes {
+        id
+        defaultLocale { locale name }
+        alternateLocales { locale name }
+        subfolderSuffix
+        domain { host }
+        rootUrls { locale url }
+      }
+    }
+  }
+}
+`;
+var MARKET_CREATE_MUTATION = `
+mutation MarketCreate($input: MarketCreateInput!) {
+  marketCreate(input: $input) {
+    market { id name handle enabled }
+    userErrors { field message }
+  }
+}
+`;
+var MARKET_UPDATE_MUTATION = `
+mutation MarketUpdate($id: ID!, $input: MarketUpdateInput!) {
+  marketUpdate(id: $id, input: $input) {
+    market { id name handle enabled }
+    userErrors { field message }
+  }
+}
+`;
+var MARKET_DELETE_MUTATION = `
+mutation MarketDelete($id: ID!) {
+  marketDelete(id: $id) {
+    deletedId
+    userErrors { field message }
+  }
+}
+`;
+async function listMarkets(first = 50, after) {
+  const client = await getShopifyClient();
+  log.debug(`Listing markets: first=${first}, after=${after}`);
+  const response = await withRateLimit(
+    () => client.graphql.request(LIST_MARKETS_QUERY, {
+      variables: { first, after }
+    }),
+    "list-markets"
+  );
+  if (response.errors && response.errors.length > 0) {
+    const errorMessage = response.errors.map((e) => e.message).join(", ");
+    throw new Error(`GraphQL error: ${errorMessage}`);
+  }
+  const marketsData = response.data?.markets;
+  if (!marketsData) {
+    throw new Error("No response data from markets query");
+  }
+  const markets = marketsData.nodes.map((node) => ({
+    id: node.id,
+    name: node.name,
+    handle: node.handle,
+    enabled: node.enabled,
+    status: node.status,
+    type: node.type,
+    currencySettings: node.currencySettings ? {
+      baseCurrency: {
+        currencyCode: node.currencySettings.baseCurrency.currencyCode
+      },
+      localCurrencies: node.currencySettings.localCurrencies
+    } : void 0
+  }));
+  log.debug(`Listed ${markets.length} markets`);
+  return {
+    markets,
+    pageInfo: {
+      hasNextPage: marketsData.pageInfo.hasNextPage,
+      endCursor: marketsData.pageInfo.endCursor
+    }
+  };
+}
+async function getMarket(marketId) {
+  const client = await getShopifyClient();
+  log.debug(`Fetching market: ${marketId}`);
+  const response = await withRateLimit(
+    () => client.graphql.request(GET_MARKET_QUERY, {
+      variables: { id: marketId }
+    }),
+    "get-market"
+  );
+  if (response.errors && response.errors.length > 0) {
+    const errorMessage = response.errors.map((e) => e.message).join(", ");
+    throw new Error(`GraphQL error: ${errorMessage}`);
+  }
+  const market = response.data?.market;
+  if (!market) {
+    log.debug(`Market not found: ${marketId}`);
+    return null;
+  }
+  return {
+    id: market.id,
+    name: market.name,
+    handle: market.handle,
+    enabled: market.enabled,
+    status: market.status,
+    type: market.type,
+    currencySettings: market.currencySettings ? {
+      baseCurrency: {
+        currencyCode: market.currencySettings.baseCurrency.currencyCode,
+        currencyName: market.currencySettings.baseCurrency.currencyName
+      },
+      localCurrencies: market.currencySettings.localCurrencies
+    } : void 0,
+    webPresences: market.webPresences?.nodes.map((wp) => ({
+      id: wp.id,
+      defaultLocale: {
+        locale: wp.defaultLocale.locale,
+        name: wp.defaultLocale.name
+      },
+      alternateLocales: wp.alternateLocales?.map((al) => ({
+        locale: al.locale,
+        name: al.name
+      })),
+      subfolderSuffix: wp.subfolderSuffix ?? void 0,
+      domain: wp.domain ? { host: wp.domain.host } : void 0,
+      rootUrls: wp.rootUrls?.map((ru) => ({
+        locale: ru.locale,
+        url: ru.url
+      }))
+    }))
+  };
+}
+async function createMarket(input) {
+  const client = await getShopifyClient();
+  log.debug(`Creating market: ${input.name}`);
+  const graphqlInput = {
+    name: input.name
+  };
+  if (input.handle !== void 0) {
+    graphqlInput.handle = input.handle;
+  }
+  if (input.regions !== void 0) {
+    graphqlInput.regions = input.regions;
+  }
+  if (input.enabled !== void 0) {
+    graphqlInput.enabled = input.enabled;
+  }
+  const response = await withRateLimit(
+    () => client.graphql.request(MARKET_CREATE_MUTATION, {
+      variables: { input: graphqlInput }
+    }),
+    "create-market"
+  );
+  if (response.errors && response.errors.length > 0) {
+    const errorMessage = response.errors.map((e) => e.message).join(", ");
+    throw new Error(`GraphQL error: ${errorMessage}`);
+  }
+  const result = response.data?.marketCreate;
+  if (!result) {
+    throw new Error("No response data from marketCreate mutation");
+  }
+  if (result.userErrors && result.userErrors.length > 0) {
+    throw new ShopifyUserErrorException(result.userErrors);
+  }
+  if (!result.market) {
+    throw new Error("Market creation succeeded but no market was returned");
+  }
+  log.debug(`Created market: ${result.market.id}`);
+  return result.market;
+}
+async function updateMarket(marketId, input) {
+  const client = await getShopifyClient();
+  log.debug(`Updating market: ${marketId}`);
+  const graphqlInput = {};
+  if (input.name !== void 0) {
+    graphqlInput.name = input.name;
+  }
+  if (input.handle !== void 0) {
+    graphqlInput.handle = input.handle;
+  }
+  if (input.enabled !== void 0) {
+    graphqlInput.enabled = input.enabled;
+  }
+  const response = await withRateLimit(
+    () => client.graphql.request(MARKET_UPDATE_MUTATION, {
+      variables: { id: marketId, input: graphqlInput }
+    }),
+    "update-market"
+  );
+  if (response.errors && response.errors.length > 0) {
+    const errorMessage = response.errors.map((e) => e.message).join(", ");
+    throw new Error(`GraphQL error: ${errorMessage}`);
+  }
+  const result = response.data?.marketUpdate;
+  if (!result) {
+    throw new Error("No response data from marketUpdate mutation");
+  }
+  if (result.userErrors && result.userErrors.length > 0) {
+    throw new ShopifyUserErrorException(result.userErrors);
+  }
+  if (!result.market) {
+    throw new Error("Market update succeeded but no market was returned");
+  }
+  log.debug(`Updated market: ${result.market.id}`);
+  return result.market;
+}
+async function deleteMarket(marketId) {
+  const client = await getShopifyClient();
+  log.debug(`Deleting market: ${marketId}`);
+  const response = await withRateLimit(
+    () => client.graphql.request(MARKET_DELETE_MUTATION, {
+      variables: { id: marketId }
+    }),
+    "delete-market"
+  );
+  if (response.errors && response.errors.length > 0) {
+    const errorMessage = response.errors.map((e) => e.message).join(", ");
+    throw new Error(`GraphQL error: ${errorMessage}`);
+  }
+  const result = response.data?.marketDelete;
+  if (!result) {
+    throw new Error("No response data from marketDelete mutation");
+  }
+  if (result.userErrors && result.userErrors.length > 0) {
+    throw new ShopifyUserErrorException(result.userErrors);
+  }
+  if (!result.deletedId) {
+    throw new Error("Market deletion succeeded but no deletedId was returned");
+  }
+  log.debug(`Deleted market: ${result.deletedId}`);
+  return result.deletedId;
+}
+
+// src/tools/create-market.ts
+var inputSchema6 = z8.object({
+  name: z8.string().min(1).describe('Market name (required). Not shown to customers. Example: "Canada", "Europe"'),
+  handle: z8.string().optional().describe(
+    'URL handle/slug for the market. Auto-generated from name if not provided. Example: "ca" for Canada, "eu" for Europe'
+  ),
+  countryCodes: z8.array(z8.string().length(2)).optional().describe(
+    'Array of ISO 3166-1 alpha-2 country codes to include in this market. Example: ["CA"] for Canada, ["FR", "DE", "IT"] for multiple European countries'
+  ),
+  enabled: z8.boolean().optional().default(true).describe("Whether the market should be enabled. Default: true")
+});
+var outputSchema6 = z8.object({
+  id: z8.string().describe("Created market GID"),
+  name: z8.string().describe("Market name"),
+  handle: z8.string().describe("URL handle"),
+  enabled: z8.boolean().describe("Whether the market is enabled")
+});
+var handleCreateMarket = async (context, params) => {
+  log.debug(`Creating market "${params.name}" on shop: ${context.shopDomain}`);
+  const input = {
+    name: params.name
+  };
+  if (params.handle !== void 0) {
+    input.handle = params.handle;
+  }
+  if (params.countryCodes !== void 0 && params.countryCodes.length > 0) {
+    input.regions = { countryCodes: params.countryCodes };
+  }
+  if (params.enabled !== void 0) {
+    input.enabled = params.enabled;
+  }
+  const market = await createMarket(input);
+  log.debug(`Created market: ${market.id}`);
+  return market;
+};
+function registerCreateMarketTool() {
+  registerContextAwareTool(
+    {
+      name: "create-market",
+      title: "Create Market",
+      description: "Create a new market for regional targeting. Markets group one or more regions (countries) for localized shopping experiences. Provide a name (required) and optionally: handle, country codes, and enabled status. **Typical workflow:** create-market \u2192 create-web-presence (configure SEO URLs) \u2192 enable-shop-locale (add languages). **Prerequisites:** None. Store must have Markets feature enabled on their plan. **Follow-ups:** get-market, create-web-presence, update-market.",
+      inputSchema: inputSchema6,
+      outputSchema: outputSchema6,
+      // AI Agent Optimization
+      category: "market",
+      relationships: {
+        relatedTools: ["list-markets", "get-market"],
+        followUps: ["get-market", "update-market"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        // Creating markets is not idempotent
+        openWorldHint: true
+      }
+    },
+    handleCreateMarket
+  );
+}
+
 // src/tools/create-page.ts
-import { z as z7 } from "zod";
+import { z as z9 } from "zod";
 
 // src/shopify/pages.ts
 var PAGE_QUERY = `
@@ -4676,28 +5132,28 @@ async function deletePage(pageId) {
 }
 
 // src/tools/create-page.ts
-var inputSchema6 = z7.object({
-  title: z7.string().min(1).describe(
+var inputSchema7 = z9.object({
+  title: z9.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: z9.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: z9.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: z9.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: z9.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 outputSchema7 = z9.object({
+  id: z9.string().describe('Created page GID (e.g., "gid://shopify/Page/123")'),
+  title: z9.string().describe("Page title"),
+  handle: z9.string().describe("URL handle/slug"),
+  isPublished: z9.boolean().describe("Whether page is visible on storefront")
 });
 var handleCreatePage = async (context, params) => {
   log.debug(`Creating page on shop: ${context.shopDomain}`);
@@ -4734,12 +5190,20 @@ function registerCreatePageTool() {
       name: "create-page",
       title: "Create Page",
       description: "Create a new online store page. Pages are static content like 'About Us', 'Contact', 'FAQ', or policy pages. Provide a title (required) and optional body content (HTML supported), handle (URL slug), and publish status. New pages are unpublished by default. Useful for: creating informational pages, legal pages, landing pages. **Typical workflow:** create-page \u2192 update-page (to publish). **Prerequisites:** None. **Follow-ups:** get-page, update-page. Returns created page ID, title, handle, and publish status.",
-      inputSchema: inputSchema6,
-      outputSchema: outputSchema6,
+      inputSchema: inputSchema7,
+      outputSchema: outputSchema7,
       category: "content",
       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
@@ -4747,78 +5211,78 @@ function registerCreatePageTool() {
 }
 
 // src/tools/create-product.ts
-import { z as z8 } from "zod";
-var inputSchema7 = z8.object({
+import { z as z10 } from "zod";
+var inputSchema8 = z10.object({
   // Required field
-  title: z8.string().min(1, "title is required").describe('Product title (required). Example: "Premium Cotton T-Shirt"'),
+  title: z10.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: z10.string().optional().describe('Product description (HTML supported). Example: "<p>Soft cotton t-shirt.</p>"'),
+  vendor: z10.string().optional().describe('Product vendor/brand name. Example: "Acme Corp"'),
+  productType: z10.string().optional().describe('Product type for categorization. Example: "T-Shirts"'),
+  tags: z10.array(z10.string()).optional().describe('Tags for search and filtering. Example: ["summer", "cotton", "casual"]'),
+  status: z10.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: z10.object({
+    title: z10.string().optional().describe("SEO title for search engine results"),
+    description: z10.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: z10.array(
+    z10.object({
+      price: z10.string().describe('Variant price as decimal string. Example: "29.99"'),
+      compareAtPrice: z10.string().optional().describe('Original price for sale display. Example: "39.99"'),
+      sku: z10.string().optional().describe('Stock keeping unit. Example: "SHIRT-001-RED-M"'),
+      barcode: z10.string().optional().describe("Barcode (UPC, EAN, etc.)"),
+      inventoryQuantity: z10.number().int().min(0).optional().describe("Initial inventory quantity (note: may require separate inventory API)"),
+      options: z10.array(z10.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: z10.array(
+    z10.object({
+      url: z10.string().url("Invalid image URL format").describe("Publicly accessible image URL"),
+      altText: z10.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 outputSchema8 = z10.object({
+  id: z10.string().describe('Product GID (e.g., "gid://shopify/Product/123")'),
+  title: z10.string().describe("Product title"),
+  handle: z10.string().describe("URL handle/slug"),
+  description: z10.string().nullable().describe("Product description (HTML)"),
+  vendor: z10.string().describe("Vendor/brand name"),
+  productType: z10.string().describe("Product type"),
+  status: z10.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).describe("Product status"),
+  tags: z10.array(z10.string()).describe("Product tags"),
+  seo: z10.object({
+    title: z10.string().nullable().describe("SEO title for search engines"),
+    description: z10.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: z10.string().describe("Creation timestamp (ISO 8601)"),
+  updatedAt: z10.string().describe("Last update timestamp (ISO 8601)"),
+  variants: z10.array(
+    z10.object({
+      id: z10.string().describe("Variant GID"),
+      title: z10.string().describe("Variant title"),
+      price: z10.string().describe("Price"),
+      compareAtPrice: z10.string().nullable().describe("Compare at price"),
+      sku: z10.string().nullable().describe("SKU"),
+      barcode: z10.string().nullable().describe("Barcode"),
+      inventoryQuantity: z10.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: z10.array(
+    z10.object({
+      id: z10.string().describe("Image GID"),
+      url: z10.string().describe("Image URL"),
+      altText: z10.string().nullable().describe("Alt text")
     })
   ).describe("Product images"),
-  totalInventory: z8.number().describe("Total inventory across variants")
+  totalInventory: z10.number().describe("Total inventory across variants")
 });
 var handleCreateProduct = async (context, params) => {
   log.debug(`Creating product on shop: ${context.shopDomain}`);
@@ -4853,14 +5317,22 @@ function registerCreateProductTool() {
       name: "create-product",
       title: "Create Product",
       description: "Create a new product in the Shopify store. Supports setting title, description, vendor, type, tags, status, and SEO metadata. Optionally include variants with pricing/SKU and images with URLs. SEO (seo.title, seo.description) is optional - defaults to product title/description if not set. Returns the created product with ID, handle, SEO, variants, and images. Status defaults to DRAFT if not specified. **Typical workflow:** create-product \u2192 add-product-image \u2192 set-product-metafields \u2192 add-products-to-collection. **Prerequisites:** None. **Follow-ups:** add-product-image, set-product-metafields, add-products-to-collection.",
-      inputSchema: inputSchema7,
-      outputSchema: outputSchema7,
+      inputSchema: inputSchema8,
+      outputSchema: outputSchema8,
       // AI Agent Optimization (Story 5.5)
       category: "product",
       relationships: {
         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
@@ -4868,7 +5340,7 @@ function registerCreateProductTool() {
 }
 
 // src/tools/create-redirect.ts
-import { z as z9 } from "zod";
+import { z as z11 } from "zod";
 
 // src/shopify/redirects.ts
 var URL_REDIRECT_CREATE_MUTATION = `
@@ -5016,20 +5488,20 @@ async function deleteRedirect(redirectId) {
 }
 
 // src/tools/create-redirect.ts
-var inputSchema8 = z9.object({
-  path: z9.string().min(1).refine((val) => val.startsWith("/"), {
+var inputSchema9 = z11.object({
+  path: z11.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: z11.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 outputSchema9 = z11.object({
+  id: z11.string().describe('Created redirect GID (e.g., "gid://shopify/UrlRedirect/123")'),
+  path: z11.string().describe("Source path that will redirect"),
+  target: z11.string().describe("Target URL visitors will be redirected to")
 });
 var handleCreateRedirect = async (context, params) => {
   log.debug(`Creating redirect on shop: ${context.shopDomain}`);
@@ -5063,13 +5535,21 @@ function registerCreateRedirectTool() {
       name: "create-redirect",
       title: "Create URL Redirect",
       description: "Create a URL redirect to preserve SEO value when URLs change. Redirects automatically forward visitors and search engines from an old path to a new target URL. Path must start with '/'. Useful for: product URL changes, collection restructuring, page migrations, fixing broken links. **Prerequisites:** None. **Follow-ups:** list-redirects to verify creation.",
-      inputSchema: inputSchema8,
-      outputSchema: outputSchema8,
+      inputSchema: inputSchema9,
+      outputSchema: outputSchema9,
       // AI Agent Optimization (Story 5.5)
       category: "seo",
       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
@@ -5077,15 +5557,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 z12 } from "zod";
+var inputSchema10 = z12.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 outputSchema10 = z12.object({
+  success: z12.boolean().describe("Whether the deletion was successful"),
+  deletedArticleId: z12.string().describe("The ID of the deleted article")
 });
 var handleDeleteArticle = async (context, params) => {
   log.debug(`Deleting article on shop: ${context.shopDomain}`);
@@ -5119,13 +5599,21 @@ function registerDeleteArticleTool() {
       name: "delete-article",
       title: "Delete Article",
       description: "Permanently delete an article by ID. This action cannot be undone. The article will no longer be accessible on the storefront. Use list-articles to find the article ID first. Consider unpublishing instead of deleting if you may need the content later. **Typical workflow:** list-articles \u2192 delete-article. **Prerequisites:** Article ID. **Follow-ups:** None. Returns success confirmation and deleted article ID.",
-      inputSchema: inputSchema9,
-      outputSchema: outputSchema9,
+      inputSchema: inputSchema10,
+      outputSchema: outputSchema10,
       category: "content",
       relationships: {
         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
@@ -5133,15 +5621,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 z13 } from "zod";
+var inputSchema11 = z13.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 outputSchema11 = z13.object({
+  success: z13.boolean().describe("Whether the deletion was successful"),
+  deletedBlogId: z13.string().describe("The ID of the deleted blog")
 });
 var handleDeleteBlog = async (context, params) => {
   log.debug(`Deleting blog on shop: ${context.shopDomain}`);
@@ -5175,12 +5663,20 @@ function registerDeleteBlogTool() {
       name: "delete-blog",
       title: "Delete Blog",
       description: "Permanently delete a blog by ID. This will also delete ALL articles within the blog. This action cannot be undone. Use list-blogs to find the blog ID first. Consider archiving articles before deletion if content may be needed later. **Typical workflow:** list-blogs \u2192 list-articles \u2192 delete-blog. **Prerequisites:** Blog ID. **Follow-ups:** None. Returns success confirmation and deleted blog ID.",
-      inputSchema: inputSchema10,
-      outputSchema: outputSchema10,
+      inputSchema: inputSchema11,
+      outputSchema: outputSchema11,
       category: "content",
       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
@@ -5188,14 +5684,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 z14 } from "zod";
+var inputSchema12 = z14.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 outputSchema12 = z14.object({
+  deletedCollectionId: z14.string().describe("The GID of the deleted collection")
 });
 var handleDeleteCollection = async (context, params) => {
   log.debug(`Deleting collection on shop: ${context.shopDomain}`);
@@ -5225,29 +5721,88 @@ function registerDeleteCollectionTool() {
       name: "delete-collection",
       title: "Delete Collection",
       description: "Permanently delete a collection from the store. This removes the collection but does NOT delete the products within it - they remain in the catalog. **Warning:** This action cannot be undone. **Prerequisites:** get-collection to verify the correct collection before deleting.",
-      inputSchema: inputSchema11,
-      outputSchema: outputSchema11,
+      inputSchema: inputSchema12,
+      outputSchema: outputSchema12,
       // AI Agent Optimization (Story 5.5)
       category: "collection",
       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
   );
 }
 
+// src/tools/delete-market.ts
+import { z as z15 } from "zod";
+var inputSchema13 = z15.object({
+  id: marketIdSchema.describe(
+    'Shopify Market GID to delete (e.g., "gid://shopify/Market/123"). Use list-markets or get-market to find market IDs. WARNING: This action cannot be undone.'
+  )
+});
+var outputSchema13 = z15.object({
+  deletedId: z15.string().describe("Deleted market GID"),
+  success: z15.boolean().describe("Whether the deletion was successful"),
+  message: z15.string().describe("Confirmation message")
+});
+var handleDeleteMarket = async (context, params) => {
+  log.debug(`Deleting market ${params.id} on shop: ${context.shopDomain}`);
+  const deletedId = await deleteMarket(params.id);
+  log.debug(`Deleted market: ${deletedId}`);
+  return {
+    deletedId,
+    success: true,
+    message: `Market ${deletedId} has been permanently deleted. All associated web presences, currency settings, and region configurations have been removed.`
+  };
+};
+function registerDeleteMarketTool() {
+  registerContextAwareTool(
+    {
+      name: "delete-market",
+      title: "Delete Market",
+      description: "Permanently delete a market from the store. **WARNING:** This action cannot be undone. Deleting a market removes all its configurations including web presences, currency settings, and region assignments. Products assigned to this market will no longer be available in those regions. **Prerequisites:** get-market to verify the correct market before deleting. **Note:** The primary market cannot be deleted.",
+      inputSchema: inputSchema13,
+      outputSchema: outputSchema13,
+      // AI Agent Optimization
+      category: "market",
+      relationships: {
+        relatedTools: ["get-market", "list-markets"],
+        followUps: ["list-markets"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        // This is a destructive operation
+        idempotentHint: false,
+        // Deleting twice will fail the second time
+        openWorldHint: true
+      }
+    },
+    handleDeleteMarket
+  );
+}
+
 // src/tools/delete-page.ts
-import { z as z13 } from "zod";
-var inputSchema12 = z13.object({
-  id: z13.string().min(1).describe(
+import { z as z16 } from "zod";
+var inputSchema14 = z16.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 outputSchema14 = z16.object({
+  success: z16.boolean().describe("Whether the deletion was successful"),
+  deletedPageId: z16.string().describe("The ID of the deleted page")
 });
 var handleDeletePage = async (context, params) => {
   log.debug(`Deleting page on shop: ${context.shopDomain}`);
@@ -5281,13 +5836,21 @@ function registerDeletePageTool() {
       name: "delete-page",
       title: "Delete Page",
       description: "Permanently delete a page by ID. This action cannot be undone. The page will no longer be accessible on the storefront. Use list-pages to find the page ID first. Consider unpublishing instead of deleting if you may need the content later. **Typical workflow:** get-page \u2192 delete-page. **Prerequisites:** Page ID. **Follow-ups:** None. Returns success confirmation and deleted page ID.",
-      inputSchema: inputSchema12,
-      outputSchema: outputSchema12,
+      inputSchema: inputSchema14,
+      outputSchema: outputSchema14,
       category: "content",
       relationships: {
         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
@@ -5295,7 +5858,7 @@ function registerDeletePageTool() {
 }
 
 // src/tools/delete-product-image.ts
-import { z as z14 } from "zod";
+import { z as z17 } from "zod";
 var FILE_DELETE_MUTATION = `
   mutation FileDelete($fileIds: [ID!]!) {
     fileDelete(fileIds: $fileIds) {
@@ -5307,14 +5870,14 @@ var FILE_DELETE_MUTATION = `
     }
   }
 `;
-var inputSchema13 = z14.object({
-  imageId: z14.string().min(1).describe(
+var inputSchema15 = z17.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 outputSchema15 = z17.object({
+  success: z17.boolean().describe("Whether the deletion was successful"),
+  deletedImageId: z17.string().describe("ID of the deleted image")
 });
 var handleDeleteProductImage = async (context, params) => {
   log.debug(`Deleting image on shop: ${context.shopDomain}`);
@@ -5365,13 +5928,22 @@ function registerDeleteProductImageTool() {
       name: "delete-product-image",
       title: "Delete Product Image",
       description: "Remove an image from a product. This permanently deletes the image from Shopify's CDN. **Warning:** Cannot be undone - the image will need to be re-uploaded using add-product-image if needed again. **Prerequisites:** get-product to find image IDs in the images array.",
-      inputSchema: inputSchema13,
-      outputSchema: outputSchema13,
+      inputSchema: inputSchema15,
+      outputSchema: outputSchema15,
       // AI Agent Optimization (Story 5.5)
       category: "media",
       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
@@ -5379,7 +5951,7 @@ function registerDeleteProductImageTool() {
 }
 
 // src/tools/delete-product-metafields.ts
-import { z as z15 } from "zod";
+import { z as z18 } from "zod";
 
 // src/shopify/metafields.ts
 var GET_PRODUCT_METAFIELDS_QUERY = `
@@ -5558,28 +6130,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 = z18.object({
+  namespace: z18.string().min(1).describe('Metafield namespace (e.g., "custom", "seo"). Must match existing metafield.'),
+  key: z18.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 inputSchema16 = z18.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: z18.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 outputSchema16 = z18.object({
+  success: z18.boolean().describe("Whether the operation succeeded"),
+  deletedMetafields: z18.array(
+    z18.object({
+      ownerId: z18.string().describe("Product GID that owned the metafield"),
+      namespace: z18.string().describe("Namespace of deleted metafield"),
+      key: z18.string().describe("Key of deleted metafield")
     })
   ).describe("Identifiers of successfully deleted metafields"),
-  deletedCount: z15.number().describe("Number of metafields deleted")
+  deletedCount: z18.number().describe("Number of metafields deleted")
 });
 var handleDeleteProductMetafields = async (context, params) => {
   log.debug(
@@ -5609,13 +6181,22 @@ function registerDeleteProductMetafieldsTool() {
       name: "delete-product-metafields",
       title: "Delete Product Metafields",
       description: "Remove metafields from a product. Identify metafields to delete by their namespace and key combination. Non-existent metafields are silently ignored (no error). **Warning:** This operation is irreversible - deleted metafield data cannot be recovered. **Prerequisites:** get-product-metafields to verify which metafields exist before deletion.",
-      inputSchema: inputSchema14,
-      outputSchema: outputSchema14,
+      inputSchema: inputSchema16,
+      outputSchema: outputSchema16,
       // AI Agent Optimization (Story 5.5)
       category: "seo",
       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
@@ -5623,13 +6204,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 z19 } from "zod";
+var inputSchema17 = z19.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 outputSchema17 = z19.object({
+  deletedProductId: z19.string().describe("The ID of the deleted product"),
+  title: z19.string().describe("The title of the deleted product (for confirmation)")
 });
 var handleDeleteProduct = async (context, params) => {
   log.debug(`Deleting product on shop: ${context.shopDomain}`);
@@ -5671,13 +6254,22 @@ function registerDeleteProductTool() {
       name: "delete-product",
       title: "Delete Product",
       description: "Delete a product from the Shopify store permanently. Requires the product ID (GID format). Returns confirmation with the deleted product ID and title. **Prerequisites:** get-product or list-products to find the correct product ID. **Warning:** This action cannot be undone.",
-      inputSchema: inputSchema15,
-      outputSchema: outputSchema15,
+      inputSchema: inputSchema17,
+      outputSchema: outputSchema17,
       // AI Agent Optimization (Story 5.5)
       category: "product",
       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
@@ -5685,15 +6277,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 z20 } from "zod";
+var inputSchema18 = z20.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 outputSchema18 = z20.object({
+  success: z20.boolean().describe("Whether the deletion succeeded"),
+  deletedRedirectId: z20.string().describe("ID of the deleted redirect")
 });
 var handleDeleteRedirect = async (context, params) => {
   log.debug(`Deleting redirect on shop: ${context.shopDomain}`);
@@ -5735,13 +6327,22 @@ function registerDeleteRedirectTool() {
       name: "delete-redirect",
       title: "Delete URL Redirect",
       description: "Remove a URL redirect by ID. **Warning:** Deleting means visitors to that path will see 404 error - can hurt SEO if old URL still receives traffic. **Prerequisites:** list-redirects to find redirect IDs.",
-      inputSchema: inputSchema16,
-      outputSchema: outputSchema16,
+      inputSchema: inputSchema18,
+      outputSchema: outputSchema18,
       // AI Agent Optimization (Story 5.5)
       category: "seo",
       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
@@ -5749,7 +6350,7 @@ function registerDeleteRedirectTool() {
 }
 
 // src/tools/get-bulk-inventory.ts
-import { z as z18 } from "zod";
+import { z as z21 } from "zod";
 
 // src/shopify/inventory.ts
 var GET_INVENTORY_ITEM_QUERY = `
@@ -6320,46 +6921,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 inputSchema19 = z21.object({
+  productIds: z21.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: z21.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 outputSchema19 = z21.object({
+  products: z21.array(
+    z21.object({
+      productId: z21.string().describe("Product GID"),
+      productTitle: z21.string().describe("Product title"),
+      totalInventory: z21.number().describe("Total inventory across all variants"),
+      variants: z21.array(
+        z21.object({
+          variantId: z21.string().describe("Variant GID"),
+          variantTitle: z21.string().describe('Variant title (e.g., "Red / Large")'),
+          sku: z21.string().nullable().describe("SKU (Stock Keeping Unit)"),
+          inventoryItemId: z21.string().describe("Inventory item GID"),
+          available: z21.number().describe("Available quantity"),
+          locations: z21.array(
+            z21.object({
+              locationId: z21.string().describe("Location GID"),
+              locationName: z21.string().describe("Human-readable location name"),
+              available: z21.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: z21.array(z21.string()).describe("Product IDs that were not found in the store"),
+  summary: z21.object({
+    productsQueried: z21.number().describe("Total number of product IDs provided"),
+    productsFound: z21.number().describe("Number of products found in the store"),
+    totalInventory: z21.number().describe("Sum of inventory across all found products")
   }).describe("Summary statistics")
 });
 var handleGetBulkInventory = async (context, params) => {
@@ -6391,14 +6992,21 @@ function registerGetBulkInventoryTool() {
       name: "get-bulk-inventory",
       title: "Get Bulk Inventory",
       description: "Efficiently query inventory levels for multiple products in a single request. Accepts up to 50 product IDs and returns total inventory plus optional per-variant breakdown. Use this instead of multiple get-inventory calls when checking stock across several products. Returns a summary with counts of products queried vs found, plus total inventory across all products. Products not found in the store are listed in the notFound array rather than causing an error. Perfect for cart verification, collection audits, and batch inventory checks. **Typical workflow:** list-products \u2192 get-bulk-inventory. **Prerequisites:** Product IDs. **Follow-ups:** update-inventory, get-inventory. Returns products with inventory data and summary statistics.",
-      inputSchema: inputSchema17,
-      outputSchema: outputSchema17,
+      inputSchema: inputSchema19,
+      outputSchema: outputSchema19,
       category: "inventory",
       relationships: {
         relatedTools: ["list-products", "get-inventory", "update-inventory"],
         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
@@ -6406,30 +7014,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 z22 } from "zod";
+var inputSchema20 = z22.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 outputSchema20 = z22.object({
+  id: z22.string().describe("Collection GID"),
+  title: z22.string().describe("Collection title"),
+  handle: z22.string().describe("URL handle/slug"),
+  description: z22.string().describe("Plain text description"),
+  descriptionHtml: z22.string().describe("HTML description"),
+  seo: z22.object({
+    title: z22.string().nullable().describe("SEO title"),
+    description: z22.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: z22.object({
+    id: z22.string().describe("Image GID"),
+    url: z22.string().describe("Image URL"),
+    altText: z22.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: z22.string().describe("Product sort order within collection"),
+  productsCount: z22.number().describe("Number of products in collection"),
+  updatedAt: z22.string().describe("Last update timestamp (ISO 8601)")
 });
 var handleGetCollection = async (context, params) => {
   log.debug(`Getting collection on shop: ${context.shopDomain}`);
@@ -6449,13 +7057,20 @@ function registerGetCollectionTool() {
       name: "get-collection",
       title: "Get Collection",
       description: "Retrieve complete details of a collection by ID. Returns all collection attributes including SEO metadata, product count, sort order, and timestamps. **Prerequisites:** list-collections to find collection IDs. **Follow-ups:** update-collection, delete-collection, add-products-to-collection.",
-      inputSchema: inputSchema18,
-      outputSchema: outputSchema18,
+      inputSchema: inputSchema20,
+      outputSchema: outputSchema20,
       // AI Agent Optimization (Story 5.5)
       category: "collection",
       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
@@ -6463,37 +7078,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 z23 } from "zod";
+var inputSchema21 = z23.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 outputSchema21 = z23.object({
+  inventoryItemId: z23.string().describe("Inventory item GID"),
+  variantId: z23.string().describe("Product variant GID"),
+  variantTitle: z23.string().describe('Variant title (e.g., "Red / Large")'),
+  productId: z23.string().describe("Product GID"),
+  productTitle: z23.string().describe("Product title"),
+  sku: z23.string().nullable().describe("SKU (Stock Keeping Unit)"),
+  tracked: z23.boolean().describe("Whether inventory tracking is enabled for this item"),
+  totalAvailable: z23.number().describe("Total available quantity across all locations"),
+  locations: z23.array(
+    z23.object({
+      locationId: z23.string().describe("Location GID"),
+      locationName: z23.string().describe("Human-readable location name"),
+      isActive: z23.boolean().describe("Whether the location is active"),
+      available: z23.number().describe("Quantity available for sale"),
+      onHand: z23.number().describe("Physical quantity on hand"),
+      committed: z23.number().describe("Quantity committed to orders")
     })
   ).describe("Inventory levels by location")
 });
@@ -6555,8 +7170,8 @@ function registerGetInventoryTool() {
       name: "get-inventory",
       title: "Get Inventory",
       description: "Retrieve inventory levels for a product variant across all store locations. Provide either a variantId (from get-product or list-products) or inventoryItemId (if you have it directly). Returns available, on-hand, and committed quantities per location, plus totals. Useful for: checking stock before making availability promises, identifying which locations have stock, understanding inventory distribution across warehouse locations. Optionally filter by locationId to get inventory at a specific location only. **Typical workflow:** get-product \u2192 get-inventory \u2192 update-inventory. **Prerequisites:** Variant ID or Inventory Item ID. **Follow-ups:** update-inventory. Returns inventory levels per location with totals.",
-      inputSchema: inputSchema19,
-      outputSchema: outputSchema19,
+      inputSchema: inputSchema21,
+      outputSchema: outputSchema21,
       category: "inventory",
       relationships: {
         relatedTools: [
@@ -6567,30 +7182,119 @@ 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
   );
 }
 
+// src/tools/get-market.ts
+import { z as z24 } from "zod";
+var inputSchema22 = z24.object({
+  id: marketIdSchema.describe(
+    'Shopify Market GID (e.g., "gid://shopify/Market/123"). Use list-markets to find market IDs.'
+  )
+});
+var outputSchema22 = z24.object({
+  id: z24.string().describe("Market GID"),
+  name: z24.string().describe("Market name (not shown to customers)"),
+  handle: z24.string().describe("URL handle"),
+  enabled: z24.boolean().describe("Whether the market is enabled"),
+  status: z24.enum(["ACTIVE", "INACTIVE"]).describe("Market status"),
+  type: z24.string().describe("Market type (PRIMARY, SINGLE_COUNTRY, MULTI_COUNTRY, CONTINENT)"),
+  currencySettings: z24.object({
+    baseCurrency: z24.object({
+      currencyCode: z24.string().describe("Base currency code (e.g., USD, EUR)"),
+      currencyName: z24.string().optional().describe("Base currency name")
+    }),
+    localCurrencies: z24.boolean().describe("Whether local currencies are enabled")
+  }).optional(),
+  webPresences: z24.array(
+    z24.object({
+      id: z24.string().describe("Web presence GID"),
+      defaultLocale: z24.object({
+        locale: z24.string().describe("Locale code (e.g., en-CA)"),
+        name: z24.string().describe("Locale display name")
+      }),
+      alternateLocales: z24.array(
+        z24.object({
+          locale: z24.string(),
+          name: z24.string()
+        })
+      ).optional(),
+      subfolderSuffix: z24.string().optional().describe("Subfolder suffix (e.g., /en-ca)"),
+      domain: z24.object({
+        host: z24.string().describe("Domain host")
+      }).optional(),
+      rootUrls: z24.array(
+        z24.object({
+          locale: z24.string(),
+          url: z24.string()
+        })
+      ).optional()
+    })
+  ).optional().describe("Web presences (SEO URL configurations)")
+});
+var handleGetMarket = async (context, params) => {
+  log.debug(`Getting market ${params.id} on shop: ${context.shopDomain}`);
+  const market = await getMarket(params.id);
+  if (!market) {
+    throw new Error(`Market not found: ${params.id}. Use list-markets to see available markets.`);
+  }
+  log.debug(`Retrieved market: ${market.name}`);
+  return market;
+};
+function registerGetMarketTool() {
+  registerContextAwareTool(
+    {
+      name: "get-market",
+      title: "Get Market",
+      description: "Retrieve full details of a specific market by ID. Returns market name, handle, status, type, currency settings, and web presences. Web presences define SEO URL structures (domains, subfolders, locales). **Prerequisites:** Use list-markets to find market IDs. **Follow-ups:** update-market, delete-market, create-web-presence.",
+      inputSchema: inputSchema22,
+      outputSchema: outputSchema22,
+      // AI Agent Optimization
+      category: "market",
+      relationships: {
+        relatedTools: ["list-markets"],
+        followUps: ["update-market", "delete-market"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    handleGetMarket
+  );
+}
+
 // src/tools/get-page.ts
-import { z as z21 } from "zod";
-var inputSchema20 = z21.object({
-  id: z21.string().min(1).describe(
+import { z as z25 } from "zod";
+var inputSchema23 = z25.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 outputSchema23 = z25.object({
+  id: z25.string().describe("Page GID"),
+  title: z25.string().describe("Page title"),
+  handle: z25.string().describe("URL handle/slug"),
+  body: z25.string().describe("HTML body content"),
+  bodySummary: z25.string().describe("Plain text summary (first 150 chars)"),
+  isPublished: z25.boolean().describe("Whether page is visible on storefront"),
+  publishedAt: z25.string().nullable().describe("ISO timestamp when published"),
+  templateSuffix: z25.string().nullable().describe("Custom template suffix"),
+  createdAt: z25.string().describe("ISO timestamp of creation"),
+  updatedAt: z25.string().describe("ISO timestamp of last update")
 });
 var handleGetPage = async (context, params) => {
   log.debug(`Getting page on shop: ${context.shopDomain}`);
@@ -6610,13 +7314,20 @@ function registerGetPageTool() {
       name: "get-page",
       title: "Get Page",
       description: "Retrieve details of a specific page by ID. Returns the full page including title, body content, handle, publish status, and timestamps. Use list-pages first to find page IDs. Useful for: inspecting page content before editing, verifying page details. **Typical workflow:** list-pages \u2192 get-page \u2192 update-page. **Prerequisites:** Page ID. **Follow-ups:** update-page, delete-page. Returns a single page object with full content.",
-      inputSchema: inputSchema20,
-      outputSchema: outputSchema20,
+      inputSchema: inputSchema23,
+      outputSchema: outputSchema23,
       category: "content",
       relationships: {
         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
@@ -6624,27 +7335,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 z26 } from "zod";
+var inputSchema24 = z26.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: z26.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: z26.array(z26.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 outputSchema24 = z26.array(
+  z26.object({
+    id: z26.string().describe('Metafield GID (e.g., "gid://shopify/Metafield/123")'),
+    namespace: z26.string().describe("Metafield namespace (grouping identifier)"),
+    key: z26.string().describe("Metafield key (field name)"),
+    value: z26.string().describe("Metafield value (the stored data)"),
+    type: z26.string().describe('Metafield type (e.g., "single_line_text_field", "json", "number_integer")'),
+    createdAt: z26.string().describe("Creation timestamp (ISO 8601)"),
+    updatedAt: z26.string().describe("Last update timestamp (ISO 8601)")
   })
 );
 var handleGetProductMetafields = async (context, params) => {
@@ -6669,14 +7380,21 @@ function registerGetProductMetafieldsTool() {
       name: "get-product-metafields",
       title: "Get Product Metafields",
       description: 'Retrieve metafields attached to a product. Metafields store custom data like SEO schema markup, product specifications, or custom attributes. Filter by namespace to get specific app/integration data, or by keys to retrieve specific fields. Common namespaces include "custom" (user-defined), "seo" (search optimization), and app-specific namespaces. Returns all matching metafields with their id, namespace, key, value, type, and timestamps. **Prerequisites:** get-product to obtain the product ID. **Follow-ups:** set-product-metafields to update values, delete-product-metafields to remove.',
-      inputSchema: inputSchema21,
-      outputSchema: outputSchema21,
+      inputSchema: inputSchema24,
+      outputSchema: outputSchema24,
       // AI Agent Optimization (Story 5.5)
       category: "seo",
       relationships: {
         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
@@ -6684,51 +7402,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 z27 } from "zod";
+var inputSchema25 = z27.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: z27.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 outputSchema25 = z27.object({
+  id: z27.string().describe('Product GID (e.g., "gid://shopify/Product/123")'),
+  title: z27.string().describe("Product title"),
+  handle: z27.string().describe("URL handle/slug"),
+  description: z27.string().nullable().describe("Product description (HTML)"),
+  vendor: z27.string().describe("Vendor/brand name"),
+  productType: z27.string().describe("Product type"),
+  status: z27.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).describe("Product status"),
+  tags: z27.array(z27.string()).describe("Product tags"),
+  seo: z27.object({
+    title: z27.string().nullable().describe("SEO title for search engines"),
+    description: z27.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: z27.string().describe("Creation timestamp (ISO 8601)"),
+  updatedAt: z27.string().describe("Last update timestamp (ISO 8601)"),
+  variants: z27.array(
+    z27.object({
+      id: z27.string().describe("Variant GID"),
+      title: z27.string().describe("Variant title"),
+      price: z27.string().describe("Price"),
+      compareAtPrice: z27.string().nullable().describe("Compare at price"),
+      sku: z27.string().nullable().describe("SKU"),
+      barcode: z27.string().nullable().describe("Barcode"),
+      inventoryQuantity: z27.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: z27.array(
+    z27.object({
+      id: z27.string().describe("Image GID"),
+      url: z27.string().describe("Image URL"),
+      altText: z27.string().nullable().describe("Alt text")
     })
   ).describe("Product images"),
-  totalInventory: z23.number().describe("Total inventory across variants")
+  totalInventory: z27.number().describe("Total inventory across variants")
 });
 var handleGetProduct = async (context, params) => {
   log.debug(`Getting product on shop: ${context.shopDomain}`);
@@ -6767,8 +7485,8 @@ function registerGetProductTool() {
       name: "get-product",
       title: "Get Product",
       description: "Retrieve details of a specific product from the Shopify store. Provide either the product ID (GID format) or handle (URL slug). Returns full product details including title, description, vendor, type, status, tags, SEO metadata (title/description for search engines), variants (with pricing/SKU/inventory), and images. **Prerequisites:** Use list-products to find product IDs or handles. **Follow-ups:** update-product, delete-product, add-product-image, get-product-metafields.",
-      inputSchema: inputSchema22,
-      outputSchema: outputSchema22,
+      inputSchema: inputSchema25,
+      outputSchema: outputSchema25,
       // AI Agent Optimization (Story 5.5)
       category: "product",
       relationships: {
@@ -6779,6 +7497,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
@@ -6786,36 +7511,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 z28 } from "zod";
+var inputSchema26 = z28.object({
+  first: z28.number().int().min(1).max(50).optional().default(10).describe("Number of articles to return (1-50). Defaults to 10."),
+  cursor: z28.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: z28.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: z28.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: z28.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 outputSchema26 = z28.object({
+  articles: z28.array(
+    z28.object({
+      id: z28.string().describe("Article GID"),
+      title: z28.string().describe("Article title"),
+      handle: z28.string().describe("URL handle/slug"),
+      blog: z28.object({
+        id: z28.string().describe("Parent blog GID"),
+        title: z28.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: z28.boolean().describe("Whether article is visible on storefront"),
+      publishedAt: z28.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: z28.boolean().describe("Whether more articles are available"),
+  endCursor: z28.string().nullable().describe("Cursor for next page pagination")
 });
 var handleListArticles = async (context, params) => {
   log.debug(`Listing articles on shop: ${context.shopDomain}`);
@@ -6859,12 +7584,19 @@ function registerListArticlesTool() {
       name: "list-articles",
       title: "List Articles",
       description: "List articles with optional filtering and pagination. Use blogId to filter articles from a specific blog. Use query to search by title or tags. Returns article ID, title, handle, blog reference, and publish status. Useful for: finding articles to edit, auditing blog content, bulk operations. **Typical workflow:** list-blogs \u2192 list-articles \u2192 update-article. **Prerequisites:** None (optional Blog ID for filtering). **Follow-ups:** update-article, delete-article, create-article. Returns a paginated list of article summaries with a response summary.",
-      inputSchema: inputSchema23,
-      outputSchema: outputSchema23,
+      inputSchema: inputSchema26,
+      outputSchema: outputSchema26,
       category: "content",
       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
@@ -6872,29 +7604,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 z29 } from "zod";
+var inputSchema27 = z29.object({
+  first: z29.number().int().min(1).max(50).optional().default(10).describe("Number of blogs to return (1-50). Defaults to 10."),
+  cursor: z29.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: z29.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: z29.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 outputSchema27 = z29.object({
+  blogs: z29.array(
+    z29.object({
+      id: z29.string().describe("Blog GID"),
+      title: z29.string().describe("Blog title"),
+      handle: z29.string().describe("URL handle/slug"),
+      commentPolicy: z29.enum(["CLOSED", "MODERATE", "OPEN"]).describe("Comment moderation policy"),
+      articlesCount: z29.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: z29.boolean().describe("Whether more blogs are available"),
+  endCursor: z29.string().nullable().describe("Cursor for next page pagination")
 });
 var handleListBlogs = async (context, params) => {
   log.debug(`Listing blogs on shop: ${context.shopDomain}`);
@@ -6932,12 +7664,19 @@ function registerListBlogsTool() {
       name: "list-blogs",
       title: "List Blogs",
       description: "List all blogs with optional filtering and pagination. Use the query parameter to search blogs by title or handle. Returns blog ID, title, handle, and article count. Useful for: finding blogs to manage, auditing content, selecting a blog for new articles. **Typical workflow:** list-blogs \u2192 list-articles. **Prerequisites:** None. **Follow-ups:** create-article, update-blog, create-blog. Returns a paginated list of blog summaries with a response summary.",
-      inputSchema: inputSchema24,
-      outputSchema: outputSchema24,
+      inputSchema: inputSchema27,
+      outputSchema: outputSchema27,
       category: "content",
       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
@@ -6945,40 +7684,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 z30 } from "zod";
+var inputSchema28 = z30.object({
+  first: z30.number().int().min(1).max(50).optional().default(10).describe("Number of collections to return (1-50). Default: 10"),
+  after: z30.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: z30.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: z30.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 outputSchema28 = z30.object({
+  collections: z30.array(
+    z30.object({
+      id: z30.string().describe("Collection GID"),
+      title: z30.string().describe("Collection title"),
+      handle: z30.string().describe("URL handle"),
+      seo: z30.object({
+        title: z30.string().nullable().describe("SEO title"),
+        description: z30.string().nullable().describe("SEO description")
       }),
-      productsCount: z26.number().describe("Number of products in collection")
+      productsCount: z30.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: z30.object({
+    hasNextPage: z30.boolean().describe("Whether more pages exist"),
+    endCursor: z30.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: z30.object({
+    totalReturned: z30.number().describe("Number of collections in this response"),
+    hasMore: z30.boolean().describe("Whether more collections are available"),
+    hint: z30.string().describe("Suggestion for next action")
   }).describe("AI-friendly summary for context management")
 });
 var handleListCollections = async (context, params) => {
@@ -7005,13 +7744,20 @@ function registerListCollectionsTool() {
       name: "list-collections",
       title: "List Collections",
       description: 'List and search collections with pagination and filtering. Use the query parameter for text search across collection titles and handles. Supports sorting by TITLE, UPDATED_AT, ID, or RELEVANCE. Returns up to 50 collections per page. Response includes summary with totalReturned, hasMore, and pagination hint. **Pagination:** Use "after" cursor from pageInfo.endCursor to get next page. **Follow-ups:** get-collection (for full details), update-collection, add-products-to-collection.',
-      inputSchema: inputSchema25,
-      outputSchema: outputSchema25,
+      inputSchema: inputSchema28,
+      outputSchema: outputSchema28,
       // AI Agent Optimization (Story 5.5)
       category: "collection",
       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
@@ -7019,47 +7765,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 z31 } from "zod";
+var inputSchema29 = z31.object({
+  threshold: z31.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: z31.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: z31.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: z31.number().int().min(1).max(100).default(50).describe("Number of products to return per page. Default: 50, max: 100."),
+  after: z31.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 outputSchema29 = z31.object({
+  products: z31.array(
+    z31.object({
+      productId: z31.string().describe('Product GID (e.g., "gid://shopify/Product/123")'),
+      productTitle: z31.string().describe("Product title"),
+      status: z31.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).describe("Product status"),
+      totalInventory: z31.number().describe("Total inventory across all variants"),
+      isOutOfStock: z31.boolean().describe("True if total inventory is zero"),
+      variants: z31.array(
+        z31.object({
+          variantId: z31.string().describe("Variant GID"),
+          variantTitle: z31.string().describe('Variant title (e.g., "Red / Large")'),
+          sku: z31.string().nullable().describe("SKU (Stock Keeping Unit)"),
+          inventoryItemId: z31.string().describe("Inventory item GID"),
+          available: z31.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: z31.object({
+    hasNextPage: z31.boolean().describe("Whether more products exist after this page"),
+    endCursor: z31.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: z31.object({
+    totalProducts: z31.number().describe("Number of products in this response"),
+    outOfStockCount: z31.number().describe("Number of products with zero inventory"),
+    lowStockCount: z31.number().describe("Number of products with inventory > 0 but below threshold")
   }).describe("Summary statistics")
 });
 var handleListLowInventory = async (context, params) => {
@@ -7083,44 +7829,125 @@ function registerListLowInventoryTool() {
       name: "list-low-inventory",
       title: "List Low Inventory",
       description: 'Find products with low or zero inventory that may need restocking. Returns products sorted by inventory level (lowest first). Use threshold parameter to customize what counts as "low stock" (default: 10 units). Includes variant breakdown and summary statistics showing how many products are out-of-stock vs. low-stock. Perfect for daily inventory checks, restocking alerts, and identifying products at risk of stockout. Use includeZero=false to exclude completely sold-out items. Use status=DRAFT to check pre-launch products before publishing. **Typical workflow:** list-low-inventory \u2192 get-inventory \u2192 update-inventory. **Prerequisites:** None. **Follow-ups:** get-inventory, update-inventory. Returns paginated products with inventory levels and summary statistics.',
-      inputSchema: inputSchema26,
-      outputSchema: outputSchema26,
+      inputSchema: inputSchema29,
+      outputSchema: outputSchema29,
       category: "inventory",
       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
   );
 }
 
+// src/tools/list-markets.ts
+import { z as z32 } from "zod";
+var inputSchema30 = z32.object({
+  first: z32.number().int().min(1).max(50).optional().default(10).describe("Number of markets to return (1-50). Default: 10"),
+  after: z32.string().optional().describe(
+    "Pagination cursor from previous response. Use the endCursor value from the previous page to get the next page of results."
+  )
+});
+var outputSchema30 = z32.object({
+  markets: z32.array(
+    z32.object({
+      id: z32.string().describe("Market GID"),
+      name: z32.string().describe("Market name (not shown to customers)"),
+      handle: z32.string().describe("URL handle"),
+      enabled: z32.boolean().describe("Whether the market is enabled"),
+      status: z32.enum(["ACTIVE", "INACTIVE"]).describe("Market status"),
+      type: z32.string().describe("Market type (PRIMARY, SINGLE_COUNTRY, MULTI_COUNTRY, CONTINENT)"),
+      currencySettings: z32.object({
+        baseCurrency: z32.object({
+          currencyCode: z32.string().describe("Base currency code (e.g., USD, EUR)")
+        }),
+        localCurrencies: z32.boolean().describe("Whether local currencies are enabled")
+      }).optional()
+    })
+  ),
+  pageInfo: z32.object({
+    hasNextPage: z32.boolean().describe("Whether more pages exist"),
+    endCursor: z32.string().nullable().describe("Cursor for next page")
+  }),
+  summary: z32.object({
+    totalReturned: z32.number().describe("Number of markets in this response"),
+    hasMore: z32.boolean().describe("Whether more markets are available"),
+    hint: z32.string().describe("Suggestion for next action")
+  }).describe("AI-friendly summary for context management")
+});
+var handleListMarkets = async (context, params) => {
+  log.debug(`Listing markets on shop: ${context.shopDomain}`);
+  const result = await listMarkets(params.first, params.after);
+  log.debug(`Listed ${result.markets.length} markets via tool`);
+  return {
+    ...result,
+    summary: {
+      totalReturned: result.markets.length,
+      hasMore: result.pageInfo.hasNextPage,
+      hint: result.pageInfo.hasNextPage ? `Use "after" parameter with value "${result.pageInfo.endCursor}" to fetch next page` : "All markets returned"
+    }
+  };
+};
+function registerListMarketsTool() {
+  registerContextAwareTool(
+    {
+      name: "list-markets",
+      title: "List Markets",
+      description: 'List all configured markets in the Shopify store with pagination. Markets enable regional targeting for international stores. Returns market id, name, handle, status, type, and currency settings. Response includes summary with totalReturned, hasMore, and pagination hint. **Pagination:** Use "after" cursor from pageInfo.endCursor to get next page. **Prerequisites:** Store must have Markets feature enabled. **Follow-ups:** get-market (for full details including web presences), create-market.',
+      inputSchema: inputSchema30,
+      outputSchema: outputSchema30,
+      // AI Agent Optimization
+      category: "market",
+      relationships: {
+        relatedTools: ["get-market"],
+        followUps: ["get-market", "create-market", "update-market"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    handleListMarkets
+  );
+}
+
 // 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 z33 } from "zod";
+var inputSchema31 = z33.object({
+  first: z33.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: z33.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: z33.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: z33.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 outputSchema31 = z33.object({
+  pages: z33.array(
+    z33.object({
+      id: z33.string().describe("Page GID"),
+      title: z33.string().describe("Page title"),
+      handle: z33.string().describe("URL handle/slug"),
+      isPublished: z33.boolean().describe("Whether page is visible"),
+      updatedAt: z33.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: z33.boolean().describe("Whether more pages exist"),
+  endCursor: z33.string().nullable().describe("Cursor for next page of results")
 });
 var handleListPages = async (context, params) => {
   log.debug(`Listing pages on shop: ${context.shopDomain}`);
@@ -7146,12 +7973,19 @@ function registerListPagesTool() {
       name: "list-pages",
       title: "List Pages",
       description: "List all pages with optional filtering and pagination. Use the query parameter to search pages by title or handle. Returns page ID, title, handle, and publish status. Use pagination (cursor) for stores with many pages. Useful for: finding pages to edit, auditing content, bulk operations. **Typical workflow:** list-pages \u2192 get-page. **Prerequisites:** None. **Follow-ups:** get-page, update-page, create-page. Returns a paginated list of page summaries with a response summary.",
-      inputSchema: inputSchema27,
-      outputSchema: outputSchema27,
+      inputSchema: inputSchema31,
+      outputSchema: outputSchema31,
       category: "content",
       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
@@ -7159,46 +7993,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 z34 } from "zod";
+var inputSchema32 = z34.object({
+  first: z34.number().int().min(1).max(50).optional().describe("Number of products to return (1-50). Default: 10"),
+  after: z34.string().optional().describe("Pagination cursor from previous response's endCursor. Omit for first page."),
+  query: z34.string().optional().describe(
     'Search query for title, description, tags. Example: "summer dress", "organic cotton"'
   ),
-  status: z29.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).optional().describe(
+  status: z34.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: z34.string().optional().describe('Filter by exact vendor name. Example: "Acme Corp", "Nike"'),
+  productType: z34.string().optional().describe('Filter by exact product type. Example: "T-Shirts", "Shoes"'),
+  sortBy: z34.enum(["TITLE", "CREATED_AT", "UPDATED_AT", "INVENTORY_TOTAL"]).optional().describe("Sort field. TITLE, CREATED_AT (default), UPDATED_AT, or INVENTORY_TOTAL"),
+  sortOrder: z34.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 outputSchema32 = z34.object({
+  products: z34.array(
+    z34.object({
+      id: z34.string().describe('Product GID (e.g., "gid://shopify/Product/123")'),
+      title: z34.string().describe("Product title"),
+      handle: z34.string().describe("URL handle/slug"),
+      status: z34.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).describe("Product status"),
+      vendor: z34.string().describe("Vendor/brand name"),
+      productType: z34.string().describe("Product type"),
+      totalInventory: z34.number().describe("Total inventory across all variants"),
+      primaryVariantPrice: z34.string().describe('Price of the first variant (e.g., "29.99")'),
+      imageUrl: z34.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: z34.object({
+    hasNextPage: z34.boolean().describe("Whether more products exist after this page"),
+    hasPreviousPage: z34.boolean().describe("Whether products exist before this page"),
+    startCursor: z34.string().nullable().describe("Cursor for the first item in this page"),
+    endCursor: z34.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: z34.number().describe("Number of products returned in this page"),
+  summary: z34.object({
+    totalReturned: z34.number().describe("Number of products in this response"),
+    hasMore: z34.boolean().describe("Whether more products are available"),
+    hint: z34.string().describe("Suggestion for next action")
   }).describe("AI-friendly summary for context management")
 });
 var handleListProducts = async (context, params) => {
@@ -7232,13 +8066,20 @@ function registerListProductsTool() {
       name: "list-products",
       title: "List Products",
       description: 'List products from the Shopify store with pagination and filtering. Returns product summaries including title, status, vendor, type, price, and inventory. Supports filtering by status (ACTIVE/DRAFT/ARCHIVED), vendor, productType, and search query. Sort by TITLE, CREATED_AT, UPDATED_AT, or INVENTORY_TOTAL. Response includes summary with totalReturned, hasMore, and pagination hint. **Pagination:** Use "after" cursor from pageInfo.endCursor to get next page. **Follow-ups:** get-product (for full details), update-product, delete-product.',
-      inputSchema: inputSchema28,
-      outputSchema: outputSchema28,
+      inputSchema: inputSchema32,
+      outputSchema: outputSchema32,
       // AI Agent Optimization (Story 5.5)
       category: "product",
       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
@@ -7246,30 +8087,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 z35 } from "zod";
+var inputSchema33 = z35.object({
+  first: z35.number().int().min(1).max(50).optional().default(10).describe("Number of redirects to return (1-50, default: 10)."),
+  cursor: z35.string().optional().describe(
     "Pagination cursor from previous response (endCursor). Use this to fetch the next page of results."
   ),
-  query: z30.string().optional().describe(
+  query: z35.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 outputSchema33 = z35.object({
+  redirects: z35.array(
+    z35.object({
+      id: z35.string().describe("Redirect GID"),
+      path: z35.string().describe("Source path"),
+      target: z35.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: z35.boolean().describe("Whether more results exist"),
+  endCursor: z35.string().nullable().describe("Cursor for fetching next page"),
+  summary: z35.object({
+    totalReturned: z35.number().describe("Number of redirects in this response"),
+    hasMore: z35.boolean().describe("Whether more redirects are available"),
+    hint: z35.string().describe("Suggestion for next action")
   }).describe("AI-friendly summary for context management")
 });
 var handleListRedirects = async (context, params) => {
@@ -7307,13 +8148,20 @@ function registerListRedirectsTool() {
       name: "list-redirects",
       title: "List URL Redirects",
       description: `List all URL redirects with optional filtering and pagination. Use query parameter to search by path or target (supports 'path:' and 'target:' prefixes). Response includes summary with totalReturned, hasMore, and pagination hint. **Pagination:** Use "cursor" with endCursor value to get next page. **Follow-ups:** delete-redirect to remove unwanted redirects.`,
-      inputSchema: inputSchema29,
-      outputSchema: outputSchema29,
+      inputSchema: inputSchema33,
+      outputSchema: outputSchema33,
       // AI Agent Optimization (Story 5.5)
       category: "seo",
       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
@@ -7321,18 +8169,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 z36 } from "zod";
+var inputSchema34 = z36.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: z36.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 outputSchema34 = z36.object({
+  success: z36.boolean().describe("Whether the operation succeeded"),
+  removedCount: z36.number().describe("Number of products removed from the collection")
 });
 var handleRemoveProductsFromCollection = async (context, params) => {
   log.debug(
@@ -7362,13 +8210,22 @@ function registerRemoveProductsFromCollectionTool() {
       name: "remove-products-from-collection",
       title: "Remove Products from Collection",
       description: "Remove products from a collection by their product IDs. This does NOT delete the products - they remain in the catalog but are no longer part of this collection. Maximum 250 products per call. **Prerequisites:** get-collection to verify collection contents before removing.",
-      inputSchema: inputSchema30,
-      outputSchema: outputSchema30,
+      inputSchema: inputSchema34,
+      outputSchema: outputSchema34,
       // AI Agent Optimization (Story 5.5)
       category: "collection",
       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
@@ -7376,7 +8233,7 @@ function registerRemoveProductsFromCollectionTool() {
 }
 
 // src/tools/reorder-product-images.ts
-import { z as z32 } from "zod";
+import { z as z37 } from "zod";
 var PRODUCT_REORDER_MEDIA_MUTATION = `
   mutation ProductReorderMedia($id: ID!, $moves: [MoveInput!]!) {
     productReorderMedia(id: $id, moves: $moves) {
@@ -7391,23 +8248,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 = z37.object({
+  id: imageIdSchema.describe('Image GID to move (e.g., "gid://shopify/MediaImage/123")'),
+  newPosition: z37.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 inputSchema35 = z37.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: z37.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 outputSchema35 = z37.object({
+  success: z37.boolean().describe("Whether the reorder operation was initiated successfully"),
+  jobId: z37.string().nullable().describe("Background job ID for tracking (may be null if processed immediately)"),
+  jobDone: z37.boolean().describe("Whether the job completed immediately"),
+  message: z37.string().describe("Human-readable message describing the result")
 });
 var handleReorderProductImages = async (context, params) => {
   log.debug(`Reordering images on shop: ${context.shopDomain}`);
@@ -7475,13 +8332,21 @@ function registerReorderProductImagesTool() {
       name: "reorder-product-images",
       title: "Reorder Product Images",
       description: "Change the display order of product images. The first image (position 0) is typically the featured/hero image shown in product listings. Provide an array of move operations specifying which image IDs should move to which positions. Positions are 0-indexed. This operation runs asynchronously in Shopify's background. **Prerequisites:** get-product to obtain current image IDs and their positions.",
-      inputSchema: inputSchema31,
-      outputSchema: outputSchema31,
+      inputSchema: inputSchema35,
+      outputSchema: outputSchema35,
       // AI Agent Optimization (Story 5.5)
       category: "media",
       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
@@ -7489,45 +8354,45 @@ function registerReorderProductImagesTool() {
 }
 
 // src/tools/set-product-metafields.ts
-import { z as z33 } from "zod";
+import { z as z38 } from "zod";
 var MAX_METAFIELDS_PER_CALL = 25;
-var metafieldInputSchema = z33.object({
-  namespace: z33.string().min(1).describe(
+var metafieldInputSchema = z38.object({
+  namespace: z38.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: z38.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: z38.string().describe("The value to store. All values are stored as strings; JSON should be stringified."),
+  type: z38.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 inputSchema36 = z38.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: z38.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 outputSchema36 = z38.object({
+  success: z38.boolean().describe("Whether the operation succeeded"),
+  metafields: z38.array(
+    z38.object({
+      id: z38.string().describe("Metafield GID"),
+      namespace: z38.string().describe("Metafield namespace"),
+      key: z38.string().describe("Metafield key"),
+      value: z38.string().describe("Metafield value"),
+      type: z38.string().describe("Metafield type"),
+      createdAt: z38.string().describe("Creation timestamp (ISO 8601)"),
+      updatedAt: z38.string().describe("Last update timestamp (ISO 8601)")
     })
   ).describe("Created or updated metafields"),
-  count: z33.number().describe("Number of metafields processed")
+  count: z38.number().describe("Number of metafields processed")
 });
 var handleSetProductMetafields = async (context, params) => {
   log.debug(
@@ -7563,14 +8428,22 @@ function registerSetProductMetafieldsTool() {
       name: "set-product-metafields",
       title: "Set Product Metafields",
       description: `Create or update up to ${MAX_METAFIELDS_PER_CALL} metafields on a product in a single operation. Each metafield requires: namespace (grouping identifier), key (field name), value (the data), and type. Existing metafields with matching namespace+key are updated; new ones are created. Common types: single_line_text_field, multi_line_text_field, number_integer, number_decimal, boolean, json. **Typical workflow:** create-product \u2192 set-product-metafields (add custom data). **Prerequisites:** get-product to obtain product ID, optionally get-product-metafields to check existing values. **Follow-ups:** get-product-metafields to verify changes.`,
-      inputSchema: inputSchema32,
-      outputSchema: outputSchema32,
+      inputSchema: inputSchema36,
+      outputSchema: outputSchema36,
       // AI Agent Optimization (Story 5.5)
       category: "seo",
       relationships: {
         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
@@ -7578,47 +8451,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 z39 } from "zod";
+var inputSchema37 = z39.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: z39.string().optional().describe("The new title for the article. Only provided if changing the title."),
+  authorName: z39.string().optional().describe("The new author name for the article."),
+  body: z39.string().optional().describe("The new HTML body content of the article. Supports HTML markup for formatting."),
+  summary: z39.string().optional().describe("A summary or excerpt of the article."),
+  tags: z39.array(z39.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: z39.object({
+    url: z39.string().url().describe("The URL of the featured image"),
+    altText: z39.string().optional().describe("Alt text for accessibility")
   }).optional().describe("Featured image for the article."),
-  isPublished: z34.boolean().optional().describe(
+  isPublished: z39.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: z39.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: z39.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: z39.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: z39.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 outputSchema37 = z39.object({
+  id: z39.string().describe("Updated article GID"),
+  title: z39.string().describe("Article title"),
+  handle: z39.string().describe("URL handle/slug"),
+  blog: z39.object({
+    id: z39.string().describe("Parent blog GID"),
+    title: z39.string().describe("Parent blog title")
   }),
-  isPublished: z34.boolean().describe("Whether article is visible on storefront")
+  isPublished: z39.boolean().describe("Whether article is visible on storefront")
 });
 var handleUpdateArticle = async (context, params) => {
   log.debug(`Updating article on shop: ${context.shopDomain}`);
@@ -7667,13 +8540,20 @@ function registerUpdateArticleTool() {
       name: "update-article",
       title: "Update Article",
       description: "Update an existing article's attributes. You can update title, body content (HTML), summary, author, tags, featured image, publish status, and template suffix. Only provided fields are updated; others remain unchanged. Use redirectNewHandle: true when changing handles. Useful for: editing content, adding tags, publishing/unpublishing articles. **Typical workflow:** list-articles \u2192 update-article. **Prerequisites:** Article ID. **Follow-ups:** list-articles. Returns the updated article object.",
-      inputSchema: inputSchema33,
-      outputSchema: outputSchema33,
+      inputSchema: inputSchema37,
+      outputSchema: outputSchema37,
       category: "content",
       relationships: {
         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
@@ -7681,30 +8561,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 z40 } from "zod";
+var inputSchema38 = z40.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: z40.string().optional().describe("The new title for the blog. Only provided if changing the title."),
+  handle: z40.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: z40.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: z40.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: z40.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 outputSchema38 = z40.object({
+  id: z40.string().describe("Updated blog GID"),
+  title: z40.string().describe("Blog title"),
+  handle: z40.string().describe("URL handle/slug"),
+  commentPolicy: z40.enum(["CLOSED", "MODERATE", "OPEN"]).describe("Comment moderation policy")
 });
 var handleUpdateBlog = async (context, params) => {
   log.debug(`Updating blog on shop: ${context.shopDomain}`);
@@ -7747,13 +8627,20 @@ function registerUpdateBlogTool() {
       name: "update-blog",
       title: "Update Blog",
       description: "Update an existing blog's attributes. You can update title, handle (URL slug), comment policy (CLOSED, MODERATE, OPEN), and template suffix. Only provided fields are updated; others remain unchanged. Use redirectNewHandle: true when changing handles. Useful for: renaming blogs, changing comment settings, updating templates. **Typical workflow:** list-blogs \u2192 update-blog. **Prerequisites:** Blog ID. **Follow-ups:** list-blogs. Returns the updated blog object.",
-      inputSchema: inputSchema34,
-      outputSchema: outputSchema34,
+      inputSchema: inputSchema38,
+      outputSchema: outputSchema38,
       category: "content",
       relationships: {
         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
@@ -7761,21 +8648,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 z41 } from "zod";
+var inputSchema39 = z41.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: z41.string().min(1).optional().describe("New collection title"),
+  handle: z41.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: z41.string().optional().describe("New HTML description"),
+  seo: z41.object({
+    title: z41.string().optional().describe("New SEO title"),
+    description: z41.string().optional().describe("New SEO meta description")
   }).optional().describe("Updated SEO metadata"),
-  sortOrder: z36.enum([
+  sortOrder: z41.enum([
     "ALPHA_ASC",
     "ALPHA_DESC",
     "BEST_SELLING",
@@ -7785,19 +8672,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: z41.object({
+    src: z41.string().url().describe("New image URL (publicly accessible)"),
+    altText: z41.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: z41.string().optional().describe("New Liquid template suffix"),
+  redirectNewHandle: z41.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 outputSchema39 = z41.object({
+  id: z41.string().describe("Updated collection GID"),
+  title: z41.string().describe("Collection title"),
+  handle: z41.string().describe("Collection URL handle")
 });
 var handleUpdateCollection = async (context, params) => {
   log.debug(`Updating collection on shop: ${context.shopDomain}`);
@@ -7836,14 +8723,22 @@ function registerUpdateCollectionTool() {
       name: "update-collection",
       title: "Update Collection",
       description: "Update an existing collection's attributes. Any field can be updated including title, handle, description, SEO fields, sort order, and image. When changing the handle, set redirectNewHandle: true for automatic URL redirect (important for SEO). Only provided fields are modified; omitted fields remain unchanged. **Prerequisites:** get-collection to view current values before updating. **Follow-ups:** add-products-to-collection, remove-products-from-collection.",
-      inputSchema: inputSchema35,
-      outputSchema: outputSchema35,
+      inputSchema: inputSchema39,
+      outputSchema: outputSchema39,
       // AI Agent Optimization (Story 5.5)
       category: "collection",
       relationships: {
         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
@@ -7851,8 +8746,8 @@ function registerUpdateCollectionTool() {
 }
 
 // src/tools/update-inventory.ts
-import { z as z37 } from "zod";
-var inventoryReasonEnum = z37.enum([
+import { z as z42 } from "zod";
+var inventoryReasonEnum = z42.enum([
   "correction",
   "cycle_count_available",
   "damaged",
@@ -7871,20 +8766,20 @@ var inventoryReasonEnum = z37.enum([
   "safety_stock",
   "shrinkage"
 ]);
-var inputSchema36 = z37.object({
-  inventoryItemId: z37.string().min(1).describe(
+var inputSchema40 = z42.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: z42.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: z42.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: z42.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(
@@ -7895,16 +8790,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 outputSchema40 = z42.object({
+  success: z42.boolean().describe("Whether the operation succeeded"),
+  inventoryItemId: z42.string().describe("Inventory item GID"),
+  locationId: z42.string().describe("Location GID where inventory was updated"),
+  locationName: z42.string().describe("Human-readable location name"),
+  previousQuantity: z42.number().describe("Quantity before the change"),
+  newQuantity: z42.number().describe("Quantity after the change"),
+  delta: z42.number().describe("The actual change applied (positive or negative)"),
+  name: z42.string().describe("Which quantity was modified (available or on_hand)"),
+  reason: z42.string().describe("Reason for the adjustment")
 });
 var handleUpdateInventory = async (context, params) => {
   log.debug(`Updating inventory on shop: ${context.shopDomain}`);
@@ -7978,47 +8873,113 @@ function registerUpdateInventoryTool() {
       name: "update-inventory",
       title: "Update Inventory",
       description: 'Update inventory quantity at a specific location. Use setQuantity for absolute values (e.g., setting stock to 50 after a count) or adjustQuantity for relative changes (e.g., +10 for received stock, -5 for shrinkage). Requires inventoryItemId (from get-inventory or get-product) and locationId (from get-inventory). Common reasons: "correction" (default), "received" (new stock), "shrinkage" (loss/theft), "damaged", "cycle_count_available" (stock take). Pre-validates that adjustments will not result in negative inventory. **Typical workflow:** get-inventory \u2192 update-inventory \u2192 get-inventory (to verify). **Prerequisites:** Inventory Item ID, Location ID. **Follow-ups:** get-inventory. Returns before/after quantities with delta.',
-      inputSchema: inputSchema36,
-      outputSchema: outputSchema36,
+      inputSchema: inputSchema40,
+      outputSchema: outputSchema40,
       category: "inventory",
       relationships: {
         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
   );
 }
 
+// src/tools/update-market.ts
+import { z as z43 } from "zod";
+var inputSchema41 = z43.object({
+  id: marketIdSchema.describe(
+    'Shopify Market GID to update (e.g., "gid://shopify/Market/123"). Use list-markets to find market IDs.'
+  ),
+  name: z43.string().min(1).optional().describe("New market name"),
+  handle: z43.string().optional().describe("New URL handle/slug for the market"),
+  enabled: z43.boolean().optional().describe("Whether the market should be enabled")
+});
+var outputSchema41 = z43.object({
+  id: z43.string().describe("Updated market GID"),
+  name: z43.string().describe("Market name"),
+  handle: z43.string().describe("URL handle"),
+  enabled: z43.boolean().describe("Whether the market is enabled")
+});
+var handleUpdateMarket = async (context, params) => {
+  log.debug(`Updating market ${params.id} on shop: ${context.shopDomain}`);
+  const input = {};
+  if (params.name !== void 0) {
+    input.name = params.name;
+  }
+  if (params.handle !== void 0) {
+    input.handle = params.handle;
+  }
+  if (params.enabled !== void 0) {
+    input.enabled = params.enabled;
+  }
+  const market = await updateMarket(params.id, input);
+  log.debug(`Updated market: ${market.id}`);
+  return market;
+};
+function registerUpdateMarketTool() {
+  registerContextAwareTool(
+    {
+      name: "update-market",
+      title: "Update Market",
+      description: "Update an existing market's properties. Only provided fields are updated; omitted fields remain unchanged. Can update: name, handle, enabled status. **Prerequisites:** get-market to view current values before updating. **Follow-ups:** get-market (to verify), delete-market.",
+      inputSchema: inputSchema41,
+      outputSchema: outputSchema41,
+      // AI Agent Optimization
+      category: "market",
+      relationships: {
+        relatedTools: ["get-market", "list-markets"],
+        followUps: ["get-market", "delete-market"]
+      },
+      // MCP Tool Annotations (Epic 9.5 - MCP Best Practices)
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        // Same update with same values produces same result
+        openWorldHint: true
+      }
+    },
+    handleUpdateMarket
+  );
+}
+
 // src/tools/update-page.ts
-import { z as z38 } from "zod";
-var inputSchema37 = z38.object({
-  id: z38.string().min(1).describe(
+import { z as z44 } from "zod";
+var inputSchema42 = z44.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: z44.string().optional().describe("The new title for the page. Only provide if you want to change it."),
+  body: z44.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: z44.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: z44.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: z44.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: z44.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 outputSchema42 = z44.object({
+  id: z44.string().describe("Updated page GID"),
+  title: z44.string().describe("Page title"),
+  handle: z44.string().describe("URL handle/slug"),
+  isPublished: z44.boolean().describe("Whether page is visible on storefront")
 });
 var handleUpdatePage = async (context, params) => {
   log.debug(`Updating page on shop: ${context.shopDomain}`);
@@ -8062,13 +9023,20 @@ function registerUpdatePageTool() {
       name: "update-page",
       title: "Update Page",
       description: "Update an existing page's attributes. You can update title, body content (HTML), handle (URL slug), publish status, and template suffix. Only provided fields are updated; others remain unchanged. Use redirectNewHandle: true when changing handles to preserve SEO. Useful for: editing content, publishing/unpublishing pages, changing URLs. **Typical workflow:** get-page \u2192 update-page. **Prerequisites:** Page ID. **Follow-ups:** get-page. Returns the updated page object.",
-      inputSchema: inputSchema37,
-      outputSchema: outputSchema37,
+      inputSchema: inputSchema42,
+      outputSchema: outputSchema42,
       category: "content",
       relationships: {
         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
@@ -8076,7 +9044,7 @@ function registerUpdatePageTool() {
 }
 
 // src/tools/update-product-image.ts
-import { z as z39 } from "zod";
+import { z as z45 } from "zod";
 var FILE_UPDATE_MUTATION = `
   mutation FileUpdate($files: [FileUpdateInput!]!) {
     fileUpdate(files: $files) {
@@ -8096,18 +9064,18 @@ var FILE_UPDATE_MUTATION = `
     }
   }
 `;
-var inputSchema38 = z39.object({
-  imageId: z39.string().min(1).describe(
+var inputSchema43 = z45.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: z45.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 outputSchema43 = z45.object({
+  id: z45.string().describe('Image GID (e.g., "gid://shopify/MediaImage/123")'),
+  url: z45.string().nullable().describe("Shopify CDN URL for the image"),
+  altText: z45.string().nullable().describe("Updated alt text for the image")
 });
 var handleUpdateProductImage = async (context, params) => {
   log.debug(`Updating image alt text on shop: ${context.shopDomain}`);
@@ -8166,14 +9134,22 @@ function registerUpdateProductImageTool() {
       name: "update-product-image",
       title: "Update Product Image",
       description: "Update the alt text of a product image for SEO and accessibility. Alt text describes the image for screen readers and helps search engines understand image content. Pass an empty string to clear alt text. **Typical workflow:** add-product-image \u2192 update-product-image (set alt text). **Prerequisites:** add-product-image or get-product to find image IDs. **Follow-ups:** reorder-product-images.",
-      inputSchema: inputSchema38,
-      outputSchema: outputSchema38,
+      inputSchema: inputSchema43,
+      outputSchema: outputSchema43,
       // AI Agent Optimization (Story 5.5)
       category: "media",
       relationships: {
         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
@@ -8181,19 +9157,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 z46 } from "zod";
+var inputSchema44 = z46.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: z46.string().optional().describe('New variant price as decimal string (e.g., "29.99")'),
+  compareAtPrice: z46.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: z46.string().nullable().optional().describe("Barcode (UPC, EAN, ISBN, etc.). Set to null to remove.")
 }).refine(
   (data) => {
     const { productId: _productId, id: _id, ...updateFields } = data;
@@ -8201,14 +9177,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 outputSchema44 = z46.object({
+  id: z46.string().describe('Variant GID (e.g., "gid://shopify/ProductVariant/123")'),
+  title: z46.string().describe('Variant title (e.g., "Red / Medium")'),
+  price: z46.string().describe("Current price as decimal string"),
+  compareAtPrice: z46.string().nullable().describe("Compare at price for sale display"),
+  sku: z46.string().nullable().describe("Stock keeping unit"),
+  barcode: z46.string().nullable().describe("Barcode (UPC, EAN, etc.)"),
+  inventoryQuantity: z46.number().nullable().describe("Available inventory quantity")
 });
 var handleUpdateProductVariant = async (context, params) => {
   log.debug(`Updating product variant on shop: ${context.shopDomain}`);
@@ -8237,13 +9213,21 @@ function registerUpdateProductVariantTool() {
       name: "update-product-variant",
       title: "Update Product Variant",
       description: 'Update an existing product variant in the Shopify store. Requires BOTH productId and variant id (GID format). Only provided fields are updated; others remain unchanged. Supports updating: price, compareAtPrice (for sale pricing), barcode. Returns the updated variant with all current details. To show sale pricing, set compareAtPrice higher than price (e.g., compareAtPrice: "39.99", price: "24.99"). **Prerequisites:** get-product to obtain productId and variant IDs. **Note:** SKU updates require separate inventory API calls.',
-      inputSchema: inputSchema39,
-      outputSchema: outputSchema39,
+      inputSchema: inputSchema44,
+      outputSchema: outputSchema44,
       // AI Agent Optimization (Story 5.5)
       category: "product",
       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
@@ -8251,23 +9235,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 z47 } from "zod";
+var inputSchema45 = z47.object({
+  id: productIdSchema.describe(
+    'Shopify product ID (GID format, e.g., "gid://shopify/Product/123"). Required.'
+  ),
+  title: z47.string().min(1).optional().describe("New product title"),
+  description: z47.string().optional().describe("New product description (HTML supported)"),
+  vendor: z47.string().optional().describe("New product vendor/brand name"),
+  productType: z47.string().optional().describe("New product type for categorization"),
+  tags: z47.array(z47.string()).optional().describe("New tags (replaces existing tags)"),
+  status: z47.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).optional().describe("New product status: ACTIVE (visible), DRAFT (hidden), ARCHIVED (hidden)"),
+  seo: z47.object({
+    title: z47.string().optional().describe("SEO title for search engine results"),
+    description: z47.string().optional().describe("SEO meta description for search engines")
   }).optional().describe("SEO metadata for search engine optimization"),
-  handle: z41.string().optional().describe(
+  handle: z47.string().optional().describe(
     'New URL handle/slug (e.g., "my-product"). Use with redirectNewHandle for URL changes.'
   ),
-  redirectNewHandle: z41.boolean().optional().describe(
+  redirectNewHandle: z47.boolean().optional().describe(
     "If true, creates automatic redirect from old handle to new handle. Use when changing handle."
   )
 }).refine(
@@ -8277,40 +9263,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 outputSchema45 = z47.object({
+  id: z47.string().describe('Product GID (e.g., "gid://shopify/Product/123")'),
+  title: z47.string().describe("Product title"),
+  handle: z47.string().describe("URL handle/slug"),
+  description: z47.string().nullable().describe("Product description (HTML)"),
+  vendor: z47.string().describe("Vendor/brand name"),
+  productType: z47.string().describe("Product type"),
+  status: z47.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).describe("Product status"),
+  tags: z47.array(z47.string()).describe("Product tags"),
+  seo: z47.object({
+    title: z47.string().nullable().describe("SEO title for search engines"),
+    description: z47.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: z47.string().describe("Creation timestamp (ISO 8601)"),
+  updatedAt: z47.string().describe("Last update timestamp (ISO 8601)"),
+  variants: z47.array(
+    z47.object({
+      id: z47.string().describe("Variant GID"),
+      title: z47.string().describe("Variant title"),
+      price: z47.string().describe("Price"),
+      compareAtPrice: z47.string().nullable().describe("Compare at price"),
+      sku: z47.string().nullable().describe("SKU"),
+      barcode: z47.string().nullable().describe("Barcode"),
+      inventoryQuantity: z47.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: z47.array(
+    z47.object({
+      id: z47.string().describe("Image GID"),
+      url: z47.string().describe("Image URL"),
+      altText: z47.string().nullable().describe("Alt text")
     })
   ).describe("Product images"),
-  totalInventory: z41.number().describe("Total inventory across variants")
+  totalInventory: z47.number().describe("Total inventory across variants")
 });
 var handleUpdateProduct = async (context, params) => {
   log.debug(`Updating product on shop: ${context.shopDomain}`);
@@ -8339,14 +9325,22 @@ function registerUpdateProductTool() {
       name: "update-product",
       title: "Update Product",
       description: "Update an existing product in the Shopify store. Requires the product ID (GID format). Only provided fields are updated; others remain unchanged. Supports updating: title, description, vendor, productType, tags, status, SEO metadata (seo.title, seo.description), and URL handle. Use handle + redirectNewHandle=true to change URLs with automatic redirect. Returns the updated product with all current details including SEO. **Prerequisites:** get-product to view current values before updating. **Follow-ups:** add-product-image, set-product-metafields.",
-      inputSchema: inputSchema40,
-      outputSchema: outputSchema40,
+      inputSchema: inputSchema45,
+      outputSchema: outputSchema45,
       // AI Agent Optimization (Story 5.5)
       category: "product",
       relationships: {
         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
@@ -8362,7 +9356,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
       }))
     };
   });
@@ -8447,6 +9443,11 @@ function registerAllTools(server) {
   registerGetInventoryTool();
   registerListLowInventoryTool();
   registerUpdateInventoryTool();
+  registerCreateMarketTool();
+  registerDeleteMarketTool();
+  registerGetMarketTool();
+  registerListMarketsTool();
+  registerUpdateMarketTool();
   const toolCount = getRegisteredTools().length;
   log.debug(`Tool registration complete: ${toolCount} tools registered`);
 }