add-tool

Add Tool

Add one or more new tools to an existing MCP collection. This skill handles creating the tool file, updating the collection index, and optionally adding integration tests and eval tests.

Use this skill when:

• A new API endpoint has been added and needs a tool
• You want to expose an additional operation from an existing collection
• /build-tools skipped the collection because it already has an index.ts

Prerequisites

Before running, ensure:

1. The collection already exists (src/umbraco-api/tools/{collection}/index.ts)
2. The API client has been generated (src/umbraco-api/api/generated/ exists — if not, run npm run generate)
3. The project compiles: npm run compile

Arguments

• Collection name (required): the collection to add the tool to (e.g. /add-tool form)
• Operation hint (optional): a description of the endpoint to add (e.g. /add-tool form "copy form endpoint")

If no arguments are provided, ask the user which collection and what endpoint to add.

Agents

This skill orchestrates the following agents:

Agent	When to use
mcp-tool-creator	Creating the tool file (Step 3)
mcp-tool-description-writer	Writing the tool description (Step 3)
mcp-tool-reviewer	Reviewing the new tool for LLM-readiness (Step 5)
integration-test-creator	Creating an integration test for the new tool (Step 6)
eval-test-creator	Updating eval tests to cover the new tool (Step 7)

Critical Rules

ONE TOOL AT A TIME. Create one tool file, compile, verify, then move to the next if adding multiple.

RUN COMMANDS SEPARATELY. Always run compile and test as separate Bash calls. Never chain with &&.

DO NOT RECREATE EXISTING INFRASTRUCTURE. The collection index, test setup, builders, and helpers already exist. This skill only adds new files and updates existing ones.

Workflow

Step 0: Understand the Request

Read the arguments to determine:

• Which collection to add to
• What endpoint(s) to add

If no operation hint was given, read .discover.json and the Swagger spec to identify operations that don't have tool files yet. Present the options to the user and ask which to add.

Step 1: Read Existing Collection

Read the existing collection to understand current patterns:

• src/umbraco-api/tools/{collection}/index.ts — current tool exports and collection metadata
• A few existing tool files in the collection — to match patterns (import style, API client usage, naming conventions)
• src/umbraco-api/api/generated/ — to find the client method and Zod schemas for the new endpoint

If the collection doesn't exist, tell the user to run /build-tools {collection} first.

Step 2: Read Swagger Spec

Fetch the swagger spec from the swaggerUrl in .discover.json:

curl -sk {swaggerUrl}

Find the operation matching the requested endpoint. Collect:

• HTTP method
• Path
• operationId
• Summary
• Parameters and request body schema
• Response schema

Step 3: Create Tool File

Use the mcp-tool-creator agent, then the mcp-tool-description-writer agent.

Create the tool file following the existing patterns in the collection. Use the same conventions for:

• File location (get/, post/, put/, delete/ subdirectories)
• Import style (match how other tools in this collection import the API client)
• Naming ({action}-{entity}.ts)
• Slices and annotations (follow the standard mapping)

HTTP Method	File pattern	Slice	Annotations
GET (single)	get/get-{entity}.ts	read	readOnlyHint: true
GET (list)	get/list-{entities}.ts	list	readOnlyHint: true
GET (search)	get/search-{entities}.ts	search	readOnlyHint: true
POST	post/create-{entity}.ts	create	destructiveHint: false, idempotentHint: false
PUT/PATCH	put/update-{entity}.ts	update	idempotentHint: true
DELETE	delete/delete-{entity}.ts	delete	destructiveHint: true

Step 4: Update Collection Index

Add the new tool to src/umbraco-api/tools/{collection}/index.ts:

1. Add an import for the new tool (matching the existing import style)
2. Add the tool to the tools array

Compile after updating:

npm run compile

Fix any TypeScript errors before proceeding.

Step 5: Review with mcp-tool-reviewer

Run the mcp-tool-reviewer agent on the new tool only (not the entire collection). Flag any issues.

Step 6: Add Integration Test (if tests exist)

Check if the collection has integration tests (src/umbraco-api/tools/{collection}/__tests__/setup.ts).

If tests exist:

1. Use the integration-test-creator agent to create a test file for the new tool
2. Follow the existing test patterns in the collection (import from setup.js, use the same builder)
3. Create src/umbraco-api/tools/{collection}/__tests__/{action}-{entity}.test.ts
4. Compile: npm run compile
5. Run the new test: npm test -- __tests__/{collection}/{action}-{entity}.test.ts
6. Fix any failures

If tests don't exist, skip — tell the user they can run /build-tools-tests {collection} to generate the full test suite.

Step 7: Update Eval Tests (if evals exist)

Check if the collection has eval tests (tests/evals/{collection}-*.test.ts).

If eval tests exist:

1. Read the existing eval test files to understand current workflow scenarios
2. Determine if the new tool fits into an existing scenario or needs a new one:
   • If it extends an existing workflow (e.g. adding an update tool to a collection that has a CRUD test), update the existing test to include the new tool
   • If it's a new capability (e.g. adding a search tool), use the eval-test-creator agent to create a new scenario
3. Build and run: npm run build then npm run test:evals -- --testPathPattern="{collection}"

If eval tests don't exist, skip — tell the user they can run /build-evals {collection} to generate eval tests.

Step 8: Report

Report what was done:

• Tool file created (path and name)
• Collection index updated
• Review findings (if any)
• Integration test created (or skipped with reason)
• Eval test updated/created (or skipped with reason)

If adding multiple tools, repeat steps 3-7 for each tool.

File Structure

After running, the new tool will be at:

src/umbraco-api/tools/{collection}/
├── {method}/
│   └── {action}-{entity}.ts          # New tool file
├── index.ts                           # Updated with new export
└── __tests__/
    └── {action}-{entity}.test.ts      # New test (if tests exist)