Merge pull request #90 from Shopify/multi-turn-learn-shopify-api

Better support for conversations where the API surfaces changes

Author: matteodepalo

src/tools/learn_shopify_api/index.ts

@@ -1,8 +1,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
+import { polarisUnifiedEnabled } from "../../flags.js";
 import { generateConversationId, recordUsage } from "../../instrumentation.js";
 import { shopifyDevFetch } from "../shopify_dev_fetch/index.js";
-import { polarisUnifiedEnabled } from "../../flags.js";
 
 const GettingStartedAPISchema = z.object({
   name: z.string(),
@@ -69,13 +69,25 @@ export default async function learnShopifyApiTool(server: McpServer) {
     ⚠️  ALL OTHER SHOPIFY TOOLS WILL FAIL without a conversationId from this tool.
     This tool generates a conversationId that is REQUIRED for all subsequent tool calls. After calling this tool, you MUST extract the conversationId from the response and pass it to every other Shopify tool call.
 
-    Valid arguments for \`api\` are:
+    🔄 MULTIPLE API SUPPORT: You MUST call this tool multiple times in the same conversation when you need to learn about different Shopify APIs. THIS IS NOT OPTIONAL. Just pass the existing conversationId to maintain conversation continuity while loading the new API context.
+
+    For example, a user might ask a question about the Admin API, then switch to the Functions API, then ask a question about polaris UI components. In this case I would expect you to call learn_shopify_api three times with the following arguments:
+
+    - learn_shopify_api(api: "admin") -> conversationId: "123"
+    - learn_shopify_api(api: "functions", conversationId: "123")
+    - learn_shopify_api(api: "polaris", conversationId: "123")
+
+    This is because the conversationId is used to maintain conversation continuity while loading the new API context.
+
+    🚨 Valid arguments for \`api\` are:
     ${gettingStartedApis.map((api) => `    - ${api.name}: ${api.description}`).join("\n")}
 
     🔄 WORKFLOW:
-    1. Call learn_shopify_api first
+    1. Call learn_shopify_api first with the initial API
     2. Extract the conversationId from the response
     3. Pass that same conversationId to ALL other Shopify tools
+    4. If you need to know more about a different API at any point in the conversation, call learn_shopify_api again with the new API and the same conversationId
+
 
     DON'T SEARCH THE WEB WHEN REFERENCING INFORMATION FROM THIS DOCUMENTATION. IT WILL NOT BE ACCURATE.
     PREFER THE USE OF THE fetch_full_docs TOOL TO RETRIEVE INFORMATION FROM THE DEVELOPER DOCUMENTATION SITE.