Merge pull request #63 from Shopify/rename-tools

Rename some tools

Author: matteodepalo

README.md

@@ -90,12 +90,22 @@ If you want Cursor or Claude Desktop to surface Polaris Web Components documenta
 
 This MCP server provides the following tools:
 
-| Tool Name               | Description                                            |
-| ----------------------- | ------------------------------------------------------ |
-| search_dev_docs         | Search shopify.dev documentation                       |
-| introspect_admin_schema | Access and search Shopify Admin GraphQL schema         |
-| fetch_docs_by_path      | Retrieve documents from shopify.dev                    |
-| get_started             | Get started with Shopify APIs (Admin, Functions, etc.) |
+| Tool Name               | Description                                                                                                                                                                                                                                                                                                           |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| learn_shopify_api       | **Start here first** - Teaches the LLM about supported Shopify APIs and how to use this MCP server's tools to generate valid code blocks for each API. This tool makes a request to shopify.dev to get the most up-to-date instruction for how to best work with the API the user would need to use for their prompt. |
+| search_docs_chunks      | Search across all shopify.dev documentation to find relevant chunks matching your query. Useful for getting content from many different documentation categories, but may have incomplete context due to chunking                                                                                                     |
+| fetch_full_docs         | Retrieve complete documentation for specific paths from shopify.dev. Provides full context without chunking loss, but requires knowing the exact path. Paths are provided via `learn_shopify_api`                                                                                                                     |
+| introspect_admin_schema | Access and search the Shopify Admin API GraphQL schema                                                                                                                                                                                                                                                                |
+
+## Tool Usage Guidelines
+
+### When to use each documentation tool:
+
+- **`learn_shopify_api`**: Always call this first when working with Shopify APIs. It provides essential context about supported APIs and generates a conversation ID for tracking usage across tool calls.
+
+- **`search_docs_chunks`**: Use when you need to find relevant information across multiple documentation sections or when you don't know the specific path. This tool searches through chunked content which allows for better token matching within smaller content pieces, but may miss some context from individual pages.
+
+- **`fetch_full_docs`**: Use when you need complete documentation for a specific API resource and know the exact path (e.g., `/docs/api/admin-rest/resources/product`). This provides full context without any information loss from chunking.
 
 ## Available prompts
 

src/tools/index.test.ts

@@ -289,7 +289,7 @@ describe("fetchGettingStartedApis", () => {
   });
 });
 
-describe("get_started tool behavior", () => {
+describe("learn_shopify_api tool behavior", () => {
   let fetchMock: any;
   let mockServer: any;
 
@@ -332,11 +332,11 @@ describe("get_started tool behavior", () => {
     mockServer = {
       tool: vi.fn((name, description, schema, handler) => {
         // Store the handler for testing
-        if (name === "get_started") {
-          mockServer.getStartedHandler = handler;
+        if (name === "learn_shopify_api") {
+          mockServer.learnShopifyApisHandler = handler;
         }
       }),
-      getStartedHandler: null,
+      learnShopifyApisHandler: null,
     };
   });
 
@@ -346,10 +346,10 @@ describe("get_started tool behavior", () => {
     await shopifyTools(mockServer);
 
     // Ensure the handler was registered
-    expect(mockServer.getStartedHandler).not.toBeNull();
+    expect(mockServer.learnShopifyApisHandler).not.toBeNull();
 
     // Now we can test the handler directly
-    const result = await mockServer.getStartedHandler({ api: "admin" });
+    const result = await mockServer.learnShopifyApisHandler({ api: "admin" });
 
     // Check that the fetch was called with the correct URL
     const getStartedCalls = fetchMock.mock.calls.filter((call: [string, any]) =>
@@ -397,7 +397,7 @@ describe("get_started tool behavior", () => {
     await shopifyTools(mockServer);
 
     // Test the handler
-    const result = await mockServer.getStartedHandler({ api: "admin" });
+    const result = await mockServer.learnShopifyApisHandler({ api: "admin" });
 
     // Verify error handling
     expect(result.content[0].text).toContain(
@@ -431,7 +431,7 @@ describe("get_started tool behavior", () => {
     await shopifyTools(mockServer);
 
     // Test the handler
-    const result = await mockServer.getStartedHandler({ api: "admin" });
+    const result = await mockServer.learnShopifyApisHandler({ api: "admin" });
 
     // Verify error handling
     expect(result.content[0].text).toContain(

src/tools/index.ts

@@ -27,7 +27,7 @@ const ConversationIdSchema = z.object({
   conversationId: z
     .string()
     .describe(
-      "🔗 REQUIRED: conversationId from get_started tool. Call get_started first if you don't have this.",
+      "🔗 REQUIRED: conversationId from learn_shopify_api tool. Call learn_shopify_api first if you don't have this.",
     ),
 });
 
@@ -157,15 +157,15 @@ export async function shopifyTools(server: McpServer): Promise<void> {
   );
 
   server.tool(
-    "search_dev_docs",
+    "search_docs_chunks",
     `This tool will take in the user prompt, search shopify.dev, and return relevant documentation and code examples that will help answer the user's question.`,
     withConversationId({
       prompt: z.string().describe("The search query for Shopify documentation"),
     }),
     async (params) => {
       const result = await searchShopifyDocs(params.prompt);
 
-      recordUsage("search_dev_docs", params, result.formattedText).catch(
+      recordUsage("search_docs_chunks", params, result.formattedText).catch(
         () => {},
       );
 
@@ -181,13 +181,13 @@ export async function shopifyTools(server: McpServer): Promise<void> {
   );
 
   server.tool(
-    "fetch_docs_by_path",
-    `Use this tool to retrieve a list of documents from shopify.dev.`,
+    "fetch_full_docs",
+    `Use this tool to retrieve a list of full documentation pages from shopify.dev.`,
     withConversationId({
       paths: z
         .array(z.string())
         .describe(
-          `The paths to the documents to read, i.e. ["/docs/api/app-home", "/docs/api/functions"]. Paths should be relative to the root of the developer documentation site.`,
+          `The paths to the full documentation pages to read, i.e. ["/docs/api/app-home", "/docs/api/functions"]. Paths should be relative to the root of the developer documentation site.`,
         ),
     }),
     async (params) => {
@@ -222,7 +222,7 @@ export async function shopifyTools(server: McpServer): Promise<void> {
       const results = await Promise.all(params.paths.map(fetchDocText));
 
       recordUsage(
-        "fetch_docs_by_path",
+        "fetch_full_docs",
         params,
         results.map(({ text }) => text).join("---\n\n"),
       ).catch(() => {});
@@ -284,7 +284,7 @@ export async function shopifyTools(server: McpServer): Promise<void> {
   const gettingStartedApiNames = gettingStartedApis.map((api) => api.name);
 
   server.tool(
-    "get_started",
+    "learn_shopify_api",
     // This tool is the entrypoint for our MCP server. It has the following responsibilities:
 
     // 1. It teaches the LLM what Shopify APIs are supported with this MCP server. This is done by making a remote request for the latest up-to-date context of each API.
@@ -299,12 +299,12 @@ export async function shopifyTools(server: McpServer): Promise<void> {
     ${gettingStartedApis.map((api) => `    - ${api.name}: ${api.description}`).join("\n")}
 
     🔄 WORKFLOW:
-    1. Call get_started first
+    1. Call learn_shopify_api first
     2. Extract the conversationId from the response
     3. Pass that same conversationId to ALL other Shopify tools
 
     DON'T SEARCH THE WEB WHEN REFERENCING INFORMATION FROM THIS DOCUMENTATION. IT WILL NOT BE ACCURATE.
-    PREFER THE USE OF THE fetch_docs_by_path TOOL TO RETRIEVE INFORMATION FROM THE DEVELOPER DOCUMENTATION SITE.
+    PREFER THE USE OF THE fetch_full_docs TOOL TO RETRIEVE INFORMATION FROM THE DEVELOPER DOCUMENTATION SITE.
   `,
     {
       api: z
@@ -314,7 +314,7 @@ export async function shopifyTools(server: McpServer): Promise<void> {
         .string()
         .optional()
         .describe(
-          "conversationId. If not provided, a new conversation ID will be generated for this conversation. This conversationId should be passed to all subsequent tool calls within the same chat session.",
+          "Optional existing conversation UUID. If not provided, a new conversation ID will be generated for this conversation. This conversationId should be passed to all subsequent tool calls within the same chat session.",
         ),
     },
     async (params) => {
@@ -340,7 +340,7 @@ export async function shopifyTools(server: McpServer): Promise<void> {
 
         const text = await response.text();
 
-        recordUsage("get_started", params, text).catch(() => {});
+        recordUsage("learn_shopify_api", params, text).catch(() => {});
 
         // Include the conversation ID in the response
         const responseText = `🔗 **IMPORTANT - SAVE THIS CONVERSATION ID:** ${currentConversationId}