adding-tools

Adding New Tools

Decision: Smart Tool vs GraphQL Query?

Use run_graphql_query when:

• Single API call
• Standard CRUD operation
• Agent can handle the response

Create a Smart Tool when:

• Multiple API calls needed
• Polling/async operations
• Complex orchestration
• Response needs transformation

Creating a Smart Tool

1. Create the tool file

// src/tools/smart-example.ts
import { z } from "zod";
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import type { AdminApiClient } from "../shopify-client.js";
import {
  formatSuccessResponse,
  formatErrorResponse,
  formatGraphQLErrors,
} from "../errors.js";
import { enqueue } from "../queue.js";
import { logOperation } from "../logger.js";

export function registerSmartExampleTools(
  server: McpServer,
  client: AdminApiClient,
  storeDomain: string
): void {
  server.registerTool(
    "smart_example",
    {
      title: "Smart Example Tool",
      description:
        "Describe what this tool does, when to use it, and what it returns. " +
        "Be specific about the workflow it handles.",
      inputSchema: {
        requiredParam: z.string().describe("What this parameter does"),
        optionalParam: z.number().optional().describe("Optional parameter"),
      },
      annotations: {
        readOnlyHint: false,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },
    async ({ requiredParam, optionalParam }) => {
      const startTime = Date.now();

      try {
        // Step 1: First API call
        const step1 = await enqueue(() =>
          client.request(QUERY_1, { variables: { requiredParam } })
        );

        if (step1.errors) {
          return formatGraphQLErrors(step1);
        }

        // Step 2: Process and make second call
        const step2 = await enqueue(() =>
          client.request(QUERY_2, { variables: { id: step1.data.id } })
        );

        // Log the operation
        await logOperation({
          storeDomain,
          toolName: "smart_example",
          operationType: "mutation",
          query: "smart_example workflow",
          variables: { requiredParam, optionalParam },
          response: step2.data,
          success: true,
          durationMs: Date.now() - startTime,
        });

        return formatSuccessResponse({
          result: step2.data,
          stepsCompleted: 2,
        });
      } catch (error) {
        return formatErrorResponse(error);
      }
    }
  );
}