Adding a New Tool

This guide walks through the process of adding a new MCP tool to the chat commerce system.

Step 1: Write the YAML Spec

Create a new YAML file in specs/tools/{category}/ following the standard format:

name: my_new_tool
category: cart                    # product, cart, order, user, display, app_context
description: Technical description of what this tool does
plain_english: >
  Non-technical description for product owners and BAs.
  Explain what the customer experiences, not how it works.

parameters:
  - name: param_name
    type: string                  # string, integer, boolean, number
    required: true
    description: What this parameter is for

  - name: optional_param
    type: integer
    required: false
    default: 10
    description: Optional parameter with default

response:
  fields:
    - name: result_field
      type: string
      description: What this field contains

platforms:
  ios:
    status: planned               # implemented, planned, not_applicable
    file: ""
    notes: ""
  android:
    status: planned
    file: ""
    notes: ""

errors:
  - code: ERROR_CODE
    description: When this error occurs

requires_auth: true               # Does the user need to be signed in?

Step 2: Submit a Pull Request

1. Create a branch: feature/tool-{tool_name}
2. Add the YAML spec file
3. Run npm run validate to check the spec is valid
4. Run npm run generate to preview the generated docs
5. Open a PR — product owners and developers review together

The PR diff on a YAML file is easy for everyone to review:

• BAs/POs review the plain_english description and parameters
• Developers review the response schema, errors, and technical description

Step 3: Implement on Each Platform

Once the spec PR is merged, implement the tool in each app:

iOS Implementation

1. Add tool definition in EcommerceMCPServer.swift → listTools():

   mcpTool("my_new_tool", description: "...") {
       $0.stringParam("param_name", description: "...", required: true)
   }

2. Add handler in executeTool(call:):

   case "my_new_tool":
       return try await executeMyNewTool(call: call)

3. Implement the handler as a private method

Android Implementation

1. Add tool definition in EcommerceMCPTools.kt:

   val MY_NEW_TOOL = mcpTool("my_new_tool") {
       description("...")
       stringParam("param_name", "...", required = true)
   }

2. Register handler in EcommerceMCPServerImpl.kt:

   registerTool(EcommerceMCPTools.MY_NEW_TOOL, ::handleMyNewTool)

3. Implement the handler

Update the Spec

Once implemented, update the YAML spec's platform status:

platforms:
  ios:
    status: implemented
    file: one-app-ios-chat/Chat/Sources/Chat/MCP/EcommerceMCPServer.swift
  android:
    status: implemented
    file: chat-pnp-android/mcp-ecommerce/.../EcommerceMCPTools.kt

Step 4: Update Documentation

Run npm run generate to regenerate the docs with the updated platform status, then commit the result.

Naming Conventions

• Tool names use snake_case: search_products, add_to_cart
• Categories: product, cart, order, user, display, app_context
• Error codes use UPPER_SNAKE_CASE: AUTH_REQUIRED, INVALID_PARAMS
• Parameters use snake_case: product_code, entry_guid

Checklist

• YAML spec written with plain_english description
• npm run validate passes
• PR reviewed by both product and engineering
• Implemented on iOS
• Implemented on Android
• Platform status updated in YAML
• npm run generate run and docs committed