add-tool— agent skill

Context

Tools use the tool() builder from @cyanheads/mcp-ts-core. Each tool lives in src/mcp-server/tools/definitions/ with a .tool.ts suffix and is registered in the barrel index.ts.

For the full tool() API, Context interface, and error codes, read:

node_modules/@cyanheads/mcp-ts-core/CLAUDE.md

Steps

1. Ask the user for the tool's name, purpose, and input/output shape
2. Determine if long-running — if the tool involves streaming, polling, or

multi-step async work, it should use task: true

1. Create the file at src/mcp-server/tools/definitions/{{tool-name}}.tool.ts
2. Register the tool in src/mcp-server/tools/definitions/index.ts
3. Run `bun run devcheck` to verify
4. Smoke-test with bun run dev:stdio or dev:http

Template

/**
 * @fileoverview {{TOOL_DESCRIPTION}}
 * @module mcp-server/tools/definitions/{{TOOL_NAME}}
 */

import { tool, z } from '@cyanheads/mcp-ts-core';

export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
  title: '{{TOOL_TITLE}}',
  description: '{{TOOL_DESCRIPTION}}',
  annotations: { readOnlyHint: true },
  input: z.object({
    // All fields need .describe(). Only JSON-Schema-serializable Zod types allowed.
  }),
  output: z.object({
    // All fields need .describe(). Only JSON-Schema-serializable Zod types allowed.
  }),
  // auth: ['tool:{{tool_name}}:read'],

  async handler(input, ctx) {
    ctx.log.info('Processing', { /* relevant input fields */ });
    // Pure logic — throw on failure, no try/catch
    return { /* output */ };
  },

  format: (result) => [{ type: 'text', text: JSON.stringify(result, null, 2) }],
});

Task tool variant

Add task: true and use ctx.progress for long-running operations:

export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
  description: '{{TOOL_DESCRIPTION}}',
  task: true,
  input: z.object({ /* ... */ }),
  output: z.object({ /* ... */ }),

  async handler(input, ctx) {
    await ctx.progress!.setTotal(totalSteps);
    for (const step of steps) {
      if (ctx.signal.aborted) break;
      await ctx.progress!.update(`Processing: ${step}`);
      // ... do work ...
      await ctx.progress!.increment();
    }
    return { /* output */ };
  },
});

Barrel registration

// src/mcp-server/tools/definitions/index.ts
import { existingTool } from './existing-tool.tool.js';
import { {{TOOL_EXPORT}} } from './{{tool-name}}.tool.js';

export const allToolDefinitions = [
  existingTool,
  {{TOOL_EXPORT}},
];

Checklist

• [ ] File created at src/mcp-server/tools/definitions/{{tool-name}}.tool.ts
• [ ] All Zod schema fields have .describe() annotations
• [ ] Schemas use only JSON-Schema-serializable types (no z.custom(), z.date(), z.transform(), z.bigint(), z.symbol(), z.void(), z.map(), z.set())
• [ ] JSDoc @fileoverview and @module header present
• [ ] handler(input, ctx) is pure — throws on failure, no try/catch
• [ ] auth scopes declared if the tool needs authorization
• [ ] task: true added if the tool is long-running
• [ ] Registered in definitions/index.ts barrel and allToolDefinitions
• [ ] bun run devcheck passes
• [ ] Smoke-tested with bun run dev:stdio or dev:http