clawdbot-workspace/mcp-factory-v3/templates/AGENT-PROMPT-TOOLS.md

Tool Build Agent Prompt

Build ALL tool files for the {{NAME}} MCP server at {{DIR}}.

Foundation Already Exists

• src/types/index.ts — TypeScript interfaces
• src/clients/{{NAME}}.ts — API client with retry, pagination, rate limiting
• src/server.ts — Server shell with lazy loading
• src/main.ts — Entry point

DO NOT modify these files. Only ADD tool files.

Tool Categories to Build

{{TOOL_CATEGORIES}}

Quality Requirements for Each Tool File

Structure

import { z } from 'zod';
import { {{PascalName}}Client } from '../clients/{{NAME}}.js';
import type { ToolDefinition } from '../server.js';

// Input schemas with Zod
const ListCustomersInput = z.object({
  limit: z.number().min(1).max(100).default(25).describe('Results per page'),
  offset: z.number().min(0).default(0).describe('Pagination offset'),
  search: z.string().optional().describe('Search by name or email'),
  sort_by: z.enum(['name', 'created_at', 'updated_at']).default('created_at'),
  sort_order: z.enum(['asc', 'desc']).default('desc'),
});

// Tool definitions
export function getTools(client: {{PascalName}}Client): ToolDefinition[] {
  return [
    {
      name: '{{name}}_list_customers',
      description: 'List customers with pagination, search, and sorting',
      inputSchema: ListCustomersInput,
      handler: async (input) => {
        const validated = ListCustomersInput.parse(input);
        const results = await client.paginate('/customers', validated);
        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
      }
    },
    // ... more tools
  ];
}

Each Tool MUST Have

• Zod input schema — with .describe() on every field
• Pagination params — limit/offset or cursor for list operations
• Search/filter — where the API supports it
• Error handling — catch and return meaningful error messages
• Consistent naming — {{name}}_verb_noun format (e.g., shopify_list_orders)

Tool Count Targets

• Each category: 4-8 tools (CRUD + search + bulk where applicable)
• Total per server: 40-60+ tools
• Every tool must be useful — no filler

Common Patterns Per Category

• list_* — paginated list with filters
• get_* — single item by ID
• create_* — create with validated input
• update_* — partial update by ID
• delete_* — delete by ID
• search_* — full-text or field search
• bulk_* — batch operations where API supports

Rules

• DO NOT modify existing files
• DO NOT create app files
• Run npx tsc --noEmit to verify everything compiles
• Commit when done